@garygentry/feature-forge 0.2.13 → 0.3.0

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

@@ -153,6 +153,60 @@ Detailed checklists for each verification mode. Execute EVERY check — do not s
 - [ ] **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.
+
 ## Implementation Mode Checklist
 
 ### Spec Compliance
@@ -190,13 +244,17 @@ Detailed checklists for each verification mode. Execute EVERY check — do not s
 > **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}`).
-- [ ] **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` 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.
+  - **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.**
 
 ## 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 by reading the
-manifest, EPIC.md, and completed members' specs.
+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')"
@@ -242,6 +300,27 @@ python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}"
   `.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.
 
 ## Findings Document Template (Step 4)
 

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

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

package/adapters/gemini/gemini-extension.json

@@ -4,7 +4,7 @@
     "regenerate": "python3 scripts/build-adapters.py"
   },
   "name": "feature-forge",
-  "version": "0.12.8",
+  "version": "0.13.0",
   "skills": [
     {
       "name": "forge-0-epic",

package/adapters/gemini/references/epic-manifest-schema.json

@@ -74,6 +74,11 @@
           "type": "array",
           "items": { "$ref": "#/definitions/consumedContract" },
           "description": "What this feature relies on from its dependencies (REQ-EPIC-03). May be empty."
+        },
+        "mutatesShared": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "OPTIONAL precision hint for cross-member coupling detection (#144): project-root-relative file/glob paths this feature writes or migrates that are shared across the epic (e.g. a corpus a sibling's tests pin). When present, forge-verify CHECK-E10 uses it directly; when absent, CHECK-E10 falls back to grepping specs/backlog for mutated paths. Not a dependency edge — declarative only. May be omitted entirely."
         }
       }
     },

package/adapters/gemini/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/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/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/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/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/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/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/scripts/epic-manifest.py

@@ -47,6 +47,21 @@ PIPELINE_STATE_FILENAME: Final = ".pipeline-state.json"
 MANIFEST_FILENAME: Final = "epic-manifest.json"
 NARRATIVE_FILENAME: Final = "EPIC.md"
 
+#: The authoritative forge-verify status vocabulary. SOURCE OF TRUTH:
+#: references/pipeline-state-schema.json (definitions.verifyEntry.properties.status.enum).
+#: A member state carrying a forge-verify-*.status outside this set is treated as
+#: incomplete-for-orchestration but SURFACED (never guessed silently) by render_status
+#: — a single typo'd status otherwise poisons the epic rollup + dependency gates (#148).
+#: NOTE: forge-session.py keeps a byte-identical copy of this constant — flat, self-
+#: contained scripts have no shared import module (each is copied verbatim into adapters).
+KNOWN_VERIFY_STATUSES: Final = frozenset(
+    {"pending", "passed", "findings-reported", "findings-applied", "skipped"}
+)
+#: The subset of KNOWN_VERIFY_STATUSES that makes a member's forge-verify-impl count as
+#: complete-for-orchestration (00 §7). A STRICT subset — 'findings-reported' (unfixed),
+#: 'skipped', and 'pending' do NOT unblock dependents. Not collapsible into the set above.
+_VERIFY_ORCH_COMPLETE: Final = frozenset({"passed", "findings-applied"})
+
 
 # --------------------------------------------------------------------------- #
 # Type Definitions (00-core-definitions.md §4, §5; 02 §8.4)
@@ -139,6 +154,10 @@ class RenderStatus(TypedDict):
         rollup: Aggregate {complete, total} counts.
         nextCommand: Recommended next command for the first actionable feature, or
             None when nothing is actionable (all complete, empty epic, or paused).
+        warnings: Human-readable diagnostics that do NOT invalidate the graph but
+            need surfacing — currently, members carrying a ``forge-verify-*.status``
+            outside ``KNOWN_VERIFY_STATUSES`` (treated as incomplete, but silently so
+            would poison the rollup + dependency gates, #148). Empty in the common case.
     """
 
     epic: str
@@ -148,6 +167,7 @@ class RenderStatus(TypedDict):
     parallelEligible: list[str]
     rollup: Rollup
     nextCommand: str | None
+    warnings: list[str]
 
 
 # --------------------------------------------------------------------------- #
@@ -542,6 +562,11 @@ _TOP_REQUIRED: Final = (
 )
 #: Required keys on each Feature object (00 §2.2).
 _FEATURE_REQUIRED: Final = ("name", "charter", "dependsOn", "exposes", "consumes")
+#: Optional keys on each Feature object. `mutatesShared` is the #144 precision
+#: hint for cross-member coupling (array of project-root-relative path strings);
+#: schema-legal when present, ignored when absent (mirrors
+#: epic-manifest-schema.json definitions.feature.properties.mutatesShared).
+_FEATURE_OPTIONAL: Final = ("mutatesShared",)
 #: Required keys on each Contract (exposes[]) object (00 §2.3).
 _CONTRACT_REQUIRED: Final = ("name", "kind", "summary")
 #: Required keys on each ConsumedContract (consumes[]) object (00 §2.4).
@@ -617,11 +642,16 @@ def _schema_findings(manifest: dict) -> list[Finding]:
                 findings.append(_schema(f"feature {label!r} missing required key {key!r}", fname))
         for key in feat:
             # 'status' is rejected separately above via the dedicated 'cached-status' code.
-            if key not in _FEATURE_REQUIRED and key != "status":
+            if key not in _FEATURE_REQUIRED and key not in _FEATURE_OPTIONAL and key != "status":
                 findings.append(_schema(f"feature {label!r} has unknown key {key!r}", fname))
         for key in ("name", "charter"):
             if key in feat and not isinstance(feat[key], str):
                 findings.append(_schema(f"feature {label!r} {key} must be a string", fname))
+        if "mutatesShared" in feat and (
+            not isinstance(feat["mutatesShared"], list)
+            or not all(isinstance(p, str) for p in feat["mutatesShared"])
+        ):
+            findings.append(_schema(f"feature {label!r} mutatesShared must be an array of strings", fname))  # noqa: E501
         if "dependsOn" in feat:
             if not isinstance(feat["dependsOn"], list) or not all(isinstance(d, str) for d in feat["dependsOn"]):  # noqa: E501
                 findings.append(_schema(f"feature {label!r} dependsOn must be an array of strings", fname))  # noqa: E501
@@ -792,7 +822,41 @@ def is_complete_for_orchestration(state: dict) -> bool:
         return True
     if not isinstance(impl, dict):
         return False
-    return impl.get("status") in {"passed", "findings-applied"}
+    return impl.get("status") in _VERIFY_ORCH_COMPLETE
+
+
+def _verify_status_warnings(name: str, state: dict) -> list[str]:
+    """Flag any ``forge-verify-*.status`` outside the known vocabulary (#148).
+
+    An unrecognized status (e.g. the eye-slip ``findings-resolved``, conflated with the
+    adjacent ``findingsResolved`` count) is correctly treated as incomplete by
+    ``is_complete_for_orchestration`` — but *silently*, so one typo on one member
+    under-reports the whole epic rollup and fabricates phantom ``unmetDeps`` on
+    dependents. Surfacing it turns that non-local corruption into a visible diagnostic.
+
+    Non-string / malformed status values (a list, an int) are also flagged, and the
+    membership test is guarded so an unhashable value never raises.
+    """
+    stages = state.get("stages", {})
+    if not isinstance(stages, dict):
+        return []
+    warnings: list[str] = []
+    known = ", ".join(sorted(KNOWN_VERIFY_STATUSES))
+    for stage_name, entry in stages.items():
+        if not (isinstance(stage_name, str) and stage_name.startswith("forge-verify-")):
+            continue
+        if not isinstance(entry, dict):
+            continue
+        status = entry.get("status")
+        if status is None:
+            continue
+        if isinstance(status, str) and status in KNOWN_VERIFY_STATUSES:
+            continue
+        warnings.append(
+            f"{name}: unknown {stage_name} status {status!r} "
+            f"(treated as incomplete; expected one of {known})"
+        )
+    return warnings
 
 
 def _read_state_safely(state_path: Path) -> dict:
@@ -927,14 +991,15 @@ def render_status(epic_dir: Path, specs_dir: Path) -> RenderStatus:
     rows: list[FeatureStatus] = []
     feature_dir_by_name: dict[str, Path] = {}
     complete: dict[str, bool] = {}
+    warnings: list[str] = []
     for feat in features:
         name = feat["name"]
         member_dir = contained_path(epic_dir, name)
         feature_dir_by_name[name] = member_dir
         rows.append(derive_status(member_dir))
-        complete[name] = is_complete_for_orchestration(
-            _read_state_safely(member_dir / PIPELINE_STATE_FILENAME)
-        )
+        member_state = _read_state_safely(member_dir / PIPELINE_STATE_FILENAME)
+        complete[name] = is_complete_for_orchestration(member_state)
+        warnings.extend(_verify_status_warnings(name, member_state))
 
     # (4) per-feature unmetDeps + blocked. A feature that is itself complete is
     #     never "blocked" — unmet deps only matter for work not yet finished.
@@ -989,6 +1054,7 @@ def render_status(epic_dir: Path, specs_dir: Path) -> RenderStatus:
         "parallelEligible": parallel_eligible,
         "rollup": rollup,
         "nextCommand": next_command,
+        "warnings": warnings,
     }
 
 
@@ -1414,6 +1480,10 @@ def _print_status_table(status: RenderStatus) -> None:
             marker = "⚠️ BLOCKING" if row["blockingEpicChangeRequests"] else "⚠️"
             line += f" — {marker} {row['openEpicChangeRequests']} pending epic change(s)"
         print(line)
+    if status["warnings"]:
+        print("Warnings:")
+        for warning in status["warnings"]:
+            print(f"  ⚠️ {warning}")
     if status["actionable"]:
         print(f"Actionable: {', '.join(status['actionable'])}")
     if status["parallelEligible"]: