feature-factory 0.8.8 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # feature-factory
 
-A durable, observed control plane for running a feature from idea to draft PR through a chain of
+A durable, observed control plane for running a feature from idea to pull request through a chain of
 focused agents, with human approval gates. Host-agnostic, zero dependencies.
 
 ```sh

package/WORKFLOW.md

@@ -5,9 +5,16 @@ skill by itself. A host integration must ship its own `SKILL.md` and place an ex
 to that skill as `WORKFLOW.md`.
 
 **Where the driver reads this file from, and when.** `factory init` stages an exact copy into the run
-directory and returns its path as `workflow`. The driver reads THAT copy, completely, before any state read,
-dispatch, gate, or factory command other than `init` itself — admission and the `init` invocation are
-specified by the host `SKILL.md`, everything after them here. A host whose agents may read outside the
+directory and returns its path as `workflow`. The driver reads THAT copy, completely, before any
+dispatch, gate, or factory command other than the bounded opening this paragraph names — admission, that
+opening, and the `init` invocation are specified by the host `SKILL.md`, everything after them here. The
+opening is: inspect the two deterministic manifest candidates, and where one exists, qualify it with
+`factory status` and read the staged workflow at `<qualified sandbox_path>/.factory/$R/WORKFLOW.md` --
+status reports `sandbox_path`, not a run directory or a workflow path, so the derivation is stated rather
+than left to be guessed. A fresh run reaches the
+staged copy through `init`; an existing one must never be initialized again, so it reaches the same copy
+through that lookup. Those two candidate reads and that one `status` call are the only state reads
+permitted before this file is in hand. A host whose agents may read outside the
 workspace may instead read the copy beside its skill; a host that denies such reads must use the staged copy,
 because the packaged one is unreadable there and a run that depends on it fails on a permission refusal
 rather than on anything about the work. Either way the bytes are identical, and a driver that cannot read
@@ -88,7 +95,7 @@ repository and the host is inside your trust boundary by construction. What that
 INTAKE ─▶ [GATE 1: Story] ─▶ RESEARCH + DESIGN ─▶ SPEC ─▶ DECOMPOSE ─▶ [GATE 2: Brief + Plan]
        ─▶ BUILD  (waves of parallel slices; per-slice OBSERVE ▶ REVIEW ▶ serial MERGE)
        ─▶ INTEGRATE: TEST + VALIDATE (on the merged feature branch)
-       ─▶ [GATE 3: Pre-PR] ─▶ DRAFT PR
+       ─▶ [GATE 3: Pre-PR] ─▶ PR (draft per pr_draft)
 ```
 
 `work-reviewer` runs on **high-risk steps only** — spec, decompose, each slice build, and test — and
@@ -184,8 +191,28 @@ left by an earlier park: neither is evidence for this park. Publishing again is
 
 For top-level needs-human, status exposes the durable next action, but no command may execute it before explicit factory resume.
 Retain the sandbox for top-level needs-human while parked, then explicitly resume it after the external fix.
-A park that asks a question about the request itself -- a contradiction between criteria, a scope lock,
-or a pinned constraint -- is not fixed by resuming. Resume continues from the existing manifest and
+**An operator answers a parked run with
+`factory decide "$R" --text "<decision>" --session "$SESSION_ID" --repo "$RUN_REPO"`.**
+The text is appended to an immutable cumulative artifact named
+`artifacts/operator-decisions-<sha256hex>.md`. The manifest's `operator_decision.artifact` is the
+authoritative pointer, and its digest identifies only the recorded bytes. Failed publication may leave
+an unreferenced file; ignore it. Recording a decision does not resume the run.
+
+When qualified status reports a non-null `operator_decision`, read the artifact at that pointer in full
+before continuing work on resume. Apply the decision to the permitted choices it names, and report how
+it was applied at the next gate or park. It cannot change ratified paths, `test_plan`, gates, or safety
+authority; path changes require the separate `amend-paths` procedure. If it names no clear permitted
+course of action, ask rather than guess. Recording is enforced; reading and applying are instructions.
+The digest identifies recorded bytes, not proof that the decision was applied.
+
+The resume command refreshes the staged `WORKFLOW.md` from the current packaged contract before
+unparking; a copy failure leaves the run parked. After successful resume, read that staged workflow in
+full as part of verifying order 7, before reconciliation, dispatch, or applying decisions. Preserve the
+publishing-identity guard before order 8. For a driver still following an older staged contract, the
+operator may instruct this updated resume sequence, including reading the recorded decision and the
+current no-default-code-ceiling rule. This preserves run state and requires no migration or reset.
+A park that asks a question the decision cannot answer -- one that changes the request itself, so the
+story or brief would have to be regenerated -- is still not fixed by resuming. Resume continues from the existing manifest and
 `status.next`; it does not re-resolve the issue, re-read `ISSUE_PAYLOAD`, or regenerate the story or
 brief, so an edited issue body cannot reach the artifacts a retained run will keep using. The supported
 route is: record the decision in the issue body, then have the operator remove the retained sandbox
@@ -196,8 +223,9 @@ run, and `factory init` refuses while either manifest candidate exists, so a rel
 reselects the parked run instead of replacing it. OPERATING.md carries the command and its cost --
 everything held only in that sandbox is lost, including merged slices whose branches were never pushed,
 so push anything worth keeping first.
-Resume is for external causes -- a timeout, an outage, credentials, an unclean tree -- where the run's own
-artifacts are still correct.
+Resume is for external causes -- a timeout, an outage, credentials, an unclean tree -- or recorded
+operator decisions consistent with the approved scope and ratified plan. Changed requirements follow the
+replacement-run route above.
 State that route in the park reason, because a decision recorded only in a host session or a sandbox
 artifact is lost with that sandbox, and the replacement run asks the same question again.
 
@@ -299,8 +327,10 @@ fresh run; an existing run follows these rules solely because its manifest alrea
   unresolved product, UX, security, or external-policy decision.
 - **Gate 2 (brief + plan)**: approve only after `work-reviewer` approves both spec and decomposition,
   every acceptance criterion maps to a slice, and same-wave slices are file-disjoint.
-- **Gate 3 (pre-PR)**: approve only on a GO or GO-WITH-NITS validator verdict with `review_ready`
-  observed evidence for the integrated branch. A NO-GO is a NO-GO.
+- **Gate 3 (pre-PR)**: approve only with `review_ready` observed evidence for the integrated branch, and
+  on a GO or GO-WITH-NITS validator verdict **for a multi-slice run**. A NO-GO is a NO-GO. A single-slice
+  run skips the validator exactly as Step 5 specifies, so requiring a verdict here would make the one
+  case Step 5 exempts unapprovable; if such a run recorded a verdict anyway, it binds.
 - **Never auto-merge.** Recording the pull request is the last externally publishing side effect an
   autonomous run may perform. Whether that PR is a draft is the repository's `pr_draft` choice and is
   independent of the run mode: autonomous does not imply draft, and `pr_draft: false` is a supported
@@ -477,8 +507,8 @@ tracker URL to select a run declares a `resolve` command recognizing those forms
 payload above. Recognition belongs to the declaration for the same reason fetching does: deciding that a
 bare integer is a reference, rather than a feature description, is repository-specific.
 
