@garygentry/feature-forge 0.1.4 → 0.1.5

package/README.md

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

package/adapters/GENERATION-REPORT.md

@@ -31,6 +31,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
@@ -58,6 +59,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
@@ -85,6 +87,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
@@ -112,6 +115,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
@@ -121,7 +125,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 These files are transported byte-for-byte from canon into every `adapters/<agent>/` bundle and intentionally carry **no** provenance header (a header would break byte-identity / corrupt parsed files):
 
 - `scripts/forge-root.sh` → `adapters/<agent>/scripts/forge-root.sh` (mode 0755, byte-identical — REQ-GEN-05).
-- the whole repo-root `references/` tree (14 files: 9 root + `stacks/`×5) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
+- the whole repo-root `references/` tree (16 files: 9 root + `stacks/`×5 + `templates/specs-hygiene/`×2) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
 - each skill's own `references/` subdir → `adapters/<agent>/skills/<name>/references/` (verbatim, where present).
 
 Regenerate all adapter output with `python3 scripts/build-adapters.py`.

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

@@ -15,8 +15,8 @@
       "description": "Root directory for generated architecture documentation."
     },
     "backlogDir": {
-      "type": "string",
-      "description": "Optional override for backlog location. If set, backlog.json is written here instead of with the feature specs. Default behavior: backlog.json is written to {specsDir}/{feature}/backlog.json."
+      "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."
     },
     "gitCommitAfterStage": {
       "type": "boolean",
@@ -28,17 +28,27 @@
       "default": "forge",
       "description": "Prefix for conventional commit messages, e.g., forge(auth): complete PRD"
     },
