@garygentry/feature-forge 0.3.1 → 0.3.4

package/adapters/claude/skills/forge-guide/references/forge-config-schema.json

@@ -67,6 +67,12 @@
       "default": true,
       "description": "When true (default), the /feature-forge:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
     },
+    "docsStage": {
+      "type": "string",
+      "enum": ["prompt", "skip"],
+      "default": "prompt",
+      "description": "How forge-6-docs' Documentation Decision Gate behaves at stage entry. \"prompt\" (default) asks generate-vs-skip once per run; \"skip\" records the stage as deliberately skipped with no prompt — the skill runs the state-skip verb and closes the pipeline honestly (stage-exit --outcome skipped), so docs are never implied-mandatory for teams that document differently. The gate's refuse-to-erase guard still applies: docs that already exist are never silently reclassified, whatever this is set to. Read directly by forge-6-docs (not part of loopRunner resolution); an unrecognized or absent value behaves as \"prompt\"."
+    },
     "autoVerify": {
       "type": "boolean",
       "default": false,
@@ -75,7 +81,7 @@
     "autoVerifyStages": {
       "type": "object",
       "default": {},
-      "description": "Per-stage overrides for autoVerify. Maps a production stage id to a boolean; the effective value for a stage is autoVerifyStages[stage] if present, else autoVerify. Keys are constrained to the five verify-capable stages so a typo (e.g. 'forge-1-prod') is a schema error, not a silent no-op. forge-6-docs has no verify step and is not a valid key.",
+      "description": "Per-stage overrides for autoVerify. Maps a production stage id to a boolean; the effective value for a stage is autoVerifyStages[stage] if present, else autoVerify. Keys are constrained to the five verify-capable stages, so a typo (e.g. 'forge-1-prod') is reported as an ignored key rather than silently taking no effect. It does not fail the command. forge-6-docs has no verify step and is not a valid key.",
       "propertyNames": {
         "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop"]
       },
@@ -195,6 +201,18 @@
           "default": "",
           "description": "Project-default coding agent id, so a project can fix its agent once without specifying it every run. Empty string ⇒ no project default (the runner's own default — claude-cli for rauf — applies, behaving exactly as today). Overridden by the per-run agent selector (run > project precedence, resolved inside forge before the single --agent is emitted). Ignored when agentArgument is absent."
         },