-This repository declares its own in `.factory.json`, so `205`, `#205`, and the canonical issue URL still
-select run `205` — through that declaration rather than through anything built in.
+For example, a repository may declare a resolver in `.factory.json` that maps `205`, `#205`, and its
+canonical issue URL to run `205`. These forms work only through that declaration, not built-in behavior.
 
 #### Resolver and repository verification boundaries
 
@@ -583,7 +613,7 @@ Resume order 3 — complete the existing effective-push proof.
 Resume order 4 — accept the feature branch only after existing reflog/provenance, branch/worktree binding, seed ancestry, cleanliness/recovery, and operator exact-ref rechecks pass in their current order.
 Resume order 5 — immediately before claiming, rerun the final operator exact-ref-absent guard.
 Resume order 6 — claim with the current host session or perform a justified existing steal, then verify qualified status still shows this fresh owner and the parked result originally observed.
-Resume order 7 — invoke explicit factory resume with the verified owning session, then verify running status, unchanged historical terminal result, real next action, and the same fresh owner.
+Resume order 7 — invoke explicit factory resume with the verified owning session, then verify running status, unchanged historical terminal result, real next action, and the same fresh owner; read the refreshed staged WORKFLOW.md in full as part of this verification.
 Resume order 8 — run only existing post-lock reconciliation for an already-recorded merge, its evidence, and repository verification.
 Resume order 9 — continue solely from the newly qualified status.next.
 
@@ -591,6 +621,14 @@ For configured order 7, the CLI binds the exact raw `run.json` bytes, the valida
 
 A clean zero records the command and exit `0`, advances `updated_at`, and changes status to `running` while preserving progress and the historical terminal result. An ordinary failure with intact bindings records the exact command and integer or `null` result, advances `updated_at`, remains `needs-human`, preserves progress and the historical result, and refuses; a later explicit resume reruns bootstrap. Changed or malformed manifest bytes, or an absent, stale, or different owner, are binding loss rather than ordinary failure: preserve current bytes and ownership, add no bootstrap evidence, and do not unpark.
 
+When the operator supplies a decision, optionally use the qualified decision command above after order 6 verifies the fresh
+owner and unchanged parked result, before order 7's explicit resume. Re-read qualified status and the
+manifest pointer; require the same fresh owner, parked status, original result, and the intended recorded
+bytes and digest. A refusal or mismatch stops recovery. This action does not replace `amend-paths` or
+resume. If staying parked after a decision or amendment, refresh the control-plane snapshot using the
+existing *Parked control-plane snapshot* procedure and report its path or failure; neither command
+archives the updated plane automatically.
+
 When the parked cause is an insufficient ownership declaration for an existing unmerged slice, the
 operator may insert exactly one optional action after order 6 has verified the fresh exact owner and
 unchanged parked result, and before the unchanged explicit resume in order 7:
@@ -616,10 +654,19 @@ When the run reports a nonempty `publishing_identity`, the mandatory guard below
 boundary between completion of resume order 7 and the first operation in resume order 8. Nothing may
 intervene between the verified running/same-owner result and that guard, or between a successful guard
 and reconciliation. A pre-0.8.0 manifest reporting `null` preserves the nine orders without adding an operation.
+The refreshed workflow read belongs to order 7 verification, before this boundary.
 
 For order 1 require the intended run ID, a valid manifest, recorded branch and mode, current parked status, and the original terminal result. Order 2 stays after selection and containment and before effective-push proof. Order 3 never absorbs containment, binding, or the post-selection exact-ref guard. During order 4 preserve every existing exact-ref recheck and the stated provenance sequence. No unrelated observation or effect occurs between order 5 and claim or justified steal. Order 6 requires `lock_session === SESSION_ID`, a fresh lock, unchanged parked status, and a terminal result deeply equal to the one first observed. Invoke `factory resume "$R" --session "$SESSION_ID" --repo "$RUN_REPO"` for order 7 — the same session order 6 just verified as the fresh owner — then require that owner unchanged. Resume refuses without it, and refuses a lock that is absent, stale, or held by anyone else. Order 8 may replay only the existing recorded-merge reconciliation path and must not move pre-lock proofs across the lock boundary. Order 9 never uses the pre-resume observation or the stop reason.
 
-If resume refuses after claim or the run later reparks, quiesce builders, tools, specialist tasks, and heartbeat loops; release the same owning session; then require qualified status to show an absent lock and null owner before another session begins.
+If resume refuses after claim or the run later reparks, quiesce builders, tools, specialist tasks, and
+heartbeat loops. Qualify the intended retained run again before reporting the stop. If it is still parked
+with the same fresh owning session and the expected historical result, republish its current control
+plane using *Parked control-plane snapshot*, then report the verified snapshot path or the publication
+failure. A refreshed workflow or recorded bootstrap failure can make the previous snapshot stale.
+Do not exclude `WORKFLOW.md` from verification, or claim that a stale snapshot is current. If state or
+ownership cannot be qualified, do not publish a snapshot; report the qualification failure instead.
+Release only the same owning session, and require qualified status to show an absent lock and null owner
+before another session begins; never release a different owner's lock.
 
 Before requesting a fresh run, inspect only the two deterministic manifest candidates described by the
 CLI contract: the legacy candidate under `O/.factory/R` and the sandbox candidate under
@@ -1171,8 +1218,9 @@ CHECKED_OUT_FEATURE_BRANCH="$(git -C "$INTEGRATION_WORKTREE" symbolic-ref --quie
 
 Require it to equal `FEATURE_BRANCH` and require `HEAD^{commit}` to equal
 `refs/heads/$FEATURE_BRANCH^{commit}` as one 40-character SHA. If no slice is merged, or `.factory.json`
-is absent, preserve the existing progression and output exactly. A present config must validate as the
-four required properties plus optional `verify_timeout_ms` object above before any entry is used.
+is absent, preserve the existing progression and output exactly. A present config must validate against the
+repository-configuration schema stated above before any entry is used; that statement is authoritative and
+is deliberately not restated here, because a restated shape goes stale as the schema gains properties.
 
 With valid config, validate canonical `evidence/test-verifier.json` as untrusted input using the same
 closed schema and derived `review_ready` rules as the CLI. Classify it into exactly four outcomes:
@@ -1406,9 +1454,10 @@ Per slice:
 
 For AC6 and AC7, terminalize means terminate the current `factory slice … merged` CLI invocation and
 its enclosing run-driver invocation after two unavailable executions; it does not mean the irreversible
-factory terminal transition. Clean, unchanged exhaustion leaves durable `status: "running"` and
-`terminal_result: null`, so a later explicit invocation may reconcile the same merge with a fresh local
-budget. Top-level needs-human remains parked while replay safety is false; explicit resume does not bypass the same safety check.
+factory terminal transition. Clean, unchanged exhaustion leaves durable `status: "running"` with its
+`terminal_result` unchanged — `null` for a run that has never parked, and the preserved historical result
+for one continued by explicit resume — so a later explicit invocation may reconcile the same merge with a
+fresh local budget. Top-level needs-human remains parked while replay safety is false; explicit resume does not bypass the same safety check.
 
 After a clean, unchanged second `unavailable`, stop dispatching and processing `status.next`, and never
 issue another same-SHA replay in this driver invocation. Await every in-flight specialist task. Stop
