@garygentry/feature-forge 0.3.2 → 0.3.4

package/adapters/codex/skills/forge/references/stage-exit-protocol.md

@@ -4,7 +4,7 @@ The single source of truth for how every forge stage closes. **One** scripted co
 covers all **nine** covered direct exits — the seven production stages `forge-0-epic`
 through `forge-6-docs`, plus direct `forge-verify` and direct `forge-fix`. It replaces the
 old ad-hoc "Next steps:" bullet lists with one fixed, correctly-ordered sequence:
-**verify (if missing or stale) → `/clear` → run the next command.**
+**verify (if missing or stale) → clear your session / start a fresh session → run the next command.**
 
 Two principles this protocol encodes (do not relitigate — they are locked product
 decisions):
@@ -18,7 +18,7 @@ decisions):
    session, so the findings digest and any fix decision land where the context to act on
    them still exists. This holds for auto-verify too: the stage skill dispatches the
    clean-room verify (and any autoFix) at stage end, in-session, before the exit — it is
-   **not** deferred to the navigator, which runs *after* the `/clear` with none of the
+   **not** deferred to the navigator, which runs *after* the session clear with none of the
    authoring context. Clearing first throws that context away.
 
 ## How this file is used
@@ -47,8 +47,8 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred` |
-| `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete` or `blocked` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |
 | direct/nested `forge-fix` | `forge-fix` | the matching `--owner`, a `FixOutcome` (`no-findings`, `decisions`, `failed`, `applied`, `reverified`, `reverify-findings`, `deferred`), and served-stage metadata |
@@ -90,19 +90,19 @@ resolves before running the command, exactly as elsewhere.
 **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 "${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/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
+python3 "$R/scripts/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host generic --verify-capability "{verify-capability}"
 ```
 
 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.
 <!-- END: scripted-stage-exit-stamp -->
 
-The stamp is shown with `--host claude`; the adapter build substitutes `pi`/`generic` per
+The stamp is shown with `--host generic`; the adapter build substitutes `pi`/`generic` per
 target, and §"Host and capability determination" below governs the value. The literal is
-deliberate — `scripts/build-adapters.py` keys its host translation on the exact string
-`--host claude`, and the stamp sites are compared byte-for-byte, so it is the one token in
-that line that is not a placeholder.
+deliberate — `scripts/build-adapters.py` keys its host translation on the exact canon
+value of that flag, and the stamp sites are compared byte-for-byte, so it is the one token
+in that line that is not a placeholder.
 
 ## Host and capability determination
 
@@ -110,12 +110,13 @@ Before the call, compute the two inputs independently. They are unrelated: **a h
 implies a capability**, and the script takes `--verify-capability` at face value.
 
 **`--host`** describes only the active adapter command surface — `claude`, `pi`, or
-`generic`. It selects command syntax (`/feature-forge:` vs `/skill:` vs host-neutral) and
-fresh-session wording (`/clear` vs `/new` vs neutral prose). Nothing else.
+`generic`. It selects command syntax (Claude's stage-command prefix vs Pi's `/skill:` vs
+host-neutral) and fresh-session wording (Claude's clear command vs Pi's `/new` vs neutral
+prose). Nothing else.
 
 **`--verify-capability interactive`** is passed only when **both** of these hold:
 
-- **(a)** a question mechanism equivalent to `AskUserQuestion` is available, **and**
+- **(a)** a question mechanism equivalent to the host's question mechanism is available, **and**
 - **(b)** a clean-room `forge-verifier` subagent can be dispatched.
 
 If either is absent, or capability cannot be established, pass `manual`.
@@ -151,7 +152,8 @@ production successor** while verification is unresolved.
 - a capable Pi session is `--host pi --verify-capability interactive`, and receives the
   same logical gate a capable Claude session does;
 - Pi without a dispatchable verifier is `--host pi --verify-capability manual`;
-- a Claude session that cannot dispatch is `--host claude --verify-capability manual`.
+- a Claude session that cannot dispatch keeps the Claude host value with
+  `--verify-capability manual`.
 
 Interactive gate options keep their explicit labels, their recommended default, and their
 one-line trade-off descriptions (below). The manual path prints the verify command as the
@@ -199,6 +201,44 @@ second sentinel-terminated block **inside** an outer stage's exit, breaking the
 exactly-one-terminal-block rule — and the canon guard cannot catch it, because both
 wordings legitimately appear in the same file. Judge the token, not the phrasing.
 