-    "stack": {
+    "branchPerFeature": {
+      "type": "boolean",
+      "default": true,
+      "description": "Offer to create an isolated git branch when a feature/epic starts on the default branch (main/master). Gated only on the project using git — independent of gitCommitAfterStage. When false, forge never prompts for a branch and works on whatever branch is checked out. See the Branch Setup block in references/shared-conventions.md."
+    },
+    "branchPrefix": {
       "type": "string",
-      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually. Examples: 'typescript', 'python', 'go', 'rust'."
+      "default": "forge/",
+      "description": "Prefix for the branch name suggested by Branch Setup, e.g. 'forge/' yields 'forge/{feature}' or 'forge/{epic}'. Ignored when branchPerFeature is false."
+    },
+    "stack": {
+      "type": ["string", "null"],
+      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually (null until then). Examples: 'typescript', 'python', 'go', 'rust'."
     },
     "typeCheckCommand": {
-      "type": "string",
-      "description": "Command to verify type correctness or lint. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
+      "type": ["string", "null"],
+      "description": "Command to verify type correctness or lint. Null until set. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
     },
     "testCommand": {
-      "type": "string",
-      "description": "Command to run tests. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
+      "type": ["string", "null"],
+      "description": "Command to run tests. Null until set. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
     },
     "loopIterationMultiplier": {
       "type": "number",
@@ -46,6 +56,22 @@
       "minimum": 1,
       "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
     },
+    "workspaces": {
+      "type": "array",
+      "description": "Monorepo members. Absent for single-package projects.",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "stack"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string"},
+          "path": {"type": "string", "description": "Repo-relative member dir"},
+          "stack": {"type": "string"},
+          "typeCheckCommand": {"type": ["string", "null"]},
+          "testCommand": {"type": ["string", "null"]}
+        }
+      }
+    },
     "loopRunner": {
       "type": "object",
       "description": "The autonomous loop runner feature-forge drives. Defaults to rauf when absent (forge-5 states 'defaulting to rauf loop runner'). Every command is a template — {bin}, {backlogDir}, {specsDir}, {iterations} are substituted at call time — so an alternative ralph-style runner conforming to rauf's SPEC-BACKLOG-TOOL-CONTRACT.md can be swapped in without editing any skill. See references/ralph-loop-contract.md.",
@@ -147,8 +173,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.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.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.7.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.8.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.8.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.8.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

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

@@ -18,6 +18,10 @@
       "type": "string",
       "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
     },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
     "createdAt": {
       "type": "string",
       "format": "date-time"

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

@@ -2,12 +2,20 @@
 
 This document describes the end-to-end feature development pipeline managed by the feature-forge plugin. All forge skills reference this document to understand the overall flow and their position within it.
 
+The pipeline compiles a fuzzy feature idea into a machine-executable `backlog.json`. Each stage narrows the idea down and adds structure, verification gates catch gaps before they reach later stages, and a swappable autonomous loop runner (rauf by default) implements the backlog in fresh per-item sessions.
+
 ## Pipeline Stages
 
 ```
-forge-1-prd → forge-2-tech → forge-3-specs → forge-verify → forge-4-backlog → forge-verify → forge-5-loop → forge-verify → forge-6-docs
+[forge-0-epic] → forge-1-prd → forge-2-tech → forge-3-specs → forge-verify → forge-4-backlog → forge-verify → forge-5-loop → forge-verify → forge-6-docs
+   (optional)
 ```
 
+### Stage 0: Epic (`/feature-forge:forge-0-epic <epic>`), optional
+**Input:** A change too large for one feature
+**Output:** `{specsDir}/{epic}/epic-manifest.json` + `EPIC.md` + one member-feature dir per feature
+**Method:** Decomposition interview splitting the change into member features with declared dependencies and `exposes`/`consumes` contracts. Purely additive: single-feature flows are unchanged. See [docs/architecture/epic-orchestration/README.md](../docs/architecture/epic-orchestration/README.md).
+
 ### Stage 1: PRD (`/feature-forge:forge-1-prd <feature>`)
 **Input:** User's feature idea and domain knowledge
 **Output:** `{specsDir}/{feature}/PRD.md`
@@ -35,13 +43,13 @@ After verification, fixes can be applied via:
 
 ### Stage 4: Backlog (`/feature-forge:forge-4-backlog <feature>`)
 **Input:** Full spec suite
-**Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/backlog.json` if backlogDir is configured)
+**Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if backlogDir is configured)
 **Method:** Generate structured backlog items with spec references, acceptance criteria, and dependencies. Backlog is collocated with feature specs by default.
 
 ### Stage 5: Rauf Loop (`/feature-forge:forge-5-loop <feature>`)
 **Input:** `backlog.json` from Stage 4
 **Output:** Implemented source code (committed per-item by rauf)
-**Method:** Execute the rauf autonomous coding loop against the feature's backlog. Spawns a fresh Claude Code session per backlog item with full spec context.
+**Method:** Execute the autonomous coding loop against the feature's backlog. Spawns a fresh session per backlog item with full spec context. rauf is the default runner but is swappable via the `loopRunner` block in `forge.config.json`; see [`references/ralph-loop-contract.md`](./ralph-loop-contract.md).
 
 ### Stage 6: Documentation (`/feature-forge:forge-6-docs <feature>`)
 **Input:** Specs + implementation
@@ -71,7 +79,9 @@ Read `forge.config.json` from project root for path overrides. See `references/f
 
 ## Git Workflow
 
-Recommended: create a `forge/{feature}` branch before starting the pipeline. All forge commits go to this branch. After implementation, merge to your development branch.
+Recommended: forge work lives on an isolated `forge/{feature}` (or `forge/{epic}`) branch so all commits land together and review as one branch. The entry stages (`forge-1-prd`, `forge-0-epic`) detect whether you're on the default branch (main/master) and **strongly recommend** creating that branch when you are — still letting you decline and stay. The chosen branch is recorded in `.pipeline-state.json`, and `forge-5-loop` re-checks it before the autonomous loop starts committing per item. After implementation, merge to your development branch.
+
+To customize: `branchPrefix` (default `forge/`) sets the branch name, and `branchPerFeature: false` disables the prompt entirely (forge then works on whatever branch is checked out). Branch Setup is gated only on the project using git — independent of `gitCommitAfterStage`.
 
 If you prefer manual commit control, set `gitCommitAfterStage: false` in `forge.config.json`.
 

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

@@ -48,6 +48,8 @@ Extract these config values (use defaults if not present):
 - `backlogDir` (default: null — backlog lives at `{specsDir}/{feature}/backlog.json`; when `backlogDir` is configured, forge-4 composes `{backlogDir}/{feature}/`)
 - `gitCommitAfterStage` (default: true)
 - `commitPrefix` (default: `forge`)
+- `branchPerFeature` (default: true)
+- `branchPrefix` (default: `forge/`)
 - `loopIterationMultiplier` (default: `1.5`)
 - `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
 
@@ -79,6 +81,27 @@ A directory counts as a **feature** only if it directly contains a `.pipeline-st
 
 **Compatibility:** for a standalone feature the resolver returns its flat path with no epic logic engaged (REQ-COMPAT-01/02) — standalone-feature behavior is unchanged. A pre-existing latent name collision is reported for manual cleanup by the navigator / forge-verify epic mode (CHECK-E08), not by aborting an unrelated command whose name resolves to exactly one dir (tech-spec §3.4).
 
+## Specs Directory Hygiene
+
+Whenever a stage creates the specs tree for the first time (the first PRD or epic written under `{specsDir}/`), ensure a spec-directory agent-instruction file exists at the **specsDir root**. This tells coding agents in the project that the specs here are pre-implementation artifacts — not live contracts to enforce against the code. It is **idempotent: never overwrite an existing file** (the project may have edited it).
+
+Run this after creating the feature/epic directory, before the stage's git commit:
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/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; }
+mkdir -p "<specsDir>"
+[ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
+```
+
+If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
+
+```bash
+[ -f "<specsDir>/CLAUDE.md" ] || cp "$R/references/templates/specs-hygiene/CLAUDE.md" "<specsDir>/CLAUDE.md"
+```
+
+Stage any file this writes (`{specsDir}/AGENTS.md`, and `{specsDir}/CLAUDE.md` when written) as part of the stage's existing git commit.
+
 ## Epic Context Injection
 
 After resolving the feature directory, check the feature's `.pipeline-state.json` for an `epic` back-pointer. **If absent, skip this block entirely** (standalone feature — REQ-COMPAT-01; standalone-feature behavior is unchanged). **If present**, load exactly the following context, and nothing transitive (REQ-CTX-01):
@@ -110,6 +133,29 @@ When loading upstream artifacts as prerequisites, check `basedOnVersions` in the
 
 > "This stage was built against {upstream} v{old}, but {upstream} is now at v{new}. The current artifacts may be outdated. Consider re-running this stage, or use --force to proceed with potentially stale inputs."
 
+## Branch Setup
+
+Invoke this block at the **very start** of a pipeline entry point — `forge-1-prd` (standalone feature) and `forge-0-epic` (epic) — **before** any directory resolution or interview, so the rest of the run lands on the intended branch. `{label}` is the feature name (forge-1-prd) or epic name (forge-0-epic); `{scope}` is `feature` or `epic` correspondingly.
+
+**Gate.** Run this block only when the project uses git (a `.git` directory resolves) **and** `branchPerFeature` is true. It is **independent of `gitCommitAfterStage`** — branch isolation matters whether or not forge auto-commits. If `branchPerFeature` is false, skip silently.
+
+**Epic-member inheritance.** In `forge-1-prd`, if the feature has an `epic` back-pointer (an `epic` field resolves via Epic Context Injection, or the directory is nested under an epic), the epic already established the branch in `forge-0-epic`. Skip the prompt — inherit the current branch.
+
+**Detection, then a branch-aware prompt:**
+
+1. Read the current branch: `git rev-parse --abbrev-ref HEAD`.
+2. Determine the default branch: `git symbolic-ref --quiet refs/remotes/origin/HEAD` (strip to the last path segment); if that fails, fall back to `main`, else `master` — whichever the repo has.
+3. **If the current branch is NOT the default branch** (the user is already on a topic/`{branchPrefix}*` branch) → record it (see below) and proceed silently. Do not prompt.
+4. **If the current branch IS the default branch** → use `AskUserQuestion` with a **strong recommendation** (still optional):
+
+   > "You're on `{defaultBranch}`. Strongly recommended: create `{branchPrefix}{label}` so this {scope}'s work stays isolated and reviewable as one branch. Create it?"
+   > Options: **Create `{branchPrefix}{label}` (recommended)** · **Stay on `{defaultBranch}`**
+
+   - **Create** → `git switch -c {branchPrefix}{label}` (or `git checkout -b` if `switch` is unavailable). If the branch already exists, `git switch {branchPrefix}{label}`.
+   - **Stay** → proceed on the default branch; note that subsequent commits (and any `forge-5-loop` run) will land directly on `{defaultBranch}`.
+
+**Record the branch.** After this block resolves, write the resulting branch name to the feature's `.pipeline-state.json` top-level `branch` field (create/update it when the state file is first written for this stage). Downstream stages and `forge-5-loop` read it to detect drift back onto the default branch.
+
 ## Git Commit Protocol
 
 When `gitCommitAfterStage` is true, follow this exact order to avoid state inconsistency:

package/adapters/claude/references/templates/specs-hygiene/AGENTS.md

@@ -0,0 +1,23 @@
+# Agent Instructions — `specs/` (feature-forge)
+
+This directory holds **pre-implementation design artifacts** produced by the
+feature-forge pipeline (PRDs, technical specs, numbered implementation specs,
+traceability matrices, and per-feature `backlog.json` files).
+
+## How to treat these specs
+
+- **Specs are not live contracts.** They exist to plan the work and establish the
+  backlog. They are intentionally **not kept in sync** with the implementation as
+  the code evolves.
+- **Do not flag spec↔code divergence.** Once a spec is finalized and its backlog has
+  been implemented, the code is the source of truth for behavior. Do not "fix" the
+  implementation to match a spec, or the spec to match the code, unless a human
+  explicitly asks for it.
+- **Read freely; reference deliberately.** It is fine — encouraged, even — for
+  pipeline artifacts here (specs, `backlog.json`) to cite each other for provenance
+  and context. But implementation artifacts shipped into the project (source code,
+  generated skills/agents, configs, docs) should be self-contained and should **not**
+  reference files under `specs/`, which may be archived or deleted after a feature
+  ships.
+
+This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/claude/references/templates/specs-hygiene/CLAUDE.md

@@ -0,0 +1,22 @@
+# Claude Instructions — `specs/` (feature-forge)
+
+This directory holds **pre-implementation design artifacts** produced by the
+feature-forge pipeline (PRDs, technical specs, numbered implementation specs,
+traceability matrices, and per-feature `backlog.json` files).
+
+## How to treat these specs
+
+- **Specs are not live contracts.** They exist to plan the work and establish the
+  backlog. They are intentionally **not kept in sync** with the implementation as
+  the code evolves.
+- **Do not flag spec↔code divergence.** Once a spec is finalized and its backlog has
+  been implemented, the code is the source of truth for behavior. Don't "fix" the
+  implementation to match a spec, or the spec to match the code, unless I explicitly
+  ask you to.
+- **Read freely; reference deliberately.** It's fine — encouraged, even — for pipeline
+  artifacts here (specs, `backlog.json`) to cite each other for provenance and context.
+  But implementation artifacts shipped into the project (source code, generated
+  skills/agents, configs, docs) should be self-contained and should **not** reference
+  files under `specs/`, which may be archived or deleted after a feature ships.
+
+This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/claude/skills/forge-0-epic/SKILL.md

@@ -87,11 +87,13 @@ python3 "$R/scripts/epic-manifest.py" check-name "{epic}" --specs-dir "{specsDir
 
 ## Creation Branch
 
-### Step 1 — Branch Setup (optional)
+### Step 1 — Branch Setup
 
-If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion`:
-"Create a `forge/{epic}` branch for this epic? (Recommended — keeps epic work isolated.)"
-If yes, create and checkout the branch before proceeding.
+Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{epic}` and
+`{scope}` = `epic`. It self-gates (skips when not a git repo or when `branchPerFeature` is false),
+detects whether you're on the default branch, and strongly recommends — still optionally — creating
+`{branchPrefix}{epic}` when you are. Each member feature's `forge-1-prd` inherits this branch rather
+than prompting again.
 
 ### Step C1 — Epic Framing Interview
 
@@ -176,7 +178,7 @@ Compose the full `epic-manifest.json` per the 00 §2 schema, setting:
 
 Write the composed JSON to `{specsDir}/{epic}/epic-manifest.json` (creating the epic dir first).
 For the *initial* creation write the skill writes the file directly — atomic guarantees are only
-required for in-place mutation, which is the helper mutators' job. Then validate:
+required for in-place mutation, which is the helper mutators' job. Creating the epic dir first creates `{specsDir}/`, so after writing the manifest invoke the **Specs Directory Hygiene** block in `references/shared-conventions.md` (idempotent; stage anything it writes with this stage's commit). Then validate:
 
 ```bash
 R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"

package/adapters/claude/skills/forge-1-prd/SKILL.md

@@ -16,7 +16,7 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 ## Step 1: Read Configuration and Check State
 
 ### Branch Setup (if using git)
-If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion` to offer: "Want me to create a `forge/{feature}` branch for this pipeline? (Recommended — keeps forge work isolated.)" If yes, create and checkout the branch before proceeding.
+Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{feature}` and `{scope}` = `feature`. It self-gates (skips when not a git repo, when `branchPerFeature` is false, or for an epic member that inherits the epic's branch), detects whether you're on the default branch, and strongly recommends — still optionally — creating `{branchPrefix}{feature}` when you are. Do this before directory resolution.
 
 Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail `not-found` for a never-started standalone feature — in that case forge-1 creates `{specsDir}/{feature}/` as today. For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
 
@@ -87,6 +87,8 @@ Once the interview is thorough, write `{resolvedFeatureDir}/PRD.md` following th
 
 Every requirement MUST have a unique ID (e.g., REQ-AUTH-01, REQ-PERF-01). These IDs are referenced by all downstream documents.
 
+After writing the PRD (this is the point where `{specsDir}/{feature}/` is first created for a standalone feature), invoke the **Specs Directory Hygiene** block in `references/shared-conventions.md` to ensure `{specsDir}/AGENTS.md` (and `{specsDir}/CLAUDE.md` on the Claude host) exists. It is idempotent — it never overwrites an existing file.
+
 ## Step 5: Review with User
 
 Present the complete PRD to the user. Ask:
@@ -110,7 +112,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
    - Check downstream stages (`forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-1-prd`, set their status to `stale`.
 2. Use `AskUserQuestion` to ask: "Anything you want to note before we wrap? (preserved across sessions)"
    - If yes, store in the `notes` field
-3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"`, then set `stages.forge-1-prd.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (including `{specsDir}/AGENTS.md` / `{specsDir}/CLAUDE.md` if the Specs Directory Hygiene step just wrote them), attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"`, then set `stages.forge-1-prd.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
 5. Tell the user: "PRD complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the PRD\n  - `/feature-forge:forge-2-tech {feature}` to start the tech spec\n  - `/feature-forge:forge {feature}` to see full pipeline status"
 
 ## Gotchas

package/adapters/claude/skills/forge-5-loop/SKILL.md

@@ -101,13 +101,8 @@ For the version-too-old case, phrase it concretely, e.g.: "Your rauf is {reporte
 
 Check that `loopRunner.preconditionFile` (default `.rauf.json`) exists in the project root. If not:
 
-- **If `loopRunner.name == "rauf"` and a legacy `.ralph.json` (or `.ralph/` directory) exists**, this is an un-migrated Ralph project. STOP and tell the user:
-
-  "This project is still on the legacy **Ralph** layout. Run `rauf migrate .` first (the loop runner only understands `.rauf/` and `RAUF_*` signals), then re-run `/feature-forge:forge-5-loop {feature}`."
-
-- **Otherwise**, STOP and show `loopRunner.setupHint` (default: "Run `rauf install .` …"), e.g.:
-
-  "The loop runner isn't set up in this project ({preconditionFile} is missing). {setupHint}"
+- **If `loopRunner.name == "rauf"` and a legacy `.ralph.json` (or `.ralph/` directory) exists**, this is an un-migrated Ralph project. STOP: "This project is still on the legacy **Ralph** layout. Run `rauf migrate .` first (the loop runner only understands `.rauf/` and `RAUF_*` signals), then re-run `/feature-forge:forge-5-loop {feature}`."
+- **Otherwise**, STOP and show `loopRunner.setupHint` (default: "Run `rauf install .` …"), e.g. "The loop runner isn't set up in this project ({preconditionFile} is missing). {setupHint}"
 
 ### 1e. Backlog File Check
 
@@ -117,6 +112,10 @@ Resolve the backlog file path (matching forge-4-backlog's composition rule, item
 
 Verify the file exists on disk. If not, STOP and tell the user: "No backlog.json found at {path}. Run `/feature-forge:forge-4-backlog {feature}` to generate it."
 
+### 1f. Branch Pre-flight (if using git)
+
+The runner commits each completed item straight onto the current branch, so guard against committing onto the default branch. Skip if not a git repo or `branchPerFeature` is false. Read the current branch (`git rev-parse --abbrev-ref HEAD`) and default branch (`git symbolic-ref --quiet refs/remotes/origin/HEAD`, else `main`/`master`). If `.pipeline-state.json` records a `branch` that differs from the current one, warn via `AskUserQuestion` (offer **switch back** or **proceed here**). Otherwise, if the current branch **is** the default, strongly recommend via `AskUserQuestion` creating/switching to `{branchPrefix}{feature}` (`git switch -c`, then record it to the state `branch` field) before the loop commits — still allowing **proceed on `{defaultBranch}`**. Never hard-stop.
+
 ## Step 2: Construct the Loop Command
 
 ### 2a. Analyze Backlog
@@ -180,6 +179,7 @@ For the full loop-runner contract — event-stream vs. log-fallback launch, the
 - **(b) Agent question.** Add an **"agent"** question to the same `AskUserQuestion` surface: **one option per advertised row** labelled `"{displayName} ({id}) — available/not found"`, **plus an explicit `"default (claude-cli)"` choice mapping to `run_selection = None`**. Resolve the pick (run > project, empty/whitespace unset, an explicit runner-default pick collapses to the default path) into `{resolved.agent, resolved.source}`. Precedence: `item.provider > --agent > project defaultAgent > runner default` (forge never reads a backlog item's provider).
 - **(c) Availability listing.** From the **same** parsed `agents[]` (no second probe), list `id` / `displayName` / available (`yes`/`no`, `detail` on unavailable rows).
 - **(d) Verdict** — only for a **non-default** resolved agent (default path `None`/`claude-cli` → no probe, byte-identical to today). Classify by **membership** then `available` (never by exit code): **UNKNOWN** (`∉` set) → **hard-reject BEFORE any loop side-effect**, error lists the **sorted** valid ids, **NO proceed-anyway**; **UNAVAILABLE** (member, `available False`) → warn with `detail`, `AskUserQuestion` offering **proceed-anyway OR choose-another** (re-presents the same `agents[]`), never silent; **AVAILABLE** → proceed, the validated id fills `{agent}`; **probe failure** (non-zero exit / unparseable / missing or empty `agents[]` / row lacking `id`) → surface it, offer **choose-another OR abort**, **never launch the non-default agent unvalidated** and never silently fall back to the default.
+- **(d-model) Claude-only model-alias guard.** Runs **only** when the resolved agent is **non-default** (not the default / `claude-cli` path). Read the backlog.json (Step 1e path); collect items whose `model` is a **Claude-specific alias** (tier `opus`/`sonnet`/`haiku` or a `claude-*` id). **If none, skip silently.** Otherwise warn before launch via `AskUserQuestion` (NOT prose): `item.model` outranks `--agent`, so the alias is forwarded verbatim to `{agent}`, which will likely reject it (e.g. codex 400 *"The 'sonnet' model is not supported…"*) — every spawn exits 1 and rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the cause. Offer: **(1) Strip `model` for this run (recommended)** — rewrite backlog.json removing the `model` key from each affected item (persistent edit; re-run forge-4-backlog to restore), then proceed; **(2) Proceed as-is** — only safe if `{agent}` understands the pinned ids. forge touches only `model`, never `provider`. Full rationale: `references/runner-contract.md`.
 - **(e) Optional-flags line.** Replace the confirmation's optional-flags line with one that lists `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
 - **(f) Resolved-agent line.** Add to the confirmation block: `Agent: {resolved.agent or claude-cli} (source: {sourceLabel})` — `sourceLabel`: `RUN` → `"per-run selection"`, `PROJECT` → `"project default (loopRunner.defaultAgent)"`, `DEFAULT` → `"runner default — claude-cli"`.
 
@@ -193,11 +193,11 @@ Before launching, update `{resolvedFeatureDir}/.pipeline-state.json`:
 - Set `currentStage` to `forge-5-loop`
 - Update `updatedAt`
 
-### 3b. Launch Background Process
+Then commit this state write before launching (mandatory). The runner refuses to run with uncommitted changes (*"…pass --force"*), and this marker is itself one — so an otherwise-clean repo fails its first launch unless committed. Commit it via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress` — a launch precondition, required regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`. See `references/runner-contract.md`.
 
-Launch the loop **backgrounded** (`run_in_background: true`) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. The background task's exit notification is the single authoritative terminal signal (Step 4). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the event-stream vs. log-fallback detail, read `references/runner-contract.md`.
+### 3b. Launch Background Process
 
-Loop runs can take significant time (minutes to hours depending on backlog size).
+Launch the loop **backgrounded** (`run_in_background: true`) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the event-stream vs. log-fallback detail, read `references/runner-contract.md`.
 
 ### 3c. Inform User
 
@@ -246,7 +246,7 @@ Run the **status-json command** (`loopRunner.statusJsonCommand`) and read
 `backlogSummary` for the authoritative counts — it separates the three non-done
 outcomes: genuine `blocked`, `needsHuman`, and runner-`deferred` ("false blocks").
 Fall back to the **list command** (`loopRunner.listCommand`) if `statusJsonCommand`
-is not configured. You will already have most of this from the live tally in 3e.
+is not configured. You will already have most of this from the live tally in 3e. If the run used a review flag (e.g. rauf's `--review`), also read any `review_completed` event (event stream, or `{loopRunner.stateDir}/events.ndjson`) for its `itemsCreated`/`summary` to surface in 4b — see `references/result-reporting.md`.
 
 ### 4b. Report Results
 
@@ -267,13 +267,15 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 2. If all items complete: set `currentStage` to `"forge-6-docs"`
 3. Update `updatedAt`
 
-**No git commit is needed** — the loop runner commits atomically per completed item during the run. The implementation code is already committed.
+**No git commit is needed** — the loop runner commits implementation code atomically per completed item during the run. (Step 6's commit, epic members only, is of pipeline state / manifest — a distinct artifact.)
+
+## Step 5b: Offer Impl-Verify (standalone path)
 
-> **Note:** Step 5's "no git commit needed" remark refers to *implementation code*, which the runner commits per-item. The epic handoff's commit in Step 6 below is of *pipeline state / manifest* — a distinct artifact — and applies only to epic members.
+**Gate:** run only if (a) the feature's `.pipeline-state.json` has **no** `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete`. Otherwise **skip** — partial runs end as today, and epic members get the equivalent offer in Step 6.1 (do **not** prompt twice). This standalone counterpart to Step 6.1 nudges verification interactively rather than via the easily-missed "Next steps" text. Use `AskUserQuestion` (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, hand off to `/feature-forge:forge-verify {feature} impl`. On **skip**, record `stages.forge-verify-impl.status` as `"skipped"` (mirrors `forge-4-backlog`'s skip handling) and point the user at `/feature-forge:forge-6-docs {feature}` — the forge-6-docs backstop re-surfaces the skip.
 
 ## Step 6: Epic Handoff
 
-**Gate:** only run this step if (a) the resolved feature's `.pipeline-state.json` has an `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete` (all backlog items done). If either is false, **skip** — standalone features and partial runs end exactly as today (REQ-COMPAT-01).
+**Gate:** only run this step if (a) the resolved feature's `.pipeline-state.json` has an `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete` (all backlog items done). If either is false, **skip** — standalone completed features are handled by Step 5b, and partial runs end as today (REQ-COMPAT-01).
 
 1. **Offer impl-verify first (recommended, skippable).** Per the completion rule (`00-core-definitions.md §7`), a feature whose `forge-verify-impl.status == findings-reported` does **not** unblock dependents. Use `AskUserQuestion` (NOT inline prose) to offer:
 
@@ -297,7 +299,7 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 - rauf resolves `RAUF.md` with fallback: checks `{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`. As long as the runner is installed in the project, the prompt template will be found.
 - State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/` — this is within the feature's spec directory and is expected. State is isolated per backlog dir, so concurrent features don't collide.
 - If the session disconnects during a long-running loop, the runner process continues independently. The user can check results later with the status / list commands.
-- Never run the run command in the foreground (without `run_in_background`) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the `Monitor` tool (3d), which is harness-driven, not a sleep loop. Never `sleep`/poll in the foreground to wait for the loop.
-- The `Monitor` must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
+- Never run the run command in the foreground (without `run_in_background`) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the `Monitor` tool (3d), never `sleep`/poll in the foreground. The `Monitor` must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
 - If a previous loop run left a stale lock, the user may need to pass `--force` to clear it. rauf will report this error clearly.
 - The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.
+- **Implementation artifacts must not cite specs.** The loop should **read** the specs and `backlog.json` freely — they are the source of truth for what to build, and the backlog rightly references specs for provenance. But the artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: they must NOT reference feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes in shipped output). Specs are pre-implementation inputs that may be archived or deleted once the feature ships; the implementation must stand on its own. This applies only to shipped implementation output — never to the backlog or spec documents, which should keep citing specs.

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

@@ -13,6 +13,19 @@ Next steps:
   - /feature-forge:forge-6-docs {feature}         Generate architecture docs
 ```
 
+**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
+writes a findings doc). When Step 4a captured a `review_completed` event, add a line
+**above** "Next steps" so the pass's effect is visible and not mistaken for "nothing
+happened":
+```
+Runner review pass: {itemsCreated} fix item(s) created and implemented.
+  {summary}
+```
+Omit this line when no `review_completed` event was emitted (no review flag passed).
+The created items are already counted in the totals above.
+
 **Some items need a human:**
 ```
 Loop completed for {feature}.

package/adapters/claude/skills/forge-5-loop/references/runner-contract.md

@@ -70,6 +70,38 @@ The default / `claude-cli` path runs **no** probe (zero extra cost). See
 `04-availability-precheck.md` for the full pre-check, classification, and allow-list,
 and `02-config-schema-and-gating.md` for the capability gate.
 
+> **Probe false-negative for Claude Code installs (advisory).** `rauf agents` may
+> report `claude-cli` **unavailable** (e.g. *"credentials file not found:
+> ~/.config/claude-code/credentials.json"*) even when a working `claude` CLI
+> authenticates elsewhere — the probe's credential heuristic doesn't cover every
+> install. This is a rauf probe concern, not something forge-5-loop fixes. The
+> **default-agent path skips the probe entirely**, so an ordinary default run is
+> unaffected; only an **explicit** `--agent claude-cli` would be flagged UNAVAILABLE,
+> and the existing **proceed-anyway** path (above) covers it. Do not attempt to
+> patch rauf's probe from here.
+
+### Claude-only model-alias guard (Step 2d, sub-step d-model)
+
+When the resolved agent is **non-default** (not the default / `claude-cli` path),
+forge must guard against a backlog whose items pin **Claude-specific** model aliases.
+forge-4-backlog (via the rauf author-backlog skill) writes Claude tier aliases
+(`opus` / `sonnet`) into each item's `model`. Because rauf's precedence puts
+`item.model` **above** `--agent`, the alias is forwarded verbatim to the selected
+agent; a non-Claude agent (e.g. codex) then 400s — *"The 'sonnet' model is not
+supported when using Codex with a ChatGPT account."* — so **every** spawn exits 1 and
+rauf reports *"Circuit breaker: 3 consecutive infra failures — halting"* with no hint
+of the real cause. forge-5-loop therefore detects Claude-specific `model` aliases in
+the backlog (tier aliases `opus`/`sonnet`/`haiku` or `claude-*` ids) and, before
+launch, **warns** and offers (via `AskUserQuestion`) to **strip `model` for this run**
+(remove the key from each affected item so each spawn uses the agent's own default) or
+**proceed as-is**. forge only ever touches the `model` field — never `provider`. The
+default / `claude-cli` path skips this guard (the aliases are valid there).
+
+> **Follow-up (out of scope here — rauf repo).** The durable fix would be for the
+> rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
+> document that writing a tier alias binds the backlog to Claude agents). That lives
+> in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
+
 ## Optional flags catalog (Step 2d, rauf)
 
 These are the optional flags the user may add to the rendered run command. If the
@@ -92,6 +124,14 @@ Launch the loop **backgrounded** so it survives session end and does not block t
 session, and prefer the machine-readable event stream so the session can supervise
 it live.
 
+> **Clean-tree precondition.** rauf refuses to run with uncommitted changes
+> (*"Refusing to run the loop with uncommitted changes… pass --force"*). Step 3a's
+> in-progress `.pipeline-state.json` write is itself an uncommitted change, so it
+> **must be committed before launch** (Step 3a) — otherwise the first launch on an
+> otherwise-clean repo always fails. If the tree still has unrelated uncommitted
+> changes after that commit, surface it and let the user commit/stash or pass
+> `--force`; never auto-pass `--force`.
+
 - **If `loopRunner.eventStreamCommand` is configured (default for rauf):** render it
   (it appends `--ndjson` to the run) and launch via the Bash tool with
   `run_in_background: true`, redirecting stdout to a stable events file:

package/adapters/claude/skills/forge-6-docs/SKILL.md

@@ -35,6 +35,10 @@ Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.js
 
 Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and has status `in-progress` (some items incomplete), include this in the warning: "The rauf loop has not fully completed — {done}/{total} items done. Documentation may need updates after remaining items are implemented."
 
+### Impl-Verify Backstop
+
+Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent** or has status `"skipped"`, use `AskUserQuestion` to warn: "Implementation hasn't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output. Generate docs anyway?" This mirrors `forge-4-backlog`'s pre-stage verification check and backstops a skipped impl-verify regardless of how the loop ended. If `stages.forge-verify-impl` shows it already ran (`findings-applied`, `findings-reported`, or `passed`), proceed with no warning.
+
 ### Epic-Level Documentation (epic members only)
 
 If the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`, run:
@@ -110,6 +114,11 @@ Present the plan and use `AskUserQuestion` to get the user's confirmation.
 - Specs are the source of truth for design intent; code is the source of truth for behavior
 - Read the actual source code to verify your documentation is correct
 
+**Don't cite or link spec files in the generated docs.**
+- Read the specs freely for context, but the docs you write are shipped implementation artifacts — they must be self-contained
+- Never link or reference `PRD.md`, `tech-spec.md`, or the numbered implementation specs (`specs/{feature}/NN-*.md`); these are pre-implementation artifacts that may be archived or deleted
+- Reference only the code, runtime contracts/configuration, and other generated docs. If you need to convey design intent, write it directly into the doc rather than pointing at a spec
+
 **Match existing conventions.**
 - If other features' docs use a specific heading structure, follow it
 - If they include diagrams, include diagrams
@@ -173,6 +182,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 ## Gotchas
 
 - Don't just rephrase the specs. Documentation should explain the implemented system, not the planned system. Read the actual code.
+- Don't cite spec files (PRD.md, tech-spec.md, numbered specs) as sources or "further reading" in the generated docs — specs are pre-implementation artifacts that may not survive. Keep the docs self-contained; link only to code, configuration, and other docs.
 - If the implementation doesn't exist yet (backlog hasn't been run), document based on specs but note prominently that docs are pre-implementation and may need updating.
 - API reference should include actual function signatures from the code, not from the spec (they may differ).
 - Don't generate docs that will immediately be stale. Focus on concepts, architecture, and patterns rather than line-by-line code walkthroughs.