@garygentry/feature-forge 0.3.5 → 0.3.7

package/adapters/pi/skills/forge-6-docs/references/stage-exit-protocol.md

@@ -90,7 +90,7 @@ 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 "${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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host pi --verify-capability "{verify-capability}"
 ```
@@ -119,7 +119,12 @@ prose). Nothing else.
 - **(a)** a question mechanism equivalent to `AskUserQuestion` is available, **and**
 - **(b)** a clean-room `forge-verifier` subagent can be dispatched.
 
-If either is absent, or capability cannot be established, pass `manual`.
+If either is absent, or capability cannot be established, pass `manual`. **(a) is rung 1 or
+rung 2** of the Interaction Capability Ladder (`references/shared-conventions.md`); at
+rung 3, (a) is false by definition, so `--verify-capability manual` follows without
+further deliberation — the ladder's "verify-capability determination" class states this
+rung-3 default once
+so it is never re-derived per stage.
 
 **(b) tests PERMISSION, not tool presence.** The question is not "is a subagent-dispatch
 tool listed in my tool surface" but "**may I dispatch `forge-verifier` right now**". A
@@ -420,7 +425,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 "${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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" state-decision \
   --feature "{feature}" --question "<phrased for the target stage>" \
@@ -440,7 +445,17 @@ sentinel `─ forge: end of stage ─`, as the **final line** of `nextSteps`. Pr
 **verbatim as your absolute last output**. Nothing follows the sentinel — no summary, no
 sign-off, no warning, no command result, no acceptance text, no caveat. The block already
 carries the fresh-session recommendation (host-aware wording via `--host`) and the exact
-next command, so trailing prose can only push the user's next action out of view.
+next command — or, at the one terminal state below, the statement that there is none — so
+trailing prose can only push the user's next action out of view.
+
+**A finished epic ends the pipeline, and its block fences nothing.** When
+`primaryCommand` is `null` (`nextCommand` and `nextStage` are `null` too), the epic is
+complete — every member done, or the manifest set to `status: "complete"` — and there is no
+next command at all. Print the block exactly as you would any other; do **not** substitute a
+command, promote `nextCommand`, or append your own "you could now run…" list. The block's own
+prose already names the optional follow-ons (start a new feature, re-open the dashboard to
+inspect state) as inline offers rather than instructions. Re-fencing the epic dashboard here
+is the specific defect this state exists to prevent: running it lands back on this same exit.
 
 **A nested payload** (`terminalOwnedBy: "outer"`) carries `nextSteps: null` and
 `sentinel: null`. It prints **no terminal block at all** — not even an empty one. Return

package/adapters/pi/skills/forge-6-docs/references/verify-state.md

@@ -0,0 +1,98 @@
+# `verify-state` — deterministic upstream-verification classification
+
+`forge-4-backlog`, `forge-5-loop` and `forge-6-docs` each open by reading a served
+stage's `stages.forge-verify-*` entry to answer one question — *has the upstream
+artifact been verified, and what do I say if not?* Each answered it with its own
+hand-rolled branch set: forge-4-backlog a binary verified/not check, forge-5-loop
+four cases, forge-6-docs five. `forge-session.py verify-state` derives that answer
+from the authoritative on-disk entry instead — one case enum, one message table,
+the same "never eyeball the graph" move `select-outcome` makes for the exit outcome
+(issue #277, part of the #265 guard-first program).
+
+The verb reads, never writes. It reads the **raw** `forge-verify-{token}` status the
+gates key on — it does **not** apply the version-aware freshness `verify_state()`
+computes for the navigator's most-recent-stage gate. A `passed` entry classifies
+`passed` regardless of the stage version, because that is exactly what the gates read
+today; layering re-verify-on-revision onto them would be a behaviour change, not an
+additive one.
+
+## Synopsis
+
+```
+python3 forge-session.py verify-state \
+  --feature F --for-stage S [--specs-dir DIR] [--epic E] [--json]
+```
+
+`--for-stage` is one of the five verify-token production stages (`forge-1-prd`,
+`forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`) — the stage whose
+`forge-verify-{token}` entry is classified. `forge-0-epic` (verification lives in
+`.epic-state.json`) and `forge-6-docs` (no verify token) are **out of scope** and
+rejected at parse time.
+
+Output — always `{case, verified, stale, message, nextCommand}`:
+
+```json
+{
+  "case": "findings-applied",
+  "verified": false,
+  "stale": true,
+  "message": "Fixes were applied to auth's forge-4-backlog but nothing re-verified them; re-verification is still outstanding — run /skill:forge-verify auth backlog.",
+  "nextCommand": "/skill:forge-verify auth backlog"
+}
+```
+
+- **`case`** — one `VerifyStateCase`, the union of the cases the three gates spell out.
+- **`verified`** — `true` only for `passed`. An explicit `skipped` is resolved but *not*
+  verified, so it is `false`.
+- **`stale`** — `true` only for `findings-applied`: fixes landed but nothing re-verified
+  them, so a re-verify is still owed.
+- **`message`** — the single canonical operator sentence for the case.
+- **`nextCommand`** — the forge-verify retry for every unresolved case; `null` for
+  `passed`, which needs no action.
+
+## The case enum
+
+`VerifyStateCase` is the union of the raw `forge-verify-*` statuses the three gates
+key on, plus `never` for the absent / `pending` / unrecognized bucket every gate
+folds into "not verified". `tests/test_verify_state.py` pins the enum to the
+enumerating gate bodies, both directions, so a gate cannot grow a seventh case or
+spell an existing one differently.
+
+| `case` | on-disk status | `verified` | `stale` | meaning |
+| --- | --- | :---: | :---: | --- |
+| `passed` | `passed` | ✓ | | verification passed — proceed |
+| `findings-reported` | `findings-reported` | | | blocking findings live and unresolved |
+| `findings-applied` | `findings-applied` | | ✓ | fixes applied, re-verify still owed |
+| `auto-verify-pending` | `auto-verify-pending` | | | scheduled automatic verification, owed but unrun |
+| `skipped` | `skipped` | | | user explicitly proceeded without verifying |
+| `never` | absent / `pending` / unrecognized | | | never verified |
+
+## Classification
+
+The status ordering mirrors `verify_state()` — an explicit `skipped` and recorded
+`auto-verify-pending` debt are tested **before** the generic bucket, so neither can
+fall through to `never`:
+
+1. `skipped` → **skipped**.
+2. `auto-verify-pending` → **auto-verify-pending**. Unusable scheduling metadata
+   (missing/malformed `scheduledStageVersion`) warns once (REQ-DEBT-02) but the debt
+   stays owed — degrading it to `never` is exactly the conflation that requirement
+   forbids.
+3. `findings-reported` → **findings-reported**.
+4. `findings-applied` → **findings-applied**.
+5. `passed` → **passed**.
+6. anything else (absent, `pending`, or an out-of-vocabulary status) → **never**. A
+   present-but-unrecognized status is flagged once (#148) then treated as unverified,
+   the same answer an absent entry gets; a known `pending` (or an absent entry) is
+   quiet.
+
+A missing, unreadable, or torn state file never raises — the entry reads as absent
+and classifies `never`, the same fail-safe the three gates take.
+
+## Messages
+
+`VERIFY_STATE_MESSAGES` holds one canonical sentence per case; the `auto-verify-pending`
+case reuses `AUTO_PENDING_DIAGNOSTIC` — the single normative owed-debt sentence every
+read-side emitter already shares — and appends the revision-advance clause when the
+recorded schedule predates the current artifact. `{subject}` is the feature (or epic
+member), `{stage}` the served production stage, `{command}` the forge-verify retry.

package/adapters/pi/skills/forge-bootstrap/SKILL.md

@@ -21,14 +21,17 @@ toolchain-missing.
 
 ## Host adaptation (conversational fallback)
 
-If the `AskUserQuestion` tool is available, ask the interview questions through it. If it is
+If the `AskUserQuestion` is available, ask the interview questions through it. If it is
 **not** available (a non-Claude host such as Codex), emit the same questions as a single
 **numbered text list** — each line one question with its options in brackets and the default
 marked — then **stop and wait for a single text reply**. Parse the reply positionally
 (answer N → question N); re-prompt only the unparseable items. The question content (text,
 options, defaults) and the conditional gating (Q4 skipped for go/rust/generic; Q6a only for
 monorepo; Q8 only after a verified-green baseline) are **identical** across both paths — only
-the rendering changes. Never assume answers; always wait for the reply.
+the rendering changes. Never assume answers; always wait for the reply. At rung 3
+(genuinely non-interactive — Interaction Capability Ladder, `references/shared-conventions.md`),
+this interview has no sane unattended default: `no-default: abort — the bootstrap interview
+requires a human answer`.
 
 Emit any context as plain text, then route **all** questions through `AskUserQuestion` (or the
 fallback) — never as inline prose questions, which stall the session.
@@ -58,7 +61,7 @@ Every bash invocation begins with the byte-identical portable-root prelude, then
 helper. Pass `--specs-dir ./specs` (the default) so the gate allow-lists the specs directory.
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-bootstrap.py" check "<target-dir>" --json --specs-dir ./specs
 ```
