feature-factory 0.8.7 → 0.8.9

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
@@ -299,8 +306,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
@@ -1171,8 +1180,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 +1416,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 +1431,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 +1444,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 +1736,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`.

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-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.
+  - No stray code comments.
   - **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

@@ -10,10 +10,10 @@ import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { readFileSync } from "node:fs";
-import { nextAction, readRun, readRunUnchecked } from "../state/index.js";
+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,6 +26,10 @@ 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"]),
@@ -972,12 +976,32 @@ const HANDLERS = {
       pr_draft: run.pr_draft ?? true,
       lock: lock.state, dead_lock: run.status === "running" && lock.state === "stale",
       lock_session: lock.owner?.session ?? null,
-      gates: Object.fromEntries(GATE_NAMES.filter((name) => run.gates[name]).map((name) => [name, run.gates[name].status])),
-      steps: run.steps.map((step) => `${step.agent}:${step.status}(${step.attempts})`),
-      slices: run.slices.map((slice) => `${slice.id}:${slice.status}(${slice.attempts})`),
-      validator: run.validator?.verdict ?? null,
+      // The whole gate record, not just its status. `at` and `artifact` were dropped here while sitting
+      // 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, 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
+      // coverage -- which is how a rendering artifact survived in a machine-readable payload. The content
+      // is unchanged; only the shape is. Breaking for anyone parsing the strings, which is safe here
+      // because an exact-match `FACTORY_VERSION` pin already forces consumers to move deliberately.
+      steps: run.steps.map((step) => ({ agent: step.agent, status: step.status, attempts: step.attempts })),
+      slices: run.slices.map((slice) => ({ id: slice.id, status: slice.status, attempts: slice.attempts })),
+      // Same narrowing: the record carries `report`, `reviewed_head` and `loops`, and only the verdict
+      // came out. `loops` says whether validation is converging; `reviewed_head` says what it judged.
+      validator: run.validator
+        ? { verdict: run.validator.verdict, report: run.validator.report ?? null,
+            reviewed_head: run.validator.reviewed_head ?? null, loops: run.validator.loops ?? null }
+        : null,
       pr_url: run.pr_url,
       terminal_result: run.terminal_result,
+      // 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`.
+      next_action: nextActionRecord(run),
       next: nextAction(run),
     });
   },
@@ -1052,6 +1076,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) } : {}),
@@ -1065,6 +1095,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" }],
@@ -1172,7 +1234,8 @@ const HANDLERS = {
     });
     if (outcome?.refusal) throw new CliError(`${outcome.refusal}; run remains needs-human and its historical terminal result is preserved`);
     return emit(flags, {
-      run_id: runId, status: next.status, terminal_result: next.terminal_result, next: nextAction(next),
+      run_id: runId, status: next.status, terminal_result: next.terminal_result,
+      next_action: nextActionRecord(next), next: nextAction(next),
     });
   },
 };

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.
@@ -194,8 +198,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.7",
+  "version": "0.8.9",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",

package/state/index.js

@@ -28,11 +28,11 @@ export function readRunUnchecked(runDir) {
 
 function nextSliceAction(slices) {
   const blockedSlice = slices.find((slice) => slice.status === "blocked");
-  if (blockedSlice) return `blocked-slice:${blockedSlice.id}`;
+  if (blockedSlice) return { kind: "blocked-slice", subject: blockedSlice.id };
   const activeSlice = slices.find((slice) => ["running", "review"].includes(slice.status));
-  if (activeSlice) return `observe-slice:${activeSlice.id}`;
+  if (activeSlice) return { kind: "observe-slice", subject: activeSlice.id };
   const pendingSlice = slices.find((slice) => slice.status === "pending");
-  return pendingSlice ? `dispatch-slice:${pendingSlice.id}` : undefined;
+  return pendingSlice ? { kind: "dispatch-slice", subject: pendingSlice.id } : undefined;
 }
 
 // The single answer to "what happens next". Both `factory status` and the opencode
@@ -42,23 +42,35 @@ function nextSliceAction(slices) {
 // Resume: the first thing a returning session needs to know. Preserves the inherited
 // rules: a pending gate re-presents, a running slice re-observes, an
 // unaccepted step re-runs.
-export function nextAction(run) {
-  if (["completed", "partial", "blocked"].includes(run.status)) return `terminal:${run.status}`;
+// `{kind, subject}`, because the answer is two facts and a consumer that must split a string on `:` to
+// recover them is parsing a rendering. `subject` is null for the kinds that name no target.
+export function nextActionRecord(run) {
+  if (["completed", "partial", "blocked"].includes(run.status)) return { kind: "terminal", subject: run.status };
   const openStep = run.steps.find((step) => step.status !== "accepted");
+  const stepAction = openStep ? { kind: "step", subject: openStep.agent } : null;
   const sliceAction = nextSliceAction(run.slices);
   for (const name of GATE_NAMES) {
     const gate = run.gates[name];
     // `pending` waits on a human; absent means the phase has not been reached, which is
     // still not "done". But naming an absent gate while an agent is mid-round reads as
     // "waiting on you" — so existing slice or step work is named instead.
-    if (gate === undefined) return sliceAction ?? (openStep ? `step:${openStep.agent}` : `gate:${name}`);
-    if (gate.status === "pending") return `gate:${name}`;
-    if (gate.status === "stop") return `stopped-at-gate:${name}`;
-    if (gate.status === "changes") return `changes-at-gate:${name}`;
-    if (name === "brief" && gate.status === "approved" && run.slices.length === 0) return "seed-slices";
+    if (gate === undefined) return sliceAction ?? stepAction ?? { kind: "gate", subject: name };
+    if (gate.status === "pending") return { kind: "gate", subject: name };
+    if (gate.status === "stop") return { kind: "stopped-at-gate", subject: name };
+    if (gate.status === "changes") return { kind: "changes-at-gate", subject: name };
+    if (name === "brief" && gate.status === "approved" && run.slices.length === 0) return { kind: "seed-slices", subject: null };
   }
   if (sliceAction) return sliceAction;
-  if (openStep) return `step:${openStep.agent}`;
-  if (!run.pr_url) return "pr";
-  return "complete";
+  if (stepAction) return stepAction;
+  if (!run.pr_url) return { kind: "pr", subject: null };
+  return { kind: "complete", subject: null };
+}
+
+// The string form is DERIVED from the record rather than computed beside it, so the two cannot disagree.
+// Retained because the driver contract, the sidebar and a great deal of prose all name `next: gate:story`,
+// and because a human-facing label is a fair thing for a CLI to keep -- as long as it is a projection of
+// the structured answer and not a second implementation of it.
+export function nextAction(run) {
+  const { kind, subject } = nextActionRecord(run);
+  return subject === null ? kind : `${kind}:${subject}`;
 }

package/state/schema.js

@@ -31,7 +31,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"]);
@@ -143,6 +148,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);