@garygentry/feature-forge 0.1.0

package/adapters/codex/skills/forge-3-specs/forge-3-specs.md

@@ -0,0 +1,153 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-3-specs/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-3-specs
+description: Generate numbered implementation spec documents from PRD and tech spec in the forge pipeline. Use when user runs /feature-forge:forge-3-specs or asks to create detailed implementation specs for a forge feature after tech spec completion. Do NOT trigger for general specification writing, design docs, or implementation planning outside the forge pipeline.
+---
+
+# forge-3-specs — Implementation Spec Suite Generator
+
+Generate a comprehensive suite of numbered implementation specification documents that provide everything needed to implement a feature.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Validate Prerequisites
+
+**Resolve the feature directory first** via the **Feature Directory Resolution** block in `references/shared-conventions.md`, setting `{resolvedFeatureDir}`.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, both `forge-1-prd` and `forge-2-tech` must be `complete`. If not, STOP and tell the user which prerequisites are missing.
+
+Read both `{resolvedFeatureDir}/PRD.md` and `{resolvedFeatureDir}/tech-spec.md` into context.
+
+After reading the PRD and tech spec, invoke the **Epic Context Injection** block in `references/shared-conventions.md`. It self-gates on the resolved feature's `epic` back-pointer: for a standalone feature it is a no-op; for an epic member it loads EPIC.md, this feature's charter, and the completed direct dependencies' specs into context before the spec suite is planned.
+
+## Step 2: Examine Existing Context
+
+1. **Read the PRD and tech spec thoroughly**: These are your source of truth
+2. **Examine the existing codebase**: Look at how other packages are structured, what patterns they follow, what types they export
+3. **Check other features' implementation specs**: Look at `{specsDir}/*/[0-9][0-9]-*.md` AND `{specsDir}/*/*/[0-9][0-9]-*.md` (depth-2, for epic-nested features) for consistency in format and depth. Subject to the **feature-shaped-dir bound**: only treat a matched directory as a feature if it directly contains a `.pipeline-state.json` (per the Feature Directory Resolution block) — ignore `EPIC.md` directories and other non-feature subtrees. Flat-only trees gain no new matches from the depth-2 glob, so standalone behavior is unchanged (REQ-COMPAT-01).
+4. **Read integration target code**: For every package listed as an integration point in the tech spec, read its actual source — types, exports, patterns. For every integration point, include the EXACT function signature and import path you read from the source code. Include the file path where you found it. If you cannot locate an expected export, say so explicitly: 'WARNING: Could not locate X export in {module} — verify this exists before implementing.'
+5. **Read spec examples**: Read `references/spec-examples.md` for the expected depth and quality of spec sections. These examples are your quality bar.
+
+## Step 3: Plan the Document Suite
+
+Read `references/spec-archetypes.md` for the menu of document types.
+
+Based on the feature's complexity, propose a document plan to the user before writing. Output the document list as text, then use `AskUserQuestion` for the question — do NOT include the question in your text output.
+
+**Example text output (no question here):**
+```
+I'll create the following spec documents for {feature}:
+
+Required:
+  00-core-definitions.md     — Type definitions, error hierarchy, shared contracts
+  01-architecture-layout.md   — Directory structure, exports map, dependency graph
+  NN-testing-strategy.md      — Test approach, coverage targets, fixture patterns
+
+Feature-specific:
+  02-{subsystem-a}.md         — {Brief description}
+  03-{subsystem-b}.md         — {Brief description}
+  04-integration-points.md    — Integration with existing project modules
+```
+
+**Then call `AskUserQuestion`** with: "Does this look right? Should I add or remove any documents?"
+
+**Incremental artifact tracking:** After each spec document is written (by you or a writer subagent), immediately update the `artifacts` array in `.pipeline-state.json` with the new file path. This enables crash recovery if the session is interrupted mid-suite (see shared-conventions.md "Crash Recovery").
+
+## Step 4: Write the Spec Suite
+
+The suite has a hard internal dependency: every domain/integration doc references the
+shared types and layout from `00-core-definitions.md` and `01-architecture-layout.md`.
+So author in two phases — a sequential foundation, then a parallel fan-out.
+
+### 4a. Foundation pass (sequential, you author)
+
+Write `00-core-definitions.md` and `01-architecture-layout.md` yourself, in the main
+session, **before** anything else. Every later document depends on these shared types
+and the directory/exports map, so they must exist and be stable first.
+
+### 4b. Domain fan-out (parallel `forge-spec-writer` subagents)
+
+Once the foundation is written, dispatch the remaining numbered docs in parallel — **one
+`forge-spec-writer` subagent per document, in a single message with multiple Agent
+calls** (the `superpowers:dispatching-parallel-agents` pattern). Each writer is given:
+- the PRD and tech-spec,
+- the just-written `00-core-definitions.md` and `01-architecture-layout.md` (so it builds
+  on the shared types, not its own),
+- the stack profile path `references/stacks/{stack}.md` (if `stack` is set in config),
+- the quality bar in `references/spec-examples.md`,
+- the **exact single filename it must write** and the archetype slice (from
+  `references/spec-archetypes.md`) it covers.
+- **(epic members only — additive context):** the relevant `EPIC.md` Contracts section(s)
+  for this feature, and the `tech-spec.md` of each completed direct dependency at {paths} — so
+  the doc is written against real upstream contracts, not guesses.
+
+Each writer authors **only its one assigned file** and returns a short **manifest** of
+the `REQ-XXX-NN` IDs it covered (feeds Step 5 traceability). Author `NN-testing-strategy.md`
+last (it can be its own writer, or you author it once the others' shapes are known).
+
+**Fallback (no subagents available):** author the documents yourself in batches of 3–5,
+foundation first; after each batch, optionally commit
+(`git add {specsDir}/{feature}/ && git commit -m "{commitPrefix}({feature}): specs batch {n}"`)
+and re-read only `00-core-definitions.md` plus the upstream docs the next batch needs —
+do not reload everything. This keeps quality up under context pressure.
+
+### Quality requirements (every document, whoever writes it)
+
+1. Number sequentially: `00-`, `01-`, `02-`, etc.
+2. Every implementation detail MUST trace to either a PRD requirement (REQ-XXX-NN) or a tech-spec decision
+3. Before the body, include a `## Requirement Coverage` table mapping every REQ-XXX-NN this document covers to the section that implements it
+4. Include complete type definitions, data structures, and function signatures in the project's language — not pseudocode. If a stack profile exists at `references/stacks/{stack}.md` (where `{stack}` comes from `forge.config.json`), follow its conventions for type definitions, error hierarchies, and documentation comments.
+5. Include error handling for every operation
+6. Include example usage where it aids clarity
+7. Cross-reference other spec documents by filename when one document depends on definitions from another
+
+### Document Conventions
+
+- Filename format: `{specsDir}/{feature}/##-<descriptive-name>.md`
+- Each document should be self-contained enough that an engineer could implement it without reading other spec docs (though cross-references help for context)
+- Include a "Dependencies" section listing which other spec docs must be implemented first
+- Include a "Verification" section describing how to confirm the implementation matches the spec
+
+## Step 5: Cross-Reference Validation
+
+After writing all documents, verify:
+
+1. Every PRD requirement has coverage in at least one spec document
+2. Every tech-spec decision is reflected in the implementation specs
+3. Cross-references between spec documents are consistent (no broken references)
+4. Type definitions used across documents are consistent
+5. No orphaned implementation details that don't trace to requirements
+6. Produce a traceability matrix: a markdown table mapping every REQ-XXX-NN from the PRD to the spec document and section that implements it. Write this to `{resolvedFeatureDir}/TRACEABILITY.md`
+
+List any gaps or inconsistencies found and resolve them.
+
+## Step 6: Review with User
+
+Present a summary of all documents created as text, with key decisions highlighted. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+
+"1. Does the level of detail match what you need? 2. Any areas that need more depth? 3. Any missing subsystems or concerns?"
+
+## Step 7: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `forge-4-backlog` (or verification if they want to verify first)
+   - Record all created files in `artifacts`, including `TRACEABILITY.md`
+   - Set `stages.forge-3-specs.basedOnVersions` to `{"forge-1-prd": <current version>, "forge-2-tech": <current version>}`
+   - Check downstream stages (forge-4-backlog, forge-5-loop, forge-6-docs). If any have `basedOnVersions` referencing older versions, set their status to `stale`
+2. Use `AskUserQuestion` to ask about notes to persist
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete implementation specs v{n}"`, then set `stages.forge-3-specs.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+5. Tell the user: "Implementation specs complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the specs (strongly recommended)\n  - `/feature-forge:forge-4-backlog {feature}` to generate the backlog\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- Don't create specs for things that are already fully specified in the tech spec. If the tech spec has complete type definitions, the implementation spec should reference them, not duplicate them.
+- Every spec document should include complete type definitions and function signatures in the project's language with documentation comments. The backlog generator and implementing engineer depend on these being exact, not approximate.
+- Resist the urge to create too many documents. Each document should represent a major concern. If a "document" would be under 50 lines, it probably belongs as a section in another document.
+- Watch for implicit dependencies between subsystems. If subsystem A's types are used by subsystem B, the spec should explicitly state this and ensure the types are defined in the shared types document.
+- If the feature is large, the spec suite might be 8-12 documents. If it's simple, 3-4 is fine. Match complexity to the feature, not a fixed template.

package/adapters/codex/skills/forge-3-specs/references/spec-archetypes.md

@@ -0,0 +1,106 @@
+# Implementation Spec Archetypes
+
+This reference defines the types of implementation spec documents and their internal structure. Use this to plan which documents a feature needs.
+
+## Always Required
+
+### 00-core-definitions.md
+The shared type system and data contracts for the feature. Every other spec document references definitions here.
+
+**Sections:**
+- Type aliases, union types, enums, or language-equivalent constructs
+- Core types/interfaces/structs with documentation comments on every field
+- Error/exception hierarchy (base error, domain-specific errors, each with typed properties)
+- Constants and enumerations
+- Utility types (if any)
+
+**Rules:**
+- Every type must have documentation comments explaining its purpose (JSDoc, docstrings, godoc, etc.)
+- Error types must include `code`, `message`, and domain-specific context fields
+- Export everything through the module's entry point following project conventions
+
+### 01-architecture-layout.md
+How the feature is structured in the project.
+
+**Sections:**
+- Directory tree (full, not abbreviated)
+- Project manifest: name, exports/entry points, dependencies, build scripts
+- Build/compiler configuration: key options
+- Module export structure: what each entry point exposes
+- Build and deployment considerations
+
+**Rules:**
+- Exports/entry points must be explicit — list every public module or subpath
+- Dependencies should distinguish runtime vs dev dependencies
+- Internal project dependencies must reference exact module/package names
+
+### NN-testing-strategy.md (always last numbered document)
+How to test this feature.
+
+**Sections:**
+- Testing framework and tooling (match project conventions — e.g., vitest, pytest, go test)
+- Unit test approach: what to test, what to mock
+- Integration test approach: how to test cross-package interactions
+- Test fixtures and factories
+- Coverage targets
+- Test file location conventions
+
+## Conditionally Required
+
+### ##-{domain-concern}.md (one per major subsystem)
+Use when the feature has distinct subsystems that warrant separate specification.
+
+**Examples:** `02-provider-registry.md`, `03-streaming-engine.md`, `04-prompt-templates.md`
+
+**Sections:**
+- Purpose and scope (which PRD requirements this covers)
+- Public API: exported functions, classes, or components with full signatures
+- Internal implementation: key algorithms, data flows, state management
+- Configuration: what's configurable, defaults, validation
+- Error handling: what can fail, how errors are typed and surfaced
+- Dependencies: on types from 00, on other subsystems, on external packages
+
+### ##-integration-points.md
+Use when the feature interacts with existing modules or packages.
+
+**Sections:**
+- Integration map: which packages, which direction (depends-on vs depended-upon-by)
+- For each integration point:
+  - Which types/interfaces are shared
+  - Data flow description
+  - Import paths and barrel exports
+  - Any adapter or bridge code needed
+- Migration considerations: does integration require changes to existing packages?
+
+### ##-ui-components.md
+Use when the feature has a frontend surface.
+
+**Sections:**
+- Component tree / hierarchy
+- Props interfaces for each component
+- State management approach
+- Styling approach (consistent with project conventions)
+- Responsive behavior
+- Accessibility requirements (ARIA, keyboard navigation)
+
+### ##-data-migration.md
+Use when the feature involves schema changes or data migration.
+
+**Sections:**
+- Schema definition (using project's ORM/migration tool, or raw SQL — match project conventions)
+- Migration steps
+- Rollback strategy
+- Data seeding / fixtures
+- Zero-downtime migration considerations (if applicable)
+
+## Document Quality Checklist
+
+Before finalizing any spec document, verify:
+
+- [ ] Every section references PRD requirement IDs
+- [ ] All code is valid syntax in the project's language (not pseudocode)
+- [ ] All type references resolve to definitions in 00-core-definitions.md or clearly stated external packages
+- [ ] Error scenarios are covered, not just happy paths
+- [ ] Cross-references to other spec docs use exact filenames
+- [ ] A "Dependencies" section states which other spec docs must be implemented first
+- [ ] A "Verification" section describes how to confirm correct implementation

package/adapters/codex/skills/forge-3-specs/references/spec-examples.md

@@ -0,0 +1,71 @@
+# Spec Examples — Quality Bar
+
+These examples demonstrate the expected depth and quality for implementation spec sections. Match this level of detail.
+
+> **Note:** The following examples use TypeScript. Adapt the language, idioms, and documentation style to match your project's stack. The STRUCTURE and DEPTH shown here is the quality bar regardless of language. See `references/stacks/{stack}.md` for language-specific conventions.
+
+## Example: Function Specification (from a session management spec)
+
+### 3.2 Token Refresh (REQ-AUTH-05, REQ-SEC-03)
+
+Refresh an expiring session token without requiring re-authentication.
+
+```typescript
+/**
+ * Refresh a session token if it's within the refresh threshold.
+ * Returns a new token with an extended expiry, or null if the session
+ * is not eligible for refresh (expired, revoked, or outside threshold).
+ *
+ * @param currentToken - The JWT string from the session cookie
+ * @param options - Refresh configuration
+ * @returns New session token string, or null if refresh is not possible
+ * @throws {SessionExpiredError} If the token has already expired
+ * @throws {TokenValidationError} If the token signature is invalid
+ */
+export async function refreshSessionToken(
+  currentToken: string,
+  options: RefreshOptions
+): Promise<string | null>;
+
+interface RefreshOptions {
+  /** Maximum age of a token eligible for refresh. Default: SESSION_DURATION_MS */
+  maxAge?: number;
+  /** How close to expiry before refresh is allowed. Default: REFRESH_THRESHOLD_MS */
+  refreshThreshold?: number;
+  /** Secret key for signing the new token */
+  signingKey: CryptoKey;
+}
+```
+
+**Error Handling:**
+- `SessionExpiredError` (code: `SESSION_EXPIRED`): Token's `exp` claim is in the past. Client must re-authenticate.
+- `TokenValidationError` (code: `TOKEN_INVALID`): Signature verification failed. Token may have been tampered with. Log a security warning.
+- Returns `null` (no error): Token is valid but not yet within the refresh threshold. No action needed.
+
+**Dependencies:**
+- Types from `00-core-definitions.md`: `SessionToken`, `SessionExpiredError`, `TokenValidationError`, `RefreshOptions`
+- Constants from `00-core-definitions.md`: `SESSION_DURATION_MS`, `REFRESH_THRESHOLD_MS`
+- `jose` library for JWT verification and signing
+
+**Verification:**
+- [ ] `refreshSessionToken` returns a new token when called with a token within the refresh threshold
+- [ ] Returns `null` for a valid token outside the refresh threshold
+- [ ] Throws `SessionExpiredError` for an expired token
+- [ ] Throws `TokenValidationError` for a token with an invalid signature
+- [ ] New token has an expiry of `SESSION_DURATION_MS` from the current time
+
+## Example: Requirement Coverage Header
+
+Every spec document should begin with a requirement coverage section:
+
+```markdown
+## Requirement Coverage
+
+| REQ ID | Requirement | Section |
+|--------|-------------|---------|
+| REQ-AUTH-05 | Token refresh without re-auth | 3.2 |
+| REQ-SEC-03 | Session expiry management | 3.1, 3.2 |
+| REQ-PERF-02 | Token validation under 10ms | 3.3 |
+```
+
+This makes traceability explicit and auditable.

package/adapters/codex/skills/forge-4-backlog/forge-4-backlog.md

@@ -0,0 +1,145 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-4-backlog/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-4-backlog
+description: Generate a structured backlog.json from forge implementation specs, then validate it via the loop runner. Use when user runs /feature-forge:forge-4-backlog or asks to create a backlog for a forge feature after specs are complete. This is the canonical backlog generator for the forge pipeline. Do NOT trigger for standalone backlog creation outside the forge pipeline context.
+---
+
+# forge-4-backlog — Backlog Generator (pipeline orchestrator)
+
+Generate a complete, validated `backlog.json` from the implementation spec
+suite, ready for the loop runner.
+
+This skill is a **thin orchestrator**: it owns the *pipeline* concerns
+(prerequisite checks, spec loading, plan review, validation, pipeline-state and
+commit). The actual **authoring craft** — granularity, acceptance criteria,
+`agentDelegation`, the schema, examples — lives in the rauf plugin's
+**`author-backlog`** skill, which this skill delegates to. That keeps a single
+home for backlog-authoring knowledge, shared with the repo-wide ad-hoc flow.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding. Resolve the feature directory `{resolvedFeatureDir}` via the **Feature Directory Resolution** block in `references/shared-conventions.md` — do not hardcode `{specsDir}/{feature}/` (see Step 1).
+
+Resolve the **backlog directory** `{backlogDir}`:
+- **`backlogDir` unset (default):** the backlog lives at the resolved feature directory — `{resolvedFeatureDir}/backlog.json` — for both flat and nested features, exactly as today.
+- **`backlogDir` configured:** compose a **per-feature subpath** — `{backlogDir}/{feature}/` — so each epic member's backlog stays independent (the authored file lands at `{backlogDir}/{feature}/backlog.json`). A bare shared `backlogDir` would collide across a multi-feature epic and violate REQ-COMPAT-03; the `{feature}` segment prevents that. Standalone features under a configured `backlogDir` likewise resolve to `{backlogDir}/{feature}/`, which is backward-compatible because each standalone feature name is already unique.
+
+This is the **single** place this rule is implemented. forge-5-loop's backlog-file check must read the same composed `{backlogDir}/{feature}/backlog.json` (that matching forge-5-loop edit lands in item 016), and forge-verify's backlog-mode load uses the same path. rauf itself is unchanged: backlogs remain per-feature and rauf is still launched against a single per-feature backlog path — only the *path composition* changes (REQ-COMPAT-03).
+
+**Let `{resolvedBacklogDir}` denote the composed target of this rule** — i.e. `{backlogDir}/{feature}` when a `backlogDir` is configured, else `{resolvedFeatureDir}`. Every downstream step below (authoring, validation) uses `{resolvedBacklogDir}`, never the bare config value, so the per-feature `{feature}` segment is never dropped.
+
+Resolve the **loop runner** from the `loopRunner` block in `forge.config.json`, filling missing fields from the defaults in `references/forge-config-schema.json` (defaults to rauf). You need its `bin`, `validateCommand`, `versionCommand`, `minRunnerVersion`, and `installHint`.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Validate Prerequisites
+
+**Resolve the feature directory first.** Invoke the **Feature Directory Resolution** block in `references/shared-conventions.md` to turn the bare feature name into `{resolvedFeatureDir}` (exit 0 → stdout is the absolute dir; exit ≥ 1 → STOP and surface the finding verbatim). Read state and specs from `{resolvedFeatureDir}/` everywhere this skill previously wrote `{specsDir}/{feature}/`. Standalone features resolve to their flat path exactly as today.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, stages `forge-1-prd`, `forge-2-tech`, and `forge-3-specs` must all be `complete`. If not, STOP and tell the user which prerequisites are missing.
+
+**Strongly recommended:** Check if specs have been verified. If not, use `AskUserQuestion` to warn: "Specs haven't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature}` first. Continue anyway?"
+
+## Step 2: Load All Specs
+
+Read all spec documents into context:
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
+- `{resolvedFeatureDir}/##-*.md` (all implementation specs)
+
+If the spec suite is large (8+ documents), focus on loading the architecture layout (01-*), shared types (00-*), and testing strategy documents first. Load individual subsystem specs as needed when writing the corresponding backlog items, rather than loading all specs simultaneously.
+
+## Step 3: Plan the Backlog
+
+Before writing any JSON, walk the specs and create a backlog plan: discrete work items, ordered by dependency (foundation first), with priorities, each scoped for a single loop iteration.
+
+Present the plan as a numbered list:
+```
+Proposed backlog for {feature} ({N} items):
+
+  001 [P1] Scaffold module with project manifest, build config, and entry points
+      Depends on: (none)
+      Specs: 00-core-definitions.md, 01-architecture-layout.md
+
+  002 [P1] Implement shared types and error hierarchy
+      Depends on: 001
+      Specs: 00-core-definitions.md
+  ...
+```
+
+After presenting the plan as text, use `AskUserQuestion` to ask: "Does this breakdown look right? Any items to split, merge, or reorder?" Do NOT include this question in your text output. Wait for the user's response before generating the JSON.
+
+## Step 4: Author backlog.json — delegate to `author-backlog`
+
+**Invoke the rauf plugin's `author-backlog` skill** (via the Skill tool) to write
+`{resolvedBacklogDir}/backlog.json`. Pass it:
+
+- the target backlog directory `{resolvedBacklogDir}`,
+- the approved plan from Step 3,
+- the spec context loaded in Step 2,
+- the project's `typeCheckCommand` / `testCommand` (from `forge.config.json`) so acceptance criteria are concrete and runnable.
+
+`author-backlog` owns all item-quality rules (granularity hard limits, self-contained descriptions, acceptance criteria, `agentDelegation`, the correct `type`/`status` enums, `dependsOn`, `specReferences`, the schema source). Do not re-encode them here — follow whatever it produces.
+
+> **If the rauf plugin / `author-backlog` skill is not available:** fall back to
+> authoring inline using the schema source rule (prefer the project's installed
+> `{stateDir}/backlog.schema.json`, else the published `$id`
+> `https://raw.githubusercontent.com/garygentry/rauf/main/schemas/backlog.schema.json`),
+> and tell the user the rauf plugin provides richer authoring guidance.
+
+**Forge-specific item requirements** layered on top of `author-backlog`'s output:
+- `specReferences` must be paths **relative to the project root** (e.g. `specs/auth/00-core-definitions.md`), NOT relative to the backlog file. The validator resolves them from the project root (not from `--specs-dir`, which only gates the check).
+
+> **Backlog schema & rauf contract are unchanged (REQ-COMPAT-03).** Epic membership adds **no** fields to backlog items — dependency edges live in the epic manifest, never in any backlog item. The JSON written here is byte-for-byte the same shape as a pre-epic standalone feature's backlog, and rauf is still launched against a single per-feature backlog path. Only the *path composition* changes (the `{feature}` segment in the backlog-directory rule above), not the schema or rauf's CLI surface.
+
+## Step 5: Validate via the loop runner
+
+Validate the generated backlog by running the runner's **validate command**
+(`loopRunner.validateCommand`), rendered with `{resolvedBacklogDir}` and `{specsDir}`
+substituted — the rauf default:
+
+```bash
+rauf backlog validate . --backlog {resolvedBacklogDir} --specs-dir {specsDir} --json
+```
+
+Interpret the result:
+- **exit 0** → valid (warnings allowed). Proceed.
+- **exit 1** → validation findings. Parse `{ valid, findings[] }`, fix the items, re-run. Do NOT present the backlog to the user until it validates.
+- **exit 2** → usage/IO error (unreadable file, bad JSON). Fix and re-run.
+
+> **forge-4 runs before forge-5's install gate**, so the runner may not be set
+> up yet. Degrade gracefully rather than hard-failing:
+> 1. First run `loopRunner.versionCommand` (`rauf version --json`). If the
+>    binary is **missing**, or its version is **< `minRunnerVersion`**
+>    (semver-compare), do NOT block authoring: keep the authored backlog, emit a
+>    loud warning with `loopRunner.installHint`, mark validation as skipped, and
+>    continue to Step 6. forge-5 will enforce the gate before running.
+> 2. If the binary is present and new enough but the project isn't set up
+>    (`validate` reports the project marker missing), likewise warn and continue
+>    — validation will run cleanly once `rauf install .` has been done.
+
+## Step 6: Review with User
+
+Present a summary: total items N, dependency-chain depth, estimated loop iterations (`ceil(pendingItems * loopIterationMultiplier)`). Note whether validation passed or was skipped (runner not yet available).
+
+Use `AskUserQuestion` to ask: "Ready to proceed, or any adjustments needed?"
+
+## Step 7: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`. Follow the Git Commit Protocol in `references/shared-conventions.md`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Record `artifacts` (path to backlog.json)
+   - Set `stages.forge-4-backlog.basedOnVersions` to `{"forge-1-prd": <current version>, "forge-2-tech": <current version>, "forge-3-specs": <current version>}`
+   - Set `currentStage` to `forge-5-loop`
+   - Check downstream stages (`forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-4-backlog`, set their status to `stale`.
+2. Use `AskUserQuestion` to ask about notes to persist
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files, attempt commit, then set status to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+4. If verification was available but the user chose to skip it, record `stages.forge-verify-backlog.status` as `"skipped"` in pipeline state.
+5. Tell user: "Backlog complete with {N} items. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the backlog\n  - `/feature-forge:forge-5-loop {feature}` to run the loop\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- The loop runs each item in a FRESH context. Every item description must be self-contained — `author-backlog` enforces this, but double-check Step-3 plan items aren't "same as above."
+- Spec references must be project-root-relative paths that actually exist — the validate command enforces this when `--specs-dir` is passed (resolving them from the project root).
+- Don't present a backlog to the user before it validates (or before you've explicitly recorded that validation was skipped because the runner isn't installed yet).