@@ -129,13 +132,18 @@ it null.
 `layout`, `license`, `members[]`, `modeB`, `modeBTarget`, `ci`, `commitStyle`, `author`,
 `host` — and pass it verbatim to `scaffold --answers '<json>'`. Invent no fields beyond that
 schema. Two fields come from your runtime, not the interview: `author` from `git config
-user.name` (else the project name; it is the LICENSE copyright holder), and `host` — `"claude"`
-when running under a Claude host (e.g. `AskUserQuestion` is available), else `"codex"`/`"other"`.
-`host` drives the host-conditional agent file: the helper always emits `AGENTS.md` and adds
-`CLAUDE.md` only when `host == "claude"`.
+user.name` (else the project name; it is the LICENSE copyright holder), and `host` —
+`"claude"` when you are running as Claude, else `"codex"`/`"other"`. Use your own runtime
+identity, never a capability proxy: **do not** infer `"claude"` from `AskUserQuestion`
+availability alone — Pi's compatibility extension registers it too, so an available
+question tool does not prove you are Claude specifically (host never implies, and is
+never implied by, a capability; Interaction Capability Ladder,
+`references/shared-conventions.md`). `host` drives the
+host-conditional agent file: the helper always emits `AGENTS.md` and adds `CLAUDE.md` only
+when `host == "claude"`.
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-bootstrap.py" scaffold "<target-dir>" --json --answers '<Answers JSON>'
 ```
