Document the v1.7 orchestration architecture

[jrpbuilds]

Parent

Part of #46.

Relationships

Depends on #66.

Goal

Document the final v1.7 orchestration ownership model so future SpecOps changes preserve the prompt/tooling boundary rather than gradually rebuilding either giant prompts or an over-deterministic TypeScript workflow engine.

Architecture to document

At minimum, capture this ownership model:

OpenSpec
  = durable workflow truth for the facts it actually represents

SpecOps TypeScript/tooling
  = normalization, validation, provable legality and non-authoritative projections

LLM Coordinator
  = judgement and orchestration among legal choices, plus any minimal semantic invariant not yet enforceable by tooling

Specialist agents
  = focused domain/planning/implementation/review work

And the primary rule:

Make mechanics deterministic, not judgement.

Alongside the complementary rule established during #48-#50:

Do not report more deterministic certainty than the canonical input state can prove.

Required topics

Deterministic vs agentic boundary

Summarize the contract established by #47 with concrete examples of what belongs on each side.

Document that some semantic workflow rules may remain minimal Coordinator guidance until a trustworthy runtime/tool boundary can enforce them; moving adjacent mechanics into TypeScript is not sufficient reason to delete those rules.

Status and eligible actions

Explain the final specops_status contract from #48/#49:

• phase represents the durable stage that can be derived from current OpenSpec/task state;
• lifecycle legality is exposed under the final lifecycle contract rather than using ambiguous OpenSpec capability terminology;
• eligible actions are mechanically legal options, not recommendations or priorities;
• ordering does not constitute a recommendation;
• actions whose full legality cannot be proven from canonical state must be omitted rather than guessed.

Archive/review boundary

Document the final outcome from #50 explicitly.

If archive legality is canonically enforceable from existing trustworthy state, document that source and how status/tool enforcement agree.

If review PASS/FAIL remains non-durable/model-owned, document that archive is intentionally absent from deterministic lifecycle/eligible-action projections and that the smallest successful-review-before-archive Coordinator invariant remains in place.

Do not describe structural OpenSpec archive readiness as equivalent to SpecOps review completion unless the implementation genuinely makes that true.

Todo and progress

Explain that native Todo and progress are derived/non-authoritative projections owned by runtime tooling and that OpenSpec remains the durable source of truth.

Dispatch context

Document the separation between permanent role prompts and current-job dispatch payloads.

Prompt philosophy

Record the v1.7 rule of thumb:

Prompt for role, semantic responsibility and judgement. Encode deterministic invariants in software. Carry mutable job facts in the dispatch.

Add the qualifier:

Remove a prompt guardrail only when runtime/tooling genuinely replaces the behaviour it protected.

Explain that prompt budgets are intentional regression guards against procedural sediment.

Anti-patterns

Explicitly warn against:

• teaching the Coordinator deterministic lifecycle algorithms in prose;
• hard-coding subjective engineering choices into TypeScript;
• reporting lifecycle legality from incomplete state;
• treating Todo/progress as workflow truth;
• adding prompt text to compensate for a missing tool validation boundary when that boundary can be implemented cleanly;
• deleting a semantic prompt invariant before tooling can actually enforce it;
• adding deterministic lane grouping merely because it is convenient to implement;
• duplicating task/artifact context across every permanent role prompt.

Public documentation

Update user-facing docs where v1.7 changes visible tools/behaviour, especially if specops_progress changes or status gains useful new fields.

Keep internal architecture detail separate from user instructions where appropriate.

Acceptance criteria

• Developer documentation clearly states the final ownership model and Define the deterministic vs agentic orchestration boundary #47 guardrail.
• Status phase/lifecycle/eligible-action semantics are documented as provable legal facts, not recommendations.
• The final archive/review boundary from Consolidate workflow legality behind one canonical derivation #50 is documented without overstating what durable state can prove.
• Todo/progress authority semantics are documented.
• Permanent prompt vs dynamic dispatch responsibility is documented.
• The rule for retaining minimal model-owned invariants until tooling replaces them is captured.
• Prompt budget philosophy and anti-patterns are captured for future contributors.
• Any public tool/config behaviour changed by v1.7 is reflected in user-facing documentation.
• Benchmark conclusions from Benchmark v1.6 vs v1.7 orchestration cost and latency #65 can be referenced in release notes where useful.
• Documentation matches the final post-cleanup implementation rather than the original design proposal.

Out of scope

• New workflow features.
• New persistent review/archive state.
• General documentation redesign unrelated to v1.7.