@garygentry/feature-forge 0.3.1 → 0.3.4

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

@@ -46,3 +46,88 @@ Detailed checklist for the **impl** verification mode, loaded by the `forge-veri
 - [ ] **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.**
 
+### Work-Order Cardinality
+
+> **When this fires:** only when the implementation ships or cites an **enumerated work
+> order, coverage list, or inventory that claims to cover a set of artifacts** — a
+> per-file work order, a "files changed" table, a per-artifact review checklist, an
+> inventory table in a spec this implementation realizes, or a registry constant in code
+> that claims to list every member of a class. No such list yields **not-applicable**;
+> absence is never a hard fail.
+
+- [ ] **CHECK-I24**: **A declared work order or coverage list covers the whole artifact set it claims — name what is missing** (#170).
+  *Heuristic with a mechanical method — **not-applicable** when the implementation declares
+  no enumerated work order, coverage list, or registry claiming full coverage; absence is
+  **never a hard fail**. A true omission is a `gap` (blocking): an unreviewed artifact is
+  missing coverage.* Any declared work order or coverage list must be checked against the
+  **actual artifact set it claims to cover**, with omissions named. The incident behind
+  this check is a hand-authored work order that enumerated **15 of 16** artifacts: the
+  sixteenth was never reviewed and would have shipped, because every reviewer worked the
+  list that was in front of them. Verify by re-deriving, never by reading the list back to
+  itself:
+  1. **Find the declared lists.** Look for enumerated lists claiming coverage of a set:
+     a work order or handoff enumerating files to change, a "files changed" or "artifacts
+     touched" table, a per-artifact review or sign-off checklist, an inventory table in an
+     implementation spec, and **registry-shaped constants in code** — a tuple, array, or
+     map documented as holding every helper, every adapter target, every generated file.
+     If no such list exists, this check is **not-applicable**.
+  2. **Re-derive the covered set from its source of record.** Enumerate the actual set
+     independently: the directory listing for a per-file list, the spec's own file
+     inventory for an implementation work order, the on-disk members for a registry
+     constant, the test suite's own collected set for a coverage table. A registry claiming
+     to hold "every script the skills invoke" is re-derived by finding the invocations, not
+     by reading the tuple.
+  3. **Difference both directions and name every discrepancy.** Every member of the
+     re-derived set with no entry in the declared list is reported **by name** — path,
+     symbol, or artifact id — never as a count delta. A list entry pointing at something
+     that does not exist is a stale entry, reported the same way.
+  4. **Severity, and what to report.** A named omission is a `gap`; a stale entry, or a
+     stated total that disagrees with an otherwise complete list, is an `inconsistency`.
+     Name the list, the source of record used for the re-derivation, and each missing or
+     stale member. This check is deliberately narrower than `CHECK-I01` (which asks whether
+     each file the architecture spec lists exists): here the *list itself* is the suspect,
+     not the artifacts it names. **Report, do not repair.**
+
+### Internal Consistency
+
+> **When this fires:** on any artifact that states the same quantity, scope claim, or
+> status **in more than one place** — front matter vs body, a summary block vs the prose
+> below it, a table vs the narrative that explains it, a docstring vs the code it
+> documents. This is deliberately **intra-artifact**: contradictions *between* artifacts
+> are already the subject of the spec-compliance checks above. An artifact that states
+> each quantity exactly once yields **not-applicable** — it degrades naturally, with
+> nothing to compare.
+
+- [ ] **CHECK-I25**: **One artifact, one answer — a quantity or claim restated inconsistently inside a single artifact** (#170).
+  *Verifier judgment — read and compare; no extractor runs (deliberately, this milestone).
+  **not-applicable** when nothing is restated. Severity defaults to `inconsistency`
+  (advisory) and escalates to `error` only when the contradiction is decision-bearing, per
+  the severity conventions in the verify skill.* An artifact can be internally false while
+  every cross-artifact check passes: in the incident behind this check, one artifact
+  asserted a claim held **universally**, while its own body — two sections below — stated
+  the correct **4-of-7** breakdown. The false summary survived a full review, propagated
+  into generated output, and would have shipped. Verify by comparing the artifact against
+  itself:
+  1. **Collect the restatements.** Read the artifact end to end and note every place it
+     states: a **count or total** ("16 files", "N of M", "all four"), a **scope claim**
+     ("every", "all", "none", "only", "universal", "always", "never"), a **status claim**
+     ("complete", "pending", "removed", "supported"), or a **named identifier or version**
+     it repeats. Note each statement with its location. Anything stated exactly once is not
+     in scope for this check.
+  2. **Compare statements about the same subject.** Group the notes by what they describe,
+     then compare within each group. Two disagreeing numbers is the obvious hit; the
+     costlier one is a **scope word contradicted by the artifact's own detail** — a
+     universal claim sitting above a partial breakdown, an "all supported" above a table
+     with a gap, a "removed" beside a surviving reference.
+  3. **Decide which statement the artifact's own evidence supports.** Prefer the
+     **enumerated detail** — the table, the list, the breakdown, the code — over the
+     summary that restates it: the summary is the derived form and is usually the one that
+     drifted. Say in the finding which statement the evidence supports and why, so the fix
+     is unambiguous.
+  4. **Set severity deliberately.** Default to `inconsistency` (advisory). Escalate to
+     `error` only when the contradiction is **decision-bearing** — a reader acting on the
+     wrong statement takes a materially different action, or the wrong statement is copied
+     into generated output, a published artifact, or a gate. An inaccuracy confined to a
+     comment, a docstring, or test narration stays at `inconsistency` under the severity
+     floor. Quote both locations verbatim in the finding. **Report, do not repair.**
+

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

@@ -45,7 +45,7 @@ Detailed checklist for the **specs** verification mode, loaded by the `forge-ver
 - [ ] **CHECK-S26**: Import paths match actual package export maps
 
 ### Edge Cases and Non-Functional