+## Caller-side resumption: the declared resume point
+
+The `owner:` token and `terminalOwnedBy` arbitrate who prints — but they specify only
+the **callee** side: a nested skill stays quiet and returns its structured result. This
+section is the reciprocal, caller-side half of that contract.
+
+**On a sub-skill's return, the caller re-owns the terminal.** Every closing instruction
+in the callee's own body — its report-and-stop posture, its "confirm the result" close,
+its own next-steps habits — is void for this turn. The caller resumes at its **declared
+resume point**, in the same turn, and its remaining steps run to its own terminal.
+
+**Every Skill-tool delegation site declares, at the invocation, what happens on
+return.** Suppression without resumption is the failure mode this section closes: the
+callee's closing posture is the freshest instruction in context while the caller's next
+step is the oldest, so an undeclared return silently ends the run one layer too early —
+the caller's remaining steps (validation, state writes, commit, stage exit) dropped,
+with no error surfaced. An implicit "let it run to its natural stopping point" is that
+bug spelled politely, and it is banned on delegation sites. A site takes one of two
+declared postures:
+
+- **Delegate-and-resume** — the callee is a sub-step of the caller: the site names the
+  caller's own step that control returns to, and the caller continues there in the same
+  turn. The callee never owns the caller's terminal. The worked instance is
+  `forge-4-backlog` Step 4's **Return contract** for the `author-backlog` delegation
+  (control returns at Step 5; the sub-skill's direct-invocation posture — its approval
+  gate and its validate-and-confirm close — is explicitly disapplied on the delegated
+  path). New delegation sites follow that pattern rather than re-deriving it.
+- **Terminal handoff** — the caller's job ends at the invocation and the invoked skill
+  owns the terminal from there on (e.g. the navigator's `autoInvokeNextStage`
+  "continue in this session" advance into the next production stage). Declaring the
+  handoff is what keeps it distinct from an accidental drop.
+
+Scope: this contract governs **Skill-tool delegation within one session**. The
+truncated-verifier-return guard (forge-verify's `findings-template.md`, "Truncated
+Verifier Returns") is a different mechanism — it polices what an **Agent-dispatched
+subagent's** return payload must contain, not where a caller resumes. A dispatch site
+can be subject to both; satisfy each on its own terms.
+
 ## Directive consumption order
 
 `stage-exit` emits a DIRECTIVES object and (for a direct owner) a NEXT-STEPS block. The
@@ -243,7 +283,7 @@ reformat, merge, or summarize them, and never dump the state file they were deri
 
 Auto-verify is effective for this stage and verification is outstanding — verify **now,
 in this session** (principle #2 applied to auto-verify: the digest and any fix decision
-land here, where the authoring context still exists — not deferred to a post-`/clear`
+land here, where the authoring context still exists — not deferred to a post-clear
 navigator). The `auto-verify-pending` debt is already durable on disk at this point, so a
 declined or deferred gate leaves recorded debt rather than a silent pass.
 
@@ -252,7 +292,7 @@ declined or deferred gate leaves recorded debt rather than a silent pass.
    same path the navigator uses (`skills/forge-verify/SKILL.md`). Dispatch it
    **synchronously and await its digest inline** — do **not** run it in the background or
    announce it as "still running"; the digest and any fix decision must land in this
-   session. It inherits none of this session's context, so no `/clear` is needed and only
+   session. It inherits none of this session's context, so no session clear is needed and only
    a compact digest returns.
    **If you may not dispatch unsolicited**, present the consent form of the Standard
    Verify Gate first and dispatch on the affirmative choice — see "Consent variant on a
@@ -299,7 +339,11 @@ first:
   a stage's artifact commit.
 - **Skip for now** — go straight to the NEXT-STEPS block without verifying. Record this
   stage's verify status as `skipped` in pipeline state (via `state-verify`, never by hand)
-  **only** on an explicit skip — a skip does not go stale.
+  **only** on an explicit skip — a skip does not go stale. Exception: if the existing
+  entry records `passed` or `findings-applied` (a resolved result whose freshness has
+  merely lapsed), write **nothing** — `state-verify` refuses to demote a resolved status
+  to `skipped` (#203), and the recorded result stands on its own; the user's decline is
+  honored by simply not re-verifying.
 
 **Advancement is allowed only after a pass, or after an explicit skip has been
 persisted.** Choosing to stop, or losing the interaction, produces no advancing terminal
@@ -358,8 +402,8 @@ directive is informational — you do **not** re-derive the wording:
   unchanged; the block appends a non-blocking reminder line ("You also flagged N epic
   change(s) to reconcile when convenient …"). This is *finish-then-edit*.
 
-Either way the added lines are host-neutral (no literal `/clear`) and sit **above** the
-sentinel; just print the NEXT-STEPS block verbatim as always.
+Either way the added lines are host-neutral (they name no fresh-session command) and sit
+**above** the sentinel; just print the NEXT-STEPS block verbatim as always.
 
 ### Deferred decisions — do not solicit next-stage decisions at this exit
 
@@ -376,7 +420,7 @@ a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by runnin
 epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
 
 ```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/forge-session.py" state-decision \
   --feature "{feature}" --question "<phrased for the target stage>" \

package/adapters/codex/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.
 
@@ -205,7 +209,7 @@ After a successful **edit-mode mutation** — the mutator returned exit `0` **an
 **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 "${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
 ```

package/adapters/codex/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/codex/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,6 +165,38 @@
         }
       }
     },
+    "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"],