@garygentry/feature-forge 0.3.0 → 0.3.1

package/adapters/gemini/skills/forge-verify/references/shared-conventions.md

@@ -133,6 +133,8 @@ mkdir -p "<specsDir>"
 If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
 
 ```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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; }
 [ -f "<specsDir>/CLAUDE.md" ] || cp "$R/references/templates/specs-hygiene/CLAUDE.md" "<specsDir>/CLAUDE.md"
 ```
 
@@ -183,7 +185,11 @@ If the helper is unavailable (a non-Claude host without the resolver), skip this
 
 ## Pipeline State Protocol
 
-Write pipeline state conforming to `references/pipeline-state-schema.json`. Always update `updatedAt` when modifying pipeline state.
+Pipeline state is written by the `state-*` verbs of `scripts/forge-session.py` — never by hand. Each verb writes `{resolvedFeatureDir}/.pipeline-state.json` atomically, conforms to `references/pipeline-state-schema.json` by construction, and refreshes `updatedAt` for you, so no stage needs to read the schema in order to author state.
+
+**Epic members MUST pass `--epic`.** Every `state-*` verb takes an optional `--epic "{epic}"`, and it is **required** whenever the feature is an epic member (its resolved directory is `{specsDir}/{epic}/{feature}/`, i.e. its state carries an `epic` back-pointer) — append it to **every** `state-*` call in this file and in every skill body, exactly as the `state-ecr` calls already do. Omit it only for a standalone feature. Without it the verb resolves the bare name itself and, mirroring `epic-manifest.py resolve`, refuses with exit 2 whenever more than one directory carries a state file rather than guessing which feature to write — so a same-named standalone feature can never be mutated in a member's place.
+
+If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbatim, do **not** proceed to the next step of the surrounding protocol, and do **not** hand-author the JSON as a workaround. The stage remains resumable because the entry stamp is already on disk — re-run the verb once the cause is fixed.
 
 ### Staleness Detection (Read-Time)
 
@@ -214,7 +220,16 @@ Invoke this block at the **very start** of a pipeline entry point — `forge-1-p
    - **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.
+**Record the branch.** After this block resolves, record the resulting branch name in the feature's top-level `branch` field by running `state-branch` (create/update it when the state file is first written for this stage). Emit the call **once the feature directory exists** — i.e. after Feature Directory Resolution and the Entry Stamp, **not** at this block: Branch Setup runs at the very start of the entry point, before any directory resolution, and a brand-new standalone feature may have no directory yet. Add `--epic "{epic}"` to the call when this feature is an epic member — required, per the Pipeline State Protocol.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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/forge-session.py" state-branch \
+  --feature "{feature}" --branch "<name>" --specs-dir "{specsDir}"
+```
+
+Downstream stages and `forge-5-loop` read it to detect drift back onto the default branch.
 
 ## Branch Reconciliation
 
@@ -227,10 +242,19 @@ python3 "$R/scripts/forge-session.py" reconcile-branch --feature "{feature}" --s
 ```
 
 Act on the emitted `action` (source of truth is where the state actually resolves, not the recorded field):
-- **`adopt-current`** — you are on a non-default topic branch where the state resolves, and the recorded `branch` differs (a stale/imposed value). Write `newBranch` into the state `branch` field with a **visible one-line note** ("recorded branch was `{stateBranch}`; work is on `{currentBranch}` — updating to match") — never silently, and **never push the user back** to the recorded branch (offer that only as a plain alternative).
+- **`adopt-current`** — you are on a non-default topic branch where the state resolves, and the recorded `branch` differs (a stale/imposed value). Run `state-branch` (below) to write `newBranch` into the state `branch` field, with a **visible one-line note** ("recorded branch was `{stateBranch}`; work is on `{currentBranch}` — updating to match") — never silently, and **never push the user back** to the recorded branch (offer that only as a plain alternative).
 - **`warn-drift`** — you are on the **default** branch and the state records a topic branch. Via `AskUserQuestion`, strongly recommend creating/switching to `{branchPrefix}{feature}` (then record it), still allowing **proceed on the default branch**. Never hard-stop.
 - **`none`** / **`not-resolved`** — nothing to do; proceed.
 
+The `adopt-current` write, with the portable plugin-root prelude. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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/forge-session.py" state-branch \
+  --feature "{feature}" --branch "{newBranch}" --specs-dir "{specsDir}"
+```
+
 If the helper is unavailable (non-Claude host without the resolver), fall back to the manual check: current branch differs from recorded → adopt the current branch unless it is the default, in which case recommend creating `{branchPrefix}{feature}`.
 
 ## Git Commit Protocol
@@ -240,14 +264,29 @@ When `gitCommitAfterStage` is true, follow this exact order to avoid state incon
 **Why two commits.** The stage's `.pipeline-state.json` is itself part of the staged commit, but the stage's `commitHash` cannot be known until *after* that commit is made. Recording it *inside* the same commit is a chicken-and-egg with no single-commit solution. Resolve it with a **deterministic two-commit sequence**, and **never** with `git commit --amend`: amending rewrites HEAD, so a hash captured before the amend points at an orphaned commit that is not in the final history (the exact defect this protocol exists to prevent).
 
 1. **Stage specific files only:** `git add {specsDir}/{feature}/` — never use `git add -A` or `git add .`
