@garygentry/feature-forge 0.2.3 → 0.2.4

package/adapters/copilot/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/*/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/copilot/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/*/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/*/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/*/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/*/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/copilot/skills/forge-fix/forge-fix.md

@@ -8,6 +8,15 @@ 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 the `/feature-forge:forge` navigator 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). 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
+navigator 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 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 +63,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 the navigator invoked you as part of an `autoFix` chain** (`skills/forge/SKILL.md` §3b step 2b): there the navigator 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 navigator 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/copilot/skills/forge-guide/forge-guide.md

@@ -0,0 +1,188 @@
+---
+# 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), `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` (fixing stays human-gated
+unless `autoFix: true`). **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/copilot/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/*/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,36 @@ 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 stage completes)
+- `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 after each stage
+> completes — it never needs a clear your session / start a fresh session and only returns a compact digest to your session.
+> **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/copilot/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/*/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/copilot/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/*/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/cursor/references/forge-config-schema.json

@@ -16,7 +16,8 @@
     },
     "backlogDir": {
       "type": ["string", "null"],
-      "description": "Optional override for backlog location. If set, backlog.json is written here instead of with the feature specs. Default behavior (null): backlog.json is written to {specsDir}/{feature}/backlog.json."
+      "default": null,
+      "description": "Optional override for the backlog root. If set, the backlog is written to {backlogDir}/{feature}/backlog.json — the {feature} subdirectory is always composed in so multi-feature epics never collide. Default behavior (null): backlog.json is written to {specsDir}/{feature}/backlog.json with the feature specs."
     },
     "gitCommitAfterStage": {
       "type": "boolean",
@@ -61,6 +62,27 @@
       "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."
     },
+    "autoVerify": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the /feature-forge:forge navigator automatically runs forge-verify after a stage completes, with no prompt. forge-verify runs in a fresh forge-verifier subagent (clean-room), so it never needs a context clear and costs the current session only a compact findings digest. Default false preserves today's manual-gate behavior. Ignored on non-Claude hosts, which always fall back to printing the verify command. Per-stage overrides in autoVerifyStages take precedence."
+    },
+    "autoVerifyStages": {
+      "type": "object",
+      "default": {},
+      "description": "Per-stage overrides for autoVerify. Maps a production stage id to a boolean; the effective value for a stage is autoVerifyStages[stage] if present, else autoVerify. Keys are constrained to the five verify-capable stages so a typo (e.g. 'forge-1-prod') is a schema error, not a silent no-op. forge-6-docs has no verify step and is not a valid key.",
+      "propertyNames": {
+        "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop"]
+      },
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "autoFix": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the navigator chains forge-fix automatically after an auto-verify that finds issues. Honored ONLY when auto-verify is effectively on for the stage, and ONLY when preconditions hold (findings doc has zero unresolved decision points, working tree is clean, and a mandatory re-verify passes) — otherwise it falls back to surfacing the findings digest and prompting. Default false keeps fixing human-gated."
+    },
     "contextWindowTokens": {
       "type": ["integer", "null"],
       "default": null,
@@ -190,8 +212,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.11.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.11.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.11.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.12.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.12.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.12.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/cursor/references/pipeline-state-schema.json

@@ -80,7 +80,7 @@
         "completedAt": { "type": ["string", "null"], "format": "date-time" },
         "commitHash": {
           "type": ["string", "null"],
-          "description": "Git commit SHA after this stage completed"
+          "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",
@@ -107,7 +107,8 @@
         },
         "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
         "fixedAt": { "type": ["string", "null"], "format": "date-time" },
-        "commitHash": { "type": ["string", "null"] }
+        "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." }
       }
     }
   }

package/adapters/cursor/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```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/*/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; }
 ```
 
@@ -24,7 +24,7 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```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/*/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
 ```

package/adapters/cursor/references/process-overview.md

@@ -36,6 +36,16 @@ The pipeline compiles a fuzzy feature idea into a machine-executable `backlog.js
 **Output:** `{specsDir}/{feature}/.verification/VERIFY-<stage>-<timestamp>.md` (includes both findings and a Fix Execution Plan)
 **Method:** Clean-context analysis producing actionable findings with an ordered fix plan.
 
+**Manual or automatic.** By default the navigator offers verification after each stage. Because
+it runs in a fresh, read-only subagent (clean-room by construction, never needs a `/clear`), it is
+safe to automate: set `autoVerify: true` (or per-stage via `autoVerifyStages`) in
+`forge.config.json` and the navigator runs `forge-verify` automatically once a stage completes,
+returning only a compact digest to the session. The freshness ledger (verify entries record the
+artifact `version` they ran against) means a stage is re-verified only when its artifact changes,
+and an explicitly `skipped` verify is respected. Fixing stays human-gated unless `autoFix: true` is
+also set, which chains `forge-fix` only when preconditions hold (zero unresolved decisions, clean
+tree, passing re-verify). See `references/shared-conventions.md` for the config keys.
+
 After verification, fixes can be applied via:
 - `/feature-forge:forge-fix <feature>` — reads the Fix Execution Plan from the findings document and applies changes (works in any session)
 - Plan mode workflow — enter plan mode, run verify, review plan, exit and execute