@garygentry/feature-forge 0.3.6 → 0.3.7

package/adapters/cursor/skills/forge-5-loop/references/preflight-and-self-heal.md

@@ -0,0 +1,183 @@
+# Preflight & Self-Heal Procedure
+
+The named procedure that turns "the environment is missing/stale/misconfigured" into a
+clear stop or a scripted, consented repair — instead of a cryptic mid-run failure or a
+silent unasked mutation. It runs whenever a skill gates on `doctor`'s structured
+`checks[]` (`roadmap/self-healing-resilience.md` §5.2); today that is `forge-5-loop`'s
+gates 1c/1d (`skills/forge-5-loop/SKILL.md`), which resolve the loop runner **before**
+touching it, `forge-init`'s install preflight (`skills/forge-init/SKILL.md`), where
+neither check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
+operator-facing repair surface, which gates nothing at all. All three are callers, not
+the procedure's scope: any skill that gates on `checks[]` follows it in full. Its seven
+ordered steps: **enumerate → cluster → consolidated prompts → record → apply → prove →
+return**.
+
+## 1. Scope and the failure rule
+
+**Input contract:** the caller has already run `doctor --json` narrowed to the `--check`
+ids it cares about (never the full catalog inside a hard gate — an advisory check must
+never block a launch it has no bearing on) and hands this procedure that call's `checks[]`
+and `remedyClusters[]`. The procedure orchestrates that data; it never re-derives it and
+never invents a remedy `doctor` did not emit (INV-4).
+
+**The failure rule (applies to every step).** `doctor` itself never exits non-zero and
+never raises (INV-3) — there is no non-zero exit to catch here. What *can* fail is a
+remedy command: any remedy invocation that exits non-zero, times out, or produces
+output the re-run in step 6 cannot confirm is surfaced **verbatim** and **STOPS** the
+procedure with a **failed preflight** report — never reported as healed. This applies the
+post-run recovery procedure's failure rule, narrowed to remedies (preflight has no
+runner-answer/unblock apply mechanism of its own).
+
+## 2. The seven steps
+
+### Step 1 — Enumerate
+
+- **Input:** the caller's `doctor --json` result (§1).
+- **Decision point:** if every requested check is `ok` or `na`, there is nothing to
+  cluster, prompt, apply, or prove: **skip steps 2–6 and return `ok` with no output and
+  no prompt** (INV-2 — a fully healthy project produces zero new preflight text). This is
+  the only step whose outcome the caller checks before calling the rest of the
+  procedure at all.
+- **Output:** the affected `checks[]` subset (`status` is `warn` or `fail`) with each
+  entry's `remedy` and `severity`.
+
+### Step 2 — Cluster
+
+- **Input:** the affected checks from step 1.
+- **Mechanism:** `remedyClusters[]`, already computed by `doctor_report` (pure
+  `cluster_checks`, `scripts/forge-session.py`) — group by identical `remedy.command`,
+  most-conservative `safety` wins the merge, `remedy: null` checks are **not** clustered
+  (report-only, no prompt to build). Reuse it as-is; do not re-cluster by hand.
+- **Output:** the final cluster set — one entry per distinct runnable remedy, each
+  carrying its `checkIds[]`, `command`, `safety`, and `description` — plus the
+  report-only set (affected checks with no `remedy` or no `remedy.command`).
+
+### Step 3 — Consolidated prompts
+
+- **Input:** the cluster set from step 2.
+- **Mechanism:** one question per cluster (never one per check) via host's question mechanism
+  (rung 1/2) or the ladder's rung-3 default (§4). Name the **exact remedy command**, its
+  **safety tier**, and **every member check id** the cluster covers — e.g. *"`runner-wired`
+  and `runner-legacy-layout` both resolve by running `{bin} migrate .` (local-write).
+  Run it?"*
+- **Per the safety ladder** (`references/shared-conventions.md` § Remedy Safety Ladder):
+  a `read-only` cluster is never prompted (run it and move to step 5); `local-write` asks
+  **once per remedy class per session** — re-affirming the same `remedy.command` string a
+  second time in the same session skips straight to apply; `global-install`/`network` are
+  **never** prompted for execution — surface them as report-only advice (§5's
+  advise-only path) even though `doctor` clustered them.
+- **Report-only set — three shapes, all print once, plainly, with no question:** checks
+  with no `remedy` at all (a corrupt manifest, an unresolvable config); a `remedy` whose
+  `command` is `null` (reinstall-only or config-edit advice with nothing to run — never
+  clustered, since `cluster_checks` skips these); and a `global-install`/`network`
+  remedy (clustered by `doctor`, but never prompted for execution here).
+- **Output:** per cluster, one of {approved, declined, advise-only (tier forbids
+  execution), unaskable→advise-only (genuinely no way to ask and wait, §4)}.
+
+### Step 4 — Record
+
+- **Input:** every outcome from step 3.
+- **Mechanism:** **output only** — a `preflight:` line per cluster, e.g.
+  `preflight: runner-wired,runner-legacy-layout → {bin} migrate . [local-write] — approved+run`.
+  The five outcome tokens are `run` (read-only, no prompt needed), `approved+run`,
+  `declined`, `advise-only` (tier forbids execution — includes the report-only,
+  null-command shape from §2 step 3), `unaskable→advise-only` (rung 3, no default
+  permits the write). **The backlog's item-keyed decision record** (the durable
+  store post-run recovery uses to survive a session boundary) **is NOT used here** — a
+  preflight remedy is environment repair, not a backlog decision, and writing one there
+  would durably attribute an environment fix to a backlog item that never asked for it.
+- **Output:** the stated line, printed before step 5 acts on anything.
+
+### Step 5 — Apply
+
+- **Input:** every cluster whose step-4 outcome is `run` or `approved+run`.
+- **Mechanism:** run `remedy.command` **verbatim** — never edited, never re-templated.
+  `doctor` already rendered every token (`{bin}`, paths) into the command string; the
+  procedure's only job is to execute exactly what was clustered.
+- **Error:** a remedy that exits non-zero, times out, or cannot be run at all (binary
+  vanished between the check and the apply) is surfaced verbatim and **STOPS** the
+  procedure — **failed preflight**, per §1. Declined and advise-only clusters are not
+  applied at all; they proceed straight to step 7's report.
+
+### Step 6 — Prove
+
+- **Input:** every cluster step 5 actually applied.
+- **Mechanism:** re-run the **identical** `doctor --json` invocation the caller made in
+  §1 (same `--check` ids, same flags) and re-read the member check ids' `status`.
+- **Decision point:** **every** member check now `ok` → the cluster is healed, continue.
+  **Any** member still `warn`/`fail` — including a partial move where some member ids
+  flipped and others did not — is a **failed preflight**: report it, naming the healed and
+  still-failing check ids from this re-read, never from the first run's stale statuses.
+  A remedy that ran but did not prove is a failure, not a partial success — the
+  ran-but-nothing-moved shape the post-run recovery procedure also treats as a failure.
+- **Output:** either "all affected checks now `ok` → return" or a failed-preflight report.
+
+### Step 7 — Return
+
+- Return the final per-check statuses (post-prove where a remedy ran, original where
+  declined/advise-only/report-only) to the caller. The procedure never selects the
+  caller's own gate outcome — `forge-5-loop`'s 1c/1d decide HARD GATE FAILURE vs. STOP vs.
+  proceed from these statuses; this reference only guarantees the statuses it returns are
+  either the original `doctor` read (nothing was touched) or a freshly proven re-read
+  (§6) — never a claim this procedure did not verify.
+
+## 3. Safety ladder (pointer)
+
+Every apply/prompt decision above is gated by the four-tier ladder declared once in
+`references/shared-conventions.md` § Remedy Safety Ladder — `read-only` / `local-write` /
+`global-install` / `network`. This reference never restates the tiers; it only names
+which step consults them (§2 steps 3 and 5).
+
+## 4. Rung-3 default
+
+This is the **preflight remedies** class of the canonical Interaction Capability Ladder
+(`references/shared-conventions.md` § Interaction Capability Ladder) — "cannot be asked"
+(§2 step 3) means rung 3: genuinely **no way to ask and wait for a reply at all**, neither
+a structured question tool NOR plain prose with a wait for the answer. It is **not** the
+same as "no structured tool": a host that lacks a structured tool but can still prompt in
+prose and wait (an interactive Codex session, per its own turn-taking rules) is rung 2,
+not rung 3, and Step 3 asks it that way. Rung 3 fires only for a genuinely non-interactive
+invocation (a headless `-p`/`exec`/JSON-mode run with no reply channel). Such a session
+follows the ladder's declared default via the safety ladder's own rule: **degrade one
+tier stricter** — a `local-write` cluster that cannot be asked is treated as
+`advise-only` (print the command, never run it), and the outcome is recorded as
+`unaskable→advise-only` (§2 step 4). Never silently skip the report, and never take an
+unasked write as implied consent.
+
+## 5. Message shapes
+
+- **`runner-binary` / `runner-version` not `ok`** (blocking, no remedy proven) — **HARD
+  GATE FAILURE**: STOP, do not proceed to run the loop, show the failing check's own
+  `remedy.description` (and `remedy.command` when set) plus its raw `detail`/`evidence`
+  for diagnosis. **Never substitute `loopRunner.installHint` for this** — three of
+  `runner-binary`'s four warn shapes and one of `runner-version`'s are a **config fix**
+  (a customized `bin` missing while the default is on PATH points at the config, not the
+  install — G4), and `installHint` only ever describes installing the default package.
+  When the remedy's `command` is `null` (a reinstall-only or config-edit instruction),
+  there is nothing to cluster or apply — print the `remedy.description` as report-only
+  advice (§2 step 3's report-only set) and STOP regardless.
+- **`runner-legacy-layout` warn** — STOP: *"This project is still on the legacy **Ralph**
+  layout. Run {check's `remedy.command`, e.g. `{bin} migrate .`} first (the loop runner
+  only understands `.rauf/` and `RAUF_*` signals), then re-run
+  `forge-5-loop {feature}`."* Use the check's own `remedy.command` — never
+  a hardcoded `rauf migrate .` — a customized `loopRunner.bin` changes the binary name.
+- **`runner-wired` warn** — STOP and show `loopRunner.setupHint`, e.g. *"The loop runner
+  isn't set up in this project ({preconditionFile} is missing). {setupHint}"*.
+- A STOP lifts **only** after a permitted `local-write` remedy ran (§2 step 5) **and**
+  the re-run (§2 step 6) shows the gating check `ok` — never on the remedy's exit code
+  alone.
+
+## 6. Failure taxonomy
+
+| Failure | When it occurs | Reaches step 6's per-check test? | Report |
+|---|---|---|---|
+| **Failed apply** | A `run`/`approved+run` remedy exits non-zero, times out, or cannot start | No — stops before the test | Verbatim command output + which cluster; **failed preflight**; procedure stops |
+| **Ran-but-not-healed** | The remedy exited 0, but the re-run still shows `warn`/`fail` for a member check | Yes — is the test failing | Healed/still-failing check ids named from the re-read; **failed preflight** |
+| **Declined / advise-only / unaskable** | The operator declined, the tier forbids execution, or the session genuinely had no way to ask and wait (§4) | N/A — no apply attempted | Reported per §2 step 4; **not** a failure — the original `doctor` statuses stand, and the caller's gate (§2 step 7) still applies to them |
+
+Rules: never report healed/succeeded past a failed step; a failed apply stops before the
+per-check test, so a remedy that errored is never conflated with one that ran cleanly but
+fixed nothing; a declined/advise-only/unaskable cluster is a normal outcome, not a
+procedure failure — the caller's own gate still decides what an unhealed `warn`/`fail`
+means for it (a blocking check stays a hard gate failure; an advisory one is just
+reported).

package/adapters/cursor/skills/forge-5-loop/references/recovery-procedure.md

@@ -77,7 +77,11 @@ ran-but-nothing-moved *proof* failure (step 6) because the former never reaches
 ### Step 3 — Consolidated prompts
 
 - **Input:** the final cluster set from step 2.
-- **Mechanism:** the host's question mechanism (never inline prose).
+- **Rung-3 default** (`references/shared-conventions.md` § Interaction Capability Ladder,
+  "recovery interview" class): no question mechanism → fall through to **needs-human** —
+  every cluster in the set is recorded as a deferral (never answered, never cancelled) and
+  step 4 states the rung-3 statement once for the whole batch.
+- **Mechanism:** host's question mechanism (never inline prose).
   - For any cluster of **two or more** items: emit **exactly one** consolidated question
     that **names every affected item id** and states the **full gated subtree** the
     cluster gates. Frame it by **blast radius** — e.g. *"This one decision gates 13 of
@@ -198,7 +202,7 @@ ran-but-nothing-moved *proof* failure (step 6) because the former never reaches
   branch its own recovery just cleared. **Any one gate failing falls the ladder
   through** to `needs-human` / `blocked` / `deferred` / `partial` / `complete` exactly
   as today. `resolved` routes **resume** — its NEXT-STEPS block fences
-  `/feature-forge:forge-5-loop {feature}`, never the navigator.
+  `forge-5-loop {feature}`, never the navigator.
 - **CLI:** the close runs through the Scripted Stage Exit (SKILL Step 7):
   `stage-exit … --outcome resolved …`. `stage-exit` does **not** re-verify the gate
   server-side (it has no runner access) — enforcement is procedural: this step.
@@ -277,13 +281,19 @@ runner-native evidence — reliable per-item provenance is **not** a prerequisit
 
 ### 4.3 Decide
 
-- **Mechanism:** the host's question mechanism (never inline prose).
+- **Rung-3 default** (`references/shared-conventions.md` § Interaction Capability Ladder,
+  "destructive confirmations" class): no question mechanism → **never mutate** — run
+  no `git` command against the tree at all (`stash` is itself a write); leave every
+  item-group and the unattributable set exactly as found, state the rung-3 default
+  once for the whole reconciliation, and rely on §4.4's Launch Blocker to stop the
+  next launch on the still-dirty tree until a human resolves it.
+- **Mechanism:** host's question mechanism (never inline prose).
   - **One question per attributed item-group:** for each candidate item-group from 4.2,
     offer **commit-for-that-item** / **stash** / **discard**.
   - **Unattributable changes → ONE consolidated decision:** everything that could not
     be attributed is presented as a single grouped question, not dropped.
 - **Discard guard:** **discard is NEVER the default** and requires its **own explicit
-  confirmation** — a second, dedicated question via the host's question mechanism confirming the specific paths
+  confirmation** — a second, dedicated question via host's question mechanism confirming the specific paths
   to be discarded before any `git checkout`/`git restore`/`git clean` runs. No path is
   discarded on a single click.
 - **Output:** per group, an executed reconciliation (commit / stash / confirmed

package/adapters/cursor/skills/forge-5-loop/references/runner-contract.md

@@ -31,9 +31,13 @@ pass after all iterations complete (an extra agent session that re-examines the
 finished work and can file follow-up backlog items). feature-forge treats **running
 with review as the recommended default** — a review pass is cheap relative to the
 loop it audits, and catches gaps before the pipeline moves on to docs. So Step 2d
-adds a **"Run mode"** question, via the host's question mechanism, to the confirmation surface with a
+adds a **"Run mode"** question, via host's question mechanism, to the confirmation surface with a
 **fixed, non-improvised option order** (determinism is the point — the option set
-must not vary run-to-run):
+must not vary run-to-run). **Rung-3 default**
+(`references/shared-conventions.md` § Interaction Capability Ladder, "launch / run-mode"
+class): no question mechanism → **STOP** — print the fully rendered command (option 1's
+`--review` included) and do not launch; the `[DEFAULT]` marker below selects the
+option's place in a live prompt, never an unattended launch:
 
 ```
 Run mode:
@@ -65,7 +69,7 @@ Notes:
 - **Option 1 is the default** and the confirmation's rendered command line shows
   `--review` appended. On any pick, append the option's flags to the rendered run
   command before Step 3 (launch).
-- **the host's question mechanism's built-in "Other"** already lets the user type ad-hoc flags
+- **host's question mechanism's built-in "Other"** already lets the user type ad-hoc flags
   (`--model <model>`, `--timeout <min>`, or any combination) — do **not** add a
   separate open-ended option for that.
 - **Option 3 is conditional.** Include it only when the Step 2a tally has `blocked
@@ -116,7 +120,7 @@ a descriptor on the file the runner immediately rotates away, so the redirected
 rotation timing. So:
 
 - **Self-persisting runner (default — rauf writes `{stateDir}/events.ndjson`):**
-  launch the **plain `runCommand`** with the host's background-execution mechanism and **no
+  launch the **plain `runCommand`** with host's background-execution mechanism: true and **no
   redirect** — the Bash tool already captures the run's stdout/stderr to the
   background task's output file (use it to diagnose a launch refusal). Supervise by
   arming the Monitor on the runner's **native** `{backlogDir}/{stateDir}/events.ndjson`
@@ -143,7 +147,7 @@ backlog size).
 ## Arm a Monitor on the event stream (Step 3d)
 
 Arm the **host's monitoring mechanism** on the structured event stream so events flow back into