@@ -1420,7 +1469,11 @@ factory lock "$R" release --session "$SESSION_ID" --repo "$RUN_REPO"
 ```
 
 Run qualified `factory status "$R" --json --repo "$RUN_REPO"` and require valid durable
-`status: "running"`, `terminal_result: null`, and proof that this `SESSION_ID` no longer owns the lock.
+`status: "running"`, a `terminal_result` unchanged from the one this invocation began with, and proof
+that this `SESSION_ID` no longer owns the lock. For a run that has never parked that value is `null`; a
+run continued by explicit resume keeps its historical result by design, since resume preserves
+`terminal_result` rather than clearing it, so requiring `null` would report every resumed run as a
+retained-lock error.
 In the uncontended orderly path require `lock: "absent"`. Only after every task and heartbeat is
 quiescent, the owning release succeeds, and qualified status proves those values may the driver report:
 
@@ -1429,7 +1482,7 @@ Run: <R>
 Run repository: <RUN_REPO>
 Outcome: repository-verify-exhausted
 Status: running
-Terminal result: null
+Terminal result: <unchanged from this invocation's start: null, or the preserved historical result>
 Lock: released
 ```
 
@@ -1721,8 +1774,12 @@ HEAD, a branch name, or an unpersisted variable.
    **before** presenting Gate 3: the gate cannot be approved without it.
 
 On NO-GO, classify each finding against the prior round and find its design-level root cause before
-spending a retry; route the top finding to the owning builder in a fresh slice worktree, or fix in the
-integration branch if it is test-only. A test-only fix there touches test files only — never production
+spending a retry. A **test-only** finding is fixed in the integration branch under the rules below. A
+finding in production source has no legal path at this point and must **park top-level needs-human**
+naming the finding and its root cause: every slice is merged, a merged slice cannot reopen or redispatch,
+seeding is one-time, and the integration fix is test-only by construction — so "route it to the owning
+builder in a fresh slice worktree" is an instruction the contract cannot carry out. Parking is the honest
+outcome and leaves the work recoverable; improvising a reopen is not. A test-only fix there touches test files only — never production
 source, never a privileged control-plane path — preserves the property under test or records why it
 cannot, lands as its own commit rather than folded into a merge, and is disclosed in the PR body naming
 the file and the cause. Respect `max_retries`.
@@ -1744,12 +1801,7 @@ callouts, remaining risks, and a `## Post-merge test-only repairs` section. When
 that section states so. Otherwise it summarizes every journal record in order, including introducing
 merge, attempt, Starting head, trigger result, sorted test paths, cause, property outcome and every
 property loss, repair commit, post-repair result, and final or active status. No attempt, outcome, or
-property loss may be omitted or collapsed into only the latest result. Include the measured landed
-production count using this exact line template:
-
-```text
-Production source: <landed count> / 4500
-```
+property loss may be omitted or collapsed into only the latest result.
 
 Present that current artifact and open the gate with:
 
@@ -1943,12 +1995,8 @@ redundancy: between the approval and this call the integration head can move, an
 describes a head nobody validated. If `pr` refuses for that reason, the PR you just opened is ahead of
 what was approved — say so at the gate rather than recording it anyway.
 
-The PR body includes the same measured landed count using this exact line template:
-
-```text
-Production source ceiling: <landed count> / 4500
-```
-
+This contract sets **no limit on how much code a change may add**. Apply a code ceiling only when the
+request or target repository explicitly sets one; factory supplies no default ceiling.
 When `.factory/$R/artifacts/post-merge-repairs.md` exists, validate it again and include every attempt under
 `## Post-merge test-only repairs` in `BODY_FILE`: introducing merge, attempt, Starting head, trigger and
 post-repair results, files, cause, property outcome, repair commit, and status. Never omit an earlier
@@ -2139,12 +2187,9 @@ Never re-do a side effect the manifest shows already done — ticket creation, p
   ready-for-review is `pr_draft`'s decision, not this rule's.
 - **Scope discipline and no fabrication.** Flag out-of-scope work at the next gate. Never invent paths,
   keys, versions, or test passes — if the evidence is thin, say so and ask.
-- **A repository may lock its own scope, and a lock is not a defect.** A check whose assertion *is* a
-  limit records a decision: a coverage floor, a bundle or performance budget, a maximum file length, a
-  dependency or import allowlist, a public-API or snapshot test, an exact list of permitted names, a
-  cap on how much of something may exist. It need not be a test — a lint rule or a CI threshold locks
-  scope the same way. Treat it as a constraint on the plan: fit inside it, prefer new cases in existing tests
-  over new test entry points, and if the work genuinely needs more, surface that at the gate with the
-  number and the reason. Editing the limit to make the suite green removes the only thing holding the
-  scope, and the failure message tells you the number, so you never need to be told it in advance.
-  Widening one is the engineer's decision, not yours.
+- **A repository may lock its own scope, and a lock is not a defect.** Honor explicit limits such as
+  coverage floors, bundle or performance budgets, file-length caps, and dependency allowlists. If work
+  needs a wider limit, surface the value and reason at the gate; widening it is the engineer's decision.
+  Expected-value ledgers and snapshots may instead record the current result, not a scope limit. Read
+  the repository's policy and the assertion's purpose before classifying a failure. Update such records
+  when the intended change requires it; do not change an explicit limit just to make tests green.

package/agents/backend-builder.md

@@ -21,7 +21,7 @@ Implement the backend of a technical brief. Write production code in this reposi
 - **You implement ONE slice, not the whole backend.** The orchestrator gives you a single **slice spec** (its `paths`, acceptance criteria, and test plan) in an isolated slice worktree `$WT` branched for that slice. Implement only that slice's acceptance criteria, and edit only files under the slice's `paths` — out-of-lane edits get rejected by the reviewer and risk colliding with a parallel slice on merge.
 - **Stay in your lane:** within your slice's `paths`, and only backend paths — the source, resource and test trees the research map identifies as backend. Never touch frontend paths (frontend-builder owns those) or vendored/subtree directories that are pull-only.
 - Implement **only what the brief specifies.** No drive-by refactors, no speculative abstraction.
-- **Do not add new code comments** to your changes (team convention) — let names and structure carry the meaning.
+- Follow the target repository's documented code-comment policy (`AGENTS.md`, `CLAUDE.md`, or their linked rules); do not assume a blanket ban on comments.
 
 ## How to build
 
@@ -76,7 +76,7 @@ Return this as your final message:
 **API surface change:** <exact schema or route change> | none
 
 **Verification:**
-- `compileJava`: pass/fail
+- build/typecheck: `<actual repository command>` — pass/fail (or "not applicable — reason")
 - tests run: `<names>` — pass/fail (or "none — reason")
 
 **Commit:** <sha + subject>

package/agents/frontend-builder.md

@@ -22,7 +22,7 @@ Implement the frontend of a technical brief. Write production code in this repos
 - **You implement ONE slice, not the whole frontend.** The orchestrator gives you a single **slice spec** (its `paths`, acceptance criteria, and test plan) in an isolated slice worktree `$WT` branched for that slice. Implement only that slice's acceptance criteria, and edit only files under the slice's `paths` — out-of-lane edits get rejected by the reviewer and risk colliding with a parallel slice on merge.
 - **Stay in your lane:** within your slice's `paths`, and only frontend paths. Never touch backend paths — that's the backend-builder.
 - Implement **only what the brief specifies.** No drive-by refactors.
