@garygentry/feature-forge 0.3.2 → 0.3.5

package/README.md

@@ -74,7 +74,7 @@ Claude Code users can alternatively install via the plugin marketplace:
 
 The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
 [`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
-read-only resolvability preflight on the pin (`@garygentry/rauf@0.13.0`) and records it; pass
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.14.0`) and records it; pass
 `--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
 `npx @garygentry/rauf` or its
 [binary script](https://github.com/garygentry/rauf#install). See the

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

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

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

@@ -18,6 +18,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 Agent tool 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/Task tool. 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
@@ -60,7 +62,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/claude/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/claude/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/claude/references/forge-config-schema.json

@@ -67,6 +67,12 @@
       "default": true,
       "description": "When true (default), the /feature-forge:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
     },
+    "docsStage": {
+      "type": "string",
+      "enum": ["prompt", "skip"],
+      "default": "prompt",
+      "description": "How forge-6-docs' Documentation Decision Gate behaves at stage entry. \"prompt\" (default) asks generate-vs-skip once per run; \"skip\" records the stage as deliberately skipped with no prompt — the skill runs the state-skip verb and closes the pipeline honestly (stage-exit --outcome skipped), so docs are never implied-mandatory for teams that document differently. The gate's refuse-to-erase guard still applies: docs that already exist are never silently reclassified, whatever this is set to. Read directly by forge-6-docs (not part of loopRunner resolution); an unrecognized or absent value behaves as \"prompt\"."
+    },
     "autoVerify": {
       "type": "boolean",
       "default": false,
@@ -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",
@@ -217,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.13.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.13.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.13.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.14.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.14.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.14.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/claude/references/forge-decisions-schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "forge-decisions",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "feature", "createdAt", "updatedAt", "decisions"],
+  "properties": {
+    "schemaVersion": { "type": "string", "enum": ["1"] },
+    "feature":       { "type": "string" },
+    "createdAt":     { "type": "string" },
+    "updatedAt":     { "type": "string" },
+    "decisions":     { "type": "array", "items": { "$ref": "#/definitions/decision" } }
+  },
+  "definitions": {
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["itemId", "question", "answer", "deferred", "decidedAt",
+                   "recordedBy", "appliedAt", "appliedBy"],
+      "properties": {
+        "itemId":     { "type": "string" },
+        "question":   { "type": "string" },
+        "answer":     { "type": ["string", "null"] },
+        "deferred":   { "type": "boolean" },
+        "clusterId":  { "type": "string" },
+        "decidedAt":  { "type": "string" },
+        "recordedBy": { "type": "string" },
+        "appliedAt":  { "type": ["string", "null"] },
+        "appliedBy":  { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/adapters/claude/references/pipeline-state-schema.json

@@ -37,7 +37,7 @@
     },
     "notes": {
       "type": "string",
-      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away). A single string with latest-note-wins semantics: `state-note` (its only sanctioned writer) OVERWRITES the previous value — an author folds any still-relevant earlier note into the one combined string. Read by the navigator dashboard AND by each downstream stage's Step 1 carried-over note check (forge-2-tech through forge-5-loop), which surfaces it as stage input; it never overrides artifacts or config."
     },
     "epicChangeRequests": {
       "type": "array",
@@ -127,7 +127,7 @@
         "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
         "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
         "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
-        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/docsStageEntry" },
         "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
         "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
         "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
@@ -165,6 +165,38 @@
         }
       }
     },
+    "docsStageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "description": "The forge-6-docs stage entry: identical to stageEntry except that `skipped` is a legal status and `skippedAt` records when the deliberate skip was written (by the `state-skip` verb, never by hand). `skipped` is a terminal, done-for-selection status — the pipeline ends without the stage claiming artifacts it never produced (#197). Deliberately scoped to the docs stage: a skipped PRD or specs stage is not a representable state, so the shared stageEntry enum does NOT carry `skipped`.",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale", "skipped"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "skippedAt": { "type": ["string", "null"], "format": "date-time", "description": "UTC ISO-8601 timestamp of the deliberate skip (status: skipped). Written by `state-skip`; absent on every other status." },
+        "commitHash": {
+          "type": ["string", "null"],
+          "description": "Git commit SHA of this stage's artifact commit (Commit 1 of the two-commit Git Commit Protocol in shared-conventions.md). Written by a small follow-up commit so it points at the artifact commit itself, never at an orphaned amend or the hash-recording commit. null until recorded (or when there was no new artifact commit)."
+        },
+        "basedOnVersions": {
+          "type": "object",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
     "verifyEntry": {
       "type": "object",
       "required": ["status"],

package/adapters/claude/references/ralph-loop-contract.md

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

package/adapters/claude/references/shared-conventions.md

@@ -36,7 +36,7 @@ I found that the codebase uses React and TanStack Router.
 
 ### Decision Support: Help the User Choose
 
-When an `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
+When a question posed through `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
 
 - **Lead with a recommended option.** Place it first and label it `(recommended)` (matching the `AskUserQuestion` "(Recommended)" convention).
 - **Put the trade-off in each option's `description`.** Say why you'd pick it and what you give up versus the alternatives — the cost, not just the benefit.
@@ -53,6 +53,17 @@ For genuinely comparable artifacts (competing module structures, two code snippe
 
 The **Branch Setup** block below is the reference pattern: a strong recommendation as the first option, rationale inline, the alternative still available, never a hard-stop.
 
+## Stage Review Gate
+
+Every authoring stage ends its "Review with User" step in exactly one of two shapes. Which shape a stage uses is declared **here, once** — each stage's review step points at this block by title, and the shape is never re-derived from the surrounding prose or inferred from how sibling stages behave (three stages block and one does not; majority-shape inference is precisely the failure this block exists to prevent):
+
+- **Blocking review (gate).** The stage presents the artifact and collects feedback through `AskUserQuestion`; it does **not** proceed until the user answers, iterating until they confirm. Stages: **forge-1-prd** (Step 5), **forge-2-tech** (Step 6), **forge-3-specs** (Step 6).
+- **Non-blocking review (invitation).** The stage states the artifact is ready and invites adjustments **as a statement, not a question** — and then **proceeds to the next step in the same turn unless the user asks for changes**. The invitation obliges the agent to *continue*: emitting the invitation sentence and stopping treats the non-gate as a gate and strands the stage `in-progress` with its completion step unrun — a defect, not caution. Stage: **forge-4-backlog** (Step 6).
+
+**Why the shapes differ.** A blocking review guards an artifact whose content was just authored from open-ended interview or synthesis — the user is the only authority on "complete", so the stage must wait. forge-4's backlog is *derived* from specs the user already approved, was planned interactively in its Step 3, and is machine-validated in its Step 5; a second hard gate would re-ask a settled question, and the loop never launches without forge-5-loop's own Step 2d confirmation anyway. The invitation is a courtesy checkpoint, not an approval gate (removed deliberately in #78's consistency sweep).
+
+A stage that changes shape changes it **in this block first**; the per-stage pointer stays a pointer.
+
 ## Configuration Reading
 
 Read `forge.config.json` from the project root. If it doesn't exist, use defaults.
@@ -130,7 +141,7 @@ mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
 ```
 