-- [ ] **CHECK-S27**: Concurrent access scenarios are addressed if relevant
+- [ ] **CHECK-S27**: Concurrent access scenarios are addressed if relevant (a PRD position of "out of scope — single writer assumed" is a complete answer; for forge state writes the standing decision is `references/decisions/single-writer-threat-model.md` — cite it, do not design a mechanism)
 - [ ] **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
@@ -62,3 +62,47 @@ Detailed checklist for the **specs** verification mode, loaded by the `forge-ver
 ### 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.
+
+### Internal Consistency
+
+> **When this fires:** on any single spec document that states the same quantity, scope
+> claim, or status **in more than one place** — a Requirement Coverage table vs the
+> sections it points at, a summary or overview paragraph vs the detail below it, a
+> Dependencies list vs the cross-references in the body, a stated count of documents or
+> types vs the list actually enumerated. It is **intra-document**: a contradiction
+> *between* two spec documents is already covered by the tech-spec-consistency and
+> cross-reference checks above. A document that states each quantity exactly once yields
+> **not-applicable**.
+
+- [ ] **CHECK-S39**: **One document, one answer — a quantity or claim restated inconsistently inside a single spec** (#170).
+  *Verifier judgment — read and compare; no extractor runs (deliberately, this milestone).
+  **not-applicable** when nothing is restated. Severity defaults to `inconsistency`
+  (advisory) and escalates to `error` only when the contradiction is decision-bearing, per
+  the severity conventions in the verify skill.* A spec document can contradict itself
+  while every cross-document check passes: in the incident behind this check, one artifact
+  asserted a claim held **universally**, while its own body — two sections below — stated
+  the correct **4-of-7** breakdown. The summary was the part downstream artifacts copied.
+  Verify by comparing the document against itself:
+  1. **Collect the restatements.** Note every place the document states a **count or
+     total** ("five documents", "N of M", "all three subcommands"), a **scope claim**
+     ("every", "all", "none", "only", "universal", "always", "never"), a **status claim**
+     ("out of scope", "deferred", "removed", "required"), or a **repeated identifier**
+     (a type name, a file path, a requirement id, a constant's value). Record each with its
+     location. Anything stated exactly once is not in scope for this check.
+  2. **Compare statements about the same subject.** Group by subject and compare within
+     each group. Watch specifically for: a Requirement Coverage table row pointing at a
+     section that no longer makes that claim; a count in an overview that disagrees with
+     the list enumerated below it; a scope word ("all", "universal", "never") that the
+     document's own breakdown contradicts; a constant given one value in a type definition
+     and another in prose.
+  3. **Decide which statement the document's own evidence supports.** Prefer the
+     **enumerated detail** — the table, the type definition, the numbered list — over the
+     summary that restates it. Name in the finding which statement the evidence supports,
+     so the fix does not have to re-derive it.
+  4. **Set severity deliberately.** Default to `inconsistency` (advisory). Escalate to
+     `error` only when the contradiction is **decision-bearing**: an implementer building
+     from the wrong statement writes different code, or the wrong statement is what a
+     downstream artifact or generated output copies. Quote both locations verbatim.
+     **Report, do not repair.**
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "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-verify/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` is a LEGACY enum value, retained so pre-0.14 state files still validate: no writer produces it (the `state-*` verbs are the only writers, and only `state-enter` touches this field, setting it to the stage being entered). A finished pipeline therefore records the last stage it started — `forge-6-docs` — and 'the whole pipeline is done' is DERIVED too: `next_stage()` returns null (surfaced as `nextStage: null` / `complete: true`). Never test this field against `complete` to decide whether a pipeline finished. (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/codex/skills/forge-verify/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` is a LEGACY enum value, retained so pre-0.14 state files still validate: no writer produces it (the `state-*` verbs are the only writers, and only `state-enter` touches this field, setting it to the stage being entered). A finished pipeline therefore records the last stage it started — `forge-6-docs` — and 'the whole pipeline is done' is DERIVED too: `next_stage()` returns null (surfaced as `nextStage: null` / `complete: true`). Never test this field against `complete` to decide whether a pipeline finished. (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." }
-      }
-    }
-  }
-}