@garygentry/feature-forge 0.2.12 → 0.2.13

package/adapters/GENERATION-REPORT.md

@@ -131,6 +131,7 @@ These files are transported byte-for-byte from canon into every `adapters/<agent
 - `scripts/forge-root.sh` → `adapters/<agent>/scripts/forge-root.sh` (mode 0755, byte-identical — REQ-GEN-05).
 - the whole repo-root `references/` tree (all root files plus the `stacks/` and `templates/specs-hygiene/` subtrees) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
 - each skill's own `references/` subdir → `adapters/<agent>/skills/<name>/references/` (verbatim, where present).
+- each bundle-root SHARED reference a skill cites (e.g. `references/shared-conventions.md`, `references/stacks/`) → that skill's `adapters/<agent>/skills/<name>/references/` (verbatim), so a bare `references/X` prose read resolves skill-local on every install layout — including the non-plugin Claude tree with no `${CLAUDE_PLUGIN_ROOT}` (#132).
 
 Regenerate all adapter output with `python3 scripts/build-adapters.py`.
 

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

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

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

@@ -51,6 +51,11 @@
       "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,

package/adapters/claude/scripts/epic-manifest.py

@@ -27,6 +27,7 @@ import argparse
 import json
 import os
 import re
+import shutil
 import sys
 import tempfile
 from datetime import datetime, timezone
@@ -1195,6 +1196,180 @@ def set_status(epic_dir: Path, specs_dir: Path, status: str) -> list[Finding]:
     return _bump_and_write(epic_dir, specs_dir, manifest)
 
 
+def _load_state_strict(state_path: Path) -> dict:
+    """Read a .pipeline-state.json, raising UsageError on a missing/corrupt file.
+
+    Unlike ``_read_state_safely`` (which downgrades a torn read to ``{}`` for the
+    read-only dashboard), an adopt mutation must NOT silently discard the
+    standalone's stage history — a corrupt source is a hard stop (exit 2) so the
+    human fixes it before the irreversible move.
+    """
+    try:
+        parsed = json.loads(state_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise UsageError(f"cannot read {state_path}: {exc}")
+    except json.JSONDecodeError as exc:
+        raise UsageError(f"{state_path} is not valid JSON: {exc}")
+    if not isinstance(parsed, dict):
+        raise UsageError(f"{state_path} is not a JSON object")
+    return parsed
+
+
+def _merge_member_state(stub: dict, standalone: dict, epic_name: str) -> dict:
+    """Merge a detached standalone's state onto an epic member stub (Issue #126).
+
+    The **stub** is the base — it carries the correct ``epic`` and ``branch``
+    back-pointers that the epic minted. The **standalone** holds the real work, so
+    its stage history / artifacts / currentStage overlay the stub. The ``epic``
+    back-pointer is forced to the target epic; the stub's ``branch`` is preserved
+    (only falling back to the standalone's when the stub has none).
+    """
+    merged = dict(stub)
+    for key in ("currentStage", "artifacts", "notes",
+                "deferredDecisions", "epicChangeRequests"):
+        if key in standalone:
+            merged[key] = standalone[key]
+    stages = dict(stub.get("stages") or {})
+    stages.update(standalone.get("stages") or {})
+    merged["stages"] = stages
+    merged["epic"] = epic_name
+    if not (isinstance(stub.get("branch"), str) and stub["branch"]) and \
+            isinstance(standalone.get("branch"), str) and standalone["branch"]:
+        merged["branch"] = standalone["branch"]
+    return merged
+
+
+def adopt_feature(
+    epic_dir: Path,
+    specs_dir: Path,
+    feature: str,
+    charter: str | None,
+    deps: list[str],
+) -> dict:
+    """Reconcile a detached standalone feature into an epic member (Issue #126).
+
+    The scripted recovery for a **split-brain epic** (#125): a feature that should
+    be an epic member was forged as a flat standalone at ``{specsDir}/{feature}/``.
+    This relocates it into the member slot ``{epicDir}/{feature}/``, merging state
+    so the stub's ``epic``/``branch`` back-pointers survive, removes the flat dir
+    (no residual), and adds the feature to the manifest if absent.
+
+    Operates on the CURRENT tree/branch — both the flat standalone and the epic
+    manifest must already be present (the human brings a cross-branch standalone
+    onto the epic's home branch first, per ``docs/recovery-detached-epic-member.md``;
+    EPIC.md prose is regenerated separately via forge-0-epic). Deliberately ordered
+    **relocate-then-manifest**: after the flat dir is gone the feature name maps to
+    exactly one dir, so ``add_feature``'s global-uniqueness re-validation stays
+    clean. Re-entrant — a half-finished run (files moved, manifest not yet updated)
+    completes on re-run.
+
+    Args:
+        epic_dir: The target epic subtree directory (must hold epic-manifest.json).
+        specs_dir: The configured specs directory.
+        feature: The detached standalone feature name to adopt.
+        charter: Charter for the manifest entry when the feature is not yet a
+            member; a default is used when omitted.
+        deps: dependsOn for the new manifest entry (ignored if already a member).
+
+    Returns:
+        A summary dict (``adopted``/``relocated``/``manifestUpdated``/…) on success.
+
+    Raises:
+        UsageError: Unsafe name, missing manifest, nothing to adopt, or an I/O
+            failure (exit 2).
+        FindingsError: A blocking manifest finding from ``add_feature`` (e.g. an
+            unknown dependency) after relocation — exit 1; re-run after fixing.
+    """
+    assert_safe_name(feature)
+    for dep in deps:
+        assert_safe_name(dep)
+
+    # The epic manifest must exist on this tree (exit 2 if not — nothing to adopt into).
+    load_manifest(epic_dir)
+
+    flat_dir = contained_path(specs_dir, feature)
+    member_dir = contained_path(epic_dir, feature)
+    if flat_dir == member_dir:
+        raise UsageError(f"feature {feature!r} resolves to the epic dir itself")
+
+    flat_state = flat_dir / PIPELINE_STATE_FILENAME
+    member_state = member_dir / PIPELINE_STATE_FILENAME
+    flat_exists = flat_state.is_file()
+    member_exists = member_state.is_file()
+
+    if not flat_exists and not member_exists:
+        raise UsageError(
+            f"nothing to adopt: neither a standalone {flat_dir} nor a member "
+            f"{member_dir} has a {PIPELINE_STATE_FILENAME}"
+        )
+
+    relocated = False
+    if flat_exists:
+        standalone = _load_state_strict(flat_state)
+        if member_exists:
+            merged = _merge_member_state(
+                _read_state_safely(member_state), standalone, epic_dir.name
+            )
+        else:
+            merged = dict(standalone)
+            merged["epic"] = epic_dir.name
+        # Move every artifact except the state file (merged separately) into the
+        # member slot; the standalone (real work) wins on any name collision.
+        member_dir.mkdir(parents=True, exist_ok=True)
+        for child in sorted(flat_dir.iterdir()):
+            if child.name == PIPELINE_STATE_FILENAME:
+                continue
+            dest = member_dir / child.name
+            if dest.is_dir():
+                shutil.rmtree(dest)
+            elif dest.exists():
+                dest.unlink()
+            shutil.move(str(child), str(dest))
+        atomic_write(member_state, merged)
+        shutil.rmtree(flat_dir)
+        relocated = True
+    else:
+        # Already nested (a prior run moved the files) — only ensure the back-pointer.
+        stub = _read_state_safely(member_state)
+        if stub.get("epic") != epic_dir.name:
+            stub["epic"] = epic_dir.name
+            atomic_write(member_state, stub)
+
+    # Ensure the feature is a manifest member (idempotent — the flat dir is gone now,
+    # so add_feature's tree-uniqueness re-check sees exactly one dir for the name).
+    manifest = load_manifest(epic_dir)
+    already_member = any(
+        isinstance(f, dict) and f.get("name") == feature
+        for f in manifest.get("features", [])
+    )
+    manifest_updated = False
+    if not already_member:
+        findings = add_feature(
+            epic_dir, specs_dir, feature,
+            charter or f"Adopted into the {epic_dir.name} epic from a detached standalone.",
+            deps,
+        )
+        if findings:
+            raise FindingsError(findings)
+        manifest_updated = True
+
+    return {
+        "adopted": True,
+        "epic": epic_dir.name,
+        "feature": feature,
+        "memberDir": str(member_dir),
+        "relocated": relocated,
+        "manifestUpdated": manifest_updated,
+        "wasAlreadyMember": already_member,
+        "nextSteps": [
+            f"Regenerate EPIC.md prose via /feature-forge:forge-0-epic {epic_dir.name}",
+            f"Confirm the dashboard via /feature-forge:forge {epic_dir.name}",
+            f"Verify the member via /feature-forge:forge-verify {feature}",
+            "Commit the surgery (stage the epic subtree and the removed flat dir).",
+        ],
+    }
+
+
 # --------------------------------------------------------------------------- #
 # CLI Dispatch (02 §9)
 # --------------------------------------------------------------------------- #
@@ -1285,6 +1460,25 @@ def _dispatch(args: argparse.Namespace, specs_dir: Path) -> int:
             _print_status_table(status)
         return 0
 
+    if cmd == "adopt-feature":
+        epic_dir = contained_path(specs_dir, args.epic)
+        summary = adopt_feature(
+            epic_dir, specs_dir, args.name, args.charter,
+            _split_list(args.depends_on),
+        )
+        if args.json_output:
+            print(json.dumps(summary, indent=2, ensure_ascii=False))
+        else:
+            print(f"Adopted {summary['feature']!r} into epic {summary['epic']!r}.")
+            print(f"  member dir:      {summary['memberDir']}")
+            print(f"  relocated files: {summary['relocated']}")
+            print(f"  manifest added:  {summary['manifestUpdated']}"
+                  f"{' (already a member)' if summary['wasAlreadyMember'] else ''}")
+            print("Next steps:")
+            for step in summary["nextSteps"]:
+                print(f"  - {step}")
+        return 0
+
     # Mutators ---------------------------------------------------------------
     if cmd in {"add-feature", "remove-feature", "reorder", "set-dep", "set-status"}:
         epic_dir = contained_path(specs_dir, args.epic)
@@ -1358,6 +1552,21 @@ def _build_parser() -> argparse.ArgumentParser:
     add_specs_dir(p_add)
     add_json(p_add)
 
+    # adopt-feature --------------------------------------------------------- #
+    p_adopt = sub.add_parser(
+        "adopt-feature",
+        help="Reconcile a detached standalone feature into an epic member (#126)",
+    )
+    p_adopt.add_argument("epic")
+    p_adopt.add_argument("name")
+    p_adopt.add_argument(
+        "--charter", default=None,
+        help="Charter for the manifest entry when the feature is not yet a member",
+    )
+    p_adopt.add_argument("--depends-on", dest="depends_on", default="", help="Comma list")
+    add_specs_dir(p_adopt)
+    add_json(p_adopt)
+
     # remove-feature -------------------------------------------------------- #
     p_remove = sub.add_parser("remove-feature", help="Remove a member feature")
     p_remove.add_argument("epic")

package/adapters/claude/scripts/forge-bootstrap.py

@@ -568,6 +568,7 @@ def write_config(answers: Answers, target: Path, sentinel: Sentinel) -> None:
         "stack": None,
         "typeCheckCommand": None,
         "testCommand": None,
+        "smokeCommand": None,
         "loopIterationMultiplier": 1.5,
         # Navigator keys — kept in lockstep with forge-init.sh's emitted field set
         # (00 §7, REQ-CFG-02) so a bootstrapped config == forge-init's + loopRunner.

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

@@ -21,6 +21,7 @@ cat > "$CONFIG_FILE" << 'EOF'
   "stack": null,
   "typeCheckCommand": null,
   "testCommand": null,
+  "smokeCommand": null,
   "loopIterationMultiplier": 1.5,
   "autoInvokeNextStage": true,
   "contextWindowTokens": null,
@@ -42,6 +43,7 @@ echo "  commitPrefix:        forge"
 echo "  stack:               null (auto-detected during forge-2-tech)"
 echo "  typeCheckCommand:    null (auto-detected during forge-2-tech)"
 echo "  testCommand:         null (auto-detected during forge-2-tech)"
+echo "  smokeCommand:        null (optional end-to-end smoke; enables impl-verify runnability check)"
 echo "  loopIterationMultiplier: 1.5 (multiplier for loop iterations)"
 echo "  autoInvokeNextStage: true (navigator auto-starts the next stage after you confirm)"
 echo "  contextWindowTokens: null (infer; set to 1000000 on a 1M-context model)"

package/adapters/claude/skills/forge/SKILL.md

@@ -89,10 +89,18 @@ Use these status indicators:
 
 After rendering a **per-feature** dashboard for an **active** pipeline (skip this for paused/abandoned pipelines and for the Epic Dashboard), don't stop at a text suggestion — actively offer to start the next stage. This removes the copy-paste-after-`/clear` chore that makes long, multi-stage runs painful (especially on mobile).
 
-**1. Read the next step.** From the `rank-features --json` output (above), find this feature's row and read its `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState`, `autoVerify`, `autoFix`, and `verifyGate` (the resolved gate: `none` → no verify action; `auto` → the §2b catch-up; `standard` → the §3 gate). If the feature is not in the `active` list (paused/abandoned), or `nextStage` is `null` (every production stage complete), skip the drive prompt — instead congratulate the user and, if `forge-6-docs` has not run, offer it; otherwise note the pipeline is complete. If the payload has a non-empty `invalidAutoVerifyKeys`, print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has unknown keys: … — they are ignored; fix the typo").
+**1. Read the next step.** From the `rank-features --json` output (above), find this feature's row and read its `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState`, `autoVerify`, `autoFix`, and `verifyGate` (the resolved gate: `none` → no verify action; `auto` → the §2b catch-up; `standard` → the §3 gate). If the feature is not in the `active` list (paused/abandoned), or `nextStage` is `null` (every production stage complete), skip the drive prompt — instead congratulate the user and, if `forge-6-docs` has not run, offer it; otherwise the whole pipeline is done, so **route into the Completion hand-off block below instead of dead-ending** (steps 2/2b/3 do not apply — there is no next stage to drive). If the payload has a non-empty `invalidAutoVerifyKeys`, print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has unknown keys: … — they are ignored; fix the typo").
 
 **Detached-epic hint (completion of a *standalone* feature, Issue #125).** When `nextStage` is `null` for a feature whose row has no `epic` (a standalone completion), run `discover-feature "{feature}" --json` (via the standard prelude) *before* congratulating. If any candidate has `isEpicMember: true` on another branch, add an **additive, non-blocking** hint — it does not change the completion, only flags a likely split-brain: "⚠️ Heads-up: `{feature}` matches a member of epic `{epic}` on branch `{stateBranch}`. This standalone pipeline may have been forged detached from that epic. To reconcile, see `docs/recovery-detached-epic-member.md` (or continue — this is only a heads-up)." Skip the hint for epic-member rows (their `epic` is non-null) and when discovery surfaces no epic-member candidate.
 
+**Completion hand-off (fires when `nextStage` is `null` AND `forge-6-docs` has run — the pipeline is fully complete, Issue #124).** Do not dead-end on "pipeline is complete" — after congratulating, point the user at the next unit of work. This is a **terminal branch**: the drive steps (2/2b/3) do not run.
+
+- **Epic member** (this feature's `rank-features` row has a non-null `epic`, i.e. its `.pipeline-state.json` carries an `epic` back-pointer): run `epic-manifest.py render-status "{epic}" --specs-dir "{specsDir}" --json` (standard prelude; you likely already have this from the Tier-1 epic rollup — reuse it rather than re-running). Then:
+  - If `actionable` is non-empty, offer the next member via `AskUserQuestion`: *"Epic '{epic}' has {total−complete} feature(s) left — next up: **{actionable[0].name}** (`{actionable[0].nextCommand}`). Start it now?"* On accept, drive it exactly like a normal next stage (honor `autoInvokeNextStage` + `Skill`-tool availability per step 3's Continue-in-this-session rule; else print `{nextCommand}`). List any remaining `actionable` members as also-available.
+  - If `actionable` is empty but the epic is **not** fully complete (members blocked on unmet `dependsOn`), say so and point at the blockers rather than offering a start.
+  - If the epic is **fully complete** (`rollup.complete == rollup.total`, `total > 0`), congratulate on the whole epic and offer the epic-level architecture doc (`/feature-forge:forge-6-docs` already surfaces this — mention it) and/or that the epic can be marked complete (`/feature-forge:forge {epic}` renders the finished dashboard).
+- **Standalone** (row's `epic` is null): offer to start a fresh feature — *"Start a new feature: `/feature-forge:forge-1-prd <feature-name>` (or group several with `/feature-forge:forge-0-epic <epic-name>`)."* Then, from the `rank-features` `active` list, surface any **other** active pipelines (exclude this just-completed one) as a one-line list with their `nextCommand`s so the user can jump straight back into in-flight work. If the **detached-epic hint above fired** for this feature, lead with that recovery path (`docs/recovery-detached-epic-member.md`) — the split-brain reconcile is the more likely next action than starting something new.
+
 **2. Check the context window.** Run the context-usage helper so you can advise whether to continue here or start the next stage in a fresh session:
 ```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')"

package/adapters/claude/skills/forge/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." }
+      }
+    }
+  }
+}