@garygentry/feature-forge 0.3.2 → 0.3.4

package/adapters/gemini/skills/forge-verify/references/stage-exit-protocol.md

@@ -4,7 +4,7 @@ The single source of truth for how every forge stage closes. **One** scripted co
 covers all **nine** covered direct exits — the seven production stages `forge-0-epic`
 through `forge-6-docs`, plus direct `forge-verify` and direct `forge-fix`. It replaces the
 old ad-hoc "Next steps:" bullet lists with one fixed, correctly-ordered sequence:
-**verify (if missing or stale) → `/clear` → run the next command.**
+**verify (if missing or stale) → clear your session / start a fresh session → run the next command.**
 
 Two principles this protocol encodes (do not relitigate — they are locked product
 decisions):
@@ -18,7 +18,7 @@ decisions):
    session, so the findings digest and any fix decision land where the context to act on
    them still exists. This holds for auto-verify too: the stage skill dispatches the
    clean-room verify (and any autoFix) at stage end, in-session, before the exit — it is
-   **not** deferred to the navigator, which runs *after* the `/clear` with none of the
+   **not** deferred to the navigator, which runs *after* the session clear with none of the
    authoring context. Clearing first throws that context away.
 
 ## How this file is used
@@ -47,8 +47,8 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred` |
-| `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete` or `blocked` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |
 | direct/nested `forge-fix` | `forge-fix` | the matching `--owner`, a `FixOutcome` (`no-findings`, `decisions`, `failed`, `applied`, `reverified`, `reverify-findings`, `deferred`), and served-stage metadata |
@@ -90,19 +90,19 @@ resolves before running the command, exactly as elsewhere.
 **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')"
+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 {stage-exit-args} --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
+python3 "$R/scripts/forge-session.py" stage-exit {stage-exit-args} --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.
 <!-- END: scripted-stage-exit-stamp -->
 
-The stamp is shown with `--host claude`; the adapter build substitutes `pi`/`generic` per
+The stamp is shown with `--host generic`; the adapter build substitutes `pi`/`generic` per
 target, and §"Host and capability determination" below governs the value. The literal is
-deliberate — `scripts/build-adapters.py` keys its host translation on the exact string
-`--host claude`, and the stamp sites are compared byte-for-byte, so it is the one token in
-that line that is not a placeholder.
+deliberate — `scripts/build-adapters.py` keys its host translation on the exact canon
+value of that flag, and the stamp sites are compared byte-for-byte, so it is the one token
+in that line that is not a placeholder.
 
 ## Host and capability determination
 
@@ -110,12 +110,13 @@ Before the call, compute the two inputs independently. They are unrelated: **a h
 implies a capability**, and the script takes `--verify-capability` at face value.
 
 **`--host`** describes only the active adapter command surface — `claude`, `pi`, or
-`generic`. It selects command syntax (`/feature-forge:` vs `/skill:` vs host-neutral) and
-fresh-session wording (`/clear` vs `/new` vs neutral prose). Nothing else.
+`generic`. It selects command syntax (Claude's stage-command prefix vs Pi's `/skill:` vs
+host-neutral) and fresh-session wording (Claude's clear command vs Pi's `/new` vs neutral
+prose). Nothing else.
 
 **`--verify-capability interactive`** is passed only when **both** of these hold:
 
-- **(a)** a question mechanism equivalent to `AskUserQuestion` is available, **and**
+- **(a)** a question mechanism equivalent to the host's question mechanism is available, **and**
 - **(b)** a clean-room `forge-verifier` subagent can be dispatched.
 
 If either is absent, or capability cannot be established, pass `manual`.
@@ -151,7 +152,8 @@ production successor** while verification is unresolved.
 - a capable Pi session is `--host pi --verify-capability interactive`, and receives the
   same logical gate a capable Claude session does;
 - Pi without a dispatchable verifier is `--host pi --verify-capability manual`;
-- a Claude session that cannot dispatch is `--host claude --verify-capability manual`.
+- a Claude session that cannot dispatch keeps the Claude host value with
+  `--verify-capability manual`.
 
 Interactive gate options keep their explicit labels, their recommended default, and their
 one-line trade-off descriptions (below). The manual path prints the verify command as the
@@ -199,6 +201,44 @@ second sentinel-terminated block **inside** an outer stage's exit, breaking the
 exactly-one-terminal-block rule — and the canon guard cannot catch it, because both
 wordings legitimately appear in the same file. Judge the token, not the phrasing.
 
+## Caller-side resumption: the declared resume point
+
+The `owner:` token and `terminalOwnedBy` arbitrate who prints — but they specify only
+the **callee** side: a nested skill stays quiet and returns its structured result. This
+section is the reciprocal, caller-side half of that contract.
+
+**On a sub-skill's return, the caller re-owns the terminal.** Every closing instruction
+in the callee's own body — its report-and-stop posture, its "confirm the result" close,
+its own next-steps habits — is void for this turn. The caller resumes at its **declared
+resume point**, in the same turn, and its remaining steps run to its own terminal.
+
+**Every Skill-tool delegation site declares, at the invocation, what happens on
+return.** Suppression without resumption is the failure mode this section closes: the
+callee's closing posture is the freshest instruction in context while the caller's next
+step is the oldest, so an undeclared return silently ends the run one layer too early —
+the caller's remaining steps (validation, state writes, commit, stage exit) dropped,
+with no error surfaced. An implicit "let it run to its natural stopping point" is that
+bug spelled politely, and it is banned on delegation sites. A site takes one of two
+declared postures:
+
+- **Delegate-and-resume** — the callee is a sub-step of the caller: the site names the
+  caller's own step that control returns to, and the caller continues there in the same
+  turn. The callee never owns the caller's terminal. The worked instance is
+  `forge-4-backlog` Step 4's **Return contract** for the `author-backlog` delegation
+  (control returns at Step 5; the sub-skill's direct-invocation posture — its approval
+  gate and its validate-and-confirm close — is explicitly disapplied on the delegated
+  path). New delegation sites follow that pattern rather than re-deriving it.
+- **Terminal handoff** — the caller's job ends at the invocation and the invoked skill
+  owns the terminal from there on (e.g. the navigator's `autoInvokeNextStage`
+  "continue in this session" advance into the next production stage). Declaring the
+  handoff is what keeps it distinct from an accidental drop.
+
+Scope: this contract governs **Skill-tool delegation within one session**. The
+truncated-verifier-return guard (forge-verify's `findings-template.md`, "Truncated
+Verifier Returns") is a different mechanism — it polices what an **Agent-dispatched
+subagent's** return payload must contain, not where a caller resumes. A dispatch site
+can be subject to both; satisfy each on its own terms.
+
 ## Directive consumption order
 
 `stage-exit` emits a DIRECTIVES object and (for a direct owner) a NEXT-STEPS block. The
@@ -243,7 +283,7 @@ reformat, merge, or summarize them, and never dump the state file they were deri
 
 Auto-verify is effective for this stage and verification is outstanding — verify **now,
 in this session** (principle #2 applied to auto-verify: the digest and any fix decision
-land here, where the authoring context still exists — not deferred to a post-`/clear`
+land here, where the authoring context still exists — not deferred to a post-clear
 navigator). The `auto-verify-pending` debt is already durable on disk at this point, so a
 declined or deferred gate leaves recorded debt rather than a silent pass.
 
@@ -252,7 +292,7 @@ declined or deferred gate leaves recorded debt rather than a silent pass.
    same path the navigator uses (`skills/forge-verify/SKILL.md`). Dispatch it
    **synchronously and await its digest inline** — do **not** run it in the background or
    announce it as "still running"; the digest and any fix decision must land in this
-   session. It inherits none of this session's context, so no `/clear` is needed and only
+   session. It inherits none of this session's context, so no session clear is needed and only
    a compact digest returns.
    **If you may not dispatch unsolicited**, present the consent form of the Standard
    Verify Gate first and dispatch on the affirmative choice — see "Consent variant on a
@@ -299,7 +339,11 @@ first:
   a stage's artifact commit.
 - **Skip for now** — go straight to the NEXT-STEPS block without verifying. Record this
   stage's verify status as `skipped` in pipeline state (via `state-verify`, never by hand)
-  **only** on an explicit skip — a skip does not go stale.
+  **only** on an explicit skip — a skip does not go stale. Exception: if the existing
+  entry records `passed` or `findings-applied` (a resolved result whose freshness has
+  merely lapsed), write **nothing** — `state-verify` refuses to demote a resolved status
+  to `skipped` (#203), and the recorded result stands on its own; the user's decline is
+  honored by simply not re-verifying.
 
 **Advancement is allowed only after a pass, or after an explicit skip has been
 persisted.** Choosing to stop, or losing the interaction, produces no advancing terminal
@@ -358,8 +402,8 @@ directive is informational — you do **not** re-derive the wording:
   unchanged; the block appends a non-blocking reminder line ("You also flagged N epic
   change(s) to reconcile when convenient …"). This is *finish-then-edit*.
 
-Either way the added lines are host-neutral (no literal `/clear`) and sit **above** the
-sentinel; just print the NEXT-STEPS block verbatim as always.
+Either way the added lines are host-neutral (they name no fresh-session command) and sit
+**above** the sentinel; just print the NEXT-STEPS block verbatim as always.
 
 ### Deferred decisions — do not solicit next-stage decisions at this exit
 
@@ -376,7 +420,7 @@ a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by runnin
 epic member — required, 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')"
+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-decision \
   --feature "{feature}" --question "<phrased for the target stage>" \

package/adapters/gemini/skills/forge-verify/references/verification-checklists/backlog.md

@@ -33,6 +33,35 @@ Detailed checklist for the **backlog** verification mode, loaded by the `forge-v
 - [ ] **CHECK-B18**: Items that depend on types/interfaces reference the item that creates them
 - [ ] **CHECK-B19**: Priority ordering is consistent with dependency ordering (dependencies should have equal or higher priority)
 