@@ -143,7 +151,7 @@ python3 "$R/scripts/forge-bootstrap.py" scaffold "<target-dir>" --json --answers
 ### Step 5 — verify
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-bootstrap.py" verify "<target-dir>" --json --answers '<Answers JSON>'
 ```
@@ -169,7 +177,7 @@ and removes the sentinel before staging so it never enters history. Read
 leave the sentinel in-progress (resumable) — do **not** declare success.
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-bootstrap.py" commit "<target-dir>" --json --answers '<Answers JSON>' [--stage-only]
 ```
@@ -245,6 +253,10 @@ no run ends silently:
 This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
 
 - **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
-- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **Non-interactive (`-p`/`--mode json`):** `AskUserQuestion` is stripped from the tool list, so its absence alone cannot tell you the rung — read that from the Interaction Capability Ladder's `interaction-mode` record. A call attempted anyway fails with `Error: UI not available (running in non-interactive mode)` — never read that as a decline. Take the Interaction Capability Ladder's declared conservative default, state it in your output, and use `no-default: abort — <question> requires a human answer` for an interview question with no sane default (`references/shared-conventions.md`).
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run. A **forge-invocation-args** compatibility extension wraps the arguments of a `/skill:forge-*` command in a `<feature-forge-invocation>` envelope before Pi expands it, so read the feature name from that envelope's `<arguments>` element (an empty element means none was supplied) rather than from unlabeled trailing text — see `references/shared-conventions.md` § Feature Name Requirement.
 - **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
-- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.
+- **Background / monitoring (forge-5-loop):** Pi has no built-in background bash, persistent monitor, or push-notification, so do **not** run the loop runner in the foreground and do **not** try to arm one. This bundle registers a **forge-loop-supervisor** extension that IS the "background-execution mechanism" and "monitoring mechanism" Steps 3b–3f refer to. Concretely:
+  - **Launch (Step 3b):** call **`forge_loop_launch`** with the backlog dir (and `review` / `agent` / `iterations` as resolved from config). It starts the loop **detached** — it runs in rauf's server and outlives this session — and returns immediately; you do not build or redirect a command yourself.
+  - **Supervise (Steps 3d–3f):** the extension then watches the runner's `events.ndjson` for you. It reports each completed item as one quiet line and **wakes this session automatically** on needs-human, blocked, stuck, review-failed, error, and completion — so do **not** arm a monitor, set a continuous tail, send a notification, poll, or foreground-sleep, and do not treat any manual stop as the terminal signal. When completion wakes you, go straight to Step 4 and read the authoritative counts with the status/list command. Use **`forge_loop_status`** to check progress on demand.
+  - **Stop / session end:** **`forge_loop_stop`** deliberately stops the runner; use it only when the user wants the loop to actually stop. Ending the Pi session does **not** stop the loop (it is detached), and the next session **reattaches automatically** without re-reporting what you already saw.