@garygentry/feature-forge 0.2.13 → 0.3.0

package/adapters/gemini/skills/forge-3-specs/references/stacks/go.md

@@ -84,6 +84,25 @@ When examining a Go project, check for:
 - **Formatting**: `gofmt -l .` or `goimports -l .` (should produce no output)
 - **Module tidiness**: `go mod tidy` (ensures `go.mod` and `go.sum` are consistent)
 
+### 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):** `func main()` in a `package main` under
+  `cmd/…` or the module root, an HTTP handler registered on a `*http.ServeMux` / router, a gRPC service
+  registration, or a worker/consumer goroutine started from `main` — not a `*_test.go` file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package-level
+  `func init()` that constructs heavy clients, package-level `var` initializers that dial/connect at
+  import time, or a single `bootstrap`/`wire` module `main` calls before serving. `init()` and
+  package-var side effects run on **every** binary start, before `main` gets control.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB drivers/pools
+  (`database/sql` + a driver, `pgx`, `gorm`, `mongo-driver`), message/queue clients (`sarama`/Kafka,
+  `amqp`, `go-redis`), telemetry SDKs (`go.opentelemetry.io/*`, `sentry-go`), or a broad internal
+  service package. An `init()` or package-var that dials any of these is the CHECK-I23 pattern —
+  recommend a `sync.Once` lazy constructor invoked from the first handler that needs it, not an
+  eager package-level connect.
+
 ## Testing
 
 - **Framework**: `testing` stdlib package

package/adapters/gemini/skills/forge-3-specs/references/stacks/python.md

@@ -111,6 +111,27 @@ async def refresh_session_token(
 - **Import validation**: `mypy` with `--strict` or `--disallow-untyped-defs` catches missing type annotations
 - **Module export validation**: `__all__` lists in `__init__.py` match spec's public API
 
+### 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 `if __name__ == "__main__":` block, a
+  `[project.scripts]` console-script target in `pyproject.toml`, an ASGI/WSGI app object
+  (`app = FastAPI()` / Django `wsgi.py` / `asgi.py`), a route/view/handler, a Celery/RQ task module, or
+  a management command — not a `test_*.py` / `conftest.py`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package
+  `__init__.py` that eagerly instantiates heavy clients at import time, a framework startup hook
+  (FastAPI `lifespan` / `@app.on_event("startup")`, Django `AppConfig.ready()`, a Gunicorn/uvicorn
+  `--preload` module), or a `conftest.py` that bootstraps production graphs. Import-time side effects
+  here run on every process start.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM engines
+  (`sqlalchemy.create_engine`, `psycopg`, Django ORM, `pymongo`, `redis`), task queues (`celery`,
+  `rq`, `kafka`), telemetry SDKs (`opentelemetry`, `sentry_sdk`), or a whole-service-layer package
+  import. An init pulling any of these at a universal entry is the CHECK-I23 pattern — recommend lazy
+  init (module-level `@lru_cache` factory, `Depends()` provider, or first-use lazy import) at the
+  handler that needs it.
+
 ## Testing
 
 - **Framework**: pytest (with `conftest.py` for fixtures)

package/adapters/gemini/skills/forge-3-specs/references/stacks/rust.md

@@ -90,6 +90,25 @@ When examining a Rust project, check for:
 - **Formatting**: `cargo fmt --check` (ensures code matches `rustfmt` style)
 - **Unsafe audit**: `cargo geiger` (if security-sensitive — counts unsafe blocks)
 
+### 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):** `fn main()` in `main.rs` or a `[[bin]]`
+  target, an async runtime entry (`#[tokio::main]`), an HTTP handler registered on an axum/actix/warp
+  router, or a worker task spawned from `main` — not a `#[cfg(test)]` module or a `tests/` integration
+  file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a `lazy_static!`
+  / `once_cell::sync::Lazy` static that eagerly constructs heavy clients, a single `bootstrap`/`setup`
+  fn `main` calls before serving, or a `#[ctor]`-style pre-`main` initializer. A `Lazy` static is only
+  a risk when it is *forced* at startup rather than on first use.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB pools
+  (`sqlx::Pool`, `diesel`, `deadpool`, `mongodb`), message/queue clients (`rdkafka`, `lapin`,
+  `redis`), telemetry SDKs (`opentelemetry`, `sentry`), or a broad internal service crate. Constructing
+  any of these eagerly at a universal entry is the CHECK-I23 pattern — recommend a `OnceCell`/`Lazy`
+  forced on **first use** by the handler that needs it, not at process start.
+
 ## Testing
 
 - **Framework**: Built-in test harness (`#[test]`, `#[cfg(test)]`)

package/adapters/gemini/skills/forge-3-specs/references/stacks/typescript.md

@@ -64,6 +64,29 @@ When examining a TypeScript project, check for:
 - **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

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

@@ -93,6 +93,9 @@ After presenting the plan as text, use the host's question mechanism following t
 
 **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).
