@garygentry/feature-forge 0.3.1 → 0.3.4

package/adapters/gemini/skills/forge-0-epic/forge-0-epic.md

@@ -164,6 +164,7 @@ sequence, **not** a dependency ordering). Preserve the C2 order unless the user
 Compose the full `epic-manifest.json` per the 00 §2 schema, setting:
 
 - `schemaVersion`: `1`
+- `revision`: `1` — the canonical artifact revision epic-scoped verification freshness compares against. Creation always writes `1`; every later mutation bumps it exactly once via the helper mutators. Never hand-edit it.
 - `epic`: `"{epic}"`
 - `description`: from C1
 - `status`: `"active"`
@@ -247,15 +248,17 @@ now self-contained: manifest + EPIC.md + one subdirectory per member.
 
 3. **Closing message — the Stage Exit Protocol.** Congratulate the user ("Epic `{epic}` created with {N} features."), then close with the Stage Exit Protocol below (single-sourced in `references/stage-exit-protocol.md`; the epic → first-PRD boundary is a full stage boundary — do not improvise a "Next steps" list). `{first-actionable-feature}` = any feature with empty `dependsOn` (or the first entry of `render-status`'s `actionable` set):
 
+Determine `{verify-capability}` per the **Host and capability determination** section of `references/stage-exit-protocol.md`: `interactive` needs both a question mechanism and *permission* to dispatch the clean-room `forge-verifier`, and a session that merely needs consent first is still `interactive`.
+
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
 ```bash
 R="$(bash -c 'for d in "${FEATURE_FORGE_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/forge-session.py" stage-exit --feature "{epic}" --stage forge-0-epic --next-feature "{first-actionable-feature}" --specs-dir "{specsDir}" --host generic
+python3 "$R/scripts/forge-session.py" stage-exit --feature "{epic}" --stage forge-0-epic --next-feature "{first-actionable-feature}" --specs-dir "{specsDir}" --host generic --verify-capability "{verify-capability}"
 ```
 
-Obey the DIRECTIVES it prints, in order, per the directive contract: `runInStageVerify: true` → dispatch the in-stage clean-room verify now (honoring `autoFixEligible`); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user; non-empty `invalidAutoVerifyKeys` → print a one-line warning. Then **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.**
+Obey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `"self"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: "outer"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.
 
 ---
 
@@ -274,6 +277,8 @@ EPIC.md patch rule, and the E6 Observability / Pipeline State & Commit machinery
 `references/edit-mode.md`. For the exact `epic-manifest.py` mutator flag surface and
 per-subcommand exit-code (`0`/`1`/`2`) handling, read `references/epic-manifest-subcommands.md`.
 
+An edit-mode mutation closes through the **same** Scripted Stage Exit command Step C8 runs — there is one scripted exit for this skill, not one per branch. Only the argument differs: edit mode re-reads live epic status **after** the mutation and its commit, passes the resulting concrete member as `--next-feature`, and **omits that flag entirely** when no member is actionable (so the router hands back to the epic dashboard instead of naming a member it cannot resolve). Those substitution rules, the `render-status` failure path, and the script's member fallback warning are all in `references/edit-mode.md` — do not improvise a closing pointer here.
+
 ---
 
 ## Error Handling

package/adapters/gemini/skills/forge-0-epic/references/edit-mode.md

@@ -9,14 +9,14 @@ Entered from Step 0 when `{specsDir}/{epic}/epic-manifest.json` already exists (
 branch). The edit branch mutates the manifest **only** through helper mutators — the skill never
 hand-rolls an in-place write. Every mutator is atomic (temp file + `os.replace`) and re-validates
 the edited graph internally, so a refused write leaves the manifest **byte-identical**. Every
-question goes through `AskUserQuestion`.
+question goes through the host's question mechanism.
 
 ## Step E1 — Load + Validate, Refuse if Invalid
 
 Before offering any edit, validate the existing manifest:
 
 ```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')"
+R="$(bash -c 'for d in "${FEATURE_FORGE_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
 ```
@@ -40,7 +40,7 @@ report it and continue with the rest — do **not** abort edit mode over one bad
 E1's "report, never silently repair" posture).
 
 If any open requests exist, present them grouped (show `kind`, `target`, `rationale`,
-`blocksCurrent`, `raisedBy`), then for **each** request use `AskUserQuestion` to offer **Apply**,
+`blocksCurrent`, `raisedBy`), then for **each** request use the host's question mechanism to offer **Apply**,
 **Dismiss**, or **Skip for now**:
 
 - **Apply — simple kinds (`add-feature`, `redep`):** pre-fill the matching E2 operation and flow
@@ -52,7 +52,7 @@ If any open requests exist, present them grouped (show `kind`, `target`, `ration
   user through a **guided-manual** sequence — the relevant `set-dep` and/or direct `exposes`/
   `consumes` edits on the composed manifest entries (per E3's "Contracts have no mutator" rule),
   across **both** affected features — re-validating after each step. Confirm each mutation via
-  `AskUserQuestion`; never batch-apply.
+  the host's question mechanism; never batch-apply.
 - **Dismiss:** the user decides the epic is fine after all — flip the source request's `status` to
   `"dismissed"` (no manifest mutation). Explicit only; there is **no auto-expiry**.
 - **Skip for now:** leave the request `open`; it resurfaces on the next edit-mode entry and stays
@@ -72,7 +72,7 @@ requests exist, say nothing and proceed straight to E2.
 
 ## Step E2 — Choose Operation
 
-Use `AskUserQuestion` to offer the edit operations, each mapping to one helper mutator:
+Use the host's question mechanism to offer the edit operations, each mapping to one helper mutator:
 
 | Operation | Helper subcommand |
 |-----------|-------------------|
@@ -80,6 +80,7 @@ Use `AskUserQuestion` to offer the edit operations, each mapping to one helper m
 | Remove a feature | `remove-feature` |
 | Reorder features | `reorder` |
 | Change a dependency edge | `set-dep` |
+| Rewrite a feature's charter | `set-charter` |
 | Change epic lifecycle status | `set-status` |
 
 For **add-feature**, first run `check-name "{feature}"` (exactly as C2) so no new duplicate is
@@ -97,7 +98,10 @@ exact `epic-manifest.py` mutator flag surface and per-subcommand exit-code handl
 **Contracts have no mutator.** `add-feature` seeds empty `exposes`/`consumes`. To populate the
 new feature's contracts, edit its `exposes`/`consumes` arrays **directly in the composed manifest
 entry** (exactly as creation C5 does), then re-run `validate "{epic}" --json` to confirm — there
-is intentionally no `--exposes-json`/`--consumes-json` flag.
+is intentionally no `--exposes-json`/`--consumes-json` flag. This carve-out is contracts-only:
+a **charter** rewrite goes through `set-charter` (#166), never a direct edit — the mutator gives
+it the same atomic write, re-validation, and revision bump as every other manifest mutation.
+After a charter change, patch the feature's EPIC.md section in E5 like any other mutation.
 
 **remove-feature leaves the member directory in place (§7.5).** The mutator drops only the
 manifest entry. The skill does **not** delete or relocate `{specsDir}/{epic}/{feature}/`. WARN the
@@ -119,13 +123,13 @@ status is **not** `not-started`, warn the user. Read the **live** status (never
 completion in prose):
 
 ```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')"
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 If the operation removes, reorders-around, or re-deps a feature whose derived status is
-`in-progress` or `complete`, use `AskUserQuestion` with an explicit warning naming the affected
+`in-progress` or `complete`, use the host's question mechanism with an explicit warning naming the affected
 in-flight/completed feature(s) and **require confirmation** before applying. Example: "`token-service`
 is already in-progress (forge-3-specs). Removing `config-store`, which it consumes `JWT_SECRET`
 from, may invalidate its in-flight specs. Proceed?" If `render-status` exits `≥ 1`, surface the
@@ -136,7 +140,7 @@ findings and STOP (do not mutate over an invalid graph).
 Patch **only** the affected feature/Contracts section(s) — the section(s) for the added, removed,
 or changed feature and any feature whose `dependsOn`/`consumes` changed — applying the §C6 mirror
 rule (one bullet per `exposes`/`consumes` entry). **Full regeneration happens only on explicit
-user request**: offer it via `AskUserQuestion` but default to the targeted patch. The skill keeps
+user request**: offer it via the host's question mechanism but default to the targeted patch. The skill keeps
 EPIC.md in sync but does not itself diff it against the manifest — drift detection is `forge-verify`
 epic mode CHECK-E06.
 
@@ -163,29 +167,15 @@ For the initial creation write (C5) the skill sets `createdAt == updatedAt`.
 - **Edit mode:** edits mutate the **manifest**, not member pipeline states — except the
   newly-created subdir for `add-feature`, which follows C7 (create the member subdir + back-pointer
   state). The skill does **not** rewrite existing members' `stages` on an edit.
-- **`.epic-state.json` (lazily created, written by skills — NOT the helper):** epic-*scoped* stage
+- **`.epic-state.json` (lazily created, written by `state-verify`):** epic-*scoped* stage
   entries that belong to no single member — currently only `forge-verify-epic` — are persisted in a
   dedicated `{specsDir}/{epic}/.epic-state.json`. It holds **only** epic-scoped stage entries,
   never derived per-feature status (so it does not violate REQ-STATE-02). `forge-0-epic` does
   **not** create this file — no epic-scoped stage runs during creation or edit; it appears only once
-  `forge-verify` epic mode runs. When a skill does write it (e.g. forge-verify epic mode), it writes
-  **directly** using an atomic temp-file + `os.replace` pattern — the helper exposes no subcommand
-  for it. On I/O failure the skill reports and leaves any prior file intact (never a partial write).
-  Minimal schema:
-
-  ```jsonc
-  {
-    "epic": "auth-overhaul",            // matches manifest `epic`
-    "stages": {
-      "forge-verify-epic": {
-        "status": "findings-reported",   // "findings-reported" | "passed" | "findings-applied"
-        "findingsFile": ".verification/VERIFY-epic-2026-06-12.md",
-        "findingsCount": 3,
-        "verifiedAt": "2026-06-12T00:00:00Z"
-      }
-    }
-  }
-  ```
+  `forge-verify` epic mode runs, and that skill records the result through `state-verify --stage
+  forge-0-epic` (the sanctioned epic writer, per the Pipeline State Protocol in
+  `references/shared-conventions.md`). No skill ever hand-authors this file, and its minimal shape
+  is documented once, alongside that call, in `skills/forge-verify/references/findings-template.md`.
 
   The git-commit step below stages the whole epic subtree, so `.epic-state.json` is captured
   automatically when present.
@@ -210,13 +200,27 @@ follow the Git Commit Protocol in shared-conventions:
 Because every mutation is committed, the git history of `epic-manifest.json` is the audit trail; no
 separate in-manifest audit log is kept.
 
-### Closing message
+### Closing the stage — fresh live status, then the Scripted Stage Exit
+
+After a successful **creation**, close with Step C8's Scripted Stage Exit, exactly as specified there.
+
+After a successful **edit-mode mutation** — the mutator returned exit `0` **and** the E6 commit above landed — confirm the change in one line (`Epic {epic} updated (<action>).`) and then close with the **same** Scripted Stage Exit. Do **not** hand-write a dashboard pointer, a "Next steps" list, or any other next command: the script owns edit-mode routing end to end, and a second hand-written command can only disagree with it.
+
+**Read live status again first.** The E4 `render-status` snapshot is stale by the time you get here — it was taken *before* the mutation, so a member the edit just unblocked (or just blocked) is misreported, and the whole point of routing from live state is lost. Re-read it **after** the mutation and the commit:
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
+```
+
+Choosing the `--next-feature` argument from that **fresh** payload is the only routing decision this step makes; every other one belongs to the script:
 
-After a successful **creation**, present the next-steps message (already specified in C8). After a
-successful **edit-mode mutation**, confirm the change and re-surface the dashboard pointer:
+- **`actionable` is non-empty** → `{first-actionable-feature}` is its **first** entry, a concrete member name. Pass it as `--next-feature "{first-actionable-feature}"`. The script then resolves that member's own `.pipeline-state.json` and routes to its **first incomplete production stage**, so a member whose PRD is already written resumes at tech/specs/backlog/loop/docs — it is never sent back to `forge-1-prd`. Do **not** derive that stage yourself and do **not** read the member's state to second-guess the script.
+- **`actionable` is empty** → there is no member to hand off to. **Omit `--next-feature` entirely**; the script routes to the epic dashboard/completion view. Never substitute a stand-in for the flag value — not the literal `{first-actionable-feature}`, not the epic name, not an arbitrary member off `features[]`. An unresolved placeholder is not a member name, and the script rejects an unsafe value with exit `2`.
+- **`render-status` exits `≥ 1`, or its payload is malformed or missing a required field** → surface every `findings[]` entry **verbatim**, then take the same no-member path: close with the epic stage exit carrying **no** `--next-feature`, so recovery lands on the epic dashboard. A failed status read is never grounds to guess a follow-up member.
 
-> Epic `{epic}` updated (`<action>`). Run `/feature-forge:forge {epic}` to see the refreshed
-> dashboard, or re-run `/feature-forge:forge-0-epic {epic}` to make another change.
+**Surface the script's warnings before the block.** `warnings` is part of the directive contract. When the selected member's pipeline state is missing, unreadable, malformed, or not a member of this epic, the script emits a named warning naming that member and the recovery command, and degrades **only** to `forge-1-prd {member}` on its own. Print that warning ahead of the terminal block exactly as emitted, and leave the routing where the script put it — do **not** "correct" the fallback to a later stage you inferred, and do **not** re-read the member's state to override it.
 
 ## EPIC.md Mirror Template (creation C6 / edit E5)
 

package/adapters/gemini/skills/forge-0-epic/references/epic-manifest-subcommands.md

@@ -12,7 +12,7 @@ the write if it would introduce a cycle, dangling ref, duplicate, or schema viol
 flag surface (owned by 02 §7):
 
 ```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')"
+R="$(bash -c 'for d in "${FEATURE_FORGE_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; }
 # Add a feature — seeds EMPTY exposes/consumes; contracts are populated below.
 python3 "$R/scripts/epic-manifest.py" add-feature "{epic}" "{feature}" \
@@ -30,6 +30,11 @@ python3 "$R/scripts/epic-manifest.py" reorder "{epic}" \
 python3 "$R/scripts/epic-manifest.py" set-dep "{epic}" "{feature}" \
   --depends-on "config-store,token-service" --specs-dir "{specsDir}"
 
+# Replace a member feature's charter (the field most likely to need revision after
+# creation — an ADR lands, a boundary moves). Refuses a blank charter (empty-charter).
+python3 "$R/scripts/epic-manifest.py" set-charter "{epic}" "{feature}" \
+  --charter "…" --specs-dir "{specsDir}"
+
 # Change epic lifecycle status (active|paused|abandoned|complete).
 python3 "$R/scripts/epic-manifest.py" set-status "{epic}" \
   --status paused --specs-dir "{specsDir}"
@@ -61,7 +66,7 @@ helper exit `≥ 1`. All findings are surfaced **verbatim**.
 
 | Condition | Helper signal | Skill behavior |
 |-----------|---------------|----------------|
-| Epic name duplicates an existing name | `check-name` exit 1 (`duplicate-name`) | STOP creation; surface finding; ask for a new name via `AskUserQuestion` |
+| Epic name duplicates an existing name | `check-name` exit 1 (`duplicate-name`) | STOP creation; surface finding; ask for a new name via the host's question mechanism |
 | Member feature name duplicates | `check-name` exit 1 (`duplicate-name`) | Reject that name in C2 / add-feature; surface verbatim; re-prompt |
 | Unsafe name (`/`, `..`, absolute) | `check-name`/mutator exit 2 (`unsafe-name`) | Reject; surface; re-prompt |
 | Composed manifest has a cycle | `validate` exit 1 (`cycle`) | Surface verbatim; re-open the dependency interview (C4); never finalize |
@@ -69,7 +74,7 @@ helper exit `≥ 1`. All findings are surfaced **verbatim**.
 | Corrupt/unparseable manifest (edit) | `validate` exit 1 (`corrupt-json`) | Surface ALL findings verbatim; **refuse all mutation** until repaired; never auto-repair |
 | Existing manifest otherwise invalid (edit) | `validate` exit 1/2 | Surface ALL findings verbatim; **refuse all mutation** (E1) |
 | Mutator would introduce cycle/dangling ref/duplicate | mutator exit 1 | Abort the edit; manifest byte-identical (atomic refusal); surface finding |
-| Bad `--status` value | `set-status` exit 2 (argparse) | Surface; re-prompt via `AskUserQuestion` with the valid choices |
+| Bad `--status` value | `set-status` exit 2 (argparse) | Surface; re-prompt via the host's question mechanism with the valid choices |
 | Edit affects in-flight/completed feature | `render-status` derived status (`in-progress`/`complete`) | Warn naming the affected feature(s); require confirmation before applying (E4) |
 | `render-status` over an invalid graph | `render-status` exit ≥ 1 | Surface findings; STOP (do not mutate over an invalid graph) |
 | Git commit fails | — | Report; leave state `in-progress`; never bypass hooks (`--no-verify`/`--force`) |

package/adapters/gemini/skills/forge-0-epic/references/pipeline-state-schema.json

@@ -37,7 +37,7 @@
     },
     "notes": {
       "type": "string",
-      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away). A single string with latest-note-wins semantics: `state-note` (its only sanctioned writer) OVERWRITES the previous value — an author folds any still-relevant earlier note into the one combined string. Read by the navigator dashboard AND by each downstream stage's Step 1 carried-over note check (forge-2-tech through forge-5-loop), which surfaces it as stage input; it never overrides artifacts or config."
     },
     "epicChangeRequests": {
       "type": "array",
@@ -127,7 +127,7 @@
         "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-6-docs": { "$ref": "#/definitions/docsStageEntry" },
         "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
         "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
         "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
@@ -165,13 +165,45 @@
         }
       }
     },
+    "docsStageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "description": "The forge-6-docs stage entry: identical to stageEntry except that `skipped` is a legal status and `skippedAt` records when the deliberate skip was written (by the `state-skip` verb, never by hand). `skipped` is a terminal, done-for-selection status — the pipeline ends without the stage claiming artifacts it never produced (#197). Deliberately scoped to the docs stage: a skipped PRD or specs stage is not a representable state, so the shared stageEntry enum does NOT carry `skipped`.",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale", "skipped"]
+        },
+        "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" },
+        "skippedAt": { "type": ["string", "null"], "format": "date-time", "description": "UTC ISO-8601 timestamp of the deliberate skip (status: skipped). Written by `state-skip`; absent on every other status." },
+        "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"]
+          "enum": ["pending", "auto-verify-pending", "passed", "findings-reported", "findings-applied", "skipped"]
         },
         "findingsFile": {
           "type": ["string", "null"],
@@ -184,7 +216,9 @@
         "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." }
+        "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." },
+        "scheduledAt": { "type": ["string", "null"], "format": "date-time", "description": "UTC ISO-8601 timestamp at which unattended in-stage verification was scheduled for this entry. Written alongside the `auto-verify-pending` status and DELETED (not nulled) by any terminal result, so an absent field means 'not scheduled'." },
+        "scheduledStageVersion": { "type": ["integer", "null"], "minimum": 1, "description": "The artifact revision current when verification was scheduled — the production stage's `version` for a feature, the epic manifest's `revision` for an epic. Makes rescheduling idempotent (an identical revision does not rewrite the entry) and lets a read tell debt owed on the current artifact from debt stranded on an older one. Deleted by any terminal result." }
       }
     }
   }