Simplify pre-implementation review to plan alignment

docs/architecture.md

@@ -18,11 +18,14 @@ flowchart TD
     U["Original task"] --> O["Orchestrator"]
     O --> SC["Contract scout"]
     SC --> C["Registered contract"]
-    C --> AR["Decision-authority review"]
-    AR --> P["Approved implementation context"]
+    O --> IP["Complete sealed iteration plan"]
+    U --> AR["Plan-alignment review"]
+    C --> AR
+    IP --> AR
+    AR --> P["Aligned implementation context"]
     P --> W["Path-scoped writer"]
     W --> D["Canonical Git diff"]
-    D --> R["Scope, technical, drift, and reflection reviews"]
+    D --> R["Technical and applicable scope/reflection reviews"]
     R --> F{"Open finding or todo?"}
     F -- yes --> P
     F -- no --> G["Supervisor completion gates"]
@@ -124,13 +127,14 @@ pre-implementation -> implementation -> post-implementation -> complete
 ### Pre-implementation
 
 1. The original task is stored immutably and hashed.
-2. A read-only contract scout emits structured `must` and `must-not` rules.
+2. When needed, a read-only contract scout emits structured `must` and
+   `must-not` rules.
 3. The supervisor seals and registers the scout artifact.
-4. A decision record selects a plan.
-5. An independent authority reviewer receives the original task, exact contract,
-   and implementation context.
-6. The writer gate opens only when the decision, plan, context, authority review,
-   and contract hashes agree.
+4. The orchestrator submits one complete iteration plan.
+5. An independent plan-alignment reviewer compares the complete sealed plan
+   directly with the original task and any registered contract.
+6. The writer gate opens only when the review reports `aligned` and its
+   original-task, plan, context, and contract hashes agree.
 
 ### Implementation
 
@@ -141,8 +145,8 @@ in parallel.
 
 ### Post-implementation
 
-The control plane computes one canonical diff hash. Scope, technical,
-decision-drift, and reflection reviewers receive:
+The control plane computes one canonical diff hash. A technical reviewer and
+any applicable scope or reflection reviewers receive:
 
 - the immutable original task;
 - the exact registered contract artifact;

docs/architecture/system-architecture.md

@@ -474,7 +474,7 @@ the authorized contract, the system uses a Simplex-style fallback: it issues no
 next operation permit, persists a supervisor-verified human-review request,
 ends the session in `human-review-required` state, and asks the user
 one bounded question. This is the same terminal authority pattern used when a
-decision-authority review detects a user-owned scope or risk choice. A later
+plan-alignment review finds that required input is absent. A later
 user answer starts a new session; model prose alone cannot clear the
 pending human boundary in the completed session.
 
@@ -766,11 +766,15 @@ role instructions, and the immutable artifacts needed for their review. They
 also have read access to the session trace corpus and the supervisor-mediated,
 read-only `prod-mcp` evidence path defined in AD-006, so evidence selection by
 another agent is not a trust boundary.
-Before implementation, the supervisor generates an immutable decision capsule
-containing the workflow revision, committed decision, selected alternative,
-original-task digest, and contract digest. Decision-authority evidence and the
-implementation permit must bind to the same capsule digest; an orchestrator
-summary cannot substitute for that binding.
+Before implementation, one independent reviewer compares the authenticated
+original request directly with the complete sealed iteration plan. The only
+semantic outcomes are `aligned` and `misaligned`: aligned plans may proceed;
+misaligned plans may not. A misaligned result returns to the orchestrator for a
+new plan unless the reviewer identifies genuinely missing user input, in which
+case the supervisor asks one bounded question. Review evidence binds directly
+to both the original-task digest and sealed-plan digest. This binding prevents
+input substitution but does not create a formal contract or a separate
+authority decision.
 
 Provider and model selection remain deployment-owned. The orchestrator chooses
 roles and dependencies, not provider credentials, model names, or prices.
@@ -811,11 +815,11 @@ immutable session grants, assignment ownership, diff binding, and the
 supervisor completion gate enforce these transitions.
 
 For source implementation, adaptivity happens at iteration boundaries. The
-orchestrator submits one complete iteration plan containing the committed
-decision, worker dependency graph, bounded ownership, and any additional
-review requests. The supervisor records the plan digest, adds review
-obligations derived from policy and persisted artifacts, and binds the
-decision-authority capsule to that digest. Once sealed, the runtime—not the
+orchestrator submits one complete iteration plan containing the implementation
+context, worker dependency graph, bounded ownership, and any additional review
+requests. The supervisor records the plan digest, obtains the binary alignment
+review described above, and adds review obligations derived from policy and
+persisted artifacts. Once sealed, the runtime—not the
 orchestrator—advances ready nodes, launches mutually independent agents, waits,
 finalizes durable evidence, freezes the candidate diff, and submits lifecycle
 transitions for that iteration. The runtime may report `needs_replan`, but it

docs/getting-started.md

@@ -151,35 +151,7 @@ project without copying prompt modules into it.
 The orchestrator normally performs the commands in this section. Operators use
 them for inspection or deliberate manual recovery.
 
-### 1. Record the Decision
-
-Create a decision, record alternatives, and commit one plan:
-
-```bash
-multiagent decision init DEC-001 --title "Choose the implementation"
-
-multiagent decision add-alternative DEC-001 \
-  --plan-id PLAN-A \
-  --summary "Small compatible change" \
-  --proposed-by contract-scout-01 \
-  --expected-outcome "Preserve behavior with minimal scope"
-
-multiagent decision add-assumption DEC-001 \
-  --assumption-id ASSUME-1 \
-  --statement "The public interface remains stable" \
-  --validation-method "source and test inspection"
-
-multiagent decision commit DEC-001 \
-  --selected-plan PLAN-A \
-  --reason "Matches the registered contract"
-
-multiagent decision list
-multiagent decision show DEC-001
-```
-
-Decision records are durable under `$MULTIAGENT_STATE_DIR/decisions`.
-
-### 2. Register the Contract
+### 1. Register a Contract When Needed
 
 For tasks with API, compatibility, security, benchmark, or hidden-contract risk,
 spawn a read-only scout:
@@ -199,83 +171,30 @@ multiagent workflow contract-register "$MULTIAGENT_WORKFLOW_ID" \
 The supervisor seals the scout result and records its hash. Later workers and
 reviewers receive the immutable original task and exact registered artifact.
 
-### 3. Open the Implementation Gate
+### 2. Execute One Sealed Iteration
 
-After an independent decision-authority review passes, bind the approved
-implementation context:
+Write the complete `IterationPlan` JSON described in
+`prompts/playbooks/implementation-lifecycle.md` under
+`$MULTIAGENT_STATE_DIR`, then make one blocking call:
 
 ```bash
-multiagent workflow prepare-implementation "$MULTIAGENT_WORKFLOW_ID" \
-  --decision-id DEC-001 \
-  --plan-id PLAN-A \
-  --decision-revision 1 \
-  --implementation-context /absolute/path/to/implementation-context.md \
-  --authority-review review-01-authority
-
-multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" implementation
+multiagent subagent execute-iteration \
+  --plan-file "$MULTIAGENT_STATE_DIR/iteration-1.json" \
+  --timeout 900
 ```
 
-The context must contain the exact registered contract. A plan that contradicts
-a registered `must-not` rule is rejected before a writer starts.
-
-### 4. Assign and Run a Worker
+The runtime seals the plan, launches one read-only plan-alignment reviewer,
+and compares the complete plan directly with the authenticated original task.
+An aligned plan proceeds to bounded workers and post-implementation technical
+review. A misaligned plan returns `needs_replan`; it asks the user only when
+the reviewer identifies genuinely missing input.
 