+### Dependency Topology
+- [ ] **CHECK-B28**: **Fragile dependency topology — a single root gates a large fraction of the
+  backlog, or the chain is deep** (#194). *Advisory heuristic — severity `improvement`, **never**
+  `error`/`gap`, and it **never blocks**. **not-applicable** when no trigger fires or the graph is
+  trivial (0–1 items, or no dependsOn edges at all).* A backlog where one root item gates most of
+  the tree, or whose critical chain is deep relative to its size, has a single point of near-total
+  failure: one defect in that root (or anywhere on the long chain) strands the dependent subtree —
+  the loop-recovery incident was 3 roots gating 81% of 16 items down a 13-deep chain, and it passed
+  both authoring and verification without comment. Verify by computing, never by eyeballing:
+  1. **Compute the topology.** Feed the runner's item array to the scripted metric:
+
+     ```
+     rauf backlog list . --backlog {resolvedBacklogDir} --json | python3 "$R/scripts/forge-session.py" backlog-topology --items-stdin --json
+     ```
+
+     Read `itemCount`, `rootCount`, `roots[].gatedCount`, `maxChainDepth`, and `warnings`. If
+     `itemCount <= 1` or there are no `dependsOn` edges, this check is **not-applicable**.
+  2. **Read the warnings, do not re-derive them.** The metric applies the fixed thresholds
+     (`single-root-fanout` when any root gates ≥50% of items; `chain-depth` when `maxChainDepth`
+     ≥50% of item count). If `warnings` is empty, record **pass** (topology computed, no fragile
+     shape). Do not invent a different threshold — the constants are canonical
+     (`forge-session.py`).
+  3. **Report each fired warning as one `improvement` finding.** For `single-root-fanout`, name the
+     root and its `gatedCount`/`itemCount` ("root 1 gates 13/16 items") and suggest splitting that
+     root's subtree or introducing an intermediate. For `chain-depth`, name
+     `maxChainDepth`/`itemCount` and suggest flattening. **Report, do not repair** — this is a
+     heads-up to the author, never a blocking gate. Cite the metric output the claim was derived
+     from.
+
 ### Completeness
 - [ ] **CHECK-B20**: There is an item for the initial package scaffold
 - [ ] **CHECK-B21**: There is an item for shared types and error hierarchy
@@ -95,3 +124,47 @@ Detailed checklist for the **backlog** verification mode, loaded by the `forge-v
   > provenance. Any item asserting a human-gated lifecycle state must trace — via `dependsOn` — to the
   > item that legitimately produces it, or assert the state through a dev-build / fixture path instead.
 
+### Work-Order Cardinality
+
+> **When this fires:** only when the backlog, or an artifact the backlog derives from,
+> **declares an enumerated per-item work list that claims to cover a set**. A backlog
+> with no such list yields **not-applicable** — absence of a declared list is never a
+> hard fail. The defect this catches is not a wrong item; it is a **missing** one, and
+> a missing entry is invisible to every reader who checks the entries that are present.
+
+- [ ] **CHECK-B29**: **A declared per-item work list covers the whole set it claims — name what is missing** (#170).
+  *Heuristic with a mechanical method — **not-applicable** when no enumerated per-item work
+  list is declared anywhere in the backlog or the artifacts it derives from; absence is
+  **never a hard fail**. A true omission is a `gap` (blocking): an unreviewed member is
+  missing coverage.* When the backlog — or an artifact it derives from, such as a
+  hand-authored work order, a per-item review sheet, a "one entry per item" table in a
+  plan the backlog cites, or a stated total in a summary line — declares an enumerated
+  list **claiming coverage of a set**, the list's cardinality must be **re-derived from
+  the actual member set** and never trusted from the list's own header, its numbering, or
+  a stated total. In the incident behind this check a hand-authored work order enumerated
+  **15 of 16** artifacts; it passed authoring and a full review, and the dropped
+  sixteenth would have been published unreviewed. Verify by re-deriving, never by
+  eyeballing:
+  1. **Find the declared lists.** Scan the backlog and the artifacts it cites for an
+     enumerated list that claims coverage of a nameable set — one entry per backlog item,
+     per spec document, per requirement id, per generated artifact, per file to touch. The
+     coverage claim reads as "one per …", "all …", "every …", "each …", or as a stated
+     total ("16 artifacts", "covers the full set"). If **no** such list exists, this check
+     is **not-applicable** — record it and move on.
+  2. **Re-derive the member set from its own source of record.** Build the actual set
+     independently of the list: backlog items from `backlog.json`, spec documents from the
+     spec directory listing, requirement ids from the PRD, artifacts from the paths the
+     items name. Count what you built; do not adopt any count the list asserts about
+     itself.
+  3. **Difference both directions and name every discrepancy.** Report each member of the
+     re-derived set that has **no** entry in the declared list **by name** — the item id,
+     file path, or requirement id — never as a count delta ("one short", "off by one"),
+     which hands the reader back exactly the derivation this check just performed. Report
+     the reverse direction too: a list entry naming something absent from the re-derived
+     set is a stale entry.
+  4. **Severity, and what to report.** A named omission is a `gap`. A stale entry, or a
+     stated total that disagrees with a list whose membership is nevertheless complete, is
+     an `inconsistency`. Every finding names the list, the source of record the set was
+     re-derived from, and each missing or stale member by name. **Report, do not repair** —
+     authoring the missing entry belongs to the fix pass.
+

package/adapters/gemini/skills/forge-verify/references/verification-checklists/epic.md

@@ -12,7 +12,7 @@ reading the manifest, EPIC.md, completed members' specs, and (for E10) sibling m
 committed tests.
 
 ```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')"
+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/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
 ```

package/adapters/gemini/skills/forge-verify/references/verification-checklists/impl.md

@@ -46,3 +46,88 @@ Detailed checklist for the **impl** verification mode, loaded by the `forge-veri
 - [ ] **CHECK-I22**: **Runtime-required bootstrap has a non-test caller.** Every exported bootstrap / `init*` / singleton-populator the specs mark as **required for runtime** must have ≥1 **non-test** call site on a runtime path — an entrypoint such as `main` / `instrumentation` / a route / a layout / a worker, NOT only test files. Statically grep for each such symbol's references (use the stack profile `references/stacks/{stack}.md` **Runtime Entrypoints & Bootstrap-Wiring Sites** list for what counts as a runtime entrypoint in this language). A symbol that is exported and covered by tests but referenced **only** from test files is a `gap` — the #121 walking-skeleton (bootstrap wired to nothing). Degrades naturally: a feature whose specs mark no bootstrap symbol as runtime-required is `not-applicable`. Weaker than `CHECK-I21` (it proves a call site exists, not that the boot succeeds), so it complements rather than replaces the smoke.
 - [ ] **CHECK-I23**: **Heavy bootstrap wired into a universal startup entry — recommend lazy init** (#149). *Advisory heuristic — a `gap`/`improvement` at most, **never** a hard fail.* When a runtime-required `init`/bootstrap/singleton-populator is wired into a **framework bootstrap entry that runs on every startup** (a Next.js `instrumentation.ts`, an app-server preload/`register` hook, a global setup module) **and** that init pulls in a **large server-only import graph** (DB clients, ORMs, queue/background workers, telemetry exporters, the whole service layer), recommend moving to **lazy initialization at the entry that already loads that graph** — the first route / handler / worker that needs it — rather than eager wiring at the universal entry. Eager wiring drags the heavy graph into every cold start, and in dev into every module re-evaluation (the watch-loop cost `CHECK-I21` also targets). **Detect statically:** from the stack profile's **Runtime Entrypoints & Bootstrap-Wiring Sites** list, identify this stack's universal bootstrap entries; grep those files for imports of the feature's runtime-required bootstrap symbols (`CHECK-I22`) and for the server-only heavy-import markers the profile names. A match → an `improvement`/`gap` finding naming the entry, the heavy graph it pulls, and the lazier call site to move initialization to. Degrades to `not-applicable` when the stack has no universal bootstrap entry, when no heavy init is wired there, or when the profile lists no bootstrap-wiring sites — **report, do not repair.**
 
+### Work-Order Cardinality
+
+> **When this fires:** only when the implementation ships or cites an **enumerated work
+> order, coverage list, or inventory that claims to cover a set of artifacts** — a
+> per-file work order, a "files changed" table, a per-artifact review checklist, an
+> inventory table in a spec this implementation realizes, or a registry constant in code
+> that claims to list every member of a class. No such list yields **not-applicable**;
+> absence is never a hard fail.
+
+- [ ] **CHECK-I24**: **A declared work order or coverage list covers the whole artifact set it claims — name what is missing** (#170).
+  *Heuristic with a mechanical method — **not-applicable** when the implementation declares
+  no enumerated work order, coverage list, or registry claiming full coverage; absence is
+  **never a hard fail**. A true omission is a `gap` (blocking): an unreviewed artifact is
+  missing coverage.* Any declared work order or coverage list must be checked against the
+  **actual artifact set it claims to cover**, with omissions named. The incident behind
+  this check is a hand-authored work order that enumerated **15 of 16** artifacts: the
+  sixteenth was never reviewed and would have shipped, because every reviewer worked the
+  list that was in front of them. Verify by re-deriving, never by reading the list back to
+  itself:
+  1. **Find the declared lists.** Look for enumerated lists claiming coverage of a set:
+     a work order or handoff enumerating files to change, a "files changed" or "artifacts
+     touched" table, a per-artifact review or sign-off checklist, an inventory table in an
+     implementation spec, and **registry-shaped constants in code** — a tuple, array, or
+     map documented as holding every helper, every adapter target, every generated file.
+     If no such list exists, this check is **not-applicable**.
+  2. **Re-derive the covered set from its source of record.** Enumerate the actual set
+     independently: the directory listing for a per-file list, the spec's own file
+     inventory for an implementation work order, the on-disk members for a registry
+     constant, the test suite's own collected set for a coverage table. A registry claiming
+     to hold "every script the skills invoke" is re-derived by finding the invocations, not
+     by reading the tuple.
+  3. **Difference both directions and name every discrepancy.** Every member of the
+     re-derived set with no entry in the declared list is reported **by name** — path,
+     symbol, or artifact id — never as a count delta. A list entry pointing at something
+     that does not exist is a stale entry, reported the same way.
+  4. **Severity, and what to report.** A named omission is a `gap`; a stale entry, or a
+     stated total that disagrees with an otherwise complete list, is an `inconsistency`.
+     Name the list, the source of record used for the re-derivation, and each missing or
+     stale member. This check is deliberately narrower than `CHECK-I01` (which asks whether
+     each file the architecture spec lists exists): here the *list itself* is the suspect,
+     not the artifacts it names. **Report, do not repair.**
+
+### Internal Consistency
+
+> **When this fires:** on any artifact that states the same quantity, scope claim, or
+> status **in more than one place** — front matter vs body, a summary block vs the prose
+> below it, a table vs the narrative that explains it, a docstring vs the code it
+> documents. This is deliberately **intra-artifact**: contradictions *between* artifacts
+> are already the subject of the spec-compliance checks above. An artifact that states
+> each quantity exactly once yields **not-applicable** — it degrades naturally, with
+> nothing to compare.
+
+- [ ] **CHECK-I25**: **One artifact, one answer — a quantity or claim restated inconsistently inside a single artifact** (#170).
+  *Verifier judgment — read and compare; no extractor runs (deliberately, this milestone).
+  **not-applicable** when nothing is restated. Severity defaults to `inconsistency`
+  (advisory) and escalates to `error` only when the contradiction is decision-bearing, per
+  the severity conventions in the verify skill.* An artifact can be internally false while
+  every cross-artifact check passes: in the incident behind this check, one artifact
+  asserted a claim held **universally**, while its own body — two sections below — stated
+  the correct **4-of-7** breakdown. The false summary survived a full review, propagated
+  into generated output, and would have shipped. Verify by comparing the artifact against
+  itself:
+  1. **Collect the restatements.** Read the artifact end to end and note every place it
+     states: a **count or total** ("16 files", "N of M", "all four"), a **scope claim**
+     ("every", "all", "none", "only", "universal", "always", "never"), a **status claim**
+     ("complete", "pending", "removed", "supported"), or a **named identifier or version**
+     it repeats. Note each statement with its location. Anything stated exactly once is not
+     in scope for this check.
+  2. **Compare statements about the same subject.** Group the notes by what they describe,
+     then compare within each group. Two disagreeing numbers is the obvious hit; the
+     costlier one is a **scope word contradicted by the artifact's own detail** — a
+     universal claim sitting above a partial breakdown, an "all supported" above a table
+     with a gap, a "removed" beside a surviving reference.
+  3. **Decide which statement the artifact's own evidence supports.** Prefer the
+     **enumerated detail** — the table, the list, the breakdown, the code — over the
+     summary that restates it: the summary is the derived form and is usually the one that
+     drifted. Say in the finding which statement the evidence supports and why, so the fix
+     is unambiguous.
+  4. **Set severity deliberately.** Default to `inconsistency` (advisory). Escalate to
+     `error` only when the contradiction is **decision-bearing** — a reader acting on the
+     wrong statement takes a materially different action, or the wrong statement is copied
+     into generated output, a published artifact, or a gate. An inaccuracy confined to a
+     comment, a docstring, or test narration stays at `inconsistency` under the severity
+     floor. Quote both locations verbatim in the finding. **Report, do not repair.**
+

package/adapters/gemini/skills/forge-verify/references/verification-checklists/specs.md

@@ -45,7 +45,7 @@ Detailed checklist for the **specs** verification mode, loaded by the `forge-ver
 - [ ] **CHECK-S26**: Import paths match actual package export maps
 
 ### Edge Cases and Non-Functional
-- [ ] **CHECK-S27**: Concurrent access scenarios are addressed if relevant
+- [ ] **CHECK-S27**: Concurrent access scenarios are addressed if relevant (a PRD position of "out of scope — single writer assumed" is a complete answer; for forge state writes the standing decision is `references/decisions/single-writer-threat-model.md` — cite it, do not design a mechanism)
 - [ ] **CHECK-S28**: Empty/null/undefined inputs are handled
 - [ ] **CHECK-S29**: Performance-sensitive paths are identified
 - [ ] **CHECK-S30**: Security considerations from PRD are reflected in implementation
@@ -64,3 +64,45 @@ Detailed checklist for the **specs** verification mode, loaded by the `forge-ver
 
 > **A quoted foreign requirement id is not an orphan.** A suite may legitimately mention a `REQ-` id it does not own — most often when a spec quotes an antecedent feature's test docstrings verbatim. Such ids may be declared, one per line, in `{resolvedFeatureDir}/.traceability-allowlist` (blank lines and `#` comments ignored), or passed as a repeatable `--allow-orphan REQ-ID` to `scripts/validate-traceability.py`. Allowed ids are reported as `ALLOWED FOREIGN REFERENCES` (`allowed_orphans` under `--json`) rather than silently dropped, and an entry matching nothing is reported as `STALE ALLOWLIST ENTRIES` (`unused_allowlist_entries`), which is advisory and does not fail the check. Before filing an orphaned reference as a finding, check whether it is already declared there — a declared id is a recorded decision, not a defect.
 
+### Internal Consistency
+
+> **When this fires:** on any single spec document that states the same quantity, scope
+> claim, or status **in more than one place** — a Requirement Coverage table vs the
+> sections it points at, a summary or overview paragraph vs the detail below it, a
+> Dependencies list vs the cross-references in the body, a stated count of documents or
+> types vs the list actually enumerated. It is **intra-document**: a contradiction
+> *between* two spec documents is already covered by the tech-spec-consistency and
+> cross-reference checks above. A document that states each quantity exactly once yields
+> **not-applicable**.
+
+- [ ] **CHECK-S39**: **One document, one answer — a quantity or claim restated inconsistently inside a single spec** (#170).
+  *Verifier judgment — read and compare; no extractor runs (deliberately, this milestone).
+  **not-applicable** when nothing is restated. Severity defaults to `inconsistency`
+  (advisory) and escalates to `error` only when the contradiction is decision-bearing, per
+  the severity conventions in the verify skill.* A spec document can contradict itself
+  while every cross-document check passes: in the incident behind this check, one artifact
+  asserted a claim held **universally**, while its own body — two sections below — stated
+  the correct **4-of-7** breakdown. The summary was the part downstream artifacts copied.
+  Verify by comparing the document against itself:
+  1. **Collect the restatements.** Note every place the document states a **count or
+     total** ("five documents", "N of M", "all three subcommands"), a **scope claim**
+     ("every", "all", "none", "only", "universal", "always", "never"), a **status claim**
+     ("out of scope", "deferred", "removed", "required"), or a **repeated identifier**
+     (a type name, a file path, a requirement id, a constant's value). Record each with its
+     location. Anything stated exactly once is not in scope for this check.
+  2. **Compare statements about the same subject.** Group by subject and compare within
+     each group. Watch specifically for: a Requirement Coverage table row pointing at a
+     section that no longer makes that claim; a count in an overview that disagrees with
+     the list enumerated below it; a scope word ("all", "universal", "never") that the
+     document's own breakdown contradicts; a constant given one value in a type definition
+     and another in prose.
+  3. **Decide which statement the document's own evidence supports.** Prefer the
+     **enumerated detail** — the table, the type definition, the numbered list — over the
+     summary that restates it. Name in the finding which statement the evidence supports,
+     so the fix does not have to re-derive it.
+  4. **Set severity deliberately.** Default to `inconsistency` (advisory). Escalate to
+     `error` only when the contradiction is **decision-bearing**: an implementer building
+     from the wrong statement writes different code, or the wrong statement is what a
+     downstream artifact or generated output copies. Quote both locations verbatim.
+     **Report, do not repair.**
+

package/adapters/pi/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "agent": "pi",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/pi/agents/forge-verifier.md

@@ -21,6 +21,8 @@ You are the "second set of eyes." You receive artifacts (PRDs, tech specs, imple
 
 You have READ-ONLY access. You cannot and should not modify any files. Your output is returned as your response — the parent agent handles writing the findings document to disk.
 
+**Your last message is the only thing the parent receives.** The host's subagent mechanism returns your final response and nothing else — no transcript, no intermediate messages, no tool results. If your run ends on a status or transition line ("Let me read the dispatch handler table."), *that line* is the entire verification result the parent gets, and the digest you spent the whole run building is silently dropped (issue #183). Your final response must therefore BE the complete report — the full Output Format block below, starting at `# Verification Report:` — never a summary of it, never an opening line, never "the report follows." Before ending, check your last message: if it is not the complete report, emit the complete report.
+
 **You ARE the verifier — you never dispatch one.** You have no Agent/host's subagent mechanism. Your pre-loaded `forge-verify` skill contains a "Subagent Delegation (parent orchestrator only)" section describing how a *parent* dispatches a `forge-verifier` — that guidance is for the parent, not for you. Ignore it: do not attempt to delegate, spawn a subagent, or return a "verification is running / will surface shortly" placeholder. Execute the verification checks yourself and return the findings block. Delegating from here is a self-referential loop that produces no work and no findings artifact.
 
 ## How You Work
@@ -63,7 +65,7 @@ At the end of each verification pass, update your memory with any new patterns y
 
 ## Output Format
 
-Return your findings as your final response using exactly this markdown structure. The parent agent will write it to `.verification/VERIFY-{mode}-{date}.md`:
+Return your findings as your final response using exactly this markdown structure — the final response IS the report (emit the entire block, not a description of it). The parent agent will write it to `.verification/VERIFY-{mode}-{date}.md`:
 
 ```markdown
 # Verification Report: {feature} ({mode})

package/adapters/pi/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/pi/references/epic-state-schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Epic Verification State",
+  "description": "Epic-scoped verification state for a single epic. Lives at {specsDir}/{epic}/.epic-state.json. Written only by forge-session.py's `state-verify` verb for epic targets (`--stage forge-0-epic`, resolved through `_load_epic_state_for_write`) — never by hand. Deliberately NOT a member `.pipeline-state.json` variant: epic verification is epic-scoped, artifact freshness is judged against the epic manifest's `revision` (never a member production-stage `version`), and there is no fallback between the two state files in either direction (REQ-SEC-01).",
+  "type": "object",
+  "required": ["epic", "updatedAt", "stages"],
+  "properties": {
+    "epic": {
+      "type": "string",
+      "description": "Epic name (matches the directory name under specsDir). epic-manifest.json's own `epic` value is canonical on conflict — the writer refuses a mismatched identity rather than resolving it."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "description": "MIRROR of pipeline-state-schema.json#/definitions/verifyEntry (minus this description) — the repo's stdlib schema validator (tests/_state_schema.py) resolves same-file `#/definitions/*` refs only, so the definition is duplicated rather than cross-file-referenced, and tests/test_epic_state_schema_conformance.py pins the two definitions equal so they cannot drift. Edit them together.",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "auto-verify-pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": { "type": ["string", "null"], "description": "Git commit SHA of the verify/fix artifact commit. Recorded via the two-commit Git Commit Protocol (shared-conventions.md) so it points at the artifact commit, never an orphaned amend." },
+        "verifiedStageVersion": { "type": ["integer", "null"], "description": "The production stage's `version` at the moment this verify was resolved. The navigator's freshness ledger compares it to the stage's current `version`: equal means the verify is fresh; a mismatch (artifact revised since) or an absent field (legacy state) means stale, so auto-verify re-fires. Recorded by forge-verify/forge-fix when writing a passed/findings-applied status." },
+        "scheduledAt": { "type": ["string", "null"], "format": "date-time", "description": "UTC ISO-8601 timestamp at which unattended in-stage verification was scheduled for this entry. Written alongside the `auto-verify-pending` status and DELETED (not nulled) by any terminal result, so an absent field means 'not scheduled'." },
+        "scheduledStageVersion": { "type": ["integer", "null"], "minimum": 1, "description": "The artifact revision current when verification was scheduled — the production stage's `version` for a feature, the epic manifest's `revision` for an epic. Makes rescheduling idempotent (an identical revision does not rewrite the entry) and lets a read tell debt owed on the current artifact from debt stranded on an older one. Deleted by any terminal result." }
+      }
+    }
+  }
+}

package/adapters/pi/references/forge-config-schema.json

@@ -67,6 +67,12 @@
       "default": true,
       "description": "When true (default), the /skill: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,
@@ -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",