feature-factory 0.8.9 → 0.9.1

package/WORKFLOW.md

@@ -191,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
@@ -203,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.
 
@@ -486,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
 
@@ -592,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.
 
@@ -600,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:
@@ -625,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
@@ -1763,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:
 
@@ -1962,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
@@ -2158,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
 
@@ -45,6 +45,16 @@ introducing a shape the repo does not use.
 
 ## Verify before reporting
 
+Before expanding a class-wide behavioral test matrix, run one representative negative control
+within your slice's owned paths. Change production behavior without changing the tests or preventing
+execution. Confirm the mapped test passes before the mutation, fails on the expected behavioral
+assertion with the mutation, and passes after restoration. A syntax, import, discovery, or unrelated
+failure does not count. Restore the mutation before committing or reporting.
+In your narrative report, name the inventory row, production symbol and mutation, exact test command,
+observed assertion failure, and restoration result. Mark an unperformed control as **not run** with
+the reason; never infer a result. This is diagnostic instruction, not a new claim-schema field or a
+replacement for the ratified test run.
+
 From the worktree, compile and run the narrowest relevant tests:
 Use the repo's own build and test commands, scoped as narrowly as they allow — a compile or
 type-check step, then the specific test class or file you touched, not the full suite. If the
@@ -76,7 +86,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)
@@ -48,6 +48,16 @@ and the repo's agent instructions (`AGENTS.md` or `CLAUDE.md`) name the concrete
 
 ## Verify before reporting
 
+Before expanding a class-wide behavioral test matrix, run one representative negative control
+within your slice's owned paths. Change production behavior without changing the tests or preventing
+execution. Confirm the mapped test passes before the mutation, fails on the expected behavioral
+assertion with the mutation, and passes after restoration. A syntax, import, discovery, or unrelated
+failure does not count. Restore the mutation before committing or reporting.
+In your narrative report, name the inventory row, production symbol and mutation, exact test command,
+observed assertion failure, and restoration result. Mark an unperformed control as **not run** with
+the reason; never infer a result. This is diagnostic instruction, not a new claim-schema field or a
+replacement for the ratified test run.
+
 A fresh worktree may share the main repo's installed dependencies via a link the orchestrator created. If they are missing, run the repo's install command via `bash -c "cd $WT && <install"` once before building.
 
 Use the repo's own build or type-check command, run inside `$WT`.

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/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

@@ -62,6 +62,16 @@ producer for anything it could supply.
 
 When the subject is a **class-wide** requirement — one that **cannot be established by a bounded witness**, so proving it means checking every in-scope member and the set has to be enumerated first. `all`/`every`/`centralize`/`across` and a whole vulnerability or behavior class are the obvious markers, but the words are instances and not the test: an absence ("no module constructs the runtime"), a preserved property ("behaviour remains unchanged") and a global capability ("the installed artifact works") each require checking every member without using any of them, and the rules below are what make such a claim reviewable at all. An existential claim is the opposite and must **not** be treated as class-wide: "a module constructs the runtime" or "the daemon accepts a connection" is settled by one witness, so demanding an exhaustive inventory for it is over-rejection:
 - The spec must carry a finite source→sink inventory with a per-call-site policy, explicit compatibility/exclusion decisions, and mapped tests. A class-wide spec lacking any of these is a **BLOCKER** — reject it as missing targeted research rather than letting an open-ended "apply everywhere" reach builders.
+  For a class-wide behavioral criterion, each inventory row must map to an executable test that
+  invokes the relevant production boundary and asserts its required effect or exclusion. The spec
+  must name that test approach; build review checks its implementation. Shared parameterized tests
+  are valid; separate tests per member are not required.
+  AST references and test names prove enumeration, not behavior.
+- Treat the builder's negative-control report as self-reported diagnostic information,
+  not independent evidence or proof of coverage for every inventory row. Check whether the named
+  mutation tests behavior and the reported failure is the expected behavioral assertion, not a
+  syntax, import, discovery, or unrelated failure. Missing attestation alone is not a blocker;
+  inadequate behavioral coverage is. Do not approve on the attestation alone.
 - On the first review of a class-wide **spec**, enumerate in one pass **every dimension of under-specification** — not just each same-class instance and call site, but every unresolved contract, policy, migration/grant, auth-gating, state, and test seam — and consolidate them all into one `required_fixes` list. A category surfaced in a later round that was discoverable in the first review is a first-pass miss to record once in `required_fixes` and carry forward until observed fixed — it stays blocking (see the precedence rule below), but do not spawn a duplicate finding or a fresh rejection cycle for it.
 - When you reject a class-wide build, make `required_fixes` **exhaustive for the class** as of the current evidence: consolidate every discoverable in-scope same-class instance and affected call site into this review. Do not cite one example while withholding equivalent findings for a later round — drip-feeding one sink per round (each fix triggering the next rejection) is exactly the churn this rule prevents.
 - **Acceptance bar (do not over-reject):** approve a class-wide spec once its inventory is finite, every in-scope sink carries a decided policy, and every row maps to a test — even if some contracts could be specified in more depth. A deferral or exclusion is legitimate **only when the approved story or scope authorizes it**; never waive, defer, or leave undecided an in-scope sink that falls under an `all`/`every`/`across` criterion. A **bounded residual** may be left to build-time remediation only when it is mechanical implementation detail whose behavior, compatibility, security, auth-gating, migration, and state policy are already decided in the brief — an unresolved behavioral or design decision is not a residual and must be decided before approval, never shipped to builders as an open choice. Reject only for a genuinely missing sink, policy, compatibility decision, or test, not for achievable-but-absent depth.
@@ -98,7 +108,7 @@ When the subject is a **class-wide** requirement — one that **cannot be establ
   - 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.
+  - 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. This is never waived.
   - The observed tests cover that acceptance — **unless the slice's ratified `test_plan` is empty**,

package/bin/factory.js

@@ -35,6 +35,7 @@ export const COMMANDS = Object.freeze({
   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"]),
@@ -649,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;
@@ -1001,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),
     });
@@ -1221,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 } : {}) }),
     });
@@ -1609,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

@@ -53,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)) {
@@ -92,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "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.
@@ -118,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" });