-If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
+If the host is Claude (the Claude-native question tool is available), also ensure the Claude-framed variant:
 
 ```bash
 R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
@@ -191,7 +202,7 @@ Pipeline state is written by the `state-*` verbs of `scripts/forge-session.py`
 
 If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbatim, do **not** proceed to the next step of the surrounding protocol, and do **not** hand-author the JSON as a workaround. The stage remains resumable because the entry stamp is already on disk — re-run the verb once the cause is fixed.
 
-**The eight `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
+**The nine `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-skip` (the deliberate forge-6-docs documentation skip — scoped to that one stage; writes `status: "skipped"` + `skippedAt`, refuses to erase a record of docs that exist, and is the only sanctioned writer of a skipped docs stage), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
 
 ### `state-verify` — verification results and provenance
 
@@ -395,7 +406,7 @@ Invoke this block **at the head of any post-entry step that writes a stage artif
 
 1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
 
-2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same warning via `AskUserQuestion` ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
 
 When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
 

package/adapters/claude/references/stage-exit-protocol.md

@@ -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 |
@@ -100,9 +100,9 @@ Obey the DIRECTIVES it prints, in the consumption order this protocol fixes: sur
 
 The stamp is shown with `--host claude`; 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,8 +110,9 @@ 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:
 
@@ -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
@@ -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