@garygentry/feature-forge 0.2.13 → 0.3.0

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

@@ -0,0 +1,125 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://feature-forge/references/epic-manifest-schema.json",
+  "title": "Feature Forge Epic Manifest",
+  "description": "Canonical record of an epic's membership, dependency edges, charters, and contracts. Lives at {specsDir}/{epic}/epic-manifest.json. Carries NO per-feature status field (REQ-STATE-02); status is derived live from each member's .pipeline-state.json.",
+  "type": "object",
+  "required": ["schemaVersion", "epic", "description", "status", "narrativeDoc", "createdAt", "updatedAt", "features"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1,
+      "description": "Schema evolution guard."
+    },
+    "epic": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Matches the epic subtree directory name. Globally unique, kebab-case."
+    },
+    "description": {
+      "type": "string",
+      "description": "One-paragraph epic summary."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned", "complete"],
+      "description": "Epic lifecycle state (REQ-ORCH-05)."
+    },
+    "narrativeDoc": {
+      "const": "EPIC.md",
+      "description": "Relative pointer to the narrative document (REQ-EPIC-03)."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Set once at creation."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Bumped by every mutator on each atomic write (REQ-OBS-01)."
+    },
+    "features": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/feature" },
+      "description": "Ordered. Order is the user-declared sequence; it is NOT a dependency ordering."
+    }
+  },
+  "definitions": {
+    "feature": {
+      "type": "object",
+      "required": ["name", "charter", "dependsOn", "exposes", "consumes"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "Globally unique across the whole specs tree, kebab-case (REQ-DIR-04)."
+        },
+        "charter": {
+          "type": "string",
+          "description": "One-paragraph scope statement + contract obligations (REQ-EPIC-04). No full PRD at creation."
+        },
+        "dependsOn": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Names of sibling features in this epic (REQ-EPIC-02). Every entry must be a name in features[]. May be empty."
+        },
+        "exposes": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/contract" },
+          "description": "What this feature provides to dependents (REQ-EPIC-03). May be empty."
+        },
+        "consumes": {
+          "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."
+        }
+      }
+    },
+    "contract": {
+      "type": "object",
+      "required": ["name", "kind", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Identifier of the exposed artifact (e.g. verifyJwt, JWT_SECRET)."
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["function", "type", "endpoint", "module", "event"],
+          "description": "Kind of exposed artifact."
+        },
+        "summary": {
+          "type": "string",
+          "description": "One-line human description."
+        }
+      }
+    },
+    "consumedContract": {
+      "type": "object",
+      "required": ["from", "name", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Name of the sibling feature providing this. Must be present in features[]."
+        },
+        "name": {
+          "type": "string",
+          "description": "Identifier being consumed; should match an exposes[].name of the from feature."
+        },
+        "summary": {
+          "type": "string",
+          "description": "One-line human description."
+        }
+      }
+    }
+  }
+}

package/adapters/pi/references/forge-config-schema.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Configuration",
+  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root.",
+  "type": "object",
+  "properties": {
+    "specsDir": {
+      "type": "string",
+      "default": "./specs",
+      "description": "Root directory for feature spec documents. Each feature gets a subdirectory."
+    },
+    "docsDir": {
+      "type": "string",
+      "default": "./docs/architecture",
+      "description": "Root directory for generated architecture documentation."
+    },
+    "backlogDir": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Optional override for the backlog root. If set, the backlog is written to {backlogDir}/{feature}/backlog.json — the {feature} subdirectory is always composed in so multi-feature epics never collide. Default behavior (null): backlog.json is written to {specsDir}/{feature}/backlog.json with the feature specs."
+    },
+    "gitCommitAfterStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "Automatically commit after each pipeline stage completes."
+    },
+    "commitPrefix": {
+      "type": "string",
+      "default": "forge",
+      "description": "Prefix for conventional commit messages, e.g., forge(auth): complete PRD"
+    },
+    "branchPerFeature": {
+      "type": "boolean",
+      "default": true,
+      "description": "Offer to create an isolated git branch when a feature/epic starts on the default branch (main/master). Gated only on the project using git — independent of gitCommitAfterStage. When false, forge never prompts for a branch and works on whatever branch is checked out. See the Branch Setup block in references/shared-conventions.md."
+    },
+    "branchPrefix": {
+      "type": "string",
+      "default": "forge/",
+      "description": "Prefix for the branch name suggested by Branch Setup, e.g. 'forge/' yields 'forge/{feature}' or 'forge/{epic}'. Ignored when branchPerFeature is false."
+    },
+    "stack": {
+      "type": ["string", "null"],
+      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually (null until then). Examples: 'typescript', 'python', 'go', 'rust'."
+    },
+    "typeCheckCommand": {
+      "type": ["string", "null"],
+      "description": "Command to verify type correctness or lint. Null until set. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
+    },
+    "testCommand": {
+      "type": ["string", "null"],
+      "description": "Command to run tests. Null until set. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
+    },
+    "smokeCommand": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Optional end-to-end smoke command that boots the wired application entrypoint and drives one happy-path request, exiting 0 on success. DISTINCT from testCommand (unit tests, which may self-bootstrap) and loopRunner.runCommand (the loop launcher). Consumed by impl-verify's runnability check (CHECK-I21): when set it is executed (pass iff exit 0); when null the check degrades to an advisory not-applicable finding, never a hard fail (mirrors how a null typeCheckCommand is treated). Examples: 'npm run smoke', './scripts/smoke.sh', 'curl -fsS localhost:3000/health'."
+    },
+    "loopIterationMultiplier": {
+      "type": "number",
+      "default": 1.5,
+      "minimum": 1,
+      "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
+    },
+    "autoInvokeNextStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (default), the /skill:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
+    },
+    "autoVerify": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the /skill:forge navigator automatically runs forge-verify after a stage completes, with no prompt. forge-verify runs in a fresh forge-verifier subagent (clean-room), so it never needs a context clear and costs the current session only a compact findings digest. Default false preserves today's manual-gate behavior. Ignored on non-Claude hosts, which always fall back to printing the verify command. Per-stage overrides in autoVerifyStages take precedence."
+    },
+    "autoVerifyStages": {
+      "type": "object",
+      "default": {},
+      "description": "Per-stage overrides for autoVerify. Maps a production stage id to a boolean; the effective value for a stage is autoVerifyStages[stage] if present, else autoVerify. Keys are constrained to the five verify-capable stages so a typo (e.g. 'forge-1-prod') is a schema error, not a silent no-op. forge-6-docs has no verify step and is not a valid key.",
+      "propertyNames": {
+        "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop"]
+      },
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "autoFix": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the navigator chains forge-fix automatically after an auto-verify that finds issues. Honored ONLY when auto-verify is effectively on for the stage, and ONLY when preconditions hold (findings doc has zero unresolved decision points, working tree is clean, and a mandatory re-verify passes) — otherwise it falls back to surfacing the findings digest and prompting. Default false keeps fixing human-gated."
+    },
+    "contextWindowTokens": {
+      "type": ["integer", "null"],
+      "default": null,
+      "description": "Context window size (tokens) used by the navigator's context-usage check to compute how full the current session is. Null (default) lets the helper infer from the session model and fall back to 200000 — and if observed usage already exceeds 200000 it auto-bumps the assumed window to 1000000 (proof a 1M-beta window is active). Set this explicitly to your model's window (e.g. 1000000 for a 1M-context model) for accurate percentages below 200000 too, since 1M cannot be detected from the transcript until usage crosses 200000."
+    },
+    "contextWarnThreshold": {
+      "type": "number",
+      "default": 0.7,
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraction of the context window (0-1) past which the navigator recommends starting the next stage in a clean session rather than continuing. Default: 0.7."
+    },
+    "workspaces": {
+      "type": "array",
+      "description": "Monorepo members. Absent for single-package projects.",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "stack"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string"},
+          "path": {"type": "string", "description": "Repo-relative member dir"},
+          "stack": {"type": "string"},
+          "typeCheckCommand": {"type": ["string", "null"]},
+          "testCommand": {"type": ["string", "null"]}
+        }
+      }
+    },
+    "loopRunner": {
+      "type": "object",
+      "description": "The autonomous loop runner feature-forge drives. Defaults to rauf when absent (forge-5 states 'defaulting to rauf loop runner'). Every command is a template — {bin}, {backlogDir}, {specsDir}, {iterations} are substituted at call time — so an alternative ralph-style runner conforming to rauf's SPEC-BACKLOG-TOOL-CONTRACT.md can be swapped in without editing any skill. See references/ralph-loop-contract.md.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "default": "rauf",
+          "description": "Display name of the loop runner."
+        },
+        "bin": {
+          "type": "string",
+          "default": "rauf",
+          "description": "The runner executable. Assumed on PATH; may be an absolute path. Substituted as {bin} in every command."
+        },
+        "runCommand": {
+          "type": "string",
+          "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations}",
+          "description": "Run the loop. Launched in the background by forge-5. Human-formatted output; used as the fallback launch command when eventStreamCommand is absent."
+        },
+        "eventStreamCommand": {
+          "type": "string",
+          "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations} --ndjson",
+          "description": "Stdout NDJSON launch command for a runner that does NOT persist its own event file — same as runCommand but emits one machine-readable JSON event per stdout line: item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). NOTE: rauf (the default runner) ALREADY persists {stateDir}/events.ndjson natively and rotates it per run, so forge-5 launches the plain runCommand and monitors that native file — it does NOT use this field, and must NOT redirect --ndjson into {stateDir} (redundant, and it collides with the runner's own writer / archive rotation). This field is only for a stdout-only runner with no native event file; forge-5 then redirects its stdout to a file OUTSIDE {stateDir} and monitors that. Omit it entirely for a runner that self-persists or cannot emit NDJSON."
+        },
+        "validateCommand": {
+          "type": "string",
+          "default": "{bin} backlog validate . --backlog {backlogDir} --specs-dir {specsDir} --json",
+          "description": "Validate a backlog. MUST exit 0=valid, 1=findings, 2=usage/IO, and emit { valid, findings[] } with --json. `specReferences` are project-root-relative (resolved against the project root); `--specs-dir` only gates the existence check, so passing the specs root ({specsDir}) is sufficient."
+        },
+        "statusCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir}",
+          "description": "One-shot loop status, human-formatted. Shown to the user as a monitoring hint."
+        },
+        "statusJsonCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir} --json",
+          "description": "Machine-readable derived status used by forge-5 for milestone tallies and the final summary. Emits { loopState, iteration, maxIterations, currentItem, lastSignal, backlogSummary{pending,inProgress,blocked,needsHuman,deferred,done,total}, lock{...} }. Distinguishes the three non-done outcomes (genuine blocked vs needsHuman vs runner-deferred 'false blocks')."
+        },
+        "listCommand": {
+          "type": "string",
+          "default": "{bin} backlog list . --backlog {backlogDir} --json",
+          "description": "List backlog items as JSON."
+        },
+        "followCommand": {
+          "type": "string",
+          "default": "{bin} follow . --backlog {backlogDir}",
+          "description": "Stream live loop events, HUMAN-formatted (pretty-printed / log tail) — for a person watching in another terminal, NOT a machine-readable surface. forge-5 supervises via eventStreamCommand (NDJSON) instead."
+        },
+        "logCommand": {
+          "type": "string",
+          "default": "{bin} log . --backlog {backlogDir} --follow",
+          "description": "Tail the runner log, human-formatted. Monitoring hint for the user."
+        },
+        "watchCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir} --json",
+          "description": "Machine-readable status used by forge-5 for stall detection. rauf's `loop watch` verb was removed in v0.5.0, so this now points at `status --json`; forge-5 keys off the iteration-status `stuckWarning` flag (read from `status --json` / `iteration-status.json`) rather than guessing liveness from state.json timestamps."
+        },
+        "versionCommand": {
+          "type": "string",
+          "default": "{bin} version --json",
+          "description": "Report runner version as { version: <semver> }. Used to enforce minRunnerVersion before running."
+        },
+        "agentArgument": {
+          "type": "string",
+          "default": "--agent {agent}",
+          "description": "Tokenized argument appended to the launch command (eventStreamCommand/runCommand) when forge resolves a non-default coding agent for the run. {agent} is substituted ONLY with a validated, advertised agent id (a member of the set agentsProbeCommand reports). PRESENCE of this field advertises the runner's agent surface: when present and non-empty, forge-5 offers the per-run agent selector, honors defaultAgent, and may run agentsProbeCommand; OMIT it for a runner with no agent dimension and forge skips agent selection entirely — no selector, no probe, no {agent} substitution, no agent argument sent (byte-identical to today). Distinct from the version gate (minRunnerVersion)."
+        },
+        "agentsProbeCommand": {
+          "type": "string",
+          "default": "{bin} agents --json",
+          "description": "Coding-agent availability probe. MUST emit { agents: [{ id, displayName, available, ... }] } and exit 0 (it always exits 0: an unknown id simply never appears; a known-unavailable one appears with available:false). forge-5 runs it ONCE (no retries) before launching a non-default agent to (a) validate the resolved id against the advertised id set and (b) report availability in the pre-launch confirmation. Ignored on the default path and when agentArgument is absent."
+        },
+        "defaultAgent": {
+          "type": "string",
+          "default": "",
+          "description": "Project-default coding agent id, so a project can fix its agent once without specifying it every run. Empty string ⇒ no project default (the runner's own default — claude-cli for rauf — applies, behaving exactly as today). Overridden by the per-run agent selector (run > project precedence, resolved inside forge before the single --agent is emitted). Ignored when agentArgument is absent."
+        },
+        "preconditionFile": {
+          "type": "string",
+          "default": ".rauf.json",
+          "description": "Project-root marker file that must exist (runner installed into the target project)."
+        },
+        "stateDir": {
+          "type": "string",
+          "default": ".rauf",
+          "description": "Per-backlog state directory name created under the backlog dir."
+        },
+        "logFile": {
+          "type": "string",
+          "default": "rauf.log",
+          "description": "Human-readable event log filename written under {stateDir}. Substituted as {loopRunner.logFile} in the log-tail fallback Monitor command when eventStreamCommand (events.ndjson) is unavailable. The structured NDJSON path uses the contract-standard name events.ndjson and is not configurable here."
+        },
+        "setupHint": {
+          "type": "string",
+          "default": "Run `rauf install .` to install rauf's per-project artifacts (.rauf/, RAUF.md, schema), then re-run forge-5.",
+          "description": "Shown when preconditionFile is missing — how to set up the runner IN THIS PROJECT (per-project artifacts)."
+        },
+        "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.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",
+          "default": "1",
+          "description": "Backlog schemaVersion this runner config targets."
+        },
+        "minRunnerVersion": {
+          "type": "string",
+          "default": "0.6.0",
+          "description": "Minimum runner version (semver). 0.6.0 is the AGENT-SURFACE FLOOR: the rauf version that ships the coding-agent selection surface (the --agent flag, the `agents` availability probe, and the preset agent registry) that this config's agentArgument/agentsProbeCommand consume. Flooring here guarantees a successful gate implies those surfaces exist. (0.5.0 was the prior grammar/contract-flip floor — unified exit codes, `loop run --detached`, explicit `review` signal, versioned events.ndjson — which predates the agent surface and so could not guarantee it.) forge-5 enforces this via versionCommand before any loop side-effects."
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Pipeline State",
+  "description": "Tracks pipeline progress for a single feature across sessions. Lives at {specsDir}/{feature}/.pipeline-state.json",
+  "type": "object",
+  "required": ["feature", "createdAt", "updatedAt", "currentStage", "stages", "pipelineStatus"],
+  "properties": {
+    "pipelineStatus": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned"],
+      "default": "active"
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name (matches directory name under specsDir)"
+    },
+    "epic": {
+      "type": "string",
+      "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "currentStage": {
+      "type": "string",
+      "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
+      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` here means the whole pipeline is done. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+    },
+    "epicChangeRequests": {
+      "type": "array",
+      "description": "Epic-level change requests raised by a member stage (forge-1-prd/forge-2-tech) when the epic DECOMPOSITION itself must change — distinct from the same-feature `notes` parking lot. Read by forge-0-epic edit mode (which applies them) and by forge-session stage-exit (which routes the exit on `blocksCurrent`). Absent/empty for standalone features. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "target", "rationale", "blocksCurrent", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["add-feature", "redep", "move-boundary", "split"],
+            "description": "The decomposition change. add-feature/redep map 1:1 onto edit-mode mutators; move-boundary/split are composite (applied guided-manual in v1)."
+          },
+          "target": {
+            "type": "string",
+            "description": "The sibling feature to add, or the feature/boundary affected."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the epic must change; seeds the edit-mode charter/prompt when applied."
+          },
+          "blocksCurrent": {
+            "type": "boolean",
+            "description": "true → the current feature's next stage would build on a soon-to-change decomposition (pause-now: reconcile before proceeding). false → a peer/downstream change (finish-then-edit). Drives stage-exit routing."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech"],
+            "description": "The stage that detected the epic-level concern."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "applied", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → applied|dismissed. Only forge-0-epic edit mode flips open→applied/dismissed; recording stages only create open entries; navigator/verify only read."
+          }
+        }
+      }
+    },
+    "deferredDecisions": {
+      "type": "array",
+      "description": "Same-feature decisions deliberately postponed to a LATER stage of THIS feature — a structured alternative to burying them in the free-text `notes` string. Distinct from `notes` (unstructured scratch) and from `epicChangeRequests[]` (the epic DECOMPOSITION must change). Use this when a stage would otherwise be tempted to solicit a decision that properly belongs to a downstream stage (e.g. forge-1-prd deferring the concrete cache backend to forge-2-tech): record it here instead of asking now (see the deferred-decisions rule in `references/stage-exit-protocol.md`), and the target stage addresses it. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["question", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "question": {
+            "type": "string",
+            "description": "The decision being deferred, phrased as a concrete question for the target stage to answer."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why it is deferred rather than decided now (e.g. depends on information the target stage produces)."
+          },
+          "targetStage": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs"],
+            "description": "The stage that should resolve this decision. Omit when unknown/any-later-stage."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog"],
+            "description": "The stage that deferred the decision."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "addressed", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → addressed|dismissed. The target stage flips open→addressed when it resolves the decision (or dismissed if it no longer applies); recording stages only create open entries."
+          }
+        }
+      }
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-0-epic": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" },
+        "forge-1-prd": { "$ref": "#/definitions/stageEntry" },
+        "forge-2-tech": { "$ref": "#/definitions/stageEntry" },
+        "forge-3-specs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-specs": { "$ref": "#/definitions/verifyEntry" },
+        "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
+        "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "stageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": {
+          "type": ["string", "null"],
+          "description": "Git commit SHA of this stage's artifact commit (Commit 1 of the two-commit Git Commit Protocol in shared-conventions.md). Written by a small follow-up commit so it points at the artifact commit itself, never at an orphaned amend or the hash-recording commit. null until recorded (or when there was no new artifact commit)."
+        },
+        "basedOnVersions": {
+          "type": "object",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": { "type": ["string", "null"], "description": "Git commit SHA of the verify/fix artifact commit. Recorded via the two-commit Git Commit Protocol (shared-conventions.md) so it points at the artifact commit, never an orphaned amend." },
+        "verifiedStageVersion": { "type": ["integer", "null"], "description": "The production stage's `version` at the moment this verify was resolved. The navigator's freshness ledger compares it to the stage's current `version`: equal means the verify is fresh; a mismatch (artifact revised since) or an absent field (legacy state) means stale, so auto-verify re-fires. Recorded by forge-verify/forge-fix when writing a passed/findings-applied status." }
+      }
+    }
+  }
+}

package/adapters/pi/references/portable-root.md

@@ -0,0 +1,71 @@
+# Portable Script-Root Resolution
+
+This file is the **single canonical home** of the feature-forge bootstrap prelude and the
+portable invocation convention. Each fenced shell block an agent runs is a separate process
+with no persisted state, so the plugin root must be re-resolved within the same block as every
+bundled-script call. The prelude below is the fixed, byte-identical snippet that does this by
+discovering and delegating to `scripts/forge-root.sh`. Downstream consumers
+(`forge-agent-adapters-build`, `cross-agent-installer`) and the spec-purity checker treat this
+file as authoritative: the checker's rule 5 compares every prelude occurrence across the canon
+against the fenced block here, byte-for-byte.
+
+## Canonical bootstrap prelude
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+```
+
+## Usage
+
+Prepend the prelude to a fenced shell block once, then invoke bundled scripts via `$R`:
+`python3 "$R/scripts/<x>"` or `bash "$R/scripts/<x>"`. One prelude per fenced block — if a block
+makes several calls, add the prelude once and reuse `$R` for each. A fresh block gets its own
+prelude (per-block re-resolution). Worked example:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
+```
+
+## Invariants (do NOT "fix" these)
+
+1. **First hint is the Claude plugin-root env var; the rest are paths.** The prelude's
+   `for d in …` list leads with the `CLAUDE_PLUGIN_ROOT` env var (in default-empty `:-` form)
+   — the exact bundle dir Claude exports in every marketplace/plugin session — followed by the
+   directory-path candidates. The hint gives exact, glob-free resolution on any current/future
+   Claude layout (no version-skew window); when unset it expands to empty and is harmlessly
+   skipped, so other hosts fall through to the path candidates unchanged. This is the **one
+   sanctioned** appearance of that variable in canonical surfaces: spec-purity rule 3 allows it
+   by stripping the byte-pinned prelude before its residual-var scan (so a stray var anywhere
+   else — including the default-empty form — still fails), and `forge-agent-adapters-build`
+   translates it to `FEATURE_FORGE_ROOT` for non-Claude bundles (which `forge-root.sh` already
+   prefers). The exact literal is shown only in the fenced prelude above and audited in
+   `vendor-construct-inventory.md`.
+2. **First-discoverable-resolver-wins.** The `exec` inside the `$(…)` command substitution means
+   the loop stops at the first directory holding an executable `forge-root.sh` and delegates ALL
+   final root resolution to that script. The `for` list is a discovery order for `forge-root.sh`
+   itself, not a fallback chain for the plugin root. Removing the `exec` to "keep looping" is a
+   regression — once `exec`'d, the loop is replaced by the resolver process and never advances.
+3. **Prelude candidate set is an agent-neutral bootstrap subset (after the env hint).** The
+   prelude's `for d` list exists only to bootstrap-discover `forge-root.sh`; the authoritative
+   multi-root probe lives in `forge-root.sh` step 2. After the leading env-var hint (invariant 1),
+   the list enumerates install roots across agents — the Claude
+   skill/plugin dirs — including the marketplace-cache layout
+   `~/.claude/plugins/cache/<marketplace>/feature-forge/<version>/`, listed before the
+   single-star plugins glob so a versioned cache install always beats the marketplace clone —
+   **and** the agent-neutral `.agents/skills/feature-forge` dirs (`$HOME` and the
+   project-relative `./.agents/...`) — so a non-Claude install (e.g. Codex under `.agents/skills`)
+   can still discover the resolver. When adding an install root, update `forge-root.sh` first;
+   extend the prelude only if the new root is needed to bootstrap-discover `forge-root.sh` itself.
+
+## The resolver
+
+The prelude delegates to [`scripts/forge-root.sh`](../scripts/forge-root.sh) — the portable
+skill/plugin-root resolver. It takes no arguments, prints the absolute plugin root to stdout and
+exits `0`, or writes an actionable message to stderr and exits `1`. It resolves the root by
+self-location → candidate-root probe → plugin-root environment-variable fallback → actionable failure,
+and never sources or executes a discovered path — it only ever prints a directory string. The
+spec-purity checker (rule 5) enforces that every prelude occurrence across the canon is
+byte-identical to the fenced block in this file.