-Create metadata before spawning a writer:
-
-```bash
-multiagent subagent assignment-create worker-01 \
-  --assignment-id IMPL-001 \
-  --role exploitation \
-  --decision-id DEC-001 \
-  --plan-id PLAN-A \
-  --branch "$(git -C "$MULTIAGENT_ROOT" branch --show-current)" \
-  --owned src/,tests/
-
-SUBAGENT_CLI="${WORKER_CLI:-claude}" \
-multiagent subagent spawn worker-01 \
-  --role worker \
-  --own src/,tests/ \
-  --assignment-id IMPL-001 \
-  --workflow-id "$MULTIAGENT_WORKFLOW_ID" \
-  --decision-id DEC-001 \
-  --plan-id PLAN-A \
-  --instruction-file /absolute/path/to/worker-instruction.md
+The supervisor binds alignment evidence to the original-task and sealed-plan
+digests, enforces worker path ownership, freezes the candidate diff, and runs
+all applicable post-implementation reviews. The orchestrator must not replay
+those internal transitions around the executor.
 
-multiagent subagent wait worker-01 --timeout 1800
-multiagent subagent assignment-check worker-01
-```
-
-Only the supervisor-authorized writer receives temporary access to its existing
-owned paths. The global writer lease prevents a second writer from becoming
-active at the same time.
-
-Update a durable checkpoint during long work:
-
-```bash
-multiagent subagent checkpoint-update worker-01 \
-  --step "implementation complete; focused tests running" \
-  --idempotency "rerun focused tests before acceptance" \
-  --status running
-```
-
-### 5. Review the Canonical Diff
-
-Freeze the current repository state:
-
-```bash
-multiagent snapshot --root "$MULTIAGENT_ROOT" --base HEAD --format json
-```
-
-Transition to post-implementation with the reported hash, then run read-only
-scope, technical, decision-drift, and reflection reviews. Review instructions
-must include the original task, registered contract, approved context, and
-canonical diff. Finalize each reviewer so the supervisor can seal its output.
-
-Record review findings and todos through `multiagent workflow` and
-`multiagent subagent` commands. A changed diff invalidates previous acceptance.
-An open finding returns the workflow to another pre-implementation iteration.
-
-### 6. Complete Atomically
+### 3. Inspect Completion
 
 Inspect both gates:
 
@@ -284,11 +203,9 @@ multiagent workflow completion-check "$MULTIAGENT_WORKFLOW_ID"
 multiagent subagent gate-check
 ```
 
-Request completion:
-
-```bash
-multiagent orchestrator complete
-```
+When `execute-iteration` reports `status=completed`, it has already requested
+supervisor completion. A `needs_replan` result leaves durable findings for the
+next iteration; do not mutate the sealed plan in place.
 
 The orchestrator cannot directly write `complete`. The supervisor runs the
 lifecycle and technical gates under the lifecycle lock and changes the phase

evaluation/README.md

@@ -163,7 +163,7 @@ python3 -m evaluation.cli \
 
 `baseline` is one ordinary Codex CLI invocation. `multiagent` runs the current
 production Rust/tmux lifecycle in Linux, including its contract scout,
-authority reviewers, workers, verifiers, and final reviews. Build the exact
+plan-alignment reviewers, workers, verifiers, and final reviews. Build the exact
 checkout before a live multiagent comparison:
 
 ```bash

prompts/playbooks/agent-spawning.md

@@ -6,8 +6,7 @@ replace, verify, or finalize worker windows or named subagents.
 ## Read-Only Reader Spawn
 
 Readers are investigation roles, not implementation assignments. Spawn them