-this session as they happen. Use **`persistent: true`** — runs can exceed the host's monitoring mechanism's
+this session as they happen. Use **`persistent: true`** — runs can exceed host's monitoring mechanism's
 maximum `timeout_ms` (1 hour), and a bounded timeout would silently stop watching a
 still-running loop.
 
@@ -192,7 +196,7 @@ high and the noise low:
   immediately** and send a **`PushNotification`** (an hours-long run means the user has
   likely stepped away). **Important — the loop is NOT paused:** the runner has set that
   item aside and kept working other items. So report *what* needs a human and *which*
-  item, then either (a) collect the user's answer via the host's question mechanism and **record it via
+  item, then either (a) collect the user's answer via host's question mechanism and **record it via
   `decision-record` now** — SKILL Step 4c's unconditional **Post-Run Recovery Procedure**
   pass (`references/recovery-procedure.md`) applies it after the run ends — or (b) offer
   to **cancel the run early** (also recorded via `decision-record` — a deferral) if the
@@ -229,13 +233,16 @@ Step 3c's instruction, relocated verbatim from the SKILL body:
 This is the verbatim "Loop started…" output the session shows the user after
 launch. Commands are the rendered `loopRunner` monitoring commands.
 
+**Verification-coverage line (always shown).** Before rendering the template, scan the backlog's **active** items (status `pending` or `in_progress` — the items this run implements) and classify each item's `acceptanceCriteria`. Read each item's full record — **including its `acceptanceCriteria`** — from the backlog **file** resolved at Step 1e; classify against that file, **never** the Step 2a list-command output, which counts items by status and does **not** surface `acceptanceCriteria` (classifying against the list output would find zero gate-shaped criteria on every item and emit a false gap scare). An acceptance criterion is **gate-shaped** when it asserts that a *runnable* verification gate passes — it names an executable check the loop can run to completion (one of the project's configured verify commands in `forge.config.json` — `typeCheckCommand` / `testCommand` / `smokeCommand` — or a bare invocation of the same class of tool: `bash scripts/verify.sh <gate>`, `pytest`, `ruff`, `tsc`, `npm test`, any lint/format/typecheck/test/smoke runner) **and** asserts a success outcome (`… passes` / `… succeeds` / `exits 0` / `is green`). A prose assertion about resulting code or file state (e.g. "X is derived from Y", "the schema requires an integer ≥ 1") is **not** gate-shaped even when a test would cover it — it describes an outcome, not a gate the loop runs. An item is **covered** when at least one of its criteria is gate-shaped. Let `covered` = the number of active items that are covered, `active` = the total active count (always ≥ 1 — Step 2a already stopped a run with no active items), `gap` = the **number** of active items with **zero** gate-shaped criteria, and `gapIds` = those uncovered items' ids.
+
+This scan is **runner-agnostic**: it reads only the backlog feature-forge owns, never the runner's own verify profile (the `loopRunner` contract exposes commands, not a verify profile). It is emitted on **every** run at the marked position in the template below — it is context, not a gate (the loop is already launched by Step 3b, so it does not block the run). Its purpose is to give the operator the real coverage picture and to defuse a benign runner warning like rauf's "No verification commands detected — RAUF.md will tell the agent to skip verification entirely": on a forge loop the coverage is the per-item acceptance criteria (plus the `--review` pass **when this run enabled review**), so an empty runner *global* verify gate is expected here, not a regression. Render the first coverage line unconditionally; render the `⚠ … gap` line only when `gap` > 0, naming `gapIds` so a real gate-coverage gap (items forge-4-backlog left without runnable criteria) surfaces as a specific signal rather than a blanket scare. The bracketed `[… `--review` pass]` clauses in the template are rendered **only when this run enabled review** (the Step 2d run mode / `loopRunner.reviewMode` resolved to a review run); drop each bracketed clause entirely on a no-review run so the line never claims a review pass that will not happen.
+
 When the agent surface is gated on (`loopRunner.agentArgument` present), add the
 `Coding agent:` line shown below immediately after the opening `Loop started …`
 line, using the same `sourceLabel` mapping as the Step 2d confirmation
 (`RUN` → `"per-run selection"`, `PROJECT` →
 `"project default (loopRunner.defaultAgent)"`, `DEFAULT` →
-`"runner default — claude-cli"`). When the gate is off, the line is **absent** and
-the template is byte-identical to today (REQ-PLUG-02). When the launch proceeded via
+`"runner default — claude-cli"`). When the gate is off, the `Coding agent:` line is **absent** — the agent gate contributes nothing to the template when off (REQ-PLUG-02); the always-shown verification-coverage line below is orthogonal to the gate and unaffected by it. When the launch proceeded via
 the UNAVAILABLE *proceed-anyway* path, use the audit variant instead:
 
 ```
@@ -254,6 +261,9 @@ This session is now monitoring it live — I'll report milestones and stop you i
 the loop needs a human. The loop also runs detached and survives this session ending.
 Each item gets a fresh agent session with full context from the backlog and specs.
 
+Verification coverage (item-level): {covered}/{active} active items carry a gate-shaped acceptance criterion (a runnable format / lint / typecheck / test / smoke gate). A forge loop verifies per item — these criteria [plus the `--review` pass] are the coverage, so an empty runner global verify gate (e.g. rauf's "No verification commands detected") is expected here, not a regression.
+⚠ {gap} active item(s) carry NO gate-shaped criterion — this run will implement them without a runnable gate, leaning on a later `forge-verify … impl` [and the `--review` pass]: {gapIds}.   # only when gap > 0
+
 Watch directly if you like (another terminal or `!` prefix):
   {rendered statusCommand}              # one-shot status
   {rendered followCommand}              # stream live events (human)