-2. **Commit 1 — artifacts + state, hash not yet known:** In `.pipeline-state.json`, set this stage's `status: "complete"` and `commitHash: null`, then `git commit -m "{commitPrefix}({feature}): <action>"`. This is the stage's **artifact commit**; its hash is the provenance hash callers rely on.
-3. **If Commit 1 succeeds — Commit 2 records the hash:** Capture the hash of Commit 1 (`git rev-parse HEAD`). Write it into this stage's `commitHash` in `.pipeline-state.json`, then commit only that one-line change: `git add {specsDir}/{feature}/.pipeline-state.json && git commit -m "{commitPrefix}({feature}): record stage commit hash"`. The stored `commitHash` now points at the artifact commit (Commit 1) — never at Commit 2, and never at an orphaned amend. The working tree is clean afterward, so the next stage's dirty-tree check passes.
-4. **If Commit 1 fails:** do NOT update pipeline state to complete. Report the error to the user and leave state as `in-progress` so the stage can be resumed. Common failure causes:
+2. **Commit 1 — artifacts + state, hash not yet known:** Run `state-complete --feature {feature} --stage {stage} --version N …` (which sets this stage's `status: "complete"`, `completedAt`, `version`, `basedOnVersions`, `artifacts` and `commitHash: null`, and applies the downstream staleness cascade), then `git commit -m "{commitPrefix}({feature}): <action>"`. This is the stage's **artifact commit**; its hash is the provenance hash callers rely on.
+3. **If Commit 1 succeeds — Commit 2 records the hash:** Capture the hash of Commit 1 (`git rev-parse HEAD`) by running `state-complete --feature {feature} --stage {stage} --version N --commit-hash $(git rev-parse HEAD)`, which writes it into this stage's `commitHash` and touches nothing else, then commit only that one-line change: `git add {specsDir}/{feature}/.pipeline-state.json && git commit -m "{commitPrefix}({feature}): record stage commit hash"`. The stored `commitHash` now points at the artifact commit (Commit 1) — never at Commit 2, and never at an orphaned amend. The working tree is clean afterward, so the next stage's dirty-tree check passes.
+4. **If Commit 1 fails:** do NOT update pipeline state to complete. Report the error to the user and leave state as `in-progress` so the stage can be resumed. Do that with `state-complete --feature {feature} --stage {stage} --version N --resumable`, which records **only** `status` — no `completedAt`, no version bump, no `basedOnVersions`/`artifacts`, no `commitHash` reset, and no staleness cascade, so the stage stays resumable. (`--version` is still REQUIRED by argparse and must be passed even though `--resumable` does not write it; omitting it makes the recovery command exit 2 every time.) Common failure causes:
    - **Pre-commit hook failure:** Report the hook output. Never use `--no-verify` to bypass. Help the user fix the underlying issue.
    - **Merge conflicts:** Report conflicting files. Suggest resolution steps appropriate to the conflict.
-   - **Nothing to commit:** If all artifacts were already committed, this is fine — mark the stage `complete`, leave `commitHash` at its existing value (or `null` if there was never an artifact commit), and skip Commit 2. There is no new artifact commit to record.
+   - **Nothing to commit:** If all artifacts were already committed, this is fine — mark the stage `complete`, leave `commitHash` at its existing value (or `null` if there was never an artifact commit), and skip Commit 2. Pass `--preserve-commit-hash` on the Commit-1 `state-complete` call so the recorded hash is left alone instead of being reset to `null`. There is no new artifact commit to record.
 5. **Never** use `git add -A`, `--amend`, `--no-verify`, or `--force` flags
 
+The two `state-complete` calls, with the portable plugin-root prelude. Add `--epic "{epic}"` to each when this feature is an epic member — required, per the Pipeline State Protocol:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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; }
+# Commit 1 — before `git commit`
+python3 "$R/scripts/forge-session.py" state-complete \
+  --feature "{feature}" --stage "{stage}" --version {n} \
+  --based-on "<upstream>=<n>" --artifact "<file>" --specs-dir "{specsDir}"
+# Commit 2 — after Commit 1 lands, so its hash exists
+python3 "$R/scripts/forge-session.py" state-complete \
+  --feature "{feature}" --stage "{stage}" --version {n} \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
 ## Stage-Entry Guard
 
 Invoke this block at the **start of an authoring stage** (`forge-1-prd`..`forge-4-backlog`), **after** Feature Directory Resolution and **before** any interview or (re-)authoring. It prevents a re-entered stage — an injected skill body or a re-invoked `Skill` — from blindly re-running the interview over an in-progress or already-complete draft. `{stage}` is the invoking skill's id (e.g. `forge-2-tech`).
