@garygentry/feature-forge 0.2.3 → 0.2.5

package/adapters/gemini/skills/forge-5-loop/references/result-reporting.md

@@ -4,15 +4,20 @@ These are the five verbatim result-report output templates for **Step 4b** of
 `forge-5-loop/SKILL.md`. Pick **every** branch that applies (a run can be both
 blocked and needs-human) and render its report.
 
-**All items done:**
+**All items done.** Print the completion summary, then close with the **warm-acceptable
+variant** of the Stage Exit Protocol (single-sourced in
+`references/stage-exit-protocol.md`) — the `forge-5-loop → forge-6-docs` boundary is the
+one place where clearing before the next stage is optional:
 ```
 Loop completed for {feature}. All {N} items implemented successfully.
-
-Next steps:
-  - /feature-forge:forge-verify {feature} impl   Verify the implementation
-  - /feature-forge:forge-6-docs {feature}         Generate architecture docs
 ```
 
+**The loop is complete — this is the one boundary where clearing before the next stage is optional.**
+
+1. **Verify is already offered above.** Impl-verify is offered interactively right after this report (Step 5b for a standalone feature, Step 6.1 for an epic member) — run it there rather than as a second gate. It runs clean-room, so it needs no fresh session.
+2. **Clearing is optional here — warm is fine.** `forge-6-docs` benefits from the still-warm context of what the loop actually did, so continuing in this same session is the easy default. A cold start also works — every artifact is on disk — but there is no need to force it.
+3. **Then run `/feature-forge:forge-6-docs {feature}`** — in this warm session, or a fresh one if you prefer.
+
 **Runner review pass.** A review flag (e.g. rauf's `--review`) makes the runner run
 a post-loop review that **auto-creates and implements fix items** rather than handing
 findings to the user — distinct from `forge-verify impl` (a clean-context audit that

package/adapters/gemini/skills/forge-6-docs/forge-6-docs.md

@@ -43,18 +43,18 @@ Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent**
 If the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`, run:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 If `render-status` fails, skip the epic-level offer and proceed with the per-feature docs only; surface the error per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
 
-**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), use the host's question mechanism to offer:
+**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), offer the extra doc as a statement the user can take or leave — not a forced question:
 
-"All {total} features in the '{epic}' epic are complete. Generate an **epic-level architecture document** spanning the features, in addition to {feature}'s per-feature docs?"
+"All {total} features in the '{epic}' epic are complete. I can also generate an **epic-level architecture document** spanning the features, alongside {feature}'s per-feature docs — say the word and I'll add it."
 
-On yes, synthesize a doc at **`{docsDir}/{epic}/`** sourced from: the `EPIC.md` narrative, each member's per-feature docs, and the manifest contracts (each feature's `exposes`/`consumes`). When the epic-level doc is written, the Step 5 commit also stages `{docsDir}/{epic}/`.
+If the user asks for it, synthesize a doc at **`{docsDir}/{epic}/`** sourced from: the `EPIC.md` narrative, each member's per-feature docs, and the manifest contracts (each feature's `exposes`/`consumes`). When the epic-level doc is written, the Step 5 commit also stages `{docsDir}/{epic}/`.
 
 If not all members are complete (or the feature has no `epic` back-pointer), **do not offer** — the per-feature doc flow proceeds unchanged.
 
@@ -96,7 +96,7 @@ Based on feature complexity and existing doc conventions, propose a doc plan:
     └── adr-001-*.md   — Architecture decision records (if significant decisions were made)
 ```
 
-Present the plan and use the host's question mechanism to get the user's confirmation.
+Present the plan as a statement and invite edits before writing — not a forced confirmation gate: "Here's the doc plan I'll generate. Tell me if you want to add, remove, or restructure any documents; otherwise I'll proceed." Write the docs unless the user asks for changes.
 
 ## Step 3: Write Documentation
 
@@ -175,7 +175,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
    - Set `currentStage` to `complete`
    - Record `artifacts`
    - Set `stages.forge-6-docs.basedOnVersions` to include versions for all completed upstream stages. Always include forge-1-prd, forge-2-tech, forge-3-specs. Include forge-4-backlog and forge-5-loop ONLY if they have status `complete`.
-2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (`git add {docsDir}/{feature}/ {resolvedFeatureDir}/` — and **also** `{docsDir}/{epic}/` when an epic-level doc was written in Step 1), attempt commit with message `"{commitPrefix}({feature}): complete architecture docs"`, then set `stages.forge-6-docs.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (`git add {docsDir}/{feature}/ {resolvedFeatureDir}/` — and **also** `{docsDir}/{epic}/` when an epic-level doc was written in Step 1), attempt commit with message `"{commitPrefix}({feature}): complete architecture docs"` (marking `stages.forge-6-docs.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.
 4. Tell user: "Documentation complete. Feature pipeline for '{feature}' is finished!\n  `/feature-forge:forge {feature}` to see the final pipeline status."
 
 ## Gotchas

package/adapters/gemini/skills/forge-bootstrap/forge-bootstrap.md

@@ -58,7 +58,7 @@ Every bash invocation begins with the byte-identical portable-root prelude, then
 helper. Pass `--specs-dir ./specs` (the default) so the gate allow-lists the specs directory.
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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-bootstrap.py" check "<target-dir>" --json --specs-dir ./specs
 ```
@@ -135,7 +135,7 @@ when running under a Claude host (e.g. the host's question mechanism is availabl
 `CLAUDE.md` only when `host == "claude"`.
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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-bootstrap.py" scaffold "<target-dir>" --json --answers '<Answers JSON>'
 ```
@@ -143,7 +143,7 @@ python3 "$R/scripts/forge-bootstrap.py" scaffold "<target-dir>" --json --answers
 ### Step 5 — verify
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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-bootstrap.py" verify "<target-dir>" --json --answers '<Answers JSON>'
 ```
@@ -169,7 +169,7 @@ and removes the sentinel before staging so it never enters history. Read
 leave the sentinel in-progress (resumable) — do **not** declare success.
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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-bootstrap.py" commit "<target-dir>" --json --answers '<Answers JSON>' [--stage-only]
 ```

package/adapters/gemini/skills/forge-fix/forge-fix.md

@@ -8,6 +8,17 @@ description: Apply fixes from the most recent forge-verify findings document. Us
 
 Apply fixes from the most recent forge-verify findings document, with step-level tracking for crash recovery.
 
+Usually invoked by the user, but an **`autoFix` caller** may also invoke this skill automatically
+when `autoFix: true` is configured **and** its preconditions hold (the findings document has zero
+unresolved decision points, the working tree is clean, and a mandatory re-verify passes afterward).
+Two callers drive that chain: an **authoring stage's in-stage auto-verify** (the primary path — see
+`references/stage-exit-protocol.md`, the in-stage verify block) and the **`/feature-forge:forge`
+navigator's catch-up** (§3b). The **fix application** below is identical either way — this skill is
+not "auto-aware" about *applying* findings; it always applies the latest findings document. The
+**caller** owns the gating decisions, including the closing re-verify: the Step 6 gate is presented
+**only on a direct invocation**, because under an `autoFix` chain the caller (stage skill or
+navigator) runs the mandatory re-verify itself.
+
 ## Prerequisites
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
@@ -54,14 +65,26 @@ Follow the Git Commit Protocol in `references/shared-conventions.md`.
 1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
    - Set the relevant `forge-verify-*` entry status to `findings-applied`
    - Record `fixedAt` timestamp
-2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files (`git add {resolvedFeatureDir}/` — or `{specsDir}/{epic}/` for an epic member so the member-state change commits atomically with the epic subtree), attempt commit with message `"{commitPrefix}({feature}): apply {mode} verification fixes"`, then record commit hash only on success.
+   - Record `verifiedStageVersion` = the current `version` of the production stage entry
+     this verify covers (e.g. fixing `tech` findings → `stages["forge-2-tech"].version`).
+     This keeps the navigator's freshness ledger accurate after a fix, so the verified
+     stage reads as `fresh` and auto-verify does not needlessly re-fire on an unchanged
+     artifact. (If the fix itself bumped the production stage's `version`, use the new
+     value so the ledger reflects what was actually verified/fixed.)
+2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files (`git add {resolvedFeatureDir}/` — or `{specsDir}/{epic}/` for an epic member so the member-state change commits atomically with the epic subtree), attempt commit with message `"{commitPrefix}({feature}): apply {mode} verification fixes"` (writing `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success.
+
+## Step 6: Re-verify Gate
+
+Fixes are applied and recorded (`findings-applied`), so the stage reads **fresh** in the navigator's ledger (Step 5 set `verifiedStageVersion` to the current version). A re-verify is nonetheless the only thing that *confirms* the fixes actually resolved the findings, so on a **direct/manual** `forge-fix` invocation, **prompt** it rather than leaving it as a passive suggestion — this is the same **Standard Verify Gate** the stage skills stamp (`references/stage-exit-protocol.md`).
+
+**Skip this gate when an `autoFix` caller invoked you as part of a chain** — the authoring stage's in-stage auto-verify (`references/stage-exit-protocol.md`, in-stage verify block) or the navigator's catch-up (`skills/forge/SKILL.md` §3b step 2b): there the caller owns the mandatory re-verify, so a second gate here would block the unattended flow or double the re-verify. Just return and let the caller proceed.
 
-## Step 6: Next Steps
+On a direct invocation, present the gate using the host's question mechanism with these three options — but only when the host has a question mechanism **and** the clean-room path is available (the host's subagent mechanism plus a dispatchable `forge-verifier` subagent):
+- **Re-verify {feature} now** *(recommended)* — dispatch the clean-room `forge-verifier` subagent from this session in require-clean mode to confirm every finding is resolved; the digest returns here so any remaining issue keeps its context. One-time — it does **not** change config.
+- **Re-verify now + enable auto-verify going forward** — re-verify now **and** patch `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every other key) so future stages verify automatically, no prompt. This complements the `forge-init` opt-in. **Do not auto-commit this config change** — treat it like `notes`: a user-facing edit the user commits on their own cadence, never folded into a stage's artifact commit.
+- **Skip for now** — proceed without re-verifying; the fixes are already recorded, so the stage stays `findings-applied` (fresh in the ledger). Run `/feature-forge:forge {feature}` when you want pipeline status.
 
-Tell the user:
-"Fixes applied. Next steps:
-  - Run `/feature-forge:forge-verify {feature}` again to confirm all issues are resolved
-  - Or `/feature-forge:forge {feature}` to see pipeline status"
+**Host / clean-room fallback (not a user-selectable option):** if the question mechanism, the host's subagent mechanism, or the `forge-verifier` subagent is unavailable, do **not** run clean-room — degrade to printing `/feature-forge:forge-verify {feature}` for the user to run inline/manually (mirroring `autoInvokeNextStage`), and offer the auto-verify enable as plain text only if a config write is possible.
 
 ---
 

package/adapters/gemini/skills/forge-guide/forge-guide.md

@@ -0,0 +1,191 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-guide/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-guide
+description: Explain what feature-forge is, when to use it, how to configure it, and its best practices — advisory guidance, not stage execution. Use when the user or another agent asks what feature-forge is, whether/when to adopt it, how the pipeline works conceptually, how to set up or configure forge.config.json, or for usage tips and best practices. Do NOT trigger to RUN a pipeline stage (use forge-1-prd … forge-6-docs), to show a specific feature's status (use forge), or for general software questions unrelated to feature-forge.
+---
+
+# Feature Forge — Usage & Best-Practices Guide
+
+You are the **guide** for feature-forge: an advisor, not an operator. Your job is to
+explain *what* forge is, *when* to use it, *how* to configure it, and *what the best
+practices are* — in plain language, grounded in the repo's own docs. You do **not**
+run pipeline stages; when the user is ready to act, point them at the right skill.
+
+## How to answer
+
+1. Identify the topic (the argument, or infer from the question).
+2. **Ground yourself in the canonical source before answering** — read the mapped
+   reference file(s) below rather than answering from memory. These are the source
+   of truth and stay current as the pipeline evolves.
+3. Answer concisely, then end with the concrete next command (`/feature-forge:forge-*`)
+   or doc pointer the user should go to.
+
+| Topic | Read first |
+|-------|-----------|
+| Pipeline architecture, stage-by-stage flow | `references/process-overview.md` |
+| Cross-stage conventions (naming, state, git, branch, epic injection) | `references/shared-conventions.md` |
+| Config keys + defaults | `references/forge-config-schema.json` |
+| Stack detection / language profiles | `references/stack-resolution.md`, `references/stacks/*.md` |
+| Loop runner interface, signals & version gate | `references/ralph-loop-contract.md` |
+| Deep dives, glossary, troubleshooting | `references/process-overview.md`, `references/shared-conventions.md` |
+
+Those `references/` files are the guaranteed grounding path — they ship in every install.
+The project's `README.md`, `COMPATIBILITY.md`, and the hosted docs site are richer but are
+**not** part of an installed bundle, so treat them as optional enrichment (offer the docs-site
+URL to a human) and never block an answer on opening them — fall back to the `references/`
+files and your own knowledge.
+
+Do NOT actually invoke stage skills or write files — this skill only explains and directs.
+
+## What feature-forge is
+
+A **feature development pipeline** that refines a vague idea into shipped code through
+discrete, auditable stages — like a compiler for features. Each stage narrows scope and
+adds structure, reading the previous stage's artifacts as standalone contracts:
+
+- **PRD** — *what* to build (requirements only, no technology).
+- **Tech spec** — *how* to build it (design, grounded in the codebase).
+- **Implementation specs** — build-ready detail (types, signatures, contracts, tests).
+- **Backlog** — self-contained work items for autonomous execution.
+- **Loop** — a fresh-context runner implements each item, tests, and commits.
+- **Docs** — architecture reference generated from the real implementation.
+
+`REQ-XXX-NN` requirement IDs form a traceability spine from PRD through implementation.
+**Verification gates** are available after any stage and run clean-room in a fresh subagent.
+
+## When to use it — and when not
+
+**Use forge when:** you have a well-defined feature or small epic to ship; you want
+requirements captured cleanly before coding; you value traceability, thorough spec
+verification, and autonomous loop execution with fresh context per item; you want
+reproducible, auditable artifacts.
+
+**Skip forge when:** the work is an exploratory spike with still-fluid requirements
+(though Stage 1's interview can help clarify them); it's a one-line bug fix or trivial
+patch where pipeline overhead isn't justified; or you're only extending mature code
+along established patterns, where new specs become noise.
+
+**Anti-patterns to warn against:** skipping the PRD and jumping to tech spec (the value
+comes from separating *what* from *how*); treating specs as living contracts (they're
+pre-implementation — drop an `AGENTS.md`/`CLAUDE.md` in the specs dir telling agents to
+ignore drift); forcing an epic for a single feature; relying on conversation memory to
+carry context across stages instead of reading upstream artifacts.
+
+## The pipeline at a glance
+
+| Stage | Skill | Produces |
+|-------|-------|----------|
+| 0 (optional) | `forge-0-epic` | `epic-manifest.json` + `EPIC.md` (members, deps, `exposes`/`consumes` contracts) |
+| 1 | `forge-1-prd` | `PRD.md` with `REQ-*` IDs |
+| 2 | `forge-2-tech` | `tech-spec.md`; detects stack + test/typecheck commands |
+| 3 | `forge-3-specs` | numbered spec suite + `TRACEABILITY.md` |
+| 4 | `forge-4-backlog` | `backlog.json` (self-contained items) |
+| 5 | `forge-5-loop` | implemented code, tested + committed per item |
+| 6 | `forge-6-docs` | architecture docs from the real code |
+| any | `forge-verify` → `forge-fix` | findings report → applied fixes |
+| any | `forge` | status dashboard / navigator |
+
+Drive the whole thing with the **navigator**: `/feature-forge:forge <feature>` shows the
+current stage and offers the next; with `autoInvokeNextStage` it launches it directly.
+
+## Setup & configuration
+
+**First-time setup:** `/feature-forge:forge-init` (existing repo) creates `forge.config.json`
+with defaults. `/feature-forge:forge-bootstrap` scaffolds a *greenfield* (empty) repo to a
+green baseline. On non-Claude agents, install via `npx @garygentry/feature-forge install`.
+
+**Key `forge.config.json` knobs** (authoritative list: `references/forge-config-schema.json`):
+
+- **Paths** — `specsDir` (`./specs`), `docsDir` (`./docs/architecture`), `backlogDir`.
+- **Git** — `gitCommitAfterStage` (true), `commitPrefix` (`forge`); commits use a two-commit
+  protocol so the stage's commit hash is recorded in state without `--amend`.
+- **Branch** — `branchPerFeature` (true), `branchPrefix` (`forge/`): isolate each feature.
+- **Stack** — `stack`, `typeCheckCommand`, `testCommand`: null until Stage 2 auto-detects them.
+- **Context** — `contextWindowTokens`, `contextWarnThreshold` (0.7): the navigator warns to
+  clear your session / start a fresh session past this fullness. On 1M-context models set `contextWindowTokens` explicitly.
+- **Verification** — `autoVerify` (false; when on, each authoring stage verifies in-stage before its exit block), `autoVerifyStages`, `autoFix` (false).
+- **Stage flow** — `autoInvokeNextStage` (true on Claude, print-only elsewhere).
+- **Loop** — `loopRunner` block (binary, command templates, version gate, agent selection);
+  defaults to **rauf** when absent. `workspaces` supports monorepos.
+
+## Verification gates
+
+`forge-verify <feature>` dispatches the read-only `forge-verifier` subagent to find gaps,
+inconsistencies, and quality issues; it writes a findings doc, and `forge-fix` applies them.
+Because verification runs in a **fresh subagent**, it's clean-room by construction — it never
+needs a clear your session / start a fresh session, and it's safe to automate with `autoVerify: true`. When on, the just-completed
+authoring stage runs verify **in-stage** — in the same session, right before its exit block — so
+the digest and any fix land where the context still exists (the navigator only catches up if a
+host couldn't run it clean-room). Fixing stays human-gated unless `autoFix: true`. The cost is one
+extra clean-room verify per stage. **Always verify before Stage 5 (the loop)** — catching errors in
+specs/backlog is far cheaper than mid-loop. Verifying after PRD and after backlog is also
+recommended. A findings pass is fresh only while the artifact `version` matches what was
+verified; revise upstream and downstream re-verifies.
+
+## Context management
+
+Each stage reads upstream artifacts as standalone contracts, so you can (and usually should)
+clear your session / start a fresh session between them:
+
+- **Clear** between PRD → tech, tech → specs, specs → backlog, backlog → loop.
+- **Stay warm** mid-interview (PRD, tech spec) — the interview needs a continuous thread.
+- **No clear needed** for any → verify (runs in a fresh subagent).
+
+The navigator warns when the session passes `contextWarnThreshold` (default 70% full).
+
+## Epics (large changes)
+
+Use Stage 0 only when a change naturally splits into **several interdependent features** that
+must agree on interfaces. `forge-0-epic` produces `epic-manifest.json` + `EPIC.md` with a
+per-member charter, `exposes`/`consumes` contracts, and `dependsOn` edges. Each member then
+runs the normal pipeline with epic context injected. At Stage 5 a **dependency gate** warns if
+a member's dependencies are unmet. Epic support is purely additive — single-feature flows are
+unchanged. Re-run `forge-0-epic` on an existing epic to enter edit mode.
+
+## The loop
+
+Stage 5 runs a configurable runner (**rauf** by default) that gives each backlog item a fresh
+agent session — implement → run the verification command → commit on pass. This is why items
+must be truly **self-contained**; context bleed breaks the model. Per-item signals:
+
+- `RAUF_DONE` — item passed; loop continues.
+- `RAUF_BLOCKED` — missing dependency / unclear requirement; set aside, loop continues others.
+- `RAUF_NEEDS_HUMAN` — decision or secret needed; set aside, loop continues.
+
+The loop doesn't pause on blocked items. Supply what's missing, then `rauf resume <path>` to
+retry set-aside items. The runner refuses to start with a **dirty working tree** and enforces
+a minimum runner version (the version gate is described in `references/ralph-loop-contract.md`).
+
+## Best practices & gotchas
+
+- Feature name is **required** for every stage command — never guess or infer it.
+- Verify **before the loop**; a bad spec is cheap to fix now, expensive mid-loop.
+- Keep backlog items self-contained — the loop has zero memory across items.
+- Let stages commit for you; don't hand-edit `.pipeline-state.json` or backlog status.
+- Re-running an upstream stage marks downstream stages **stale** — re-run them rather than
+  reaching for `--force`, which skips prerequisite checks and should be rare.
+- Specs are pre-implementation artifacts, not living docs — don't cite them from generated code.
+- Use the navigator (`/feature-forge:forge <feature>`) to orient; use `forge-verify` to inspect.
+
+## Troubleshooting starters
+
+- **Stage 5 won't start:** backlog exists and is verified? runner installed and ≥ min version?
+  working tree clean? See `references/ralph-loop-contract.md` for the runner contract and version gate.
+- **Loop stopped mid-run:** check the signal — `BLOCKED`/`NEEDS_HUMAN` items are set aside, not
+  failures; the loop keeps going.
+- **Downstream flagged stale:** an upstream stage was revised; re-run the downstream stage.
+- **Where am I?** `/feature-forge:forge <feature>` renders the full pipeline status.
+
+For anything deeper, ground yourself in `references/process-overview.md` and
+`references/shared-conventions.md`, and point the *user* at the hosted docs site —
+<https://garygentry.github.io/feature-forge/> — for the full guides and glossary.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/gemini/skills/forge-init/forge-init.md

@@ -9,7 +9,7 @@ description: Initialize feature-forge configuration in the current project. Use
 Run the initialization script to create `forge.config.json` with default settings:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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; }
 bash "$R/scripts/forge-init.sh"
 ```
@@ -26,9 +26,37 @@ After initialization, the config file will contain defaults for:
 - `autoInvokeNextStage`: `true` (the navigator auto-starts the next stage after you confirm; set `false` to only print the command)
 - `contextWindowTokens`: `null` (the navigator infers the context window; set to your model's window, e.g. `1000000` for a 1M-context model, for accurate context-usage advice)
 - `contextWarnThreshold`: `0.7` (fraction of the window past which the navigator suggests a clean session)
+- `autoVerify`: `false` (set `true` to run `forge-verify` automatically after each authoring stage completes — in-stage, in the same session, before the exit block; it costs an extra clean-room verify per stage, so it trades a little time/tokens for catching errors early)
+- `autoVerifyStages`: `{}` (per-stage overrides for `autoVerify`)
+- `autoFix`: `false` (set `true` to chain `forge-fix` after an auto-verify finds issues)
 
 If `forge.config.json` already exists, the script will not overwrite it.
 
+## Offer auto-verify
+
+The template writes `autoVerify: false`. After the config is created (and only when the script
+actually created it — skip this if it reported the file already exists), offer to turn
+auto-verify on, then write the choice back into `forge.config.json`.
+
+If the host's question mechanism is available, ask exactly one question:
+
+> **Enable auto-verify?** Verification runs in a clean-room subagent in-stage after each
+> authoring stage completes — in the same session, before the exit block, so any fix
+> decision keeps its context. It never needs a clear your session / start a fresh session and only returns a compact digest.
+> **Recommended: on.** (Change later by editing `autoVerify` in `forge.config.json`.)
+
+Options: **Enable (recommended)** / **Leave off**.
+
+- On **Enable**: patch `"autoVerify": false` → `"autoVerify": true` in the generated
+  `forge.config.json` in place, preserving formatting and every other key.
+- On **Leave off**: leave the config as written (`autoVerify: false`).
+
+If the host lacks a structured question tool but can still prompt the user (e.g. Codex asks in
+plain text), use that — ask the one question directly and wait for the reply; it is the same
+choice, just rendered differently. Only when the host has **no** way to ask at all (a fully
+non-interactive / headless run) do you skip the prompt: leave `autoVerify: false` and print the
+one-line note `Set "autoVerify": true in forge.config.json to verify automatically after each stage.`
+
 After initialization, start the pipeline with `/feature-forge:forge-1-prd <feature-name>`.
 
 ---

package/adapters/gemini/skills/forge-verify/forge-verify.md

@@ -47,7 +47,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 
 The verifier(s) are read-only — they return findings as their response; **you** (the
 parent) assemble and write the single document to
-`{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. When you fanned out:
+`{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.
 2. **Dedup** overlaps — when two instances flag the same file+location+issue (e.g. a
@@ -72,15 +72,39 @@ without subagents), fall back to running verification inline in the current sess
 
 **Inline execution guidance:** If running inline (not as subagent), process verification checklists one category at a time to manage context pressure. Load only the artifacts needed for each category, verify, summarize findings, then move to the next category.
 
+### Require-clean (`auto`) mode — unattended auto-verify
+
+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`
+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.
+
+So in require-clean mode, **do NOT fall back to inline execution**. If the host's subagent mechanism
+or `forge-verifier` subagent is not dispatchable, return a **sentinel** instead of doing
+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
+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.
+
 ## Prerequisites
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
+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.
+
 **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
 
-Read `{specsDir}/{feature}/.pipeline-state.json` to understand current pipeline state.
+Read `{resolvedFeatureDir}/.pipeline-state.json` to understand current pipeline state.
 
 ### Mode Selection
 
@@ -100,16 +124,16 @@ If ambiguous, use the host's question mechanism to ask which stage to verify.
 Load into context ALL artifacts for this feature based on mode:
 
 **For prd mode:**
-- `{specsDir}/{feature}/PRD.md`
+- `{resolvedFeatureDir}/PRD.md`
 
 **For tech mode:**
-- `{specsDir}/{feature}/PRD.md`
-- `{specsDir}/{feature}/tech-spec.md`
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
 
 **For specs mode:**
-- `{specsDir}/{feature}/PRD.md`
-- `{specsDir}/{feature}/tech-spec.md`
-- `{specsDir}/{feature}/##-*.md` (all implementation specs)
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
+- `{resolvedFeatureDir}/##-*.md` (all implementation specs)
 
 **For backlog mode:**
 - All of the above, PLUS
@@ -150,7 +174,7 @@ Every finding must include:
 
 ## Step 4: Write Findings Document
 
-Ensure the `.verification/` subdirectory exists, then write findings to `{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`.
+Ensure the `.verification/` subdirectory exists, then write findings to `{resolvedFeatureDir}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`.
 
 **For epic mode**, the target is `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` (the same format, with `{mode}=epic`).
 
@@ -186,9 +210,16 @@ Do NOT embed this question in your text output.
 
 Write pipeline state conforming to `references/pipeline-state-schema.json`.
 
-Update `{specsDir}/{feature}/.pipeline-state.json`:
-- Set the relevant verify entry status to `findings-reported`
+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).
 
 Do NOT mark as `findings-applied` — that happens after the fix pass.
 
@@ -213,13 +244,13 @@ Do NOT mark as `findings-applied` — that happens after the fix pass.
 - Don't verify things that are intentionally left open (check the PRD's "Open Questions" section).
 - If you find zero issues, say so honestly. Don't manufacture findings to seem thorough. But zero findings on a complex feature is suspicious — double-check.
 - The findings document must be self-contained. A fresh agent reading it should be able to apply every fix without needing conversational context from this session.
-- For backlog verification, also run the loop runner's validate command (resolve `loopRunner` from `forge.config.json`, default rauf: `rauf backlog validate . --backlog {backlogDir} --specs-dir {specsDir}/{feature} --json`). Include any findings it reports (exit 1) as verification findings; if the runner isn't installed yet (command missing), note that backlog validation was skipped rather than failing.
+- For backlog verification, also run the loop runner's validate command (resolve `loopRunner` from `forge.config.json`, default rauf: `rauf backlog validate . --backlog {backlogDir} --specs-dir {resolvedFeatureDir} --json`). Include any findings it reports (exit 1) as verification findings; if the runner isn't installed yet (command missing), note that backlog validation was skipped rather than failing.
 - For specs verification, also run the deterministic traceability validator to supplement agent-driven traceability checks. Include any uncovered requirements or orphaned references as findings:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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/validate-traceability.py" {specsDir}/{feature}/PRD.md {specsDir}/{feature}/ --json
+python3 "$R/scripts/validate-traceability.py" {resolvedFeatureDir}/PRD.md {resolvedFeatureDir}/ --json
 ```
 
 ---

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

@@ -192,7 +192,7 @@ findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07 by readi
 manifest, EPIC.md, and completed members' specs.
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 "$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/dist/apply.js

@@ -91,8 +91,9 @@ async function applyCopyInstall(planned, ctx) {
     if (!placementResult.ok)
         return fail(ctx, planned, placementResult.error);
     // No-op short-circuit (REQ-IDEM-01): every action — primary AND placement — unchanged ⇒ zero
-    // writes, manifest untouched.
-    if (allUnchanged(planned)) {
+    // writes, manifest untouched — UNLESS manifest metadata (raufPin) drifted, which must persist
+    // even with no file change (F1) so report / on-disk manifest / a later `list` agree.
+    if (allUnchanged(planned) && !manifestNeedsRewrite(ctx)) {
         return success(ctx, planned);
     }
     const manifest = buildManifest({
@@ -113,6 +114,18 @@ async function applyCopyInstall(planned, ctx) {
         return fail(ctx, planned, wrote.error);
     return success(ctx, planned);
 }
+/**
+ * True when manifest metadata diverges from the prior manifest, so the manifest must be rewritten
+ * even when every file action is "unchanged" (F1). Today the only such field is `raufPin`; a null
+ * prior manifest also counts (there is nothing recorded yet). `updatedAt` is deliberately NOT a
+ * trigger — it is a consequence of writing, so keying on it would defeat the idempotency short-circuit.
+ */
+function manifestNeedsRewrite(ctx) {
+    const prior = ctx.priorManifest;
+    if (prior === null)
+        return true;
+    return prior.raufPin !== ctx.raufPin;
+}
 /** True iff every planned action — primary files and all placement files — is "unchanged". */
 function allUnchanged(planned) {
     return (planned.files.every((f) => f.action === "unchanged") &&
@@ -164,8 +177,8 @@ async function applySymlinkInstall(planned, ctx) {
     const primary = planned.files;
     const primaryUntouched = primary.every((f) => f.action === "unchanged") ||
         primary.every((f) => f.action === "skip-modified");
-    // Nothing changed anywhere ⇒ zero writes, manifest untouched.
-    if (allUnchanged(planned)) {
+    // Nothing changed anywhere ⇒ zero writes, manifest untouched — unless raufPin drifted (F1).
+    if (allUnchanged(planned) && !manifestNeedsRewrite(ctx)) {
         return success(ctx, planned);
     }
     // The recorded mode/link reflect the primary namespace dir: only (re)link when it actually changed
@@ -285,12 +298,25 @@ async function applyMirror(pl, ctx, source, prior) {
             case "skip-modified": {
                 // Carry the prior record forward; if none exists (e.g. a v1→v2 manifest migration where the
                 // file is already on disk), reconstruct it by hashing the destination so the inventory stays
-                // faithful rather than silently dropping an unrecorded-but-present file.
+                // faithful rather than silently dropping an unrecorded-but-present file. Guard the hash: a
+                // TOCTOU vanish (file removed after planning) must yield an err Result, never throw ENOENT
+                // out of apply (REQ-OBS-03 — a throw would abort every sibling agent at the CLI boundary).
                 const p = priorByPath.get(fa.relpath);
-                if (p !== undefined)
+                if (p !== undefined) {
                     inventory.push(p);
-                else
-                    inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                }
+                else {
+                    try {
+                        inventory.push({ path: fa.relpath, sha256: sha256File(destAbs) });
+                    }
+                    catch {
+                        return err({
+                            code: "UNEXPECTED",
+                            agent: ctx.agent,
+                            message: `mirror file "${fa.relpath}" vanished before it could be recorded (${destAbs})`,
+                        });
+                    }
+                }
                 break;
             }
         }