@garygentry/feature-forge 0.3.1 → 0.3.4

package/adapters/cursor/skills/forge-verify/forge-verify.mdc

@@ -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 host's subagent mechanism once with
   `the forge-verifier custom agent`, 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 subagent
   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.
@@ -88,7 +87,7 @@ without subagents), fall back to running verification inline in the current sess
 When the navigator auto-invokes this skill (its `autoVerify` path), it passes a
 **require-clean** signal (e.g. args include `--require-clean`, or the invocation is
 described as auto-verify). In this mode the clean-room guarantee is load-bearing: the
-whole reason auto-verify is safe to run without a clear your session / start a fresh session is that the `forge-verifier`
+whole reason auto-verify is safe to run without a session clear is that the `forge-verifier`
 subagent inherits none of the dispatching session's context. Running inline would break
 that — it would consume the dispatching session's context and invalidate the no-clear
 justification.
@@ -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 the host's question mechanism. 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 the host's question mechanism to ask which stage to verify.
+If ambiguous, use the host's question mechanism 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 host's subagent mechanism, 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 the host's question mechanism 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 the host's question mechanism 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 "${FEATURE_FORGE_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 "${FEATURE_FORGE_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 the host's question mechanism 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 "${FEATURE_FORGE_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 generic --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/cursor/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.

package/adapters/cursor/skills/forge-verify/references/findings-template.md

@@ -2,11 +2,45 @@
 
 Loaded by the **parent orchestrator** role of `forge-verify` at Step 4 (write the findings document) and Step 6 (epic-mode state write). The `forge-verifier` leaf subagent MUST NOT load this file — it holds only orchestrator-facing material (see `SKILL.md` → "Which role are you?").
 
+## Truncated Verifier Returns (Synthesize gate)
+
+The host's subagent mechanism hands the parent **only the verifier's final message**. A verifier that
+ends its run on a status line instead of the report returns *that line* as the entire
+result — the digest it built exists in its transcript but never reaches you. Observed
+in the wild (issue #183): two ~130k-token, 40+-tool-call runs each returned a single
+plausible-sounding opening sentence ("I'll start by loading the pipeline state…") while
+the recovered digest contained two BLOCKER findings. The failure is quiet precisely
+because the returned line reads like progress, not like an error.
+
+**Gate every verifier return before using it.** A return is a **non-answer** when it
+lacks the report structure — no `# Verification Report:` header, no `## Findings`
+section, no `Checks Executed:` line (for a skeptic dispatch: no per-finding
+CONFIRMED/REFUTED verdicts). Length is the tell: a real report is rarely under ~20
+lines; a one-or-two-sentence return from a run that did real work is a dropped digest,
+not a clean result.
+
+On a non-answer:
+
+1. **Resume, don't re-run.** `SendMessage` to the returned agent id: *"Your run ended
+   without returning the report. Return your FINAL report now, from the work you
+   already did, in the Output Format — your final message is the only thing I
+   receive."* The agent replays from its transcript and typically returns the full
+   digest with zero further tool calls.
+2. **Re-dispatch** the same prompt only if the resume also fails or the id is gone.
+3. **Never** synthesize findings from a truncated return, write a findings document
+   around it, record a verify result (`state-verify`) from it, or present it to the
+   user as the verification outcome. A gate decision made on a dropped digest is the
+   #183 failure mode: BLOCKER findings silently converted into a pass.
+
 ## Findings Document Template (Step 4)
 
 Write findings to `{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`
 (for epic mode, `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` — same
 format, with `{mode}=epic`). Ensure the `.verification/` subdirectory exists first.
+**Never overwrite an existing report:** if the 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 the
+round ledger reads (`references/stage-exit-protocol.md` § Escalation).
 
 ```markdown
 # Verification Report: {feature} ({mode})
@@ -20,6 +54,7 @@ Artifacts Reviewed: {list of files}
 - Inconsistencies: {N}
 - Improvements: {N}
 - Errors: {N}
+- Blocking (errors + gaps): {N} — {"report records findings-reported" | "0: advisory-only, report records passed with this file attached"}
 
 ## Findings
 
@@ -72,7 +107,7 @@ Here are complete example findings showing the expected quality:
 - **Severity:** inconsistency
 - **Location:** 00-core-definitions.md section 2.3 vs 03-session-management.md section 1.1
 - **Issue:** 00-core-definitions.md defines `SESSION_DURATION_MS = 7 * 24 * 60 * 60 * 1000` (7 days), but 03-session-management.md section 1.1 states "sessions expire after 30 days." These contradict each other.
-- **Suggested fix:** Align both documents to the PRD requirement. PRD.md REQ-SEC-03 says "sessions should have a reasonable expiry" without specifying a duration — use `AskUserQuestion` to ask the user which value is intended, then update both documents.
+- **Suggested fix:** Align both documents to the PRD requirement. PRD.md REQ-SEC-03 says "sessions should have a reasonable expiry" without specifying a duration — use the host's question mechanism to ask the user which value is intended, then update both documents.
 - **References:** PRD.md REQ-SEC-03, 00-core-definitions.md section 2.3, 03-session-management.md section 1.1
 ```
 
@@ -95,63 +130,48 @@ state file `{specsDir}/{epic}/.epic-state.json` — **never** into any member's
 violate REQ-STATE-02; per-feature status is always derived live from each 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 minimal
-shape:
+Set `stages.forge-verify-epic.status` to `findings-reported` when the report lists at
+least one **blocking** finding (`error`/`gap`), else `passed` — for an advisory-only
+report pass `--findings-file`/`--findings-count` alongside `--status passed`, exactly
+as in feature mode (the severity floor in `skills/forge-verify/SKILL.md`) — recording
+`findingsFile`, `findingsCount`, and `verifiedAt`.
+
+**Write it with `state-verify`, never by hand.** `--stage forge-0-epic` is the sanctioned
+epic writer: it creates the file lazily, mutates only `stages.forge-verify-epic` plus the
+top-level `updatedAt`, writes atomically, and leaves any prior file intact on failure.
+This is the one `state-*` call site where the member `--epic` rule does **not** apply:
+`--feature` names the **epic**, and `--epic` must be absent or exactly equal to it. Its
+`--verified-stage-version` is the **epic manifest's `revision`** — never a member's stage
+version — which is what keeps the result reading fresh rather than stale.
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_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 "{passed|findings-reported}" \
+  --findings-file "{relative findings path}" --findings-count {n} \
+  --verified-stage-version {manifest revision} --specs-dir "{specsDir}"
+```
+
+On exit 2 nothing was recorded: surface the `Error:` line verbatim, name the epic, and do
+not claim the verification was persisted. The minimal shape this writes:
 
 ```jsonc
 {
-  "epic": "auth-overhaul",              // matches the manifest `epic`
+  "epic": "auth-overhaul",               // matches the manifest `epic`
+  "updatedAt": "2026-06-12T00:00:00Z",   // refreshed on every successful write
   "stages": {
     "forge-verify-epic": {
-      "status": "findings-reported",     // "findings-reported" | "passed" | "findings-applied"
+      "status": "findings-reported",     // "findings-reported" | "passed" | "findings-applied" | "skipped" | "auto-verify-pending"
       "findingsFile": ".verification/VERIFY-epic-2026-06-12.md",
       "findingsCount": 3,
-      "verifiedAt": "2026-06-12T00:00:00Z"
+      "verifiedAt": "2026-06-12T00:00:00Z",
+      "verifiedStageVersion": 3,         // the epic manifest revision this covers
+      "commitHash": null                 // filled by the Commit 2 provenance call
+      // "scheduledAt" / "scheduledStageVersion" appear only while an
+      // auto-verify-pending schedule is outstanding; a terminal result removes them
     }
   }
 }
 ```
-
-**Write mechanism.** `epic-manifest.py` exposes no subcommand that writes this file, so
-the skill writes it **directly**, using an atomic temp-file + `os.replace()` pattern
-(mirroring `02-manifest-helper-cli.md §3.3`): serialize the merged state to a sibling
-temp file in `{specsDir}/{epic}/`, flush, then `os.replace()` it into place. Create the
-file **lazily on first write** (a missing file is simply created; an existing file is
-read, its `stages.forge-verify-epic` entry merged/replaced, and rewritten). On any I/O
-failure, **report the error and leave any prior `.epic-state.json` intact** (never a
-partial write). For example:
-
-```bash
-python3 - "$SPECS_DIR/$EPIC" <<'PY'
-import json, os, sys, tempfile
-from pathlib import Path
-epic_dir = Path(sys.argv[1])
-path = epic_dir / ".epic-state.json"
-state = {}
-if path.exists():
-    state = json.loads(path.read_text())
-state.setdefault("epic", epic_dir.name)
-state.setdefault("stages", {})
-state["stages"]["forge-verify-epic"] = {
-    "status": "findings-reported",   # or "passed" when findingsCount == 0
-    "findingsFile": ".verification/VERIFY-epic-2026-06-12.md",
-    "findingsCount": 3,
-    "verifiedAt": "2026-06-12T00:00:00Z",
-}
-fd, tmp = tempfile.mkstemp(dir=str(epic_dir), prefix=".epic-state.", suffix=".tmp")
-try:
-    with os.fdopen(fd, "w") as f:
-        json.dump(state, f, indent=2)
-        f.flush()
-        os.fsync(f.fileno())
-    os.replace(tmp, path)
-except OSError as e:
-    try:
-        os.unlink(tmp)
-    except OSError:
-        pass
-    print(f"failed to write .epic-state.json: {e}", file=sys.stderr)
-    raise
-PY
-```