@garygentry/feature-forge 0.2.13 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Cross-agent installer for the [**feature-forge**](https://github.com/garygentry/feature-forge)
 skill suite — an end-to-end feature-development pipeline that runs on any coding agent
-(Claude, Codex, Copilot, Cursor, or Gemini).
+(Claude, Codex, Copilot, Cursor, Gemini, or Pi).
 
 This package installs the canonical forge skills into the agents detected on your machine.
 It is dependency-free and performs sandboxed, manifest-tracked writes.
@@ -33,7 +33,7 @@ npx @garygentry/feature-forge install --dry-run --json
 
 | Flag                | Description                                                            |
 | ------------------- | --------------------------------------------------------------------- |
-| `-a, --agent <id>`  | Scope to one agent (`claude`/`codex`/`copilot`/`cursor`/`gemini`).    |
+| `-a, --agent <id>`  | Scope to one agent (`claude`/`codex`/`copilot`/`cursor`/`gemini`/`pi`). |
 | `-g, --global`      | Install into the user-level config dir (default: project-local).      |
 | `--symlink`         | Symlink the bundle instead of copying (Windows always copies).        |
 | `--dry-run`         | Print the planned actions without changing anything.                  |
@@ -52,6 +52,9 @@ Each agent's bundle is installed where that agent actually loads it (project sco
 | copilot | `.github/feature-forge/`             | managed block in `.github/copilot-instructions.md`      |
 | cursor  | `.cursor/rules/feature-forge/`       | —                                                       |
 | gemini  | `.gemini/extensions/feature-forge/`  | —                                                       |
+| pi      | `.pi/skills/feature-forge/`          | —                                                       |
+
+For Pi, `--global` installs to `~/.pi/agent/skills/feature-forge/` and project scope installs to `./.pi/skills/feature-forge/`. The Pi bundle includes real `package.json` metadata plus the `AskUserQuestion` compatibility extension; run `/trust` (or use `--approve` in non-interactive tests) before relying on project-local Pi resources.
 
 The Copilot block is delimited by `<!-- feature-forge:managed:start -->` /
 `<!-- feature-forge:managed:end -->` sentinels and merged without disturbing the rest of the
@@ -71,7 +74,7 @@ Claude Code users can alternatively install via the plugin marketplace:
 
 The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
 [`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
-read-only resolvability preflight on the pin (`@garygentry/rauf@0.12.0`) and records it; pass
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.13.0`) and records it; pass
 `--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
 `npx @garygentry/rauf` or its
 [binary script](https://github.com/garygentry/rauf#install). See the

package/adapters/GENERATION-REPORT.md

@@ -124,6 +124,26 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-verify/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 
+## pi
+
+| Source | Construct | Reason |
+|--------|-----------|--------|
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | Claude model aliases (opus/sonnet) are not Pi model ids; pin via subagents.agentOverrides.<name>.model in Pi settings instead (D1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | Claude model aliases (opus/sonnet) are not Pi model ids; pin via subagents.agentOverrides.<name>.model in Pi settings instead (D1) |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | Claude model aliases (opus/sonnet) are not Pi model ids; pin via subagents.agentOverrides.<name>.model in Pi settings instead (D1) |
+| `skills/forge-0-epic/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-1-prd/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-2-tech/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-3-specs/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-4-backlog/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-5-loop/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-6-docs/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-fix/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-guide/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-verify/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+
 ## Copied verbatim (no provenance header)
 
 These files are transported byte-for-byte from canon into every `adapters/<agent>/` bundle and intentionally carry **no** provenance header (a header would break byte-identity / corrupt parsed files):

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

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

package/adapters/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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"]:

package/adapters/claude/scripts/forge-root.sh

@@ -21,14 +21,56 @@ is_root() {  # $1 = candidate dir
   [ -f "$1/.feature-forge-bundle.json" ] || [ -f "$1/.claude-plugin/plugin.json" ]
 }
 
+# Completeness gate (#152). A dir can carry the sentinel yet be a partial/stale install —
+# a skill-only extraction, or an install predating the shared-reference fan-out — where the
+# scripts/references the skills load at every stage are absent. Such a root looks usable but
+# runs DEGRADED silently (hand-improvised state schema, skipped Mint Guard + scripted exit).
+# These are the assets a complete install MUST carry beyond the sentinel; a resolved root
+# missing any of them is reported as degraded rather than handed back as if it were whole.
+CORE_ASSETS=(
+  "scripts/forge-session.py"
+  "references/pipeline-state-schema.json"
+  "references/stage-exit-protocol.md"
+)
+
+# Echo the first missing core asset (relative path) for $1, or nothing when complete.
+first_missing_asset() {  # $1 = candidate dir
+  local a
+  for a in "${CORE_ASSETS[@]}"; do
+    [ -f "$1/$a" ] || { printf '%s' "$a"; return 0; }
+  done
+}
+
+# A sentinel-bearing candidate that lacks a core asset is remembered here (first one wins)
+# so a COMPLETE root found later in the probe order still takes precedence; only if the probe
+# ends with no complete root do we report this degraded install (step 4).
+partial_root=""
+partial_missing=""
+
+# Given a candidate that already passed is_root: print + exit 0 if it is complete; otherwise
+# record it as the degraded fallback and return so probing continues. Always returns 0 on the
+# fall-through path so `set -e` never aborts the resolver on a partial candidate.
+accept_root() {  # $1 = candidate dir (already is_root)
+  local miss
+  miss="$(first_missing_asset "$1")"
+  if [ -z "$miss" ]; then
+    printf '%s\n' "$1"
+    exit 0
+  fi
+  if [ -z "$partial_root" ]; then
+    partial_root="$1"
+    partial_missing="$miss"
+  fi
+  return 0
+}
+
 # ── Step 1: self-location — parent of this script's dir is the install root. ─────────────
 # This is the PRIMARY path: a bundle ships its own scripts/forge-root.sh, so the parent of
 # this script's dir is that bundle's root under any agent's layout.
 self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
 root="$(cd -- "$self_dir/.." && pwd -P)"
 if is_root "$root"; then
-  printf '%s\n' "$root"
-  exit 0
+  accept_root "$root"
 fi
 
 # ── Step 2a: Claude marketplace-cache installs — ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/.
@@ -42,8 +84,7 @@ fi
 while IFS= read -r manifest; do
   candidate="${manifest%/.claude-plugin/plugin.json}"
   if is_root "$candidate"; then
-    printf '%s\n' "$candidate"
-    exit 0
+    accept_root "$candidate"
   fi
 done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/plugin.json 2>/dev/null || true)
 
@@ -51,9 +92,24 @@ done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/pl
 # Globs that match nothing expand to themselves; the is_root test rejects such literals. Covers
 # every supported agent's install destination under BOTH global ($HOME) and project ($PWD) scope,
 # matching the installer's per-agent layout: claude .claude/skills, codex .agents/skills, copilot
-# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions. The cache glob repeats
-# step 2a's path for a cache install that carries only the neutral bundle sentinel (no
-# plugin.json for ls -t to key on).
+# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions, pi .pi/skills or
+# $PI_CODING_AGENT_DIR/skills. The cache glob repeats step 2a's path for a cache install that
+# carries only the neutral bundle sentinel (no plugin.json for ls -t to key on).
+if [ -n "${PI_CODING_AGENT_DIR:-}" ]; then
+  for candidate in \
+    "$PI_CODING_AGENT_DIR/skills/feature-forge" \
+    "$PI_CODING_AGENT_DIR"/git/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/git/*/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/packages/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/npm/*/@garygentry/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/node_modules/@garygentry/feature-forge/adapters/pi \
+  ; do
+    if is_root "$candidate"; then
+      accept_root "$candidate"
+    fi
+  done
+fi
+
 for candidate in \
   "$HOME/.claude/skills/feature-forge" \
   "$PWD/.claude/skills/feature-forge" \
@@ -67,25 +123,57 @@ for candidate in \
   "$PWD/.cursor/rules/feature-forge" \
   "$HOME/.gemini/extensions/feature-forge" \
   "$PWD/.gemini/extensions/feature-forge" \
+  "$HOME/.pi/agent/skills/feature-forge" \
+  "$PWD/.pi/skills/feature-forge" \
+  "$HOME"/.pi/agent/git/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/git/*/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/packages/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/npm/*/@garygentry/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/node_modules/@garygentry/feature-forge/adapters/pi \
+  "$PWD"/.pi/git/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/git/*/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/packages/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/npm/*/@garygentry/feature-forge/adapters/pi \
+  "$PWD"/.pi/node_modules/@garygentry/feature-forge/adapters/pi \
 ; do
   if is_root "$candidate"; then
-    printf '%s\n' "$candidate"
-    exit 0
+    accept_root "$candidate"
   fi
 done
 
+# Project-scoped Pi installs may be discovered from a subdirectory of the repository. Probe
+# ancestor .pi roots up to the filesystem root; this is bounded by path depth and avoids
+# recursive globs. Scoped to .pi ONLY — every other agent's project layout is probed at $PWD
+# in the fixed list above, and widening those to ancestors here would silently change
+# established discovery behaviour for agents this bundle did not introduce.
+probe_dir="$PWD"
+while :; do
+  candidate="$probe_dir/.pi/skills/feature-forge"
+  if is_root "$candidate"; then
+    accept_root "$candidate"
+  fi
+  [ "$probe_dir" = "/" ] && break
+  next_probe_dir="$(dirname -- "$probe_dir")"
+  [ "$next_probe_dir" = "$probe_dir" ] && break
+  probe_dir="$next_probe_dir"
+done
+
 # ── Step 3: env fallback — neutral FEATURE_FORGE_ROOT, then the legacy CLAUDE_PLUGIN_ROOT. ─
 # The neutral override works for every agent; CLAUDE_PLUGIN_ROOT is kept only for backwards
 # compatibility with existing Claude installs (C-4).
 if [ -n "${FEATURE_FORGE_ROOT:-}" ] && is_root "$FEATURE_FORGE_ROOT"; then
-  printf '%s\n' "$FEATURE_FORGE_ROOT"
-  exit 0
+  accept_root "$FEATURE_FORGE_ROOT"
 fi
 if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
-  printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
-  exit 0
+  accept_root "$CLAUDE_PLUGIN_ROOT"
 fi
 
-# ── Step 4: failure — actionable message to stderr, exit 1 (REQ-RES-04). ─────────────────
+# ── Step 4: failure. A sentinel-bearing but asset-incomplete root found along the way is a
+# DEGRADED install (#152) — report it distinctly and actionably rather than the generic
+# cannot-locate message, so the operator knows to reinstall/update rather than reconfigure. ─
+if [ -n "$partial_root" ]; then
+  echo "feature-forge: install incomplete/degraded at $partial_root (missing $partial_missing) — reinstall with 'npx @garygentry/feature-forge' (or 'feature-forge update' for a stale install)." >&2
+  exit 1
+fi
 echo "feature-forge: cannot locate install root. Set FEATURE_FORGE_ROOT to the bundle dir, or run from an installed skill dir." >&2
 exit 1