-- **Do not add new code comments** to your changes (team convention) — let names and structure carry the meaning.
+- Follow the target repository's documented code-comment policy (`AGENTS.md`, `CLAUDE.md`, or their linked rules); do not assume a blanket ban on comments.
 - For framework API questions, use whatever framework skill or documentation tool this repository provides rather than guessing from older patterns.
 
 ## How to build (repo frontend rules — non-negotiable)

package/agents/implementation-validator.md

@@ -27,7 +27,7 @@ The skeptic. The builders and test-verifier just reported success — your job i
 
 1. **Acceptance criteria coverage:** each AC from the story — is it actually implemented AND tested? Map AC → code → test. Flag any AC with code but no test, or a test that doesn't really assert the criterion.
 2. **Brief adherence:** did the builders follow the layered plan, the named patterns, and the read-path, API-surface and migration decisions? Note deviations and whether they're defensible.
-3. **Repo conventions** (`AGENTS.md` or `CLAUDE.md`, and the rules files they point at): layering, component conventions, migration metadata and registration, no vendored-tree edits, no stray comments.
+3. **Repo conventions** (`AGENTS.md` or `CLAUDE.md`, and the rules files they point at): layering, component conventions, migration metadata and registration, no vendored-tree edits, and the target repository's documented code-comment policy (not an assumed blanket ban).
 4. **Correctness & blast radius:** obvious bugs, missing null/error handling, auth/role gaps, N+1 risks, migration safety in production, feature-flag gating.
 5. **Scope:** anything built that the story didn't ask for (scope creep) or any out-of-scope file touched.
 

package/agents/story-writer.md

@@ -49,8 +49,8 @@ Return this as your final message:
 - Out: <...>
 
 **Suggested ticket fields (orchestrator will use these if you approve creating the ticket):**
-- Issue type: Story | Task
-- Components: <user interface | api | Agent — pick from what the change touches>
+- Issue type: <choose from the supplied tracker issue types; if unavailable, mark unspecified>
+- Components: <choose from the supplied tracker components; if unavailable, mark unspecified>
 - Labels: <optional>
 
 **Should this be split?** <no | yes — propose N stories with one-line titles>
@@ -59,4 +59,4 @@ Return this as your final message:
 - <call out every assumption so the human can correct it at the gate>
 ```
 
-Never fabricate an APP- key or claim a ticket exists — you only draft. The orchestrator handles creation.
+Never fabricate an issue key or claim a ticket exists — you only draft. The orchestrator handles creation.

package/agents/test-verifier.md

@@ -85,10 +85,15 @@ Then append a machine-readable **claim block** the orchestrator parses (it re-ru
  "tests": {"cmd": "<the test command you ran>", "exit": 0}, "blockers": []}
 ```
 
-Use exactly these field names and exactly this `status` vocabulary. The orchestrator feeds this
-block to `factory observe --claim`, which compares each field against what it observes itself and
-records every disagreement as a review finding. `completed` is the word the evidence uses; any
-other spelling reads as a disagreement about status. `tests.exit` must be the real exit code — a
-claimed zero against an observed failure is the most important disagreement this catches.
+Use exactly these field names and exactly this `status` vocabulary.
+
+**`files_changed` is your report to the reviewer, not a claim the orchestrator reconciles.** Unlike a
+build slice, this stage is observed against the **integrated** worktree from the run's original branch
+point, so the observed diff legitimately contains every merged builder's changes as well as your tests,
+and the workflow's integration observation passes no `--claim`. Listing only your own test files and
+having it compared against that diff would manufacture a `claim_mismatch` on correct work. `completed` is the word the evidence uses; any
+other spelling reads as a disagreement about status. `tests.exit` must be the real exit code: the
+orchestrator re-runs the suite itself, and a claimed zero against an observed failure is the
+disagreement that matters most.
 
 Commit test files separately to the worktree branch (`git -C $WT add <tests> && git -C $WT commit -m "<KEY>: tests for <feature>"`). A FAIL is a valid, useful result — report it honestly; do not weaken a test to make it pass.

package/agents/work-decomposer.md

@@ -82,15 +82,14 @@ a re-read rather than a run.
 6. **A slice must be able to make its ratified `test_plan` green using only the paths it owns.** This is
    one invariant with several faces, and it is the only rule in this list whose violation admits *no legal
    move*: `paths` freeze at seeding, a blocked slice's dependents cannot be dispatched, and the slice's own
-   ratified command includes whatever its change affected. No retry count fixes it. Three runs have died
-   here, each arriving at it differently.
+   ratified command includes whatever its change affected. No retry count fixes it.
 
    **The check is mechanical, and it is the same one every time.** Cross-check every slice's `test_plan`
    against every other slice's `paths` before you emit the plan. For each slice ask: when this command
    runs, is everything it must change in order to pass owned by *this* slice? If not, the plan is wrong,
    whatever the topic suggests. Ownership follows the change, not the subject matter.
 
-   Three observed faces of it:
+   Three forms of this ownership problem:
 
    - **Proving an absence a later slice fills.** Two kinds, and only the first is a contradiction:
      - **Invalidated when the later path lands.** The claim holds only while the thing is absent, so the
@@ -110,15 +109,11 @@ a re-read rather than a run.
      once not.
    - **Breaking callers a later slice owns.** If a change invalidates existing call sites, fixtures or
      tests — a signature, a return shape, sync/async nature, a module contract other code imports — those
-     belong to the slice making the change. mimir 1410 lost a run at seven of ten merged slices this way:
-     `evidence-routing` made `observe_evidence` async and SafeGit-only, sixteen orchestrator and reattach
-     tests called the old contract, and only the dependent `orchestrator-publication` slice owned them.
+     belong to the slice making the change, not a dependent slice.
    - **Moving a repo-wide rule whose inventory another slice owns.** A closed-inventory test — every env
      var documented, every tool in an allowlist, every surface in a list, a budget or a limit — fails the
-     moment your change adds a member, and passes again only when the inventory is updated. mimir 1423
-     merged a slice that read `XDG_CONFIG_HOME` while `docs/configuration.md` and
-     `tests/test_config_docs_complete.py` sat in a later slice; the merged slice could not be repaired,
-     because a merged slice cannot be amended.
+     moment your change adds a member, and passes again only when the inventory is updated. The slice
+     adding the member must own the required inventory updates; a merged slice cannot be amended.
 
    **The trigger is invalidation, not change.** A backward-compatible change needs none of this: a
    defaulted optional parameter, or an added field on a returned object, leaves every existing caller,

package/agents/work-reviewer.md

@@ -36,9 +36,27 @@ Do not delegate, and do not open a fresh repo-wide survey. Keep verification sco
 ## Reconcile claim vs. observation (the core rule)
 
 The producer returns a **claim** (its JSON summary / report). The orchestrator's observed evidence is the **truth**. Your first job is to reconcile them:
-- Claim says files changed / tests passed but the observed evidence disagrees → **REJECT** (`claim_mismatch`).
-- Observed `review_ready` is false (empty diff, unobserved/failed tests, `diff_observed=false`) → **REJECT**.
+- Claim says files changed / tests passed but the observed evidence disagrees → **REJECT**
+  (`claim_mismatch`) — reconciled **against the claim's own subject**. For a build slice the observation
+  is that slice's diff, so its file list must match. For `test-verifier` the observation is the whole
+  **integrated** diff, which legitimately contains every merged builder's files as well as the tests, so
+  extra files there are not a mismatch; what must reconcile is its `tests.exit` against the observed run.
+- **For a build slice or `test-verifier` only:** observed `review_ready` is false (empty diff, unobserved/failed tests, `diff_observed=false`) → **REJECT**.
 - Never approve on the producer's word alone.
+- **Repair evidence substitutes for ordinary evidence where Step 5 permits it.** After a test-only repair,
+  the failed ordinary evidence is deliberately preserved alongside a qualifying repair record, and the
+  repair evidence is what stands. Requiring a green `evidence/test-verifier.json` in that situation rejects
+  the recovery path the workflow defines. Check the repair record and its evidence, not the superseded
+  failure.
+
+**This whole section applies only to subjects that have observed evidence.** A planning subject —
+`spec-writer`, `work-decomposer` — produces an artifact under `.factory/$R/artifacts/`, not a worktree
+commit, so it has no diff and no `evidence/<subject>.json`, and the workflow reviews it with a
+`--review-ref` rather than observing it. Its ground truth is the artifact and the cited files, per
+"Review discipline" above. Never reject a planning subject for missing, empty or not-`review_ready`
+evidence: an empty diff is that subject's correct shape, `review_ready` is false for every zero-diff
+observation by construction, and rejecting on it blocks the step permanently rather than asking the
+producer for anything it could supply.
 
 ## Class-wide completeness (the anti-drip-feed rule)
 
@@ -77,10 +95,18 @@ When the subject is a **class-wide** requirement — one that **cannot be establ
   - Backend: the repo's layering, its projection/read path, its API boundary.
   - Frontend: the repo's component conventions, binding forms, state approach and design tokens.
   - Migrations: the repo's filename, author, context, manifest-registration and permission steps.
-  - No edits to vendored or generated trees. No stray code comments.
+  - No **hand**-edits to vendored or generated trees. Regeneration is different and is required: the
+    slice that changes the source owns regenerating what derives from it, so a regenerated client or
+    type set in that slice's lane is expected output, not a finding.
+  - Code comments follow the target repository's documented policy; do not invent a blanket ban.
   - **Slice discipline:** the diff stays within the slice's `paths` (out-of-lane edits are a finding).
-  - The slice's `acceptance` is actually implemented, and the observed tests cover it.
-- **Test step (`test-verifier`):** each AC maps to a real assertion that would fail if the behavior broke; no test weakened to pass; the observed command is the suite the plan named and was not narrowed to exclude failures, which is a separate finding from weakening a test; observed test run is green (or honestly WRITTEN-NOT-RUN with a reason).
+  - The slice's `acceptance` is actually implemented. This is never waived.
+  - The observed tests cover that acceptance — **unless the slice's ratified `test_plan` is empty**,
+    which the plan decided at Gate 2 and which the workflow and `deriveReviewReady` both honour. A
+    docs-only slice reviewed against tests it was ratified not to have is rejected forever; that
+    exemption is a plan decision, not yours to re-open here. It waives **test execution only**: the
+    acceptance must still be implemented and the diff must still be observed.
+- **Test step (`test-verifier`):** each AC maps to a real assertion that would fail if the behavior broke; no test weakened to pass; the observed command is the suite the plan named and was not narrowed to exclude failures, which is a separate finding from weakening a test; observed test run is green. **There is no WRITTEN-NOT-RUN waiver for this subject:** the stage exists to run the tests, so the evidence must record an observed run that exited zero. Reporting WRITTEN-NOT-RUN honestly is valid; approving on it is not.
 
 ## Security proportionality
 
@@ -88,7 +114,7 @@ The repository's real trust boundaries stay fully blocking: unauthenticated or a
 
 ## Severity
 
-- **BLOCKER** — claim/observation mismatch, `review_ready=false`, an AC unmet or untested, a convention violation a human reviewer would bounce (unguarded prod migration, subtree edit, out-of-lane file), a correctness/security bug.
+- **BLOCKER** — claim/observation mismatch, `review_ready=false` on a subject that has observed evidence, an AC unmet, an AC untested against a non-empty ratified `test_plan`, a convention violation a human reviewer would bounce (unguarded prod migration, subtree edit, out-of-lane file), a correctness/security bug.
 - **MAJOR** — deviates from brief/conventions in a way that will draw review friction; secondary AC untested.
 - **MINOR** — nits; safe to proceed.
 
@@ -126,6 +152,6 @@ Write this structure to the narrative report:
 1. <the specific change the producer must make>
 ```
 
-Cite `path:line` for every finding — an unsourced finding is noise. If it's genuinely clean and the evidence is review-ready, APPROVE without manufacturing problems. If evidence is missing when it should exist (a build slice with no observed diff/tests), that itself is a BLOCKER — do not approve unobserved work.
+Cite `path:line` for every finding — an unsourced finding is noise. If it's genuinely clean and the evidence is review-ready, APPROVE without manufacturing problems. If evidence is missing when it should exist (a build slice with no observed diff/tests), that itself is a BLOCKER — do not approve unobserved work. "When it should exist" excludes a planning subject, which has no observed evidence by design. It does **not** excuse a missing diff for a slice whose ratified `test_plan` is empty: that slice still changes files and is still observed; only its test run is waived.
 
 Your final response may confirm both file writes, but it must not substitute for either file.

package/bin/factory.js

@@ -13,7 +13,7 @@ import { readFileSync } from "node:fs";
 import { nextAction, nextActionRecord, readRun, readRunUnchecked } from "../state/index.js";
 import { transition } from "../state/transition.js";
 import { buildEvidence, deriveReviewReady, EVIDENCE_KEYS, evidenceRef, git, observeAncestry, observeCleanliness, observeTrackedCleanliness, observeWorktree, privilegedPaths, proveInitContainment, resolveWorktree, runBootstrap, unownedPaths } from "../observe/index.js";
-import { assertPublicationReady, assertReviewBinding, observeMergeProof, readEvidence, readReview, readValidatorReview } from "../observe/review.js";
+import { assertPublicationReady, assertReviewBinding, isApproving, observeMergeProof, readEvidence, readReview, readValidatorReview } from "../observe/review.js";
 import { readRepositoryConfig, RepositoryConfigError } from "../observe/repository-config.js";
 import { reverifyRepair } from "../observe/repair-reverification.js";
 import { archiveReviewAttempt } from "../state/review-archive.js";
@@ -26,11 +26,16 @@ import {
   claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SESSION_LOCK_FILE, SessionLockHeldError,
 } from "../state/session-lock.js";
 
+// work-reviewer runs on these and must approve before the step is accepted; the others are not
+// auto-reviewed, so requiring a reference for them would block the workflow's own sequence.
+const REVIEWED_STEPS = Object.freeze(["spec-writer", "work-decomposer", "test-verifier"]);
+
 export const COMMANDS = Object.freeze({
   init: Object.freeze(["--repo", "--branch", "--worktree", "--pr-base", "--issue", "--issue-key", "--publishing-identity", "--mode", "--max-parallel-slices", "--max-retries", "--now", "--json"]),
   status: Object.freeze(["--repo", "--json"]),
   "amend-paths": Object.freeze(["--repo", "--add", "--reason", "--session", "--now", "--json"]),
   resume: Object.freeze(["--repo", "--session", "--now", "--json"]),
+  decide: Object.freeze(["--repo", "--text", "--session", "--now", "--json"]),
   // No --force: `lock <id> steal` is the same operation with a name that says what it
   // does, and two spellings of "take someone else's lock" is one too many.
   lock: Object.freeze(["--repo", "--session", "--branch", "--ttl-ms", "--now", "--json"]),
@@ -645,6 +650,47 @@ const HANDLERS = {
     return emit(flags, { run_id: runId, seeded: next.slices.length, slices: next.slices.map((slice) => slice.id) });
   },
 
+  // Enforcement: publish cumulative decision text separately, then atomically select it in run.json.
+  // A refused transition must not change the artifact the driver was told to read. Unreferenced files
+  // from an interrupted publication are harmless; only operator_decision.artifact is authoritative.
+  async decide([runId], flags) {
+    if (!runId) throw new CliError("factory decide requires <run-id>");
+    if (typeof flags.text !== "string" || !flags.text.trim()) throw new CliError("factory decide requires nonblank --text <decision>");
+    if (typeof flags.session !== "string" || !flags.session.trim()) throw new CliError("factory decide requires nonblank --session <id>");
+    const runDir = runDirFor(flags, runId);
+    const current = readRun(runDir);
+    if (current.status !== "needs-human") {
+      throw new CliError(`factory decide requires current status needs-human; found '${current.status}'`);
+    }
+    const owner = assertFreshSessionOwner(runDir, runId, flags.session, "decide");
+    const at = stamp(flags);
+    if (Date.parse(at) <= Date.parse(current.updated_at)) throw new CliError("decide must move updated_at forwards");
+    const prior = current.operator_decision;
+    const existing = prior ? readFileSync(join(runDir, prior.artifact), "utf8") : "";
+    if (prior && planDigest(Buffer.from(existing)) !== prior.digest) throw new CliError("recorded operator decision does not match its digest");
+    const bytes = Buffer.from(`${existing}${existing ? "\n" : ""}## ${at}\n\n${flags.text.trim()}\n`);
+    const digest = planDigest(bytes);
+    const artifact = join("artifacts", `operator-decisions-${digest.slice(7)}.md`);
+    const absolute = join(runDir, artifact);
+    mkdirSync(dirname(absolute), { recursive: true });
+    if (existsSync(absolute)) {
+      if (!lstatSync(absolute).isFile() || !readFileSync(absolute).equals(bytes)) throw new CliError("operator decision artifact differs from the intended bytes");
+    } else {
+      await writeProtectedFileAtomic(dirname(absolute), basename(absolute), bytes, { createOnly: true });
+    }
+    const next = await transition(runDir, {
+      participants: [{ familyId: "envelope", mode: "decide" }],
+      apply: (state) => {
+        if (!isDeepStrictEqual(state, current)) throw new CliError("run changed while recording the operator decision; retry from current state");
+        return { ...state, updated_at: at, operator_decision: { at, digest, artifact } };
+      },
+      finalGuard: () => {
+        if (!sameSessionOwner(runDir, owner)) throw new CliError("operator decision session ownership changed; current decision was preserved");
+      },
+    });
+    return emit(flags, { run_id: runId, status: next.status, operator_decision: next.operator_decision });
+  },
+
   async ["amend-paths"](positional, flags) {
     if (positional.length !== 2) throw new CliError("factory amend-paths requires exactly <run-id> <slice-id>");
     const [runId, sliceId] = positional;
@@ -976,7 +1022,8 @@ const HANDLERS = {
       // intact in `run.json` -- and `at` is what tells a controller whether "approved" happened a minute
       // ago or three hours ago, which is most of what "is this run stuck" means.
       gates: Object.fromEntries(GATE_NAMES.filter((name) => run.gates[name])
-        .map((name) => [name, { status: run.gates[name].status, at: run.gates[name].at ?? null, artifact: run.gates[name].artifact ?? null }])),
+        .map((name) => [name, { status: run.gates[name].status, at: run.gates[name].at ?? null,
+          artifact: run.gates[name].artifact ?? null, reviewed_head: run.gates[name].reviewed_head ?? null }])),
       // Structured, not `${agent}:${status}(${attempts})`. Attempts are the field a controller reads to
       // decide whether an attempt was consumed, and reaching them meant regexing a display string out of
       // a JSON contract. Nothing in the suite asserted the string form, so it was a public shape with no
@@ -996,6 +1043,8 @@ const HANDLERS = {
       // Both, deliberately. `next_action` is the machine answer; `next` is its rendering, derived from the
       // same record by one formatter so they cannot drift, and kept because the driver contract, the
       // sidebar and a lot of prose name `next: gate:story`.
+      // Identifies the committed decision bytes, not whether the driver applied them.
+      operator_decision: run.operator_decision ?? null,
       next_action: nextActionRecord(run),
       next: nextAction(run),
     });
@@ -1071,6 +1120,12 @@ const HANDLERS = {
             status: decision,
             at: decision === "pending" ? null : at,
             artifact: flags.artifact ?? state.gates[name]?.artifact ?? null,
+            // What this approval judged. The reobserver above already observes the integration head to
+            // prove readiness; recording it is what lets publication tell a fresh approval from a stale
+            // one, which is the whole difference between re-running tests and re-approving.
+            reviewed_head: name === "pre_pr" && decision === "approved"
+              ? integrationHead(repo, state).commit
+              : state.gates[name]?.reviewed_head ?? null,
           },
         },
         ...(name === "brief" ? { plan_digest: briefDigestFor(decision, state, runDir) } : {}),
@@ -1084,6 +1139,38 @@ const HANDLERS = {
     if (!STEP_STATUSES.includes(status)) throw new CliError(`status must be one of ${STEP_STATUSES.join(" | ")}`);
     const runDir = runDirFor(flags, runId);
     assertRunNotParked(runDir, "step");
+    // The reference was stored and never read, so `accepted` was recorded against a missing review file,
+    // a REJECT with blocking fixes, and an approval naming a commit that does not exist -- all three
+    // reproduced through this CLI. That made the enforcement the README claims, and the workflow's
+    // "must APPROVE before you accept that step", instruction rather than fact. A reviewed step now
+    // consumes its review the way a slice does, minus the head binding: a planning subject's output is
+    // an artifact in the control plane, not a commit, so there is no head for the review to name.
+    const priorStep = readRunUnchecked(runDir).run?.steps?.find((step) => step.agent === agent) ?? null;
+    const reviewedRef = flags.reviewRef ?? priorStep?.review_ref ?? null;
+    if (status === "accepted" && REVIEWED_STEPS.includes(agent)) {
+      if (!reviewedRef) throw new CliError(`step '${agent}' cannot be accepted without --review-ref; work-reviewer must approve it first`);
+      const review = readReview(runDir, reviewedRef);
+      if (review.subject !== agent) throw new CliError(`review '${reviewedRef}' approved '${review.subject}', not '${agent}'`);
+      if (!isApproving(review.verdict)) throw new CliError(`review '${reviewedRef}' verdict is ${review.verdict}, not an approval`);
+      // The attempt, or the reference fallback silently re-consumes the previous round's approval: accept
+      // attempt 1, record `running --attempts 2`, then accept again with no `--review-ref` and the stored
+      // attempt-1 review approves attempt 2. Reproduced through the CLI. The fallback stays -- re-passing
+      // an unchanged reference is ordinary -- but it must still be an approval OF THIS attempt.
+      const attempt = flags.attempts === undefined ? priorStep?.attempts ?? 1 : integer(flags.attempts, 1, "--attempts");
+      if (review.attempt !== attempt) {
+        throw new CliError(`review '${reviewedRef}' is for attempt ${review.attempt}, step is at attempt ${attempt}`);
+      }
+      // A planning subject has no commit to bind to, which is why this check omits the head that a slice
+      // merge requires. `test-verifier` is not a planning subject: it judges the integrated branch, so its
+      // review names a commit and that commit must be the head now. Without this it inherited the planning
+      // exemption and a review naming a nonexistent commit was accepted. Caught in review.
+      if (agent === "test-verifier") {
+        const head = integrationHead(resolve(flags.repo ?? process.cwd()), readRun(runDir)).commit;
+        if (review.reviewed_commit !== head) {
+          throw new CliError(`review '${reviewedRef}' approved ${String(review.reviewed_commit).slice(0, 12)} but the integration head is ${String(head).slice(0, 12)}`);
+        }
+      }
+    }
     const at = stamp(flags);
     const next = await transition(runDir, {
       participants: [{ familyId: "steps", mode: "record" }],
@@ -1178,14 +1265,16 @@ const HANDLERS = {
       if (!isDeepStrictEqual(state, current)) throw new CliError("factory resume bootstrap refused: run.json bytes changed while bootstrap ran; current state was preserved");
       if (!sameSessionOwner(runDir, boundOwner)) throw new CliError("factory resume bootstrap refused: factory.lock is absent, stale, or no longer names the same owner; current state and owner were preserved");
     };
+    // Enforcement: never unpark a driver that would keep reading an obsolete staged contract.
+    if (success) await writeProtectedFileAtomic(runDir, "WORKFLOW.md", readFileSync(new URL("../WORKFLOW.md", import.meta.url)));
     const next = await transition(runDir, {
       participants: [{ familyId: "envelope", mode: success ? "resume-needs-human" : "record-bootstrap" }],
-      ...(outcome ? { reobservers: new Map([["envelope", assertBinding]]), finalGuard: ({ state }) => {
+      reobservers: new Map([["envelope", assertBinding]]), finalGuard: ({ state }) => {
         if (!readFileSync(join(runDir, "run.json")).equals(boundRunBytes) || !isDeepStrictEqual(state, current)) {
           throw new CliError("factory resume bootstrap refused: run.json bytes changed while bootstrap ran; current state was preserved");
         }
         if (!sameSessionOwner(runDir, boundOwner)) throw new CliError("factory resume bootstrap refused: factory.lock is absent, stale, or no longer names the same owner; current state and owner were preserved");
-      } } : {}),
+      },
       apply: (state) => ({ ...state, ...(success ? { status: "running" } : {}), updated_at: at,
         ...(outcome ? { bootstrap_command: config.bootstrapCommand, bootstrap_exit: outcome.exit } : {}) }),
     });
@@ -1566,6 +1655,7 @@ function usage() {
   factory init <run-id> [--branch B=feature/<run-id>] [--worktree W=.] [--pr-base TARGET] [--issue KEY] [--mode interactive|headless|autonomous]
   factory status <run-id> [--json]
   factory amend-paths <run-id> <slice-id> --add PATH [--add PATH ...] --reason TEXT --session ID [--now ISO]
+  factory decide <run-id> --text TEXT --session ID [--now ISO]
   factory resume <run-id> --session ID [--now ISO]
   factory reverify-repair <run-id> <repair-record-id> [--repo PATH] [--now ISO] [--json]
   factory lock <run-id> <claim|steal|release> --session ID [--ttl-ms N]

package/core/contracts.js

@@ -10,6 +10,10 @@
 import { isDeepStrictEqual } from "node:util";
 import { GATE_NAMES, GATE_STATUSES, SLICE_STATUSES, STEP_STATUSES, TERMINAL_STATUSES } from "../state/schema.js";
 
+// The steps whose output the plan is derived from. A revision to one of these after seeding would leave
+// the run describing a decomposition its slices were not built from.
+const PLANNING_STEPS = Object.freeze(["spec-writer", "work-decomposer"]);
+
 const TERMINAL_MODES = new Set(["terminalize"]);
 
 // The core hands each contract the observer the caller registered; it does not call it.
@@ -49,11 +53,34 @@ const envelope = contract({
     created_at: state.created_at,
     updated_at: state.updated_at,
     terminal_result: state.terminal_result ?? null,
+    operator_decision: state.operator_decision ?? null,
     bootstrap_command: state.bootstrap_command,
     bootstrap_exit: state.bootstrap_exit,
   }),
   validateTransition: ({ mode, before, after, current, candidate }) => {
     if (before.status === "needs-human") {
+      // Recording an operator decision is the one write a parked run accepts besides amend-paths, and it
+      // touches nothing but the decision itself: the park stands, its reason stands, and resuming stays an
+      // explicit separate act. Answering the question is not the same as deciding to continue.
+      if (mode === "decide") {
+        if (after.status !== "needs-human") throw new Error("decide must preserve parked status");
+        if (!isDeepStrictEqual(after.terminal_result, before.terminal_result)) {
+          throw new Error("decide must preserve terminal_result");
+        }
+        if (isDeepStrictEqual(after.operator_decision, before.operator_decision)) {
+          throw new Error("decide must record a decision");
+        }
+        if (Date.parse(after.updated_at) <= Date.parse(before.updated_at)) {
+          throw new Error("decide must move updated_at forwards");
+        }
+        for (const key of Object.keys(before).filter((key) => !["updated_at", "operator_decision"].includes(key))) {
+          if (!isDeepStrictEqual(before[key], after[key])) throw new Error(`decide cannot change envelope.${key}`);
+        }
+        for (const key of Object.keys(current).filter((key) => !Object.hasOwn(before, key))) {
+          if (!isDeepStrictEqual(current[key], candidate[key])) throw new Error(`decide cannot change run.${key}`);
+        }
+        return;
+      }
       if (mode === "amend-paths") {
         if (after.status !== "needs-human") throw new Error("amend-paths must preserve parked status");
         if (!isDeepStrictEqual(after.terminal_result, before.terminal_result)) {
@@ -88,6 +115,7 @@ const envelope = contract({
       return;
     }
     if (mode === "amend-paths") throw new Error(`amend-paths requires current status needs-human; found '${before.status}'`);
+    if (mode === "decide") throw new Error(`decide requires current status needs-human; found '${before.status}'`);
     if (["resume-needs-human", "record-bootstrap"].includes(mode)) throw new Error(`${mode} requires current status needs-human; found '${before.status}'`);
     // Identity is immutable for the life of a run. Nothing legitimate renames a
     // run, and allowing it would let a transition retarget another run's record.
@@ -194,8 +222,30 @@ const steps = contract({
       }
       if (step.attempts < prior.attempts) throw new Error(`step '${step.agent}' attempts cannot decrease`);
       if (step.attempts > prior.attempts + 1) throw new Error(`step '${step.agent}' attempts cannot skip`);
-      if (prior.status === "accepted" && step.status !== "accepted") {
-        throw new Error(`step '${step.agent}' is already accepted`);
+      // An accepted step was frozen in every direction except accepted -> accepted, so a Gate 2 revision
+      // could record its success and never its rejection: the reviewer's REJECT on the revised artifact
+      // had no legal transition. Reopening is a REVISION, which is narrower than "any raised attempt" --
+      // the first version of this allowed a raised attempt alone, and that reopened settled planning work
+      // after the plan was seeded and reopened steps on completed, blocked and partial runs, none of which
+      // any lifecycle asks for. Caught in review, reproduced through the CLI.
+      // Any departure from the settled row is a revision -- including accepted -> accepted at a higher
+      // attempt, which is what a driver recording only the successful final result produces. Scoping this
+      // to a status change let that path skip every restriction below, on a terminal run included. Exact
+      // same-attempt re-acceptance stays legal, because that is what a resumed driver re-records.
+      const revises = prior.status === "accepted" && (step.status !== "accepted" || step.attempts > prior.attempts);
+      if (revises) {
+        if (step.status !== "accepted" && step.attempts === prior.attempts) {
+          throw new Error(`step '${step.agent}' is already accepted; a revision must raise --attempts`);
+        }
+        if (TERMINAL_STATUSES.includes(candidate.status)) {
+          throw new Error(`step '${step.agent}' cannot reopen on a ${candidate.status} run`);
+        }
+        // A planning revision belongs before the plan is acted on. Once slices are seeded, the decomposition
+        // the step produced is what every slice was derived from, so reopening it here changes nothing that
+        // has already been built and leaves the run describing a plan it did not follow.
+        if (PLANNING_STEPS.includes(step.agent) && (candidate.slices ?? []).length > 0) {
+          throw new Error(`step '${step.agent}' cannot reopen after slices are seeded`);
+        }
       }
       if (!STEP_STATUSES.includes(step.status)) throw new Error(`step '${step.agent}' status is invalid`);
     }

package/observe/review.js

@@ -281,6 +281,23 @@ export function assertPublicationReady({ runDir, state, runId, repo, observeHead
   if (validator && head !== validator.reviewed_head) {
     refuse(`the validator judged ${String(validator.reviewed_head).slice(0, 12)} but the integration head is ${head.slice(0, 12)}`);
   }
+  // Without a validator nothing else binds the approval to a commit, and a single-slice run skips the
+  // validator by design -- so approving Gate 3 at A, committing B and re-observing tests at B published
+  // under the older approval. Reproduced through the CLI. A gate record written before this field existed
+  // cannot be bound and is left to the contract's instruction rather than refused retroactively.
+  const approvedHead = state.gates?.pre_pr?.reviewed_head ?? null;
+  if (!validator && approvedHead && head !== approvedHead) {
+    refuse(`Gate 3 approved ${String(approvedHead).slice(0, 12)} but the integration head is ${head.slice(0, 12)}; re-approve the gate for the current head`);
+  }
+  // Publication read gates, slices, evidence and the validator, and never the step rows -- so a verifier
+  // revision recorded AFTER Gate 3 was approved did not reach it: accept the verifier at attempt 1,
+  // approve the gate, then record a genuine REJECT at attempt 2, and publication still succeeded under
+  // the older approval. Reproduced through the CLI. Permitting verifier revisions is what made this
+  // reachable, so the approval rule has to follow: the verifier's own row must be settled as accepted.
+  const verifier = (state.steps ?? []).find((step) => step.agent === "test-verifier") ?? null;
+  if (verifier && verifier.status !== "accepted") {
+    refuse(`test-verifier is ${verifier.status} at attempt ${verifier.attempts}; accept its resolved revision before publishing`);
+  }
 
   let repair;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",

package/state/schema.js

@@ -15,6 +15,13 @@ export const RUN_KEYS = Object.freeze([
   "version", "run_id", "issue_key", "branch", "worktree", "pr_base", "pr_draft", "created_at", "updated_at",
   "status", "mode", "max_parallel_slices", "max_retries",
   "gates", "steps", "slices", "validator", "terminal_result", "pr_url",
+  // The one channel an operator has into a parked run. `resume` carries no message and every command
+  // that could carry a decision is refused while parked, so a park that asks a question -- a changed
+  // ceiling, a scope call -- could only be answered by editing the issue, which a retained run never
+  // re-reads. The decision is recorded against the run instead, as `{at, digest, artifact}`, and the
+  // digest identifies the recorded bytes; application remains the driver's responsibility. Absent in manifests
+  // written before this field existed, which still read.
+  "operator_decision",
   // Recorded at init from the flag or the environment, never from a checked-in file: the account
   // a run is expected to publish as is a property of where it runs, not of the repository. Absent
   // only in manifests written before 0.8.0, which still read.
@@ -31,7 +38,12 @@ export const MODES = Object.freeze(["interactive", "headless", "autonomous"]);
 
 export const GATE_NAMES = Object.freeze(["story", "brief", "pre_pr"]);
 export const GATE_STATUSES = Object.freeze(["pending", "approved", "changes", "stop"]);
-export const GATE_KEYS = Object.freeze(["status", "at", "artifact"]);
+// `reviewed_head` is the integration head a `pre_pr` approval judged. Without it nothing bound a human
+// approval to a commit, so on a single-slice run -- which skips the validator that carries that binding
+// for multi-slice runs -- approving at A, committing B and re-observing tests at B published under the
+// older approval. Fresh evidence is not fresh approval. Optional, because every other gate has no head
+// to name and a manifest written before this field exists stays valid.
+export const GATE_KEYS = Object.freeze(["status", "at", "artifact", "reviewed_head"]);
 
 export const STEP_STATUSES = Object.freeze(["running", "accepted", "rejected", "blocked"]);
 export const STEP_KEYS = Object.freeze(["agent", "status", "attempts", "review_ref", "evidence_ref"]);
@@ -113,6 +125,14 @@ export function validateRun(run) {
   for (const key of ["branch", "worktree"]) required(errors, run, key, "run");
   for (const key of ["created_at", "updated_at"]) pattern(errors, run, key, ISO, "run");
   for (const key of ["max_parallel_slices", "max_retries"]) positiveInt(errors, run, key, "run");
+  if (run.operator_decision !== null && run.operator_decision !== undefined) {
+    const path = "run.operator_decision";
+    if (object(errors, run.operator_decision, path, ["at", "digest", "artifact"])) {
+      pattern(errors, run.operator_decision, "at", ISO, path);
+      pattern(errors, run.operator_decision, "digest", /^sha256:[0-9a-f]{64}$/u, path);
+      runLocalRef(errors, run.operator_decision, "artifact", path);
+    }
+  }
   for (const key of ["issue_key", "pr_base", "pr_url", "plan_digest", "publishing_identity"]) optionalString(errors, run, key, "run");
   if (Object.hasOwn(run, "pr_draft") && typeof run.pr_draft !== "boolean") {
     errors.push({ path: "run.pr_draft", message: "must be a boolean" });
@@ -143,6 +163,7 @@ function gates(errors, value) {
     if (gate === undefined) continue;
     const path = `run.gates.${name}`;
     if (!object(errors, gate, path, GATE_KEYS)) continue;
+    if (gate.reviewed_head !== null && gate.reviewed_head !== undefined) optionalPattern(errors, gate, "reviewed_head", SHA, path);
     enumValue(errors, gate, "status", GATE_STATUSES, path);
     if (gate.at !== null) optionalPattern(errors, gate, "at", ISO, path);
     if (gate.artifact !== undefined && gate.artifact !== null) optionalString(errors, gate, "artifact", path);