-without `--own`, `--assignment-id`, `--decision-id`, `--plan-id`, or
-`--decision-revision`:
+without `--own`, `--assignment-id`, `--decision-id`, or `--plan-id`:
 
 ```bash
 SUBAGENT_CLI="$VERIFIER_CLI" multiagent subagent spawn reader-01-question \

prompts/playbooks/implementation-lifecycle.md

@@ -6,7 +6,7 @@ use the selected Markdown runbook and reviewed ops path instead.
 Do not use this lifecycle for an external-only task that does not modify
 repository source. Such work uses `prompts/playbooks/reviewed-ops-cycle.md`.
 
-## Iteration Contract
+## Iteration Plan
 
 Adapt the role graph at the beginning of an iteration, then let the runtime
 execute that sealed graph. The orchestrator makes semantic choices between
@@ -18,18 +18,19 @@ Normal lifecycle phases remain:
     pre-implementation -> implementation -> post-implementation -> complete
     post-implementation -> pre-implementation  when a repair TODO remains
 
-A substantive finding, changed assumption, expanded scope, risk change, or
-needed user choice ends the current iteration. It must produce a newly reviewed
-plan; never mutate a sealed plan in place.
+A substantive alignment finding, changed assumption, expanded scope, risk
+change, or needed user input ends the current iteration. It must produce a newly
+reviewed plan; never mutate a sealed plan in place.
 
 ## Build One Complete Plan
 
 Read the authenticated task once through `multiagent workflow context`. Choose
 the smallest worker dependency graph that can satisfy it. Skip a contract scout
 when the task already gives an exact bounded artifact schema and values. Add a
 scout only when an unknown can materially change the plan.
-The explicit task contract is already approved; ask the user only when
-materially different outcomes remain consistent with it.
+The original user request is authoritative. Ask the user only when required
+information is genuinely absent or materially different outcomes remain
+consistent with the complete request and available evidence.
 
 Write one UTF-8 JSON plan under `MULTIAGENT_STATE_DIR`, using exactly this
 schema:
@@ -40,22 +41,7 @@ schema:
   "kind": "IterationPlan",
   "workflowId": "WORKFLOW_ID",
   "iteration": 1,
-  "decision": {
-    "id": "DECISION_ID",
-    "title": "single-line title",
-    "selectedPlan": "PLAN_ID",
-    "reason": "single-line reason",
-    "rollbackPolicy": "single-line rollback condition",
-    "alternatives": [
-      {
-        "id": "PLAN_ID",
-        "summary": "single-line bounded plan",
-        "expectedOutcome": "single-line exact outcome",
-        "risk": "single-line residual risk"
-      }
-    ]
-  },
-  "implementationContext": "Complete goal, authority basis, constraints, exact target paths, ownership, prohibitions, acceptance criteria, and unresolved risks.",
+  "implementationContext": "Complete goal, constraints, exact target paths, ownership, prohibitions, acceptance criteria, and unresolved risks.",
   "workers": [
     {
       "id": "worker-primary-01",
@@ -71,39 +57,38 @@ schema:
 
 Use `worker-ops-plan-01` for a bounded repository artifact whose deliverable is
 an operations plan so the launcher selects the focused planning role. Use
-ordinary `worker-*` identities for other source work. Include all genuinely
-material alternatives; do not add a fake alternative merely to populate the
-decision ledger. Worker ownership must be non-overlapping. Dependencies name
-other worker IDs. Put only `decision-drift`, `scope`, or `reflection` in
-`additionalReviews`, and only when that extra review can affect acceptance.
+ordinary `worker-*` identities for other source work. Worker ownership must be
+non-overlapping. Dependencies name other worker IDs. Put only `scope` or
+`reflection` in `additionalReviews`, and only when that extra review can affect
+acceptance.
 On a repair iteration, `resolvesTodos` must exactly list every active direct
 TODO that the sealed worker graph will address. Resolve evidence or decision
 TODOs before submitting the plan; the runtime marks declared direct TODOs
 complete only after the candidate passes every supervisor review.
 
-The supervisor always requires an independent decision-authority review and a
-technical review for a produced diff. It also derives decision-drift review
-when the committed decision contains multiple alternatives or assumptions, and
-may add other obligations from persisted artifacts. The orchestrator may add
-review but cannot remove supervisor obligations.
+The supervisor always requires one independent plan-alignment review before
+implementation and one technical review for a produced diff. It may add other
+obligations from persisted artifacts. The orchestrator may add review but
+cannot remove supervisor obligations.
 
 ## Execute the Sealed Iteration
 
 Make one blocking runtime call after the plan file is complete:
 
     multiagent subagent execute-iteration --plan-file PLAN_PATH --timeout 900
 
-The runtime validates and records the plan digest, materializes the committed
-decision, launches exactly one digest-bound decision-authority reviewer, and
-stops on authority findings. After acceptance it prepares the complete
-implementation context, schedules ready worker nodes, waits and finalizes them,
+The runtime validates and records the plan digest, launches exactly one
+digest-bound plan-alignment reviewer, and stops on misalignment. After alignment
+it prepares the complete implementation context, schedules ready worker nodes,
+waits and finalizes them,
 checks the candidate against the union of owned paths, freezes the diff, asks
 the supervisor for review obligations, launches independent reviewers in
 parallel, records their structured evidence, and requests supervisor
 completion. Do not duplicate any of these commands around the executor.
 
-The authority capsule is supervisor-generated and includes the sealed plan
-digest. Neither the orchestrator nor a worker may manufacture or edit it.
+The review is mechanically bound to both the sealed plan digest and the
+authenticated original-task digest. This binding proves which inputs were
+reviewed; it is not a substitute contract or a separate authority decision.
 Reviewer access remains mechanically read-only, and worker writes remain
 bounded by assignments.