+        "agentMode": {
+          "type": "string",
+          "enum": ["prompt", "auto"],
+          "default": "prompt",
+          "description": "Gates forge-5's Step 2d agent AskUserQuestion. \"prompt\" (default) presents the agent question — byte-identical to today. \"auto\" suppresses ONLY the interactive pick: the agent resolves from defaultAgent (or the runner default when unset), and the availability probe, the verdict classification (UNKNOWN hard-reject before side-effects / UNAVAILABLE proceed-or-choose / probe-failure handling), and the Claude-alias model guard ALL still run; the resolved 'Agent: {id} (source: …)' confirmation line still shows, so the choice is never hidden. Meaningless when agentArgument is absent/empty — that capability gate already removes the entire agent surface, and this field adds no second gate. An unrecognized value behaves as \"prompt\"."
+        },
+        "reviewMode": {
+          "type": "string",
+          "enum": ["prompt", "always", "never"],
+          "default": "prompt",
+          "description": "Gates forge-5's Step 2d Run-mode AskUserQuestion (rauf only — ignored when name != \"rauf\", where no Run-mode question exists). \"prompt\" (default) surfaces the question with the review pass pre-selected — byte-identical to today. \"always\" skips the question and appends --review unconditionally; the rendered command in the confirmation still shows --review, so the choice is never hidden. \"never\" skips the question and launches the bare rendered command. Under \"always\"/\"never\", a NARROWER situational retry-blocked question still surfaces when — and only when — the backlog has blocked items (the --review decision itself is fixed by the mode and never re-asked); with no blocked items the launch is prompt-free. An unrecognized value behaves as \"prompt\"."
+        },
         "preconditionFile": {
           "type": "string",
           "default": ".rauf.json",

package/adapters/claude/skills/forge-guide/references/ralph-loop-contract.md

@@ -58,9 +58,12 @@ defined authoritatively in rauf's
 > item aside and **keeps working other runnable items to completion** (rauf:
 > `runner.ts` needs_human handler). So a supervising session can surface those
 > events live (visibility) and cancel early, but it cannot inject an answer and
-> resume the set-aside item mid-run — resolution is a follow-up retry pass. A
-> first-class pause/resume-with-answer capability is a desirable runner
-> enhancement (see `plans/rauf-enhancement-recommendations.md`).
+> resume the set-aside item mid-run — resolution is the **Post-Run Recovery
+> Procedure** (`skills/forge-5-loop/references/recovery-procedure.md`): record the
+> answer via `decision-record` at the moment of collection, then drive recovery
+> from the record after the run ends. A first-class pause/resume-with-answer
+> capability is a desirable runner enhancement (see
+> `plans/rauf-enhancement-recommendations.md`).
 
 ## rauf is the default and reference implementation
 

package/adapters/claude/skills/forge-guide/references/shared-conventions.md

@@ -36,7 +36,7 @@ I found that the codebase uses React and TanStack Router.
 
 ### Decision Support: Help the User Choose
 
-When an `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
+When a question posed through `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
 
 - **Lead with a recommended option.** Place it first and label it `(recommended)` (matching the `AskUserQuestion` "(Recommended)" convention).
 - **Put the trade-off in each option's `description`.** Say why you'd pick it and what you give up versus the alternatives — the cost, not just the benefit.
@@ -53,6 +53,17 @@ For genuinely comparable artifacts (competing module structures, two code snippe
 
 The **Branch Setup** block below is the reference pattern: a strong recommendation as the first option, rationale inline, the alternative still available, never a hard-stop.
 
+## Stage Review Gate
+
+Every authoring stage ends its "Review with User" step in exactly one of two shapes. Which shape a stage uses is declared **here, once** — each stage's review step points at this block by title, and the shape is never re-derived from the surrounding prose or inferred from how sibling stages behave (three stages block and one does not; majority-shape inference is precisely the failure this block exists to prevent):
+
+- **Blocking review (gate).** The stage presents the artifact and collects feedback through `AskUserQuestion`; it does **not** proceed until the user answers, iterating until they confirm. Stages: **forge-1-prd** (Step 5), **forge-2-tech** (Step 6), **forge-3-specs** (Step 6).
+- **Non-blocking review (invitation).** The stage states the artifact is ready and invites adjustments **as a statement, not a question** — and then **proceeds to the next step in the same turn unless the user asks for changes**. The invitation obliges the agent to *continue*: emitting the invitation sentence and stopping treats the non-gate as a gate and strands the stage `in-progress` with its completion step unrun — a defect, not caution. Stage: **forge-4-backlog** (Step 6).
+
+**Why the shapes differ.** A blocking review guards an artifact whose content was just authored from open-ended interview or synthesis — the user is the only authority on "complete", so the stage must wait. forge-4's backlog is *derived* from specs the user already approved, was planned interactively in its Step 3, and is machine-validated in its Step 5; a second hard gate would re-ask a settled question, and the loop never launches without forge-5-loop's own Step 2d confirmation anyway. The invitation is a courtesy checkpoint, not an approval gate (removed deliberately in #78's consistency sweep).
+
+A stage that changes shape changes it **in this block first**; the per-stage pointer stays a pointer.
+
 ## Configuration Reading
 
 Read `forge.config.json` from the project root. If it doesn't exist, use defaults.
@@ -130,7 +141,7 @@ mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
 ```
 
-If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
+If the host is Claude (the Claude-native question tool is available), also ensure the Claude-framed variant:
 
 ```bash
 R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
@@ -191,6 +202,44 @@ Pipeline state is written by the `state-*` verbs of `scripts/forge-session.py`
 
 If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbatim, do **not** proceed to the next step of the surrounding protocol, and do **not** hand-author the JSON as a workaround. The stage remains resumable because the entry stamp is already on disk — re-run the verb once the cause is fixed.
 
+**The nine `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-skip` (the deliberate forge-6-docs documentation skip — scoped to that one stage; writes `status: "skipped"` + `skippedAt`, refuses to erase a record of docs that exist, and is the only sanctioned writer of a skipped docs stage), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
+
+### `state-verify` — verification results and provenance
+
+`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may additionally carry `--findings-file` + `--findings-count` together for an **advisory-only** report (`inconsistency`/`improvement` findings only, per forge-verify's severity floor) — the stage resolves without a fix round and the report stays attached:
+
+**`auto-verify-pending` is not a skill-facing status.** It is written by `stage-exit`'s scheduling boundary, which records the debt automatically when auto-verify is effective for a stage. The value is accepted on this CLI so the entry stays inspectable and repairable, not so a skill can hand-schedule verification: no skill body and no reference passes it, and none should. Every other status in the list is the recorded *result* of a verification that ran (or was explicitly skipped); this one records that one was *owed*.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{served-production-stage}" --status "<status>" \
+  --specs-dir "{specsDir}"
+```
+
+Provenance follows the same two-commit sequence as `state-complete`: the result transition above writes `commitHash: null`, Commit 1 records the findings document and the state, and a second `state-verify` call records the full 40-hex hash of Commit 1 and touches nothing else (never `--amend`; an abbreviated hash is refused rather than expanded). Add `--epic "{epic}"` for an epic member — required, per the member rule above:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{served-production-stage}" \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
+Epic-scoped verification is the single exception to the member rule: with `--stage forge-0-epic`, `--feature` names the **epic** and `--epic` must be absent or exactly equal to it. That call writes `{specsDir}/{epic}/.epic-state.json` and never a member's `.pipeline-state.json`, and its freshness version is the epic manifest's `revision`, never a member's stage version:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{epic}" --stage forge-0-epic --status "<status>" \
+  --specs-dir "{specsDir}"
+```
+
+On exit 2 the verification result is **not** recorded: surface the `Error:` line verbatim, name the feature (and epic), and do not claim the verification was persisted or advance past it.
+
 ### Staleness Detection (Read-Time)
 
 When loading upstream artifacts as prerequisites, check `basedOnVersions` in the pipeline state for this stage. If any upstream stage's current version is newer than the version recorded in `basedOnVersions`, warn the user before proceeding:
@@ -199,6 +248,31 @@ When loading upstream artifacts as prerequisites, check `basedOnVersions` in the
 
 Frame the choice with its cost: re-running re-derives this stage from the current upstream (safest, but discards any hand-edits to this stage's artifacts); proceeding stale is faster but risks baking outdated assumptions into everything downstream. Recommend re-running unless the user knows the upstream change doesn't affect this stage.
 
+## Immediate Downstream Note (Parking Lot)
+
+When an interview raises a concern that belongs to a *later stage of this same feature*, acknowledge it and persist it **immediately, at the moment it is raised** — not at stage closure — by running `state-note` with a concise one-line statement of the concern. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol above; omitting it for a member is an error and must never be allowed to fall back to a same-named flat feature.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-note \
+  --feature "{feature}" --note "<concise downstream concern>" \
+  --specs-dir "{specsDir}"
+```
+
+`state-note` **overwrites** the single top-level `notes` string — it does not append. To preserve an earlier note, read the current `notes` value out of the feature's `.pipeline-state.json` first and pass one combined concise string in a single `--note`; never edit or round-trip the JSON by hand. This interview-time call is separate from the optional completion note offered at stage closure and must not be deferred until then — a session that ends before closure would otherwise lose the concern entirely.
+
+On `UsageError`/exit 2, surface the `Error:` line verbatim together with the named feature (and epic) and the recovery instruction, and **stop claiming the concern was recorded** — it was not. Epic *decomposition* changes are not notes: they go through `state-ecr` into `epicChangeRequests`, never into `notes`.
+
+## Verify Capability
+
+Skills that close a stage pass `--verify-capability interactive|manual` to `stage-exit`. The full determination rule, the Standard Verify Gate, and the recovery path live in `references/stage-exit-protocol.md`; the two facts that are most often gotten wrong:
+
+- **Dispatch capability is *permitted* dispatch, not a listed tool.** The question is "**may I dispatch `forge-verifier` right now**", not "is a subagent-dispatch tool in my tool surface". A session can carry a standing host instruction against dispatching subagents unless the user asked; such instructions are injected by the harness, sit outside this project's control, and outrank skill prose. Classify on permission, up front.
+- **A consent requirement is `interactive`, not `manual`.** When dispatch is barred only *unless the user asked* and a question mechanism is available, pass `interactive`: the gate's own affirmative choice supplies the missing user request. Pass `manual` only when there is **no** question mechanism **and** **no** permitted dispatch.
+
+A bar on unsolicited dispatch is never grounds to skip verification, and never grounds to fence the production successor while verification is unresolved. On the `runInStageVerify: true` path the emitted `verifyGate` stays `none`: reuse the Standard Verify Gate block for consent with **choice 2 omitted** (auto-verify is already effective, so "enable auto-verify going forward" is a no-op), leaving exactly two choices: *Verify now* (recommended) and *Skip for now*. The clean-room `forge-verifier` is **dispatched on the affirmative choice**, never merely printed for the user to run later; *Skip for now* is persisted as an explicit `skipped` before any advancing block.
+
 ## Branch Setup
 
 Invoke this block at the **very start** of a pipeline entry point — `forge-1-prd` (standalone feature) and `forge-0-epic` (epic) — **before** any directory resolution or interview, so the rest of the run lands on the intended branch. `{label}` is the feature name (forge-1-prd) or epic name (forge-0-epic); `{scope}` is `feature` or `epic` correspondingly.
@@ -332,7 +406,7 @@ Invoke this block **at the head of any post-entry step that writes a stage artif
 
 1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
 
-2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same warning via `AskUserQuestion` ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
 
 When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
 

package/adapters/claude/skills/forge-verify/SKILL.md

@@ -2,7 +2,7 @@
 # GENERATED — DO NOT EDIT. Source: skills/forge-verify/SKILL.md. Regenerate: python3 scripts/build-adapters.py
 name: forge-verify
 description: Verify forge pipeline artifacts for completeness, consistency, and quality. Use when user runs /feature-forge:forge-verify or asks to check forge specs, backlog, or implementation for gaps. Do NOT trigger for general code review, quality checks, or verification tasks outside the forge pipeline.
-argument-hint: '<feature-name> [stage: prd|tech|specs|backlog|impl] [--require-clean]'
+argument-hint: '<feature-name> [stage: prd|tech|specs|backlog|impl] [--served-stage <production-stage>] [--require-clean]'
 ---
 
 # forge-verify — Verification Gate
@@ -30,7 +30,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 - **Small modes (prd 15, tech 17): single verifier.** Use the Agent tool once with
   `subagent_type="forge-verifier"`, passing the feature name and mode. It runs all
   checks and returns findings.
-- **Large modes (specs 38, backlog 27, impl 23): parallel dimensioned fan-out.**
+- **Large modes (specs 39, backlog 29, impl 25): parallel dimensioned fan-out.**
   Split the mode's checklist into **dimension groups** and dispatch **one
   `forge-verifier` per group, in parallel — a single message with multiple Agent
   calls** (the `superpowers:dispatching-parallel-agents` pattern). Each instance owns a
@@ -38,14 +38,14 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
   run concurrently. Suggested groups (map to the category clusters in that mode's own
   checklist file):
   - **specs** (`references/verification-checklists/specs.md`): (1) types/contracts,
-    (2) architecture/layout, (3) cross-reference &
-    traceability, (4) testing strategy, (5) integration.
+    (2) architecture/layout, (3) cross-reference & traceability (owns CHECK-S39),
+    (4) testing strategy, (5) integration.
   - **backlog** (`references/verification-checklists/backlog.md`): (1) item scoping &
     acceptance criteria, (2) dependency/ordering sanity,
-    (3) spec coverage & traceability, (4) schema/enum correctness.
-  - **impl** (`references/verification-checklists/impl.md`): (1) requirement coverage vs specs, (2) integration correctness,
-    (3) testing, (4) code-quality/conventions, (5) runnability (owns CHECK-I21/I22 —
-    the smoke command and the non-test-caller heuristic).
+    (3) spec coverage & traceability (owns CHECK-B29), (4) schema/enum correctness.
+  - **impl** (`references/verification-checklists/impl.md`): (1) requirement coverage vs specs (owns CHECK-I24/I25),
+    (2) integration correctness, (3) testing, (4) code-quality/conventions,
+    (5) runnability (owns CHECK-I21/I22 — the smoke command and the non-test-caller heuristic).
 
   In each parallel instance's prompt, pass: the feature, the mode, the **dimension
   label**, the **exact CHECK-IDs it owns**, and a note that **it is one of several
@@ -56,8 +56,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 
 ### Synthesize (parent session)
 
-The verifier(s) are read-only — they return findings as their response; **you** (the
-parent) assemble and write the single document to
+The verifier(s) are read-only — they return findings as their response. **Gate every return first** through "Truncated Verifier Returns" in `references/findings-template.md`: a return without the report structure is a dropped digest (issue #183) — resume the agent via `SendMessage` (or re-dispatch), and never synthesize, write a document, or record a verify result from a truncated return. Then **you** (the parent) assemble and write the single document to
 `{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. When you fanned out:
 1. Concatenate all instances' findings and **renumber `V-NNN` IDs uniquely** across the
    merged set.
@@ -100,7 +99,7 @@ any work:
 > `CLEAN_ROOM_UNAVAILABLE: forge-verifier subagent not dispatchable — verify not run.`
 
 Do not analyze artifacts, do not write a findings document, and do not touch pipeline
-state. The navigator detects this sentinel and degrades to its manual verify gate (Tier
+state. This is an **operational failure, not a user skip** — close through Step 7 with `--outcome failed`; as a nested owner that call writes no state and prints no terminal block, so the sentinel is your structured result. The navigator detects this sentinel and degrades to its manual verify gate (Tier
 2/3), so verify state stays outstanding and the stage is never marked verified on false
 assurance. **Manual / interactive invocation** (the normal `/feature-forge:forge-verify`
 path, no require-clean signal) keeps the inline fallback above unchanged.
@@ -111,6 +110,8 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 
 Resolve the feature directory via the **Feature Directory Resolution** block in `references/shared-conventions.md` (so a standalone feature resolves to its flat `{specsDir}/{feature}/` path exactly as today, and an epic member resolves to its nested `{specsDir}/{epic}/{feature}/` path). Use the resulting `{resolvedFeatureDir}` everywhere this skill reads or writes a per-feature artifact or state file — the `{specsDir}/{feature}/…` forms below are shorthand for the resolved path, not a literal flat layout. This does not apply to **epic mode**, whose paths are epic-scoped (`{specsDir}/{epic}/…`) by design.
 
+Determine branch ownership **at entry**, from the literal `owner: nested` / `owner: direct` token in the dispatching prompt (absent the token you are `direct`), and preserve that value unchanged through any re-verify — see Step 7, which passes it through as `--owner`.
+
 **Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Read Configuration and Determine Mode
@@ -119,7 +120,9 @@ Read `{resolvedFeatureDir}/.pipeline-state.json` to understand current pipeline
 
 ### Mode Selection
 
-If a stage is specified as a second argument (e.g., `/feature-forge:forge-verify auth specs`), use that mode. Otherwise, auto-detect based on pipeline state:
+An explicit `--served-stage <production-stage>` argument on this invocation is authoritative — it is what the scripted exit and forge-fix pass when they route back here (the fix rejoin fences `/feature-forge:forge-verify {feature} --served-stage {stage}`). Map it to the mode directly (`forge-0-epic`→epic, `forge-1-prd`→prd, `forge-2-tech`→tech, `forge-3-specs`→specs, `forge-4-backlog`→backlog, `forge-5-loop`→impl) and skip auto-detection.
+
+Otherwise, if a stage is specified as a second argument (e.g., `/feature-forge:forge-verify auth specs`), use that mode. Otherwise, auto-detect based on pipeline state:
 
 - **epic mode**: Explicit via `/feature-forge:forge-verify {epic} epic`, or auto-detected when the named argument resolves to an **epic directory** — i.e. `{specsDir}/{name}/epic-manifest.json` exists (an epic root holds `epic-manifest.json` but no `.pipeline-state.json` of its own). When the argument is an epic, prefer epic mode over feature-mode resolution.
 - **prd mode**: If `forge-1-prd` is complete but `forge-verify-prd` is not `passed` or `findings-applied`
@@ -128,7 +131,7 @@ If a stage is specified as a second argument (e.g., `/feature-forge:forge-verify
 - **backlog mode**: If `forge-4-backlog` is complete but `forge-verify-backlog` is not `passed` or `findings-applied`
 - **impl mode**: If user explicitly requests or if implementation code exists for this feature
 
-If ambiguous, use `AskUserQuestion` to ask which stage to verify.
+If ambiguous, use `AskUserQuestion` to ask which stage to verify — **before any write**. Serialize the resolved mode as `--verify-mode` at Step 7: that mode, never conversational context and never `currentStage`, determines the served production stage.
 
 ## Step 2: Load All Relevant Artifacts
 
@@ -163,9 +166,9 @@ Load into context ALL artifacts for this feature based on mode:
 
 ## Step 3: Run Verification Checklists
 
-Read `references/verification-checklists/{mode}.md` for the detailed checklist for the mode being verified — one of `references/verification-checklists/prd.md`, `references/verification-checklists/tech.md`, `references/verification-checklists/specs.md`, `references/verification-checklists/backlog.md`, `references/verification-checklists/impl.md`, `references/verification-checklists/epic.md`. Read only that mode's file. Execute every check. Do not skip checks because things "look fine." The orchestrator-only **Findings Document Template (Step 4)**, worked **Example Findings (Step 4)**, and **Epic Mode State Write Detail (Step 6)** sections live in `references/findings-template.md`, read later by the parent role at Steps 4/6.
+Read `references/verification-checklists/{mode}.md` for the detailed checklist for the mode being verified — one of `references/verification-checklists/prd.md`, `references/verification-checklists/tech.md`, `references/verification-checklists/specs.md`, `references/verification-checklists/backlog.md`, `references/verification-checklists/impl.md`, `references/verification-checklists/epic.md`. Read only that mode's file. Execute every check. Do not skip checks because things "look fine." **Exception — a re-verify is scoped, not a fresh sweep:** when the served stage's verify entry is `findings-applied`, follow "Re-verify scope and convergence" in `references/stage-exit-protocol.md` — confirm the prior report's findings against their acceptance evidence and examine the fix's own delta; only an unresolved prior finding or a new blocking defect the fix itself introduced may block, every other observation is advisory, and a finding with a recorded decision is never re-filed. The orchestrator-only **Findings Document Template (Step 4)**, worked **Example Findings (Step 4)**, and **Epic Mode State Write Detail (Step 6)** sections live in `references/findings-template.md`, read later by the parent role at Steps 4/6.
 
-Each check in that mode checklist has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: 15 checks, tech: 17 checks, specs: 38 checks, backlog: 27 checks, impl: 23 checks, epic: 10 checks), you likely skipped checks — go back and complete them.
+Each check in that mode checklist has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: 15 checks, tech: 17 checks, specs: 39 checks, backlog: 29 checks, impl: 25 checks, epic: 10 checks), you likely skipped checks — go back and complete them.
 
 **Epic mode dispatch.** Epic mode is a small (10-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the Agent tool, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E10 from the `## Epic Mode Checklist` in `references/verification-checklists/epic.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07, E09, and E10 are verifier judgment) and returns its findings.
 
@@ -176,7 +179,13 @@ GOOD finding: "PRD.md REQ-ERR-04 requires rate limit retry behavior, but spec 03
 
 Every finding must include:
 1. A unique ID (V-001, V-002, etc.)
-2. Severity: `gap` (missing requirement coverage), `inconsistency` (contradictory specs), `improvement` (not wrong but could be better), `error` (factually incorrect)
+2. Severity: `gap` (missing requirement coverage), `inconsistency` (contradictory specs), `improvement` (not wrong but could be better), `error` (factually incorrect **with a behavioral, CLI-output, or decision-bearing consequence**)
+
+   **Severity floor (anti-churn).** An inaccuracy confined to comments, docstrings, or test narration — prose no runtime path executes and no decision consumes — caps at `inconsistency`, never `error`. It is worth recording, but a wrong sentence beside correct code does not block a stage the way wrong behavior does. **Routing consequence:** `error` and `gap` are the two **blocking** severities; `inconsistency` and `improvement` are **advisory**. A report with at least one blocking finding records `findings-reported` and routes to forge-fix. A report whose findings are all advisory records `passed` **with the report still attached** (Step 6) and the pipeline advances — an advisory-only report never fences a fix round. A **meta-guard** (a test protecting other tests or prose) is judged against its declared protection set: guard-incompleteness against a declared non-goal is never a finding (`references/stage-exit-protocol.md` § Re-verify scope).
+
+   **A checklist item with no PRD position behind it is a PRD gap, not a design to invent.** Several checks are deliberately conditional — `CHECK-S27` ("Concurrent access scenarios are addressed **if relevant**") is the clearest, and the same shape appears for performance, observability, and security checks that defer to the PRD. When such a check fires and the PRD takes **no position** on the concern, the finding is that the *requirements* are silent. Report it as an `improvement` (or a `gap` against the PRD, in `prd` mode) whose suggested fix is to **record the position** — including "out of scope, single writer assumed", which is a complete answer. Do **not** specify a mechanism to satisfy the check: a verifier that answers an open requirements question by designing a protocol converts a one-sentence PRD amendment into a foundational change that no requirement asked for, at the stage where it is least visible. Precedent both ways: `epic-orchestration` V-008 raised `CHECK-S27` against a PRD that *had* scoped concurrency out and correctly cost one sentence at `improvement`; `stage-exit-coverage` V-006 raised the same check against a silent PRD, was filed as a `gap`, and induced a full locking protocol that was later removed. For **forge state writes** specifically, the standing owner decision is recorded in `references/decisions/single-writer-threat-model.md` (issue #180): single writer assumed, detection-not-locking — answer `CHECK-S27` by citing it (or the per-feature requirement restating it), never by designing a mechanism.
+
+   Relatedly, **do not let `improvement` fall out of use.** A report containing only `gap`/`error`/`inconsistency` usually means observations that should have been `improvement` were promoted into must-fix findings. If a finding would not block implementation, it is an `improvement` — say so.
 3. Exact location (file + section)
 4. What's wrong
 5. Suggested fix (specific enough that a fresh agent can apply it)
@@ -185,9 +194,9 @@ Every finding must include:
 
 ## Step 4: Write Findings Document
 
-Ensure the `.verification/` subdirectory exists, then write findings to `{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`.
+Ensure the `.verification/` subdirectory exists, then write findings to `{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. **Never overwrite an existing report:** if that name already exists (an earlier round the same day), write `VERIFY-{mode}-{YYYY-MM-DD}-round{N}.md` with the smallest `N ≥ 2` not yet on disk — each round's report and Fix Progress is an audit record later rounds and the round ledger (`references/stage-exit-protocol.md` § Escalation) read.
 
-**For epic mode**, the target is `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` (the same format, with `{mode}=epic`).
+**For epic mode**, the target is `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` (the same format and the same no-overwrite round rule, with `{mode}=epic`).
 
 The full findings-document template (report header, `V-NNN` finding shape, and the
 Fix Execution Plan layout) and the worked **Example Findings** (gap / inconsistency /
@@ -210,51 +219,73 @@ When building the Fix Execution Plan:
 **If not in plan mode:** Output the following as text:
 "Findings and fix plan written to `{findings-file}`."
 
-Then use `AskUserQuestion` to ask how to proceed. Follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
+**Advisory-only reports skip the question.** When the report contains no blocking finding (`error`/`gap`), there is nothing to route to forge-fix: do not present the fix options below — state that the report is advisory-only, record `passed` with the report attached (Step 6), and continue; the advisories stay discoverable in the findings document for whoever next touches the artifact. Otherwise (at least one blocking finding), use `AskUserQuestion` to ask how to proceed — **unless this report closes the SECOND consecutive `reverify-findings` for this served stage** (count the round-discriminated reports in `.verification/`), in which case follow "Escalation (the round ledger)" in `references/stage-exit-protocol.md` instead: present the digest and recommend explicit acceptance of the residual findings, never another fix pass. Otherwise follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
 - **(a) Review the findings first** — read `{findings-file}` and decide per-finding; safest, but you act on nothing until you return.
-- **(b) Run `/feature-forge:forge-fix {feature}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
+- **(b) Run `/feature-forge:forge-fix {feature} --served-stage {servedStage}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
 - **(c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}`** — produces a reviewable plan before any edits; best for large or risky fix sets.
 
 Do NOT embed this question in your text output.
 
-## Step 6: Update Pipeline State
+## Step 6: Record the Result Through `state-verify`
 
-Write pipeline state conforming to `references/pipeline-state-schema.json`.
+Never hand-author a verify entry. Every `stages.forge-verify-*` transition is written by the `state-verify` verb described in the **Pipeline State Protocol** in `references/shared-conventions.md`, which owns its full flag surface, its status matrix, and the exit-2 failure protocol. Write `findings-reported` when the report lists at least one **blocking** finding (`error`/`gap`); write `passed` when it lists none — including an **advisory-only** report (`inconsistency`/`improvement` findings only), which records `passed` with the report still attached: pass `--findings-file` and `--findings-count` alongside `--status passed` so the advisories remain discoverable without blocking the stage. (One exception routes blocking findings to `passed`: residual findings the user explicitly accepted at the round-ledger escalation — recorded first as a `state-decision`, then `passed` with the report attached, per "Escalation" in `references/stage-exit-protocol.md`.) Never write `findings-applied` here — that belongs to the fix pass. `--stage` names the **served production stage** (Step 1's mode, mapped through the served-stage mapping in Step 7), `--findings-file` is the report path **relative to** the feature directory (the Step 4 filename, round discriminator included), and `--verified-stage-version` is that production stage entry's current `version`, so a later revision of the artifact makes this verification read stale and re-fires. Add `--epic "{epic}"` when the feature is an epic member — required, per the Pipeline State Protocol; omitting it for a member is an error and must never fall back to a same-named flat feature.
 
-> **Deliberate R4 exclusion.** This step writes a **verify entry**
-> (`stages.forge-verify-*`), and no `state-*` verb writes verify entries — the verbs
-> cover production stage entries and the two array types only. So this one step stays
-> hand-authored, and the schema citation above is retained to serve it. This skill
-> authors no production stage entry of its own; where it needs one, the owning stage
-> skill records it via a verb per the Pipeline State Protocol in
-> `references/shared-conventions.md`.
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{servedStage}" --status "{passed|findings-reported}" \
+  --findings-file "{relative findings path}" --findings-count {n} \
+  --verified-stage-version {version} --specs-dir "{specsDir}"
+```
 
-Update `{resolvedFeatureDir}/.pipeline-state.json`:
-- Set the relevant verify entry status to `findings-reported` (or `passed` when there
-  are zero findings)
-- Record `findingsFile`, `findingsCount`, `verifiedAt`
-- Record `verifiedStageVersion` = the current `version` of the production stage entry
-  this verify covers (e.g. verifying `tech` → `stages["forge-2-tech"].version`). This
-  feeds the navigator's freshness ledger: a later revision to that artifact bumps its
-  `version`, so the recorded value no longer matches and auto-verify re-fires. Omitting
-  this leaves the verify looking stale (safe: the navigator re-verifies rather than
-  skips).
+**Two-commit provenance — never `--amend`.** The write above records `commitHash: null`. Commit 1 records the findings document and the state together (Git Commit Protocol, `references/shared-conventions.md`). Then record the provenance of that commit in Commit 2, passing the **full 40-character** hash of Commit 1 — an abbreviation is refused rather than expanded, and this call touches nothing but `commitHash`. Add `--epic "{epic}"` when the feature is an epic member — required, per the Pipeline State Protocol.
 
-Do NOT mark as `findings-applied` — that happens after the fix pass.
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{servedStage}" \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
+On exit 2 **nothing was recorded**: surface the `Error:` line verbatim together with the named feature (and epic), do not claim the result was persisted, and close the stage with `--outcome failed` in Step 7 — the verify entry is unchanged, so no success block may be printed.
 
 ### Epic mode state (`.epic-state.json`)
 
-Epic mode is **epic-scoped**, not per-feature: record its result into the epic-level
-state file `{specsDir}/{epic}/.epic-state.json` — **never** into any member's
-`.pipeline-state.json`. Set `stages.forge-verify-epic.status` to `findings-reported`
-(or `passed` if zero findings), recording `findingsFile`, `findingsCount`, and
-`verifiedAt`. The full `.epic-state.json` schema (minimal shape) and the atomic
-temp-file + `os.replace()` **write-mechanism** detail (lazy-create, merge/replace,
-fail-intact) — including the worked Python snippet — live in
-`references/findings-template.md` under the **Epic Mode State Write Detail
-(Step 6)** section. Follow it verbatim.
-
-Do NOT mark as `findings-applied` — that happens after the fix pass.
+Epic mode is **epic-scoped**, not per-feature: `--stage forge-0-epic` writes `{specsDir}/{epic}/.epic-state.json` and **never** any member's `.pipeline-state.json`. It is the one exception to the member rule — `--feature` names the **epic**, and `--epic` must be absent or exactly equal to it — and its `--verified-stage-version` is the epic manifest's `revision`, never a member's stage version. The exact call and the minimal written shape live in `references/findings-template.md` under the **Epic Mode State Write Detail (Step 6)** section. Follow it verbatim.
+
+## Step 7: Close the Stage
+
+**Ownership.** Read branch ownership from the literal `owner: nested` / `owner: direct` token in the prompt that dispatched you. **Absent the token you are `direct`** — a user-typed `/feature-forge:forge-verify` is the only path that carries no dispatcher. Never infer ownership from how the invocation happened to be phrased; judge the token, not the wording. Pass the resolved value straight through as `--owner`, and preserve it through any re-verify. As a **nested** owner you return your structured result (mode, served stage, outcome, findings file, findings count) to the caller and print **no terminal block at all** — the outer authoring stage is the sole terminal owner. As a **direct** owner you print the script's NEXT-STEPS block verbatim as your absolute final output, with nothing after its sentinel line. `references/stage-exit-protocol.md` § "Branch ownership: the `owner:` token" owns this rule.
+
+**Served stage.** Pass `--verify-mode` carrying Step 1's explicit or auto-detected mode (`epic`, `prd`, `tech`, `specs`, `backlog`, `impl`); the script maps it to the served production stage. When the caller already owns a stage and states it, additionally pass that value as `--served-stage` — if the two disagree the script fails closed rather than guessing. Derive the served stage **only** from that mode argument or from authoritative pipeline state: conversational context and `currentStage` are never valid inference sources.
+
+**Capability.** Pass `--verify-capability interactive` only when **both** a question mechanism equivalent to `AskUserQuestion` is available **and** a clean-room `forge-verifier` may actually be dispatched right now. Clause (b) tests **permitted dispatch, not a listed tool**: a session that may dispatch only when the user asked, but does have a question mechanism, is `interactive` — the gate's affirmative choice supplies the request. Reserve `manual` for **no** question mechanism **and** **no** permitted dispatch. An auto-verify directive under a no-unsolicited-dispatch bar is presented through the gate and dispatched on the affirmative choice — never skipped, and never resolved by advancing to the production successor.
+
+**Outcome.** Invoke the exit **exactly once**, with the `--outcome` this run's result maps to:
+
+| This run's result | `--outcome` |
+|---|---|
+| Zero findings — the artifacts are clean | `passed` |
+| Advisory-only report (no `error`/`gap`) — recorded `passed` with the report attached | `passed` |
+| A report with at least one blocking finding (`error`/`gap`) was written | `findings` |
+| The user explicitly chose to defer pipeline action **and** that skip was persisted via `state-verify --status skipped` | `skipped` |
+| A dispatch, a check, or a state write failed and needs intervention | `failed` |
+
+Merely **presenting** blocking findings is `findings`, not `skipped` — all three Step 5 options are `findings`, including (a) "review the findings first", which defers *your* next action rather than the pipeline's. `skipped` is available only for an explicit user deferral of **pipeline action** whose skip has already been persisted. A `CLEAN_ROOM_UNAVAILABLE` sentinel or a non-answer from an advertised dispatch is an operational failure, not a user skip: it is `failed`. A state-write failure is `failed`, and no success block may be printed after one.
+
+Add `--epic "{epic}"` when the feature is an epic member, and `--served-stage "{servedStage}"` when the caller supplied one. Pass no other flags.
+
+**Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" stage-exit --feature "{feature}" --stage forge-verify --owner "{owner}" --outcome "{VerifyOutcome}" --verify-mode "{mode}" --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
+```
+
+Obey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `"self"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: "outer"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.
 
 ## Gotchas
 

package/adapters/claude/skills/forge-verify/references/decisions/single-writer-threat-model.md

@@ -0,0 +1,53 @@
+# Decision: single-writer state model — detection welcome, locking out of scope
+
+**Decided:** 2026-08-08 · **Issue:** [#180](https://github.com/garygentry/feature-forge/issues/180) · **Owner:** repository owner
+
+## The decision
+
+Concurrent multi-session mutation of forge state is **out of scope**. Every forge state
+writer — `forge-session.py` (`.pipeline-state.json`) and `epic-manifest.py`
+(`epic-manifest.json`, `.epic-state.json`) — assumes a **single writer**. Atomicity
+(sibling temp file → flush/fsync → `os.replace`) protects against an *interrupted* write;
+it is not, and is not intended to be, mutual exclusion between simultaneous writers.
+
+The standing posture is **detection, not locking**:
+
+- **No locking mechanism will be added on the authority of a verification finding or a
+  single feature's spec.** If concurrent multi-session use ever becomes a supported
+  workflow, that is a product decision needing its own PRD — and a state lock alone would
+  be false comfort, because git operations, the two-commit provenance protocol, and
+  adapter regeneration are equally unsynchronized.
+- **Cheap, opportunistic detection is welcome if someone proposes it** — e.g. an
+  epic-root writer re-reading and failing loudly on an unexpected `revision` before
+  `os.replace`. It is an explicitly optional hardening, not a requirement, and nothing is
+  scheduled.
+
+## Accepted residual risk
+
+Everything in-session is sequential, and member `.pipeline-state.json` files are
+disjoint. The one real exposure: two sessions working **different members of one epic**
+share two epic-root files, `epic-manifest.json` and `.epic-state.json`. A lost
+read-modify-write increment of the manifest's `revision` can leave it unchanged after a
+semantic mutation landed, and the freshness comparison then classifies a **stale epic
+verification as `fresh`** — a correctness consequence, not just a lost edit.
+
+This is **accepted and documented**, not mitigated. Anyone who hits it has this document
+to cite; do not run two concurrent sessions against members of the same epic.
+
+## What this means for verification (CHECK-S27)
+
+When `CHECK-S27` ("Concurrent access scenarios are addressed if relevant") fires against
+forge state writes, the answer is a **citation, not a design**: cite this document (or
+the per-feature requirement restating it, e.g. `stage-exit-coverage` `REQ-REL-04`,
+`epic-orchestration` `REQ-ROBUST-03`). A PRD silent on concurrency gets a one-sentence
+position recorded; a verifier must never answer the silence by specifying a mechanism.
+
+## Provenance
+
+Both precedents ran the same check; the only variable was whether the PRD had a position:
+
+- `stage-exit-coverage` V-006 raised CHECK-S27 against a silent PRD, was filed as a
+  `gap`, and induced a ~140-line portable lock protocol answering no requirement. It was
+  removed (`302c93f`), and the PRD now records the position as `REQ-REL-04`.
+- `epic-orchestration` V-008 raised the same check against a PRD that had scoped
+  concurrency out (`REQ-ROBUST-03`), was filed as an `improvement`, and cost one sentence.