@@ -263,16 +302,27 @@ Invoke this block at the **start of an authoring stage** (`forge-1-prd`..`forge-
 
 3. **Re-authoring** (`status: "complete"` or `"stale"`) — a finished draft exists. Warn via `AskUserQuestion` before overwriting: "A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?" On confirm, proceed to the Entry Stamp and author a new version (the version increments at exit, per that stage's Update-Pipeline-State step).
 
-**Entry Stamp** (fresh, restart, and re-author paths — NOT the resume path). Before authoring, write to `{resolvedFeatureDir}/.pipeline-state.json` and update `updatedAt`:
-- `stages.{stage}.status` → `"in-progress"`
-- `stages.{stage}.startedAt` → current ISO-8601 UTC timestamp
-- top-level `currentStage` → `"{stage}"` (where the pipeline IS, per O1)
+**Entry Stamp** (fresh, restart, and re-author paths — NOT the resume path). Before authoring, record the entry stamp by running `state-enter` — one atomic write that sets `stages.{stage}.status` → `"in-progress"`, `stages.{stage}.startedAt` → current ISO-8601 UTC timestamp, top-level `currentStage` → `"{stage}"` (where the pipeline IS, per O1), and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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/forge-session.py" state-enter \
+  --feature "{feature}" --stage "{stage}" --specs-dir "{specsDir}"
+```
 
 This write is **left uncommitted**: it is staged and committed as part of this stage's existing exit commit (Git Commit Protocol), so no extra commit is needed at entry. If the run is interrupted after the stamp but before the exit commit, the marker survives on disk (uncommitted) and the next entry classifies as **Interrupted** — which is exactly the intent.
 
 **Force Mode.** When `--force` is passed, skip the interactive gate: do not prompt for resume-vs-restart or the re-author warning. Treat entry as a fresh restart — apply the Entry Stamp and author. (`--force` already skips prerequisite checks; here it likewise bypasses the self-stage gate. Existing on-disk artifacts are still loaded per Force Mode.)
 
-**Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
+**Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), run `state-artifact --feature {feature} --stage {stage} --path <file>` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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/forge-session.py" state-artifact \
+  --feature "{feature}" --stage "{stage}" --path "<file>" --specs-dir "{specsDir}"
+```
 
 ## Stage-Completion Re-check
 

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

@@ -0,0 +1,97 @@
+# Backlog Verification Checklist
+
+Detailed checklist for the **backlog** verification mode, loaded by the `forge-verifier` leaf subagent dispatched for that mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## Backlog Mode Checklist
+
+### Schema Compliance
+- [ ] **CHECK-B01**: backlog.json is valid JSON
+- [ ] **CHECK-B02**: Every item has all required fields: id, type, priority, title, description, acceptanceCriteria, status, dependsOn, specReferences
+- [ ] **CHECK-B03**: All `id` values are unique
+- [ ] **CHECK-B04**: All `type` values are valid (feature, bugfix, chore, etc.)
+- [ ] **CHECK-B05**: All `priority` values are valid numbers
+- [ ] **CHECK-B06**: All `status` values are valid (pending, in-progress, complete, etc.)
+
+### Spec Coverage
+- [ ] **CHECK-B07**: Every implementation spec document is referenced by at least one backlog item
+- [ ] **CHECK-B08**: Every P0 PRD requirement is covered by at least one backlog item's acceptance criteria
+- [ ] **CHECK-B09**: No backlog item references a spec file that doesn't exist
+- [ ] **CHECK-B10**: specReferences paths are valid relative paths to actual files
+
+### Task Quality
+- [ ] **CHECK-B11**: Each item is scoped to be completable in a single rauf loop iteration
+- [ ] **CHECK-B12**: Descriptions are detailed enough for a fresh agent with no prior context
+- [ ] **CHECK-B13**: Acceptance criteria are objectively verifiable (not subjective like "works well")
+- [ ] **CHECK-B14**: Each item specifies what files to create or modify
+
+### Dependency Ordering
+- [ ] **CHECK-B15**: `dependsOn` references are valid item IDs
+- [ ] **CHECK-B16**: No circular dependencies exist
+- [ ] **CHECK-B17**: Foundation items (types, scaffold) have no dependencies
+- [ ] **CHECK-B18**: Items that depend on types/interfaces reference the item that creates them
+- [ ] **CHECK-B19**: Priority ordering is consistent with dependency ordering (dependencies should have equal or higher priority)
+
+### Completeness
+- [ ] **CHECK-B20**: There is an item for the initial package scaffold
+- [ ] **CHECK-B21**: There is an item for shared types and error hierarchy
+- [ ] **CHECK-B22**: There are items for each major subsystem
+- [ ] **CHECK-B23**: There are items for integration wiring (not just isolated subsystems)
+- [ ] **CHECK-B24**: There are items for tests (or testing is included in each feature item's acceptance criteria)
+- [ ] **CHECK-B25**: No large items that try to do too many things (should be broken down)
+
+### Generated-Artifact Freshness
+- [ ] **CHECK-B26**: **Generated-artifact freshness vs. `testCommand` `--check` gates** (#145). When a
+  project's configured `testCommand` (forge.config.json) gates on **staleness of generated artifacts**
+  — sub-commands of the shape `<generator> --check` / `--verify` / `:check` that fail if a checked-in
+  generated file is out of date with its source — every backlog item that regenerates *one* gated
+  artifact must regenerate (and commit) **all** the sibling artifacts those same `--check` gates
+  depend on, or the item will pass locally yet red-gate on the stale-generated check. Verify
+  heuristically:
+  1. **Enumerate the gates.** String-scan `testCommand` for `--check`-style freshness sub-commands and
+     collect the generator/artifact each one guards (e.g. `build-benchmarks --check` guards
+     `partner-program-benchmarks`). If the command shape is unrecognized (no parseable `--check`
+     tokens), this check is **advisory / not-applicable** — never a hard fail.
+  2. **A gate with no regenerator.** If a `--check` gate guards an artifact that **no** backlog item
+     regenerates, and some item edits that artifact's *source*, flag a `gap`: the source change will
+     trip the freshness gate with nothing scheduled to refresh the output.
+  3. **Partial regeneration.** If an item regenerates a proper subset of the artifacts gated by the
+     `--check` set it touches (e.g. runs `build-partner-programs` + `build-analysis` but the gate also
+     covers `build-benchmarks`), flag an `inconsistency` naming the missing generator(s) and
+     recommending they be added to that item's execute + commit sequence. Same posture as the authoring
+     guidance in `forge-4-backlog` / rauf `author-backlog`: enumerate the whole `--check`-gated set, not
+     just the artifact the item is "about".
+
+### Artifact Lifecycle Consistency
+- [ ] **CHECK-B27**: **No test item forcing a lifecycle transition another item forbids** (#150).
+  *Advisory heuristic — keyword/artifact-name based; **not-applicable** when no lifecycle vocabulary is
+  present, **never** a hard fail.* A **lifecycle state** (draft / published / released / approved /
+  reviewed / signed-off / gated) is a downstream-project concept forge does not itself track — but a
+  backlog can still encode a **contradiction** about one named artifact: item A pins artifact `X` as
+  *draft* / *unpublished* / *unreviewed* while item B asserts (in its acceptance criteria or a test it
+  adds) that `X` is *published* / *released* / *approved*, with **no** publishing/review item for `X`
+  anywhere in B's dependency closure. That leaves a **test/e2e item as the only thing forcing the
+  transition** — and since the autonomous loop can neither publish a package nor stand in for a human
+  reviewer, asked to make such a test green it **fabricates** the publication or sign-off (a provenance
+  defect a `--review` pass has caught in the wild). Verify heuristically:
+  1. **Find lifecycle assertions.** Scan item titles/descriptions/`acceptanceCriteria` for a named
+     artifact paired with a lifecycle-state keyword — earlier states (`draft` / `unpublished` /
+     `pending review` / `unreleased`) vs later states (`published` / `released` / `approved` / `live` /
+     `signed-off` / `gated`). If **no** item carries such vocabulary, this check is **not-applicable**.
+  2. **Pair by artifact name.** Group assertions that reference the **same named artifact**. A pair
+     where one item requires the *earlier* state and another asserts the *later* state is a candidate.
+  3. **Check the dependency closure.** If the later-state item has **no** publish / review / human-gated
+     item for that artifact in its transitive `dependsOn`, flag an `inconsistency`: name the artifact,
+     both items, and recommend either (a) adding a `dependsOn` on an explicit human-gated publish/review
+     item that legitimately produces the state, or (b) re-asserting the state via a dev-build / fixture
+     path — never letting a test item be the sole driver of the transition (mirrors the authoring
+     guidance in `forge-4-backlog` / rauf `author-backlog`). **Report, do not repair.**
+
+  > **Anti-pattern (visible even where the heuristic can't fire):** a test/e2e item whose pass condition
+  > is "artifact `X` is published / approved / reviewed" while the backlog contains no human-gated
+  > publish or review item producing that state. The autonomous loop cannot publish or sign off on
+  > behalf of a human; asked to make such a test green it will **fabricate** the published/reviewed
+  > provenance. Any item asserting a human-gated lifecycle state must trace — via `dependsOn` — to the
+  > item that legitimately produces it, or assert the state through a dev-build / fixture path instead.
+

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

@@ -0,0 +1,79 @@
+# Epic Verification Checklist
+
+Detailed checklist for the **epic** verification mode, loaded by the `forge-verifier` leaf subagent dispatched for that mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## Epic Mode Checklist
+
+Run `epic-manifest.py validate "{epic}" --specs-dir "{specsDir}" --json` once; map its
+findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07, E09, and E10 by
+reading the manifest, EPIC.md, completed members' specs, and (for E10) sibling members'
+committed tests.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
+```
+
+### Manifest Integrity (helper-delegated)
+- [ ] **CHECK-E01**: `epic-manifest.json` conforms to `epic-manifest-schema.json`
+  (delegated: `validate` reports `schema` / `corrupt-json` findings).
+- [ ] **CHECK-E02**: the `dependsOn` graph is **acyclic** (delegated: `validate` reports
+  `cycle`).
+- [ ] **CHECK-E03**: no dangling `dependsOn` / `consumes.from` — every reference names a
+  feature in `features[]` (delegated: `validate` reports `dangling-ref`).
+- [ ] **CHECK-E08**: **global name uniqueness** across the specs tree — no feature name
+  resolves to more than one feature-shaped dir (delegated: `validate` / `check-name`
+  report `duplicate-name` / `ambiguous`). Surfaced non-fatally for manual cleanup.
+
+### Charter & Contract Coverage (verifier judgment)
+- [ ] **CHECK-E04**: **charter coverage** — every feature has a non-empty `charter`
+  stating scope **and** contract obligations (REQ-EPIC-04).
+- [ ] **CHECK-E05**: each feature has a meaningful `exposes`/`consumes` declaration — flag
+  a feature with empty contracts that the narrative implies should have them
+  (REQ-EPIC-03). (Empty is *schema-legal* but suspicious for a feature other features
+  depend on.)
+- [ ] **CHECK-E06**: **EPIC.md ⇆ manifest contract drift, for completed features only** —
+  the contracts in `EPIC.md` match the manifest `exposes`/`consumes`, and a completed
+  feature's specs actually deliver what it `exposes`. Drift between EPIC.md prose and the
+  manifest, or between the manifest and the built spec, is a finding (REQ-VERIFY-01).
+- [ ] **CHECK-E07**: **back-pointer ⇆ manifest consistency** — every member's
+  `.pipeline-state.json` `epic` value names this epic, and every `features[]` entry has a
+  matching member directory. On conflict the **manifest wins** (REQ-STATE-01); report, do
+  not auto-repair.
+- [ ] **CHECK-E09**: **open epic change requests** — any member whose `.pipeline-state.json`
+  carries `epicChangeRequests[]` entries with `status: "open"` is surfaced as a **non-fatal**
+  finding (one per open request). Severity keys off `blocksCurrent`: a **blocking** request →
+  `inconsistency` (the epic decomposition and an in-flight member disagree; specs written now
+  would build on a soon-invalid premise), a **non-blocking** request → `improvement` (a
+  peer/downstream change to reconcile when convenient). Name the request's `kind`, `target`,
+  and `rationale`, and point at `/feature-forge:forge-0-epic {epic}` to reconcile. **Report, do
+  not repair** (same posture as CHECK-E07). Which members have open requests comes from the
+  same `render-status --json` counts the navigator uses (`features[].openEpicChangeRequests` /
+  `.blockingEpicChangeRequests`); the per-request `kind`/`target`/`rationale` detail is read
+  from the member `.pipeline-state.json` already loaded in Step 2. This is the pre-emptive
+  surface for the divergence class CHECK-E06/E07 otherwise catch only after the fact.
+- [ ] **CHECK-E10**: **cross-member shared-state test coupling** (#144). A member that writes or
+  migrates a file a *sibling's* committed tests already pin will break the sibling's suite the
+  moment it runs — blocking every one of its own commits from a green test gate — yet nothing in
+  E04–E09 catches it (contracts cover code symbols, not shared data files). Detect it heuristically,
+  per member `M`:
+  1. **Collect `M`'s mutated paths.** Take `M`'s `mutatesShared[]` from the manifest if present
+     (the authored precision hint). If absent or empty, fall back to grepping `M`'s specs
+     (change-maps / "files this writes") and backlog item `execute` steps for project-root-relative
+     paths it creates, writes, or migrates (data corpora, generated fixtures, migration outputs —
+     not `M`'s own source modules or its own tests).
+  2. **Grep sibling tests for reads of those paths.** For every *other* member `S` that is already
+     **`complete`** (derived status — its regression suite is live and gating), grep `S`'s committed
+     **test** files/globs for a read/import/load of any path in step 1. Use the stack profile
+     (`references/stacks/{stack}.md`) for what a test glob looks like in this language.
+  3. **Emit the finding.** A hit → a non-fatal `inconsistency` finding: name `M`, the shared path,
+     the sibling `S` and the specific test, and **recommend a reconciliation backlog item** on `M`
+     (regenerate/re-pin `S`'s fixture, or update `S`'s test to the new shape) scheduled *before*
+     `M`'s first mutating item — so the coupling is planned, not discovered mid-loop on a red gate.
+     **Report, do not repair** (same posture as CHECK-E07/E09). Degrades to a clean no-op when no
+     member declares or greps a shared write, or when no completed sibling reads it — never a
+     spurious hard-fail.
+

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

@@ -0,0 +1,48 @@
+# Implementation Verification Checklist
+
+Detailed checklist for the **impl** verification mode, loaded by the `forge-verifier` leaf subagent dispatched for that mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## Implementation Mode Checklist
+
+### Spec Compliance
+- [ ] **CHECK-I01**: Every file listed in 01-architecture-layout.md exists
+- [ ] **CHECK-I02**: Package.json exports map matches what the spec describes
+- [ ] **CHECK-I03**: Every type in 00-core-definitions.md is implemented
+- [ ] **CHECK-I04**: Every error class is implemented with correct properties
+
+### Backlog Completion
+- [ ] **CHECK-I05**: Every backlog item marked "complete" has its acceptance criteria met
+- [ ] **CHECK-I06**: No backlog items are still "pending" or "in-progress"
+- [ ] **CHECK-I07**: Acceptance criteria can be verified by reading the code
+
+### Integration
+- [ ] **CHECK-I08**: Import paths work (no broken imports)
+- [ ] **CHECK-I09**: Module exports/entry points re-export everything the spec says they should
+- [ ] **CHECK-I10**: Types shared with other packages are compatible
+- [ ] **CHECK-I11**: Type checking / linting passes for the module (`{typeCheckCommand}` from forge.config.json succeeds)
+- [ ] **CHECK-I12**: Type checking / linting passes for modules that depend on this one
+
+### Code Quality
+- [ ] **CHECK-I13**: No placeholder or TODO comments that should have been resolved
+- [ ] **CHECK-I14**: Error handling matches what the specs describe
+- [ ] **CHECK-I15**: No hardcoded values that should be configurable
+- [ ] **CHECK-I16**: Tests exist and pass
+- [ ] **CHECK-I17**: No obvious missing test cases for documented edge cases
+
+### Documentation
+- [ ] **CHECK-I18**: Package has a README or the docs directory has been populated
+- [ ] **CHECK-I19**: Exported functions/classes have documentation comments (JSDoc, docstrings, godoc, etc.)
+- [ ] **CHECK-I20**: Configuration options are documented
+
+### Runnability
+
+> **When these fire:** only at impl-verify **completion** (impl mode runs post-loop), never mid-loop — an early skeleton that only compiles is not punished. **Both degrade gracefully:** a feature with no runnable surface (a pure library with no bootstrap contract) or no configured `smokeCommand` yields an **advisory not-applicable** finding, never a hard fail — the same way a null `{typeCheckCommand}` is handled. These exist because `CHECK-I01..I20` are all static reads + typecheck/lint + "tests exist"; nothing here asserts the assembled application actually **runs**. A bootstrap that is exported and unit-tested (each test calls it manually) but never wired into a runtime entrypoint passes every other check yet serves no real request (#121).
+
+- [ ] **CHECK-I21**: **End-to-end smoke passes.** If `smokeCommand` from forge.config.json is set, execute it — it boots the wired entrypoint and drives one happy-path request end-to-end; **pass iff exit 0**. A non-zero exit is an `error` finding (the assembled app does not run — quote the command's failing output). If `smokeCommand` is `null`, this is **advisory**: emit a `not-applicable` finding recommending the user configure a `smokeCommand` so "clean" means "it runs" (never fabricate or guess a command — run only the user-configured one, exactly as `CHECK-I11` runs only a configured `{typeCheckCommand}`).
+  - **Prefer the dev runtime the developer actually uses (#149).** Recommend the configured `smokeCommand` boot the app in its **development** mode — the dev server / watch loop / HMR runtime — not only a clean production build. The failure modes that a static typecheck and a prod smoke both miss live in the dev runtime: **module-graph-identity** bugs (a "singleton" duplicated across a re-evaluated module graph, so the initialized instance and the one the request path reads are different objects) and **watch-loop** bugs (an init that fires once but never re-fires on hot reload, or fires on every reload and leaks). A prod build evaluates the graph once and hides both. When the project is served in dev during development, the `smokeCommand` should exercise that same runtime.
+  - **For a fix, re-verify in the mode the bug manifested.** When impl-verify runs after a **fix** (not a greenfield build), re-run the smoke in the **same runtime mode where the original bug appeared** — a bug reproduced in dev/watch mode is not proven fixed by a green prod-mode smoke, and vice versa. Note the mode in the finding so "smoke passed" is unambiguous about *which* runtime was exercised.
+- [ ] **CHECK-I22**: **Runtime-required bootstrap has a non-test caller.** Every exported bootstrap / `init*` / singleton-populator the specs mark as **required for runtime** must have ≥1 **non-test** call site on a runtime path — an entrypoint such as `main` / `instrumentation` / a route / a layout / a worker, NOT only test files. Statically grep for each such symbol's references (use the stack profile `references/stacks/{stack}.md` **Runtime Entrypoints & Bootstrap-Wiring Sites** list for what counts as a runtime entrypoint in this language). A symbol that is exported and covered by tests but referenced **only** from test files is a `gap` — the #121 walking-skeleton (bootstrap wired to nothing). Degrades naturally: a feature whose specs mark no bootstrap symbol as runtime-required is `not-applicable`. Weaker than `CHECK-I21` (it proves a call site exists, not that the boot succeeds), so it complements rather than replaces the smoke.
+- [ ] **CHECK-I23**: **Heavy bootstrap wired into a universal startup entry — recommend lazy init** (#149). *Advisory heuristic — a `gap`/`improvement` at most, **never** a hard fail.* When a runtime-required `init`/bootstrap/singleton-populator is wired into a **framework bootstrap entry that runs on every startup** (a Next.js `instrumentation.ts`, an app-server preload/`register` hook, a global setup module) **and** that init pulls in a **large server-only import graph** (DB clients, ORMs, queue/background workers, telemetry exporters, the whole service layer), recommend moving to **lazy initialization at the entry that already loads that graph** — the first route / handler / worker that needs it — rather than eager wiring at the universal entry. Eager wiring drags the heavy graph into every cold start, and in dev into every module re-evaluation (the watch-loop cost `CHECK-I21` also targets). **Detect statically:** from the stack profile's **Runtime Entrypoints & Bootstrap-Wiring Sites** list, identify this stack's universal bootstrap entries; grep those files for imports of the feature's runtime-required bootstrap symbols (`CHECK-I22`) and for the server-only heavy-import markers the profile names. A match → an `improvement`/`gap` finding naming the entry, the heavy graph it pulls, and the lazier call site to move initialization to. Degrades to `not-applicable` when the stack has no universal bootstrap entry, when no heavy init is wired there, or when the profile lists no bootstrap-wiring sites — **report, do not repair.**
+

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

@@ -0,0 +1,31 @@
+# PRD Verification Checklist
+
+Detailed checklist for the **prd** verification mode, loaded by the `forge-verifier` leaf subagent dispatched for that mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## PRD Mode Checklist
+
+### Completeness
+- [ ] **CHECK-P01**: All template sections from `references/prd-template.md` are populated
+- [ ] **CHECK-P02**: No TBD or TODO placeholders remain in the document
+- [ ] **CHECK-P03**: Out-of-scope section exists and is specific (not just "everything else")
+- [ ] **CHECK-P04**: Open questions section contains only actionable items (not vague concerns)
+- [ ] **CHECK-P05**: Success criteria are measurable and verifiable
+
+### Requirement Quality
+- [ ] **CHECK-P06**: Every requirement has a unique ID (REQ-XXX-NN format)
+- [ ] **CHECK-P07**: Every requirement has a priority assigned (P0/P1/P2)
+- [ ] **CHECK-P08**: Every requirement is testable/verifiable — could you write an acceptance test for it?
+- [ ] **CHECK-P09**: No requirements contain technology decisions (specific libraries, frameworks, or implementation choices) unless clearly labeled as constraints with justification
+- [ ] **CHECK-P10**: User stories cover all identified actors/personas
+
+### Non-Functional Requirements
+- [ ] **CHECK-P11**: Non-functional requirements are quantified where applicable (latency targets, uptime SLAs, throughput minimums)
+- [ ] **CHECK-P12**: Security requirements are explicit, not assumed
+- [ ] **CHECK-P13**: Constraints section distinguishes mandates (must) from preferences (should/nice-to-have)
+
+### Open-Ended Analysis
+- [ ] **CHECK-P14**: Are there implicit requirements that should be made explicit? (e.g., assumptions about authentication, authorization, data retention)
+- [ ] **CHECK-P15**: Are there requirement conflicts or tensions? (e.g., performance vs. completeness, simplicity vs. flexibility)
+

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

@@ -0,0 +1,64 @@
+# Specs Verification Checklist
+
+Detailed checklist for the **specs** verification mode, loaded by the `forge-verifier` leaf subagent dispatched for that mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## Specs Mode Checklist
+
+### Requirement Coverage
+- [ ] **CHECK-S01**: Every PRD requirement (REQ-XXX-NN) is referenced by at least one implementation spec
+- [ ] **CHECK-S02**: Every P0 (must-have) requirement has detailed implementation guidance, not just a mention
+- [ ] **CHECK-S03**: Every P1 requirement is at least acknowledged with an implementation approach
+- [ ] **CHECK-S04**: No implementation spec sections exist that don't trace to a PRD requirement or tech-spec decision (orphaned specs indicate scope creep)
+
+### Tech Spec ↔ Implementation Spec Consistency
+- [ ] **CHECK-S05**: Every technology decision in the tech spec is reflected in the implementation specs
+- [ ] **CHECK-S06**: Package structure in 01-architecture-layout.md matches what the tech spec describes
+- [ ] **CHECK-S07**: Dependencies listed in the tech spec match those in the architecture spec
+- [ ] **CHECK-S08**: No implementation spec contradicts a tech-spec decision
+
+### Type System Integrity
+- [ ] **CHECK-S09**: All type definitions in 00-core-definitions.md are valid syntax in the project's language (not pseudocode)
+- [ ] **CHECK-S10**: All types referenced in other spec docs are defined in 00-core-definitions.md or an explicit external package
+- [ ] **CHECK-S11**: Error classes form a consistent hierarchy with no gaps
+- [ ] **CHECK-S12**: No duplicate or conflicting type definitions across documents
+- [ ] **CHECK-S13**: Every type/interface/struct has documentation comments on every field (JSDoc, docstrings, godoc, etc.)
+
+### Cross-Reference Consistency
+- [ ] **CHECK-S14**: All file references between spec documents point to actual files
+- [ ] **CHECK-S15**: Section references (e.g., "see section 3.2 of 02-provider-registry.md") point to actual sections
+- [ ] **CHECK-S16**: Dependency ordering between spec docs is consistent (no circular dependencies)
+- [ ] **CHECK-S17**: Import paths referenced in specs are consistent with the exports map in 01-architecture-layout.md
+
+### Error Handling Coverage
+- [ ] **CHECK-S18**: Every operation that can fail has an error type defined
+- [ ] **CHECK-S19**: Error propagation is described: where errors are thrown, caught, transformed, and surfaced
+- [ ] **CHECK-S20**: User-facing error messages are specified (not just error codes)
+- [ ] **CHECK-S21**: Recovery behavior is described for recoverable errors
+
+### Integration Point Completeness
+- [ ] **CHECK-S22**: Every package listed in the tech spec's integration section has corresponding detail in the implementation specs
+- [ ] **CHECK-S23**: For each integration: the shared types/contracts are explicitly named
+- [ ] **CHECK-S24**: For each integration: data flow direction is clear
+- [ ] **CHECK-S25**: If integration requires changes to existing packages, those changes are specified
+- [ ] **CHECK-S26**: Import paths match actual package export maps
+
+### Edge Cases and Non-Functional
+- [ ] **CHECK-S27**: Concurrent access scenarios are addressed if relevant
+- [ ] **CHECK-S28**: Empty/null/undefined inputs are handled
+- [ ] **CHECK-S29**: Performance-sensitive paths are identified
+- [ ] **CHECK-S30**: Security considerations from PRD are reflected in implementation
+- [ ] **CHECK-S31**: Observability (logging, metrics, tracing) approach is specified if PRD requires it
+- [ ] **CHECK-S32**: Each implementation spec has a clear "public API" section that defines what is exported vs internal
+
+### Testing Strategy
+- [ ] **CHECK-S33**: Testing strategy document exists
+- [ ] **CHECK-S34**: Test approach covers unit, integration, and e2e as appropriate
+- [ ] **CHECK-S35**: Mock/fixture strategy is defined for external dependencies
+- [ ] **CHECK-S36**: Coverage targets are stated
+- [ ] **CHECK-S37**: Test fixtures and mocks defined in specs align with real interface shapes from 00-core-definitions.md
+
+### Traceability
+- [ ] **CHECK-S38**: Build a complete traceability matrix from every REQ-XXX-NN to the spec document and section that implements it. Any REQ ID not found in at least one spec is a gap finding.
+

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

@@ -0,0 +1,35 @@
+# Tech-Spec Verification Checklist
+
+Detailed checklist for the **tech** verification mode, loaded by the `forge-verifier` leaf subagent dispatched for that mode. Execute EVERY check — do not skip.
+
+> **Stack-specific details:** When a stack profile exists at `references/stacks/{stack}.md`, load it alongside this checklist for language-specific check criteria (e.g., what "valid syntax" means, what the type check command is, how module exports work).
+
+## Tech-Spec Mode Checklist
+
+### Requirement Traceability
+- [ ] **CHECK-T01**: Every tech decision traces to at least one PRD requirement (REQ-XXX-NN)
+- [ ] **CHECK-T02**: No tech decisions contradict PRD constraints
+- [ ] **CHECK-T03**: Every P0 PRD requirement has a corresponding tech decision or is explicitly deferred with rationale
+
+### Integration Analysis
+- [ ] **CHECK-T04**: Integration analysis section is complete — all packages identified
+- [ ] **CHECK-T05**: Import paths and function signatures are verified against actual source code
+- [ ] **CHECK-T06**: For each integration point: shared types/contracts are explicitly named
+- [ ] **CHECK-T07**: For each integration point: data flow direction is clear
+- [ ] **CHECK-T08**: Changes required to existing packages are specified
+
+### Design Quality
+- [ ] **CHECK-T09**: Alternatives considered for major decisions (not just "we chose X")
+- [ ] **CHECK-T10**: Error handling strategy is defined (error types, propagation, recovery)
+- [ ] **CHECK-T11**: Testing approach is specified (unit, integration, e2e strategy)
+- [ ] **CHECK-T12**: Data model aligns with PRD data requirements
+
+### Completeness
+- [ ] **CHECK-T13**: Package/module structure is defined with exports map
+- [ ] **CHECK-T14**: Configuration approach is specified
+- [ ] **CHECK-T15**: Migration/deployment considerations are addressed if applicable
+
+### Open-Ended Analysis
+- [ ] **CHECK-T16**: Are there integration points that could cause implementation surprises? (e.g., undocumented behavior, version incompatibilities, missing APIs)
+- [ ] **CHECK-T17**: Are there scalability concerns unaddressed by the current design? (e.g., data growth, concurrent users, resource limits)
+

package/adapters/pi/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "agent": "pi",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/pi/agents/forge-verifier.md

@@ -27,7 +27,7 @@ You have READ-ONLY access. You cannot and should not modify any files. Your outp
 
 1. Read the pipeline state file to understand what stage the feature is at
 2. Load all relevant artifacts for the current verification mode
-3. Execute every check in the verification checklists (loaded via the forge-verify skill)
+3. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
 4. Return structured findings as your response in the Output Format specified below
 5. Generate a fix plan suitable for a fresh agent to execute
 

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

@@ -33,7 +33,7 @@
     "currentStage": {
       "type": "string",
       "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
-      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` here means the whole pipeline is done. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
+      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` is a LEGACY enum value, retained so pre-0.14 state files still validate: no writer produces it (the `state-*` verbs are the only writers, and only `state-enter` touches this field, setting it to the stage being entered). A finished pipeline therefore records the last stage it started — `forge-6-docs` — and 'the whole pipeline is done' is DERIVED too: `next_stage()` returns null (surfaced as `nextStage: null` / `complete: true`). Never test this field against `complete` to decide whether a pipeline finished. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
     },
     "notes": {
       "type": "string",