@garygentry/feature-forge 0.2.14 → 0.3.0

package/adapters/pi/skills/forge-guide/references/stacks/typescript.md

@@ -0,0 +1,134 @@
+# TypeScript Stack Profile
+
+Stack-specific guidance for TypeScript projects (Node.js/Bun, monorepo or single-package).
+
+## Stack Identity
+
+- **Language**: TypeScript
+- **Runtime**: Node.js or Bun (check `package.json` `engines` field and lock files)
+- **Package management**: npm, pnpm, yarn, or bun (check for respective lock files)
+- **Common monorepo tools**: Turborepo (`turbo.json`), Nx (`nx.json`), Lerna (`lerna.json`)
+
+## Discovery Checklist
+
+When examining a TypeScript project, check for:
+
+- **Runtime**: Bun or Node.js (check `package.json` for which)
+- **Package management**: Check for `bun.lockb`, `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock`
+- **Monorepo**: Check for `turbo.json` (Turborepo), `nx.json` (Nx), or `lerna.json` (Lerna)
+- **Framework**: Check existing packages for Hono, Express, Fastify, etc.
+- **Frontend**: Check for React, Vue, Svelte, etc.
+- **Routing**: Check for TanStack Router, React Router, Next.js, etc.
+- **Database**: Check for Drizzle, Prisma, TypeORM, etc.
+- **Validation**: Check for Zod, Yup, io-ts, etc.
+- **UI Components**: Check for shadcn/ui, Radix, MUI, etc.
+- **Styling**: Check for Tailwind (v3 or v4), CSS Modules, styled-components, etc.
+
+## Archetype Conventions
+
+### 00-core-definitions.md (TypeScript)
+
+- **Type aliases and union types**: Use `type` declarations for unions, intersections, utility types
+- **Core interfaces**: Define with `interface` keyword, JSDoc on every field
+- **Error class hierarchy**: Base error class extending `Error` with `code: string` property; domain-specific subclasses with typed properties
+- **Constants and enums**: Use `const` declarations and `as const` assertions; prefer string union types over `enum`
+- **Utility types**: Generic helpers like `Result<T, E>`, `Optional<T>`, etc.
+- **Barrel exports**: Export everything from `src/index.ts`
+
+### 01-architecture-layout.md (TypeScript)
+
+- **Package.json**: `name`, `exports` map (subpath exports like `.`, `./server`, `./client`, `./react`), `dependencies`, `devDependencies`, `scripts`
+- **tsconfig.json**: Key compiler options, extends root config
+- **Barrel export structure**: What each `index.ts` re-exports
+- **Build considerations**: Bundle vs unbundled, ESM vs CJS
+
+### Monorepo conventions
+
+- **Package naming**: `@repo/{name}` for shared packages, `@starter/{name}` for app-specific (adapt to project convention)
+- **Internal dependencies**: Reference as `@repo/{package}` in `package.json`
+- **Workspace protocol**: `"@repo/config": "workspace:*"` in pnpm, `"@repo/config": "*"` in bun
+
+## Spec Quality Rules
+
+- All TypeScript must be valid syntax — not pseudocode
+- Include complete interfaces with generics where applicable
+- Use discriminated unions for result types (e.g., `{ success: true; data: T } | { success: false; error: E }`)
+- Every interface field must have JSDoc explaining its purpose
+- Include explicit import paths in all code examples
+- Use `async/await` for asynchronous operations (not raw Promises)
+
+## Verification Specifics
+
+- **Type checking**: `bun run typecheck`, `tsc --noEmit`, or `npx tsc --noEmit`
+- **Barrel export validation**: Every `index.ts` re-exports what the spec says
+- **Cross-package type checks**: `bun run typecheck` (or equivalent) passes for both the feature package AND packages that depend on it
+- **Import path validation**: All import paths resolve correctly per the `exports` map in `package.json`
+
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** a `package.json` `bin` / CLI `main`; a
+  server entry that actually starts listening (`src/server.ts`, `src/index.ts` invoking `listen`); a
+  worker/consumer file; and for Next.js — `middleware.ts`, `app/**/route.ts` route handlers,
+  `app/**/{page,layout,template}.tsx`, server actions, and `instrumentation.ts`. Express/Hono/Fastify:
+  the file that constructs the app and calls `.listen()`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** Next.js
+  `instrumentation.ts` / `instrumentation.js` (its `register()` runs once per server process before
+  any request), an app-server preload/`register`/`--import` hook, a root `app/layout.tsx` that
+  eagerly imports server singletons, and global test setup (`vitest.setup.ts`, `jest.setup.ts`) if it
+  bootstraps production graphs. Wiring a heavy init here loads it on **every** cold start (and, under
+  the dev server, on every module re-evaluation).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM clients
+  (`drizzle-orm`, `@prisma/client`, `pg`, `mongoose`, `kysely`), queue/worker libs (`bullmq`, `bull`,
+  `kafkajs`, `ioredis`), telemetry/observability SDKs (`@opentelemetry/*`, `@sentry/node`), and a
+  whole-service-layer barrel (`import * as services from "@repo/services"`). An init that pulls any of
+  these into a universal bootstrap entry is the CHECK-I23 pattern — recommend lazy init at the first
+  route/handler/worker that needs it.
+
+## Testing
+
+- **Framework**: Vitest (most common in modern TS), Jest, or testing-library
+- **Test file location**: Co-located (`*.test.ts` next to source) or in `__tests__/` directories
+- **Fixture patterns**: Factory functions, test builders
+- **Type testing**: `expectTypeOf` from vitest for type-level assertions
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Backend | Hono, Express, Fastify, Koa |
+| Frontend | React, Vue, Svelte, Solid |
+| Routing | TanStack Router, React Router, Next.js App Router |
+| Database | Drizzle, Prisma, TypeORM, Kysely |
+| Validation | Zod, Valibot, Yup, io-ts |
+| UI Components | shadcn/ui, Radix, MUI, Mantine |
+| Styling | Tailwind CSS, CSS Modules, styled-components, vanilla-extract |
+
+## Example: Project-Level Override
+
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Bun 1.x for runtime and package management
+- Turborepo for monorepo orchestration
+
+## Backend
+- Hono for HTTP framework
+- Drizzle ORM with PostgreSQL
+- Zod for runtime validation
+
+## Frontend
+- React 19 with TanStack Router (SPA-first)
+- shadcn/ui component library
+- Tailwind CSS v4 with oklch color theming
+
+## Conventions
+- Barrel exports from index.ts in every package
+- Package naming: @repo/{name} for shared, @starter/{name} for app-specific
+- Vitest for testing
+```

package/adapters/pi/skills/forge-init/SKILL.md

@@ -0,0 +1,72 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-init/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-init
+description: Initialize feature-forge configuration in the current project. Use when user runs /skill:forge-init or asks to set up forge for the first time. Creates forge.config.json with defaults. Do NOT trigger for general project initialization or setup tasks outside the forge pipeline.
+---
+
+# Initialize Feature Forge
+
+Run the initialization script to create `forge.config.json` with default settings:
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+bash "$R/scripts/forge-init.sh"
+```
+
+After initialization, the config file will contain defaults for:
+- `specsDir`: `./specs`
+- `docsDir`: `./docs/architecture`
+- `backlogDir`: `null` (backlog lives alongside specs)
+- `gitCommitAfterStage`: `true`
+- `commitPrefix`: `forge`
+- `stack`: `null` (detected during `/skill:forge-2-tech`)
+- `typeCheckCommand`: `null` (set during `/skill:forge-2-tech`)
+- `testCommand`: `null` (set during `/skill:forge-2-tech`)
+- `smokeCommand`: `null` (optional end-to-end smoke that boots the wired app and drives one request; set it to enable impl-verify's runnability check `CHECK-I21` — distinct from `testCommand`)
+- `autoInvokeNextStage`: `true` (the navigator auto-starts the next stage after you confirm; set `false` to only print the command)
+- `contextWindowTokens`: `null` (the navigator infers the context window; set to your model's window, e.g. `1000000` for a 1M-context model, for accurate context-usage advice)
+- `contextWarnThreshold`: `0.7` (fraction of the window past which the navigator suggests a clean session)
+- `autoVerify`: `false` (set `true` to run `forge-verify` automatically after each authoring stage completes — in-stage, in the same session, before the exit block; it costs an extra clean-room verify per stage, so it trades a little time/tokens for catching errors early)
+- `autoVerifyStages`: `{}` (per-stage overrides for `autoVerify`)
+- `autoFix`: `false` (set `true` to chain `forge-fix` after an auto-verify finds issues)
+
+If `forge.config.json` already exists, the script will not overwrite it.
+
+## Offer auto-verify
+
+The template writes `autoVerify: false`. After the config is created (and only when the script
+actually created it — skip this if it reported the file already exists), offer to turn
+auto-verify on, then write the choice back into `forge.config.json`.
+
+If the `AskUserQuestion` tool is available, ask exactly one question:
+
+> **Enable auto-verify?** Verification runs in a clean-room subagent in-stage after each
+> authoring stage completes — in the same session, before the exit block, so any fix
+> decision keeps its context. It never needs a `/new` and only returns a compact digest.
+> **Recommended: on.** (Change later by editing `autoVerify` in `forge.config.json`.)
+
+Options: **Enable (recommended)** / **Leave off**.
+
+- On **Enable**: patch `"autoVerify": false` → `"autoVerify": true` in the generated
+  `forge.config.json` in place, preserving formatting and every other key.
+- On **Leave off**: leave the config as written (`autoVerify: false`).
+
+If the host lacks a structured question tool but can still prompt the user (e.g. Codex asks in
+plain text), use that — ask the one question directly and wait for the reply; it is the same
+choice, just rendered differently. Only when the host has **no** way to ask at all (a fully
+non-interactive / headless run) do you skip the prompt: leave `autoVerify: false` and print the
+one-line note `Set "autoVerify": true in forge.config.json to verify automatically after each stage.`
+
+After initialization, start the pipeline with `/skill:forge-1-prd <feature-name>`.
+
+---
+
+## Host execution notes (Pi)
+
+This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
+
+- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.

package/adapters/pi/skills/forge-verify/SKILL.md

@@ -0,0 +1,273 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-verify/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-verify
+description: Verify forge pipeline artifacts for completeness, consistency, and quality. Use when user runs /skill:forge-verify or asks to check forge specs, backlog, or implementation for gaps. Do NOT trigger for general code review, quality checks, or verification tasks outside the forge pipeline.
+---
+
+# forge-verify — Verification Gate
+
+Analyze feature artifacts for completeness, consistency, and quality. Produce structured, actionable findings designed for a fresh-context agent to apply.
+
+## Which role are you? (read this first)
+
+This skill is loaded in two different roles. Determine yours before proceeding:
+
+- **You ARE the `forge-verifier` subagent** — you were dispatched via the host's subagent mechanism, you have read-only tools (Read, Glob, Grep, Bash) and **no** Agent/host's subagent mechanism, and this skill is pre-loaded in your context. **SKIP "Subagent Delegation (parent orchestrator only)" and "Synthesize" below — those describe how a *parent* dispatches *you*, not work for you to do.** Do **not** dispatch anything, do **not** try to spawn a verifier. Go straight to **Prerequisites → Steps 1–6**, execute the checks yourself, and **return your findings as your response** (the parent writes the document to disk). Dispatching a subagent from here is the classic self-referential loop — never do it.
+- **You are the parent orchestrator** — a navigator (`/skill:forge`), a stage skill's in-stage auto-verify, or a direct `/skill:forge-verify` invocation, and you have the host's subagent mechanism. Use "Subagent Delegation" to dispatch the `forge-verifier` subagent, then "Synthesize" to assemble and write the document.
+
+## Subagent Delegation (parent orchestrator only)
+
+This skill is delegated to the `forge-verifier` subagent via the host's subagent mechanism. The verifier subagent has:
+- **Read-only tools** (Read, Glob, Grep, Bash) — it cannot accidentally modify specs
+- **Persistent memory** — it accumulates knowledge about this project's recurring issues and patterns across sessions
+- **The forge-verify skill pre-loaded** — so it has all verification checklists and guidance at startup
+
+### Choose single vs. parallel dispatch
+
+Pick based on how many checks the mode carries (see the per-mode totals in Step 3):
+
+- **Small modes (prd ~15, tech ~15): single verifier.** Use the host's subagent mechanism once with
+  `the forge-verifier custom agent`, passing the feature name and mode. It runs all
+  checks and returns findings.
+- **Large modes (specs ~38, backlog ~27, impl ~23): parallel dimensioned fan-out.**
+  Split the mode's checklist into **dimension groups** and dispatch **one
+  `forge-verifier` per group, in parallel — a single message with multiple subagent
+  calls** (the `superpowers:dispatching-parallel-agents` pattern). Each instance owns a
+  disjoint slice of CHECK-IDs, so it verifies deeper over a narrower scope and they all
+  run concurrently. Suggested groups (map to the category clusters in
+  `references/verification-checklists.md`):
+  - **specs:** (1) types/contracts, (2) architecture/layout, (3) cross-reference &
+    traceability, (4) testing strategy, (5) integration.
+  - **backlog:** (1) item scoping & acceptance criteria, (2) dependency/ordering sanity,
+    (3) spec coverage & traceability, (4) schema/enum correctness.
+  - **impl:** (1) requirement coverage vs specs, (2) integration correctness,
+    (3) testing, (4) code-quality/conventions, (5) runnability (owns CHECK-I21/I22 —
+    the smoke command and the non-test-caller heuristic).
+
+  In each parallel instance's prompt, pass: the feature, the mode, the **dimension
+  label**, the **exact CHECK-IDs it owns**, and a note that **it is one of several
+  parallel instances** — it must verify ONLY its assigned checks and return findings
+  for that slice. Tell parallel instances to treat their `MEMORY.md` as **read-only**
+  (apply learned patterns, but do NOT write it — concurrent writers would race);
+  memory consolidation is left to single-verifier runs.
+
+### Synthesize (parent session)
+
+The verifier(s) are read-only — they return findings as their response; **you** (the
+parent) assemble and write the single document to
+`{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
+   cross-reference and a type-contract verifier both catch one mismatch), keep one,
+   union their `Checklist:` IDs.
+3. Build the **single Fix Execution Plan** over the merged findings (Step 5). The output
+   document format is unchanged, so `forge-fix` consumes it identically.
+
+### Adversarial confirmation (opt-in "deep verify")
+
+When the user asks for a deep/thorough verify, add a confirmation pass before writing:
+for each `error`- and `gap`-severity finding, dispatch a short skeptic `forge-verifier`
+prompted to **refute** it ("here is a claimed finding; prove it wrong; default to
+REFUTED if you cannot confirm it from the artifacts"). Drop findings the skeptic refutes
+with confidence — this cuts false positives before they reach the user. Lower-severity
+findings (`improvement`, `inconsistency`) skip this pass.
+
+### Fallback
+
+If the `forge-verifier` subagent is not available (not installed, or an environment
+without subagents), fall back to running verification inline in the current session.
+
+**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 `/new` 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 `/skill: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 `AskUserQuestion`. 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 `{resolvedFeatureDir}/.pipeline-state.json` to understand current pipeline state.
+
+### Mode Selection
+
+If a stage is specified as a second argument (e.g., `/skill:forge-verify auth specs`), use that mode. Otherwise, auto-detect based on pipeline state:
+
+- **epic mode**: Explicit via `/skill:forge-verify {epic} epic`, or auto-detected when the named argument resolves to an **epic directory** — i.e. `{specsDir}/{name}/epic-manifest.json` exists (an epic root holds `epic-manifest.json` but no `.pipeline-state.json` of its own). When the argument is an epic, prefer epic mode over feature-mode resolution.
+- **prd mode**: If `forge-1-prd` is complete but `forge-verify-prd` is not `passed` or `findings-applied`
+- **tech mode**: If `forge-2-tech` is complete but `forge-verify-tech` is not `passed` or `findings-applied`
+- **specs mode**: If `forge-3-specs` is complete but `forge-verify-specs` is not `passed` or `findings-applied`
+- **backlog mode**: If `forge-4-backlog` is complete but `forge-verify-backlog` is not `passed` or `findings-applied`
+- **impl mode**: If user explicitly requests or if implementation code exists for this feature
+
+If ambiguous, use `AskUserQuestion` to ask which stage to verify.
+
+## Step 2: Load All Relevant Artifacts
+
+Load into context ALL artifacts for this feature based on mode:
+
+**For prd mode:**
+- `{resolvedFeatureDir}/PRD.md`
+
+**For tech mode:**
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
+
+**For specs mode:**
+- `{resolvedFeatureDir}/PRD.md`
+- `{resolvedFeatureDir}/tech-spec.md`
+- `{resolvedFeatureDir}/##-*.md` (all implementation specs)
+
+**For backlog mode:**
+- All of the above, PLUS
+- `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if `backlogDir` is configured) — resolve `{resolvedFeatureDir}` via the **Feature Directory Resolution** block in `references/shared-conventions.md`, using the same composed path as forge-4-backlog and forge-5-loop (04 §6.2)
+
+**For impl mode:**
+- All of the above, PLUS
+- The actual source code for this feature (read package directory)
+- Source code of packages this feature integrates with
+
+**For epic mode:**
+- `{specsDir}/{epic}/epic-manifest.json`
+- `{specsDir}/{epic}/EPIC.md`
+- each member feature's `.pipeline-state.json` (for the `epic` back-pointer + derived status)
+- each **completed** member's `PRD.md` + `tech-spec.md` (for contract-drift checking, CHECK-E06)
+
+## Step 3: Run Verification Checklists
+
+Read `references/verification-checklists.md` for the detailed checklists per mode. Execute every check. Do not skip checks because things "look fine." That same reference also holds the relocated **Findings Document Template (Step 4)**, the worked **Example Findings (Step 4)**, and the **Epic Mode State Write Detail (Step 6)** sections used later in this skill.
+
+Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~27 checks, impl: ~23 checks, epic: ~10 checks), you likely skipped checks — go back and complete them.
+
+**Epic mode dispatch.** Epic mode is a small (~10-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E10 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07, E09, and E10 are verifier judgment) and returns its findings.
+
+### Important: Be Specific, Not General
+
+BAD finding: "The error handling could be more thorough."
+GOOD finding: "PRD.md REQ-ERR-04 requires rate limit retry behavior, but spec 03-provider-registry.md only handles rate limits by throwing — no retry logic is specified."
+
+Every finding must include:
+1. A unique ID (V-001, V-002, etc.)
+2. Severity: `gap` (missing requirement coverage), `inconsistency` (contradictory specs), `improvement` (not wrong but could be better), `error` (factually incorrect)
+3. Exact location (file + section)
+4. What's wrong
+5. Suggested fix (specific enough that a fresh agent can apply it)
+6. References (which other files/sections are involved)
+7. Related checklist item(s) (e.g., CHECK-P01, CHECK-S12)
+
+## Step 4: Write Findings Document
+
+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`).
+
+The full findings-document template (report header, `V-NNN` finding shape, and the
+Fix Execution Plan layout) and the worked **Example Findings** (gap / inconsistency /
+improvement) live in `references/verification-checklists.md` under the **Findings
+Document Template (Step 4)** and **Example Findings (Step 4)** sections — follow that
+template verbatim when writing the document.
+
+## Step 5: Fix Plan and Next Steps
+
+The Fix Execution Plan (written as part of the findings document in Step 4) is ALWAYS generated regardless of mode. This ensures the findings document is self-contained: diagnosis + action plan in one artifact.
+
+When building the Fix Execution Plan:
+1. Group related findings into logical steps (e.g., all type-system fixes together)
+2. Order steps to avoid conflicts (fix shared types before documents that reference them)
+3. Each step must be specific enough for a fresh agent with zero prior context to execute
+4. Flag any findings that require user decisions before fixes can be applied
+
+**If in plan mode:** Also write the Fix Execution Plan to the active plan file so the plan mode workflow is preserved. The user reviews the plan, exits plan mode, and a fresh agent executes the fixes.
+
+**If not in plan mode:** Output the following as text:
+"Findings and fix plan written to `{findings-file}`."
+
+Then use `AskUserQuestion` to ask how to proceed. Follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
+- **(a) Review the findings first** — read `{findings-file}` and decide per-finding; safest, but you act on nothing until you return.
+- **(b) Run `/skill:forge-fix {feature}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
+- **(c) Enter plan mode and re-run `/skill:forge-verify {feature}`** — produces a reviewable plan before any edits; best for large or risky fix sets.
+
+Do NOT embed this question in your text output.
+
+## Step 6: Update Pipeline State
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+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.
+
+### Epic mode state (`.epic-state.json`)
+
+Epic mode is **epic-scoped**, not per-feature: record its result into the epic-level
+state file `{specsDir}/{epic}/.epic-state.json` — **never** into any member's
+`.pipeline-state.json`. Set `stages.forge-verify-epic.status` to `findings-reported`
+(or `passed` if zero findings), recording `findingsFile`, `findingsCount`, and
+`verifiedAt`. The full `.epic-state.json` schema (minimal shape) and the atomic
+temp-file + `os.replace()` **write-mechanism** detail (lazy-create, merge/replace,
+fail-intact) — including the worked Python snippet — live in
+`references/verification-checklists.md` under the **Epic Mode State Write Detail
+(Step 6)** section. Follow it verbatim.
+
+Do NOT mark as `findings-applied` — that happens after the fix pass.
+
+## Gotchas
+
+- This skill should be run in plan mode for best results. The plan gives the user a chance to review before committing to changes.
+- Verification is most valuable when it finds things that are MISSING, not just things that are present but imperfect. Prioritize gap detection over style preferences.
+- 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 {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="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/validate-traceability.py" {resolvedFeatureDir}/PRD.md {resolvedFeatureDir}/ --json
+```
+
+---
+
+## Host execution notes (Pi)
+
+This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
+
+- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.