+- **Epic members — cross-member shared-state coupling (#144).** When authoring the backlog for an epic member, check whether this feature writes or migrates a file that a *sibling* member's already-shipped tests pin (its `mutatesShared[]` hint in `epic-manifest.json`, or a shared data corpus / generated fixture its specs say it mutates). If so, schedule a **reconciliation item up front** — before the first mutating item — that regenerates or re-pins the sibling's fixture (or updates the sibling test to the new shape), so the sibling suite stays green instead of red-gating every commit mid-loop. This is the authoring counterpart to forge-verify's CHECK-E10.
+- **Generated-artifact freshness vs. `testCommand` `--check` gates (#145).** If the project's `testCommand` gates on staleness of generated artifacts (`<generator> --check`-style sub-commands that fail when a checked-in generated file is out of date), then any item that regenerates **one** such artifact must regenerate **and commit all** the sibling artifacts those `--check` gates depend on — enumerate the whole gated set, not just the artifact the item is "about", or the item passes locally yet red-gates on the stale-generated check. Pass this to `author-backlog` alongside `testCommand` so the full regeneration sequence lands in each affected item; forge-verify's CHECK-B26 flags a partial set or an ungated regenerator after the fact.
+- **Lifecycle-gated artifacts — no test item forcing a forbidden transition (#150).** A test/e2e item whose acceptance asserts a *published / released / approved / human-reviewed* artifact state must either (a) `dependsOn` an explicit, human-gated publish/review item that legitimately produces that state, or (b) assert the state via a **dev-build / fixture path**. A test item must **never** be the only thing forcing a lifecycle transition another item pins the other way (e.g. one item keeps artifact `X` *draft* while a test demands it *published*, with nothing between to publish it) — the loop, unable to publish or obtain a human sign-off, will **fabricate** the provenance. `author-backlog` owns the general rule; forge-verify's CHECK-B27 flags a contradictory pair with no publisher in the dependency closure after the fact.
 
 > **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.
 
@@ -130,6 +133,8 @@ State that the backlog is ready and invite adjustments before committing — a s
 
 ## Step 7: Update Pipeline State and Commit
 
+Before writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references/shared-conventions.md` with `{stage}` = `forge-4-backlog` — a resumed mid-stage continuation must not overwrite a committed `backlog.json` or re-fire a finished exit.
+
 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`:

package/adapters/gemini/skills/forge-4-backlog/references/forge-config-schema.json

@@ -217,8 +217,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.12.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.12.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.12.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.13.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.13.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.13.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **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.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-5-loop/forge-5-loop.md

@@ -151,7 +151,7 @@ Use the host's question mechanism to present the rendered run command and option
 ```
 Ready to run the loop for {feature}:
 
-  {rendered runCommand}
+  {rendered runCommand}   # + " --review" when the recommended Run-mode option (below) is picked
 
 Backlog summary:
   - Pending: {pending}
@@ -160,15 +160,13 @@ Backlog summary:
   - Blocked: {blocked}
   - Iterations: {iterationCount} ({activeItems} items x {loopIterationMultiplier} multiplier)
 
-Optional flags you can add (rauf): --review, --model <model>, --timeout <min>,
---retry-blocked. For the full optional-flags catalog and the model-selection
-precedence (item.model > --model/options > project default > provider default),
-read references/runner-contract.md.
-
-Proceed with this command, or would you like to adjust?
+For the model-selection precedence (item.model > --model/options > project default >
+provider default) and the full optional-flags catalog, read references/runner-contract.md.
 ```
 
-For the full loop-runner contract — event-stream vs. log-fallback launch, the live-supervision/monitor rules, and the model-selection precedence — read `references/runner-contract.md`. If the user requests additional flags, append them to the rendered run command.
+**Run mode (gated on `loopRunner.name == "rauf"`).** When the runner is rauf, add a **"Run mode"** question to this same the host's question mechanism surface with these options **in this exact order** (do NOT improvise — deterministic ordering is the point): **(1) "Run with review pass (recommended)"** — append `--review`, and this is the default; **(2) "Run without review"** — the bare rendered command; **(3, only when 2a counted blocked items) "Review + retry blocked"** — append `--review --retry-blocked`. the host's question mechanism's built-in "Other" covers ad-hoc flags (`--model`/`--timeout`); add no separate open-ended option. The command line shown above renders `--review` (the recommended default). **When the runner is not rauf**, add NO Run-mode question — present the bare rendered command and let the user adjust via "Other" (byte-identical to today). Verbatim option labels: `## Run mode (Step 2d, rauf)` in `references/runner-contract.md`.
+
+For the full loop-runner contract — event-stream vs. log-fallback launch, the live-supervision/monitor rules, and the model-selection precedence — read `references/runner-contract.md`. Whichever Run-mode option (or "Other") the user picks, append its flags to the rendered run command before Step 3.
 
 #### Agent selection (gated on `loopRunner.agentArgument`)
 
@@ -179,7 +177,7 @@ For the full loop-runner contract — event-stream vs. log-fallback launch, the
 - **(c) Availability listing.** From the **same** parsed `agents[]` (no second probe), list `id` / `displayName` / available (`yes`/`no`, `detail` on unavailable rows).
 - **(d) Verdict** — only for a **non-default** resolved agent (default path `None`/`claude-cli` → no probe, byte-identical to today). Classify by **membership** then `available` (never by exit code): **UNKNOWN** (`∉` set) → **hard-reject BEFORE any loop side-effect**, error lists the **sorted** valid ids, **NO proceed-anyway**; **UNAVAILABLE** (member, `available False`) → warn with `detail`, the host's question mechanism offering **proceed-anyway OR choose-another** (re-presents the same `agents[]`), never silent; **AVAILABLE** → proceed, the validated id fills `{agent}`; **probe failure** (non-zero exit / unparseable / missing or empty `agents[]` / row lacking `id`) → surface it, offer **choose-another OR abort**, **never launch the non-default agent unvalidated** and never silently fall back to the default.
 - **(d-model) Claude-only model-alias guard.** Runs **only** when the resolved agent is **non-default** (not the default / `claude-cli` path). Read the backlog.json (Step 1e path); collect items whose `model` is a **Claude-specific alias** (tier `opus`/`sonnet`/`haiku` or a `claude-*` id). **If none, skip silently.** Otherwise warn before launch via the host's question mechanism (NOT prose): `item.model` outranks `--agent`, so the alias is forwarded verbatim to `{agent}`, which will likely reject it (e.g. codex 400 *"The 'sonnet' model is not supported…"*) — every spawn exits 1 and rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the cause. Offer: **(1) Strip `model` for this run (recommended)** — rewrite backlog.json removing the `model` key from each affected item (persistent edit; re-run forge-4-backlog to restore), then proceed; **(2) Proceed as-is** — only safe if `{agent}` understands the pinned ids. forge touches only `model`, never `provider`. Full rationale: `references/runner-contract.md`.
-- **(e) Optional-flags line.** Replace the confirmation's optional-flags line with one that lists `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
+- **(e) Optional-flags line.** Augment the confirmation block's closing flags/precedence pointer to list `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
 - **(f) Resolved-agent line.** Add to the confirmation block: `Agent: {resolved.agent or claude-cli} (source: {sourceLabel})` — `sourceLabel`: `RUN` → `"per-run selection"`, `PROJECT` → `"project default (loopRunner.defaultAgent)"`, `DEFAULT` → `"runner default — claude-cli"`.
 
 ## Step 3: Execute the Loop

package/adapters/gemini/skills/forge-5-loop/references/forge-config-schema.json

@@ -217,8 +217,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.12.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.12.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.12.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.13.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.13.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.13.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

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

@@ -109,6 +109,47 @@ default / `claude-cli` path skips this guard (the aliases are valid there).
 > feature-forge's launch-time export is the mitigation; the upstream fix lives in the
 > rauf plugin/repo. Track as a follow-up.
 
+## Run mode (Step 2d, rauf)
+
+**Applies only when `loopRunner.name == "rauf"`.** rauf's `--review` runs a review
+pass after all iterations complete (an extra agent session that re-examines the
+finished work and can file follow-up backlog items). feature-forge treats **running
+with review as the recommended default** — a review pass is cheap relative to the
+loop it audits, and catches gaps before the pipeline moves on to docs. So Step 2d
+adds a **"Run mode"** question to the confirmation's `AskUserQuestion` surface with a
+**fixed, non-improvised option order** (determinism is the point — the option set
+must not vary run-to-run):
+
+```
+Run mode:
+  1. Run with review pass (recommended)   → append `--review`   [DEFAULT]
+     After all iterations, a review agent re-examines the finished work and may
+     file follow-up items. Recommended for every forge run.
+  2. Run without review                    → bare rendered command
+     Skip the review pass — iterations only, no post-run audit.
+  3. Review + retry blocked                → append `--review --retry-blocked`
+     ONLY offered when Step 2a counted one or more `blocked` items. Runs the
+     review pass and also unblocks/retries the previously blocked items.
+```
+
+Notes:
+
+- **Option 1 is the default** and the confirmation's rendered command line shows
+  `--review` appended. On any pick, append the option's flags to the rendered run
+  command before Step 3 (launch).
+- **`AskUserQuestion`'s built-in "Other"** already lets the user type ad-hoc flags
+  (`--model <model>`, `--timeout <min>`, or any combination) — do **not** add a
+  separate open-ended option for that.
+- **Option 3 is conditional.** Include it only when the Step 2a tally has `blocked
+  > 0`; otherwise present options 1 and 2 only.
+- **Version floor.** rauf's explicit `review` signal ships in 0.5.0, below the
+  `minRunnerVersion` floor (0.6.0) enforced at gate 1c — so `--review` is always
+  available once the loop is cleared to launch. No extra version check is needed.
+- **Non-rauf runners.** When `loopRunner.name != "rauf"`, add **no** Run-mode
+  question — present the bare rendered command and let the user adjust via "Other",
+  byte-identical to the pre-review-default behavior. `--review` is a rauf-specific
+  flag; a swapped-in runner conforming to the contract need not support it.
+
 ## Optional flags catalog (Step 2d, rauf)
 
 These are the optional flags the user may add to the rendered run command. If the

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **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.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **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.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **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.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-guide/references/forge-config-schema.json

@@ -217,8 +217,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.12.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.12.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.12.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.13.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.13.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.13.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **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.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/gemini/skills/forge-guide/references/stacks/_generic.md

@@ -79,6 +79,27 @@ Replace stack-specific checks with these generic equivalents:
 | "JSDoc on every field" | "Documentation comments on every field" |
 | "tsconfig.json extends root" | "Build configuration follows project conventions" |
 
+### 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).
+Since no dedicated profile applies, identify these by role rather than exact filename:
+
+- **Runtime entrypoints (a legitimate non-test call site):** the process/main entry the build's
+  run command actually launches (from the CI/`Makefile`/manifest "start" target), an HTTP/RPC handler
+  or route, a scheduled/worker task, or a CLI subcommand — **not** a file in the project's test
+  directory or matching its test-file convention.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** any
+  module/hook the framework runs **once per process before serving** — a startup/lifecycle hook, an
+  import-time initializer, a global preload, or a shared test-setup module that bootstraps production
+  graphs. Side effects here run on every process start (and, under a dev/watch runtime, on every
+  reload).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** database/ORM
+  clients and connection pools, message/queue clients, telemetry/observability SDKs, or a broad
+  whole-service-layer import. An init pulling any of these into a universal bootstrap entry is the
+  CHECK-I23 pattern — recommend lazy initialization at the first handler/worker that needs the graph,
+  not eagerly at process start.
+
 ## Acceptance Criteria Patterns
 
 Use these placeholder patterns in backlog items. Replace `{typeCheckCommand}`, `{testCommand}`, and `{module}` with values from `forge.config.json` and the project structure:

package/adapters/gemini/skills/forge-guide/references/stacks/go.md

@@ -84,6 +84,25 @@ When examining a Go project, check for:
 - **Formatting**: `gofmt -l .` or `goimports -l .` (should produce no output)
 - **Module tidiness**: `go mod tidy` (ensures `go.mod` and `go.sum` are consistent)
 
+### 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):** `func main()` in a `package main` under
+  `cmd/…` or the module root, an HTTP handler registered on a `*http.ServeMux` / router, a gRPC service
+  registration, or a worker/consumer goroutine started from `main` — not a `*_test.go` file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package-level
+  `func init()` that constructs heavy clients, package-level `var` initializers that dial/connect at
+  import time, or a single `bootstrap`/`wire` module `main` calls before serving. `init()` and
+  package-var side effects run on **every** binary start, before `main` gets control.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB drivers/pools
+  (`database/sql` + a driver, `pgx`, `gorm`, `mongo-driver`), message/queue clients (`sarama`/Kafka,
+  `amqp`, `go-redis`), telemetry SDKs (`go.opentelemetry.io/*`, `sentry-go`), or a broad internal
+  service package. An `init()` or package-var that dials any of these is the CHECK-I23 pattern —
+  recommend a `sync.Once` lazy constructor invoked from the first handler that needs it, not an
+  eager package-level connect.
+
 ## Testing
 
 - **Framework**: `testing` stdlib package

package/adapters/gemini/skills/forge-guide/references/stacks/python.md

@@ -111,6 +111,27 @@ async def refresh_session_token(
 - **Import validation**: `mypy` with `--strict` or `--disallow-untyped-defs` catches missing type annotations
 - **Module export validation**: `__all__` lists in `__init__.py` match spec's public API
 
+### 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 `if __name__ == "__main__":` block, a
+  `[project.scripts]` console-script target in `pyproject.toml`, an ASGI/WSGI app object
+  (`app = FastAPI()` / Django `wsgi.py` / `asgi.py`), a route/view/handler, a Celery/RQ task module, or
+  a management command — not a `test_*.py` / `conftest.py`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package
+  `__init__.py` that eagerly instantiates heavy clients at import time, a framework startup hook
+  (FastAPI `lifespan` / `@app.on_event("startup")`, Django `AppConfig.ready()`, a Gunicorn/uvicorn
+  `--preload` module), or a `conftest.py` that bootstraps production graphs. Import-time side effects
+  here run on every process start.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM engines
+  (`sqlalchemy.create_engine`, `psycopg`, Django ORM, `pymongo`, `redis`), task queues (`celery`,
+  `rq`, `kafka`), telemetry SDKs (`opentelemetry`, `sentry_sdk`), or a whole-service-layer package
+  import. An init pulling any of these at a universal entry is the CHECK-I23 pattern — recommend lazy
+  init (module-level `@lru_cache` factory, `Depends()` provider, or first-use lazy import) at the
+  handler that needs it.
+
 ## Testing
 
 - **Framework**: pytest (with `conftest.py` for fixtures)

package/adapters/gemini/skills/forge-guide/references/stacks/rust.md

@@ -90,6 +90,25 @@ When examining a Rust project, check for:
 - **Formatting**: `cargo fmt --check` (ensures code matches `rustfmt` style)
 - **Unsafe audit**: `cargo geiger` (if security-sensitive — counts unsafe blocks)
 
+### 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):** `fn main()` in `main.rs` or a `[[bin]]`
+  target, an async runtime entry (`#[tokio::main]`), an HTTP handler registered on an axum/actix/warp
+  router, or a worker task spawned from `main` — not a `#[cfg(test)]` module or a `tests/` integration
+  file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a `lazy_static!`
+  / `once_cell::sync::Lazy` static that eagerly constructs heavy clients, a single `bootstrap`/`setup`
+  fn `main` calls before serving, or a `#[ctor]`-style pre-`main` initializer. A `Lazy` static is only
+  a risk when it is *forced* at startup rather than on first use.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB pools
+  (`sqlx::Pool`, `diesel`, `deadpool`, `mongodb`), message/queue clients (`rdkafka`, `lapin`,
+  `redis`), telemetry SDKs (`opentelemetry`, `sentry`), or a broad internal service crate. Constructing
+  any of these eagerly at a universal entry is the CHECK-I23 pattern — recommend a `OnceCell`/`Lazy`
+  forced on **first use** by the handler that needs it, not at process start.
+
 ## Testing
 
 - **Framework**: Built-in test harness (`#[test]`, `#[cfg(test)]`)

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

@@ -64,6 +64,29 @@ When examining a TypeScript project, check for:
 - **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

package/adapters/gemini/skills/forge-verify/forge-verify.md

@@ -29,7 +29,7 @@ Pick based on how many checks the mode carries (see the per-mode totals in Step
 - **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 ~25, impl ~22): parallel dimensioned fan-out.**
+- **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
@@ -162,9 +162,9 @@ Load into context ALL artifacts for this feature based on mode:
 
 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: ~25 checks, impl: ~22 checks, epic: ~9 checks), you likely skipped checks — go back and complete them.
+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 (~9-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..E09 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 and E09 are verifier judgment) and returns its findings.
+**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
 

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **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.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning: