@garygentry/feature-forge 0.3.0 → 0.3.2

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

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

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

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

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

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

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Cross-agent installer for the feature-forge skill suite — installs the canonical forge pipeline into Claude, Codex, Copilot, Cursor, Gemini, or Pi.",
   "license": "MIT",
   "type": "module",

package/adapters/claude/skills/forge-1-prd/references/pipeline-state-schema.json

@@ -1,191 +0,0 @@
-{
-  "$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." }
-      }
-    }
-  }
-}