@gobing-ai/spur 0.3.91 → 0.3.93

package/plugins/sp/skills/dogfood-testing/references/monitor-ledger.md

@@ -1,6 +1,6 @@
 ---
 name: monitor-ledger
-description: "The dogfood monitor methodology + on-disk live ledger column contract + dual-write + token/cache estimation heuristic + the cache-health finding rule. The on-disk ledger is the single source of truth the report is assembled from — recorded live, per step, never reconstructed."
+description: "The dogfood monitor methodology + on-disk live ledger column contract + dual-write + token/cache estimation heuristic + evidence-based context-reuse observation rules. The on-disk ledger is the single source of truth the report is assembled from — recorded live, per step, never reconstructed."
 see_also:
   - dogfood-testing
   - report-template
@@ -99,14 +99,16 @@ in the report's §6 Findings (no exemption applies).
 | `Finding` | One-line finding surfaced at this step, or `—`. A finding does **not** change `Outcome`. |
 | `Fresh Tokens` | Estimated fresh context for the step. Prefix with `~`. |
 | `Cached Tokens` | Estimated reused context for the step. Prefix with `~`. |
-| `Cache %` | `Cached Tokens / (Fresh Tokens + Cached Tokens)`, rounded to the nearest whole percent. An `~unknown` row carries `—`, never `0%` — unknown basis is not an observed zero. |
+| `Cache %` | Estimated context-reuse share: `Cached Tokens / (Fresh Tokens + Cached Tokens)`, rounded to the nearest whole percent. This is a **heuristic estimate** of how much context the step reused — it is not observed provider cache behavior (task 0913, R3). An `~unknown` row carries `—`, never `0%` — unknown basis is not an observed zero. |
 | `Basis` | Observable basis for the estimate: command output, prior file read reused, generated text, etc. |
 | `Wall-clock` | Elapsed time for the step. |
 
-## Token + cache estimation heuristic
+## Token + context-reuse estimation heuristic
 
 A skill **cannot read its own exact token meter** — derive an estimate and label every number
-`~estimate`. The accepted methodology is deterministic from the ledger rows:
+`~estimate`. These chars/4 figures estimate **context volume and reuse within the driver's own
+session**; they do not measure provider cache hits, cache cost, or realized savings (task 0913,
+R3). The accepted methodology is deterministic from the ledger rows:
 
 1. Estimate **Fresh Tokens** from new material consumed or produced by the step:
    - text read from files or command output: `ceil(characters / 4)`, rounded to the nearest 100;
@@ -122,8 +124,9 @@ A skill **cannot read its own exact token meter** — derive an estimate and lab
    both sums (or surfaced as a separate unknown bucket), never folded in as `Cached ~0`:
    `aggregate cache% = round(sum(Cached Tokens) / sum(Fresh Tokens + Cached Tokens) * 100)`.
 
-The **trend across runs** is the signal, not the absolute value: rising cache% = the testee is
-reusing context efficiently; falling cache% = context bloat creeping in.
+The **trend across runs** is the signal, not the absolute value: a falling estimated reuse share
+suggests context bloat creeping in; a rising one, efficient reference reuse. Trend claims from
+estimates stay labeled as such — they never become causal waste findings on their own.
 
 > Never print a precise token number you cannot substantiate. The numbers exist to show a *trend*,
 > not to bill anyone.
@@ -169,27 +172,58 @@ missing, mark the row `~unknown`, exclude it from the aggregate (or surface it a
 bucket), and explain the missing basis — never fold it in as `Cached Tokens = ~0`: unknown cache use
 is not an observed zero-percent hit rate, and a low-cache diagnosis needs observed data.
 
-## Cache-health finding rule
-
-Cache% is the operational signal for testee-tuning:
-
-- Any **individual step with cache% < 40%** → it is re-reading files or re-sending prompt context
-  unnecessarily. Emit a **P3** finding naming that step, **even if the step succeeded**.
-- A run with **aggregate cache% < 50%** → the testee is a tuning candidate regardless of the
-  PASS/PARTIAL/FAIL verdict. Emit a **P3** finding: "Low cache hit rate — candidate for
-  context-window or prompt trimming."
-
-These feed the report's §6 Findings (see [report-template.md](report-template.md)).
+## Context-reuse observation rule (task 0913, R3 — replaces the fixed-threshold cache-health rule)
+
+The estimated reuse share is a **heuristic** (chars/4 over the driver's own session); it cannot
+prove provider cache behavior, unnecessary re-reading, or realized savings. Threshold crossings
+(40%, 50%, or any other fixed line) therefore **never auto-generate a causal waste finding**.
+Instead:
+
+- **Estimated-only evidence** (chars/4 ledger, no external meter): a low estimated reuse share may
+  be reported only as a **labeled hypothesis** finding carrying the `[unverifiable]` tag, naming
+  the confirmation it needs (per-step provider telemetry, a real meter, or a measured reread
+  trace). Example shape: `P3 — estimated reuse share 36%, below the run's own trend — hypothesis:
+  repeated task-list refetching; confirm with per-step metering` `[unverifiable]`.
+- **Measured evidence** (ccusage session/day delta, or agent usage fields in tool results): report
+  the measured figures with their scope label and confidence, and keep them out of per-step ledger
+  cells. A waste finding may then name the measured evidence — still without claiming causality
+  the meter does not show.
+- **Unavailable evidence**: print `Meter: n/a` and totals `n/a` rather than a fabricated share;
+  route the missing-measurement gap to its owner as an improvement proposal.
+
+Unobservable chained-step cost keeps its **mandatory** P3 finding (`P3 — chained-step cost not
+observable`, task 0278 R3) — that rule reports missing evidence, not causal waste, and stays.
+
+These findings feed the report's §6 Findings (see [report-template.md](report-template.md)).
+
+## Pipeline-run provenance observations (task 0913, R5)
+
+When the testee drives a task pipeline, the driver may adopt the supported findings from the
+0912 workflow baseline (`docs/reports/i31/0912-workflow-baseline.md`) as bounded observations —
+with artifact anchors and owner handoffs, never as invented performance conclusions:
+
+- **Run-row closure / structured emission (supported, pilot-selected):** if the observed pipeline
+  run leaves a non-terminal run row or emits no `action_runs` rows, record the observation with
+  the run id as anchor and hand off to the owners named in the baseline (driver adoption: D62;
+  row-closure defect: P). These are the baseline's pilot-eligible findings (F1/F2).
+- **Performance conclusions (INSUFFICIENT_EVIDENCE in the baseline):** no token/USD, percentage,
+  speedup, or fleet claim may be derived from a dogfood run. Record the limitation explicitly
+  (what was unmeasured and why) and route the missing evidence to the baseline's named gaps
+  (session/cost joins E6; scoped-gate experiment F3/F4; fleet serve session S5).
+- Historical comparison, recurrence, and cohort trends stay with history-anatomy and existing
+  doctor tooling — the dogfood report owns only what its own ledger observed.
 
 ## Cache-conservation discipline (how to keep cache% high)
 
-The cache-health rule above *detects* waste; this section is the mitigation. The dogfooding driver
+The context-reuse observation rule above interprets the signal; this section is the mitigation. The
+dogfooding driver
 (the agent running Phase 2/3) controls most of the cache% it later reports — low cache% is usually
 the driver re-fetching data it already holds. Apply these while monitoring each step:
 
 ### Driver cache checklist (task 0278 R7)
 
-When aggregate cache% risks falling under 50%, apply this checklist **before** re-reading:
+When the estimated reuse share looks low (or trends down across runs), apply this checklist
+**before** re-reading:
 
 | # | Action | Why |
 | --- | -------- | ----- |
@@ -198,12 +232,13 @@ When aggregate cache% risks falling under 50%, apply this checklist **before** r
 | 3 | Prefer `--json` CLI over re-parsing freeform prose | Smaller, stable payloads |
 | 4 | Dual-write ledger rows without re-reading the whole report each step | Append/patch; don't full-file re-load |
 | 5 | Skip redundant `bun test` full suite between steps when a focused file suite already green | Run the broad suite once at the end |
-| 6 | For batch testees (`verifyall` / `runall` / `refineall`): freeze `task list --json` once at resolve | Re-listing the set per task is the #1 sub-50% cache pattern on feature dogfoods |
-| 7 | On re-verify of done tasks: re-read only cited `file:line` anchors, not full Solution blobs | Anchor-first re-verify keeps cache% above the 50% floor |
+| 6 | For batch testees (`verifyall` / `runall` / `refineall`): freeze `task list --json` once at resolve | Re-listing the set per task is the #1 low-reuse-estimate pattern on feature dogfoods |
+| 7 | On re-verify of done tasks: re-read only cited `file:line` anchors, not full Solution blobs | Anchor-first re-verify keeps the reuse estimate honest and high |
 
 1. **Reuse CLI output already in context.** If a prior step (or a prior tool call this step)
    captured `spur task show`/`check`/`list` output, do **not** re-invoke the same command for that
-   data — reference the prior result. Re-invocation is the #1 cause of sub-40% steps. Only re-fetch
+   data — reference the prior result. Re-invocation is the #1 cause of low estimated-reuse steps.
+   Only re-fetch
    when the underlying state *changed* (e.g. you just wrote a section and need the new
    `requiredSections`).
 2. **Don't re-ground shared scaffolding per step.** Command docs, the skill preamble, and the
@@ -217,7 +252,8 @@ When aggregate cache% risks falling under 50%, apply this checklist **before** r
    useful as a trend if it reflects what actually happened.
 
 The point is not to game the number — it is to drive the testee (and your own monitoring) toward
-reusing context, which is the real cost saving the cache% signal stands for.
+reusing context, which is the context-efficiency gain the estimated reuse share stands for. The
+share itself remains a heuristic trend signal (task 0913, R3), not a measured saving.
 
 ## Worked ledger example
 
@@ -230,6 +266,7 @@ reusing context, which is the real cost saving the cache% signal stands for.
 | 4 profile | 1 | PASS | — | — | ~500 | ~350 | 41% | command output + prior profile reused | ~2s |
 ```
 
-Aggregate: total = `3700 + 2050 = 5750`; cached = `2050`; cache% =
-`round(2050 / 5750 * 100) = 36%` `[~estimate]` — below the 50% floor, so emit the P3 cache-health
-finding.
+Aggregate: total = `3700 + 2050 = 5750`; cached = `2050`; estimated reuse share =
+`round(2050 / 5750 * 100) = 36%` `[~estimate]`. A low estimated reuse share is reported only as a
+labeled-hypothesis `[unverifiable]` finding (or backed by a real meter) — never as an automatic
+causal waste claim (task 0913, R3).

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -96,8 +96,21 @@ Skeleton is written in Phase 1; filled as the run progresses; finalized in Phase
 - **Mode:** `observe-only (--max-retry 0)` | `fix (--max-retry N)`
 - **Task under test:** WBS + title (if applicable)
 - **Run id:** `<run_id>` · **Live:** `<live_path>` · **Report:** `<report_path>`
+- **Source evidence:** `<commit sha>` + dirty-state (`clean` | `porcelain hash` | `unrecorded`)
+- **Definition:** resolved definition digest, or `path+hash`; `unknown` when not resolvable
+- **Execution mode:** `<observe-only | fix>` · driver/testee separation noted for chained legs
+- **Measurement scope:** `<driver ledger (chars/4, per-step) | ccusage <day\|session> | agent usage fields>`; external meter name or `none`
+- **Sample coverage:** `<k>/<n>` executed steps observed; testee workflow/run/session IDs `<ids | unknown>`
 ```
 
+**Provenance and comparability (task 0913, R4 — additive).** The provenance lines above are
+optional in `@1.2`: legacy reports without them remain readable and valid, but are **not
+automatically eligible for comparison**. Before treating two reports as comparable, require
+compatible measurement scope, execution mode, and resolved definition identity; otherwise emit
+**`not comparable`** and route the missing evidence to its owner. Unsupported identifiers are
+recorded as `unknown` — never invented. Driver cost and testee/chained-leg cost stay separate
+rows; pilot comparisons must not mix them.
+
 When `status` is `aborted` or the report is partial, add under §1:
 
 ```
@@ -122,14 +135,22 @@ When `status` is `aborted` or the report is partial, add under §1:
 
 **Cost honesty rules:**
 
-- Always include ledger-derived `~estimate` total / cached / cache% with a **Method** line and
+- Separate the three evidence classes in every Cost block (task 0913, R3): **measured** usage
+  (real meter, scope-labeled), **heuristic estimates** (chars/4 ledger, labeled `~estimate`,
+  confidence `LOW`), and **unavailable** values rendered `n/a` — never a fabricated number or a
+  share computed over unknown rows.
+- Always include ledger-derived `~estimate` total / cached / reuse share with a **Method** line and
   **confidence** (`LOW` when estimate-only; `MEDIUM` when a real meter is also present).
 - Optional meters when available (never invent):
   - `ccusage` session/daily delta — label scope (`day` / `session`), **not** per-step
   - agent usage fields if present in tool results
-- If no meter: print `Meter: n/a` explicitly.
+- If no meter: print `Meter: n/a` explicitly; if no ledger row is observable, print totals and
+  share as `n/a` rather than folding unknowns into zero.
 - Never present an unsubstantiated precise integer as billed/metered cost.
-- Aggregate cache% MUST equal the ledger formula (see §3); otherwise the report is invalid.
+- Observable totals MUST satisfy `total = fresh + cached` and the share MUST equal the ledger
+  formula over observable rows within display rounding (±1 point); the validator (task 0913)
+  rejects violations. The chars/4 figures estimate the driver session's context reuse — they are
+  **not** provider cache measurements and establish no realized savings.
 - **Chained-step segmentation (@1.2):** when a derived step is implement-heavy (the step runs a
   pipeline leg, writes code, or mutates more than its own arguments), its cost MUST be a separate
   ledger row tagged `chained:<step>` and kept out of the driver's row. If the chained leg ran in a
@@ -251,8 +272,8 @@ from the trailing feasibility tag:
 ```
 
 Omitting the class preserves the current line shape; untagged findings remain valid and the
-protocol stays `sp:dogfood-testing@1.2` (the validator gains no required field; the cache-health
-P3 above needs no class).
+protocol stays `sp:dogfood-testing@1.2` (the validator gains no required field; an
+evidence-based reuse observation needs no class).
 
 - `testee` — a defect in the testee's contract (the protocol the run grades). Bounded fix-mode
   may repair it, unchanged.
@@ -278,13 +299,15 @@ Severity scale:
   finding:** when a drift row (`drift:external`) is present in the ledger, a P2 finding naming the
   drifted paths is mandatory in the report (not optional). The finding states the run's evidence is
   degraded, not voided. See [SKILL.md §Workspace-drift guard](../SKILL.md#workspace-drift-guard-r2--task-0296).
-- **P3** — efficiency / DX / observation (includes the cache-health rule below).
+- **P3** — efficiency / DX / observation (includes evidence-based context-reuse observations below).
 - **P4** — nice-to-have, cosmetic, or speculative.
 
-**Cache-health rule** (from [monitor-ledger.md](monitor-ledger.md)): if aggregate cache% < 50% or any
-step < 40%, emit a **P3** — "Low cache hit rate — candidate for context-window or prompt trimming"
-with the offending step(s). Absolute token totals from the heuristic are trend-only (`[unverifiable]`
-as billable cost proof is expected).
+**Context-reuse observation rule** (task 0913 — replaces the fixed-threshold cache-health rule;
+see [monitor-ledger.md](monitor-ledger.md)): estimated reuse shares (chars/4) never auto-generate
+causal waste findings. Report a low estimated share only as a labeled-hypothesis finding carrying
+`[unverifiable]` and naming the confirmation needed, or cite measured meter evidence with its
+scope. Absolute token totals from the heuristic are trend-only (`[unverifiable]` as billable cost
+proof is expected).
 
 **Migration grep rule.** When dogfooding migrations or retired surfaces, distinguish intentional
 legacy-term mentions in guidance from live routed surfaces. Pair any broad grep for old skill or

package/plugins/sp/skills/history-anatomy/references/modes.md

@@ -1,7 +1,9 @@
 # Mode contract — `sp:history-anatomy` (HA-S1, 0658)
 
 The skill resolves exactly two modes. Everything else fails loud. This matrix is the enforcement
-surface the workflow (0660) and the skill share; keep the vocabulary frozen.
+surface the workflow (0660) and the skill share; keep the vocabulary frozen. Execution note
+(0920): argument validation runs deterministically in the `history-anatomy-cache` helper `paths`
+command before the workflow starts; the model hop no longer performs it.
 
 ## Mode vocabulary (frozen)
 
@@ -26,7 +28,7 @@ Rejected arguments (each fails loud, naming the offending argument):
 | --- | --- |
 | focus text (positional) | Daily mode has no focus string. |
 | `--since` / `--until` | Daily always uses the calendar-day window. |
-| `--output` | Daily always writes to the run directory (see 0660). |
+| `--output` | Daily always writes to `docs/report/<date>-history-anatomy.md` (the executing helper's default; 0660). |
 
 A daily invocation must print the normalized **inclusive ISO bounds** and the timezone used, so the
 wall-clock window is auditable.
@@ -40,7 +42,7 @@ Requires a **non-empty focus** and **two ordered inclusive bounds**.
 | focus (positional) | Required; a missing or empty focus fails loud. |
 | `--since <iso>` | Required; the inclusive lower bound. |
 | `--until <iso>` | Required; must be present with `--since`; must not be earlier than `--since`. |
-| `--output <path>` | Optional; when present, writes to that explicit path. When absent, writes to the run directory. |
+| `--output <path>` | Optional; when present, writes to that explicit path. When absent, writes to `docs/report/<date>-history-anatomy.md` (the executing helper's default). |
 
 Rejected arguments (each fails loud, naming the offending argument):
 

package/plugins/sp/skills/next-feature/references/ranking-rubric.md

@@ -40,7 +40,7 @@ and no command-derived number or `file:line` citation is a defect in the report,
 ## The gated list
 
 Gated features are listed **separately, never ranked**, each with its gate reason from the
-actionability pass (`blocked: 0142 — external trigger` / `no open tasks` / `all tasks terminal`).
+actionability pass (`blocked: <wbs> — external trigger` / `no open tasks` / `all tasks terminal`).
 Features whose gate reason is "all tasks terminal" are T4 candidates — say so once, in the sync-first
 block, rather than repeating per row.
 

package/plugins/sp/skills/next-router/references/routing-table.md

@@ -113,6 +113,13 @@ token, deterministic).
 | C3 | A5/A6 when Testing empty/N/A **and** verify would fail for missing tests — only if prior implement claims code exists | Coverage/test signal: `bun test` fail attributed to task paths OR explicit "insufficient tests" in prior verify verdict artifact `.spur/run/<wbs>-verdict.json` | test fail / coverage gap | `/sp:dev-unit <wbs> --auto` | continue |
 | C4 | A3/A5/A6 when operator or task tags mention rules, OR `spur rule run` last report dirty in `.spur/` if present | `spur rule run` (default project preset) non-zero with findings | rule findings | **HITL STOP** — print rule summary; suggest `/sp:rule-scan` or `rule-add`/`rule-refine` (do not auto-author rules) | continue |
 | C5 | A6 only | Existing `.spur/run/<wbs>-verdict.json` with FAIL and findings pointing at coverage | verdict artifact | `/sp:dev-unit <wbs>` then re-verify on next invocation (`--once` friendly) | `/sp:dev-verify …` |
+| C6 | A4/A5 | `.spur/run/<wbs>-verdict.json` has a failing (PARTIAL/FAIL) `residual-sweep` check — the bounded remediation loop already ran and failed (F96) | folded verdict artifact | **HITL STOP** — print `.spur/run/<wbs>-residual-report.md` and the recovery command `/sp:dev-run <wbs>`; never auto-dispatch a fix (repeating the loop unattended burns quota without new information) | continue |
+
+**C-row precedence note (F96):** C6 outranks C2/C3/C5 for the same task — a residual-sweep failure
+means the workspace holds unfinished task residue, so fixall/unit reruns would either clean it
+unintentionally or re-certify a folded verdict. C6 fires before any fix/unit dispatch; recovery is
+the operator re-running the pipeline (`/sp:dev-run <wbs>`), which re-enters the normal
+verify → test-fix remediation budget.
 
 **Explicit non-probes in v1:** no freeform chat history; no always-on full `bun run test` for every
 call; no git dirtiness as a route (optional advisory print only).

package/plugins/sp/skills/parallel-execution/references/dispatch-surface.md

@@ -37,7 +37,7 @@ native subagent.
 | 1 | **Different model or coding agent required** | The step needs a model or a coding agent the host session cannot provide (`--model`, `--agent`). | "verify on o3" where the host is Claude Code; "run this through omp" from a non-omp host. |
 | 2 | **Headless or unattended step** | The step must run without a live session - scheduled, detached, or driven by a non-interactive caller. | A batch launched by `spur workflow run --async` with no operator attached. |
 | 3 | **Durable auditable run record required** | The dispatch must produce a persisted run record (cost ledger, trace, exit code) for after-the-fact audit. | `spur agent run` writes `.spur/run/` artifacts; a native subagent does not. |
-| 4 | **Workspace or credential isolation required** | The step must run in a separate workspace, worktree, or credential scope from the orchestrating session. | A destructive step isolated to a throwaway worktree; a step that must not inherit the session's `cwd` secrets. |
+| 4 | **Workspace or credential isolation required** | The step must run in a separate workspace, worktree, or credential scope from the orchestrating session. | A destructive step isolated to a throwaway worktree; a step that must not inherit the session's `cwd` secrets; `--mode parallel` batch fan-out, one worktree per task ([execution-batch.md § Parallel isolation](../../spur-dev/references/execution-batch.md#parallel-isolation---mode-parallel)). |
 
 ## The naming requirement
 

package/plugins/sp/skills/session-review/SKILL.md

@@ -84,7 +84,14 @@ three buckets — never skip triage and start fixing from the raw findings list.
    Apply the placement rule in
    [the environment-improvement mapping](../../references/environment-lens.md): automate with a
    check when possible, place coding standards on the review path, and keep always-loaded steering
-   as navigation pointers.
+   as navigation pointers. When the session drove a task pipeline, at most three bounded
+   diagnostic questions may be drawn from the supported observations (F1/F2) and measured
+   overhead candidates (F3/F4) in the 0912 workflow baseline
+   (`docs/reports/i31/0912-workflow-baseline.md`) — e.g. repeated gate runs (F4), full-loss
+   test-fix timeouts (F3), or unemitted/non-terminal run rows (F1/F2) — each citing its artifact
+   anchor and owner handoff (driver adoption D62, row-closure defect P). Areas the baseline marks
+   INSUFFICIENT_EVIDENCE (token/USD, percentages, fleet) stay excluded; record the limitation
+   instead of a performance conclusion.
 5. **Render the report.** Use the exact compact output contract below. Omit empty table rows, not
    headings; write `None observed` when a section has no supported entry.
 
@@ -123,7 +130,10 @@ session. Do not list ordinary implementation steps as issues.
 ### Process and environment improvements
 
 For each supported proposal, name its owner surface, expected impact, verification method, and
-reversibility. Proposals remain report-only: apply no change and create no task.
+reversibility. Proposals remain report-only: apply no change and create no task. A pipeline
+observation adopted from the 0912 workflow baseline cites its anchor
+(`docs/reports/i31/0912-workflow-baseline.md`) and owner handoff, and carries no unsupported
+performance claim.
 
 ### Triage (only when `--triage` was passed)
 

package/plugins/sp/skills/spur-check/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: spur-check
+description: 'Two-tier check primitive for the sp pipeline: light (changed-scope biome, per-workspace typecheck, related tests) during development; full (bun run spur-check) once at the quality boundary. Reads/writes fingerprint-bound check receipts (.spur/run/<wbs>-check-receipt.json) and reuses a PASS full receipt only at the same proof digest.'
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: check-execution
+  interactions:
+    - pipeline
+  operations:
+    - check
+    - accumulate
+    - reuse
+  openclaw:
+    emoji: "🧾"
+see_also:
+  - sp:spur-dev
+  - sp:spur-cli
+  - sp:code-verification
+---
+
+# sp:spur-check — the two-tier check primitive (ADR-124)
+
+One check primitive with two tiers behind the shipped `quality-gate` script
+([task 0939](../../../../docs/tasks5/0939_add-the-two-tier-spur-check-primitive-with-fingerprint-bound.md),
+[workflow catalogue refactor §4](../../../../docs/design/workflow-catalogue-refactor.md)): light
+checks accumulate during development, the full chain runs once at the quality boundary, and every
+gate writes a fingerprint-bound receipt that downstream stages read instead of re-running checks.
+
+## Tiers
+
+| Tier | Mode | When | Scope |
+| --- | --- | --- | --- |
+| `light` | `quality-gate.ts light` | after each implement/fix edit | `bunx biome check` on the changed files (`git diff --name-only HEAD` + untracked), `bun run typecheck` per touched workspace, and related tests (`<ws>/src/**/x.ts` → `<ws>/tests/**/x.test.ts` filename mapping) run via `cd <ws> && bun test …` — never from the repo root, whose bunfig preload does not apply inside the workspace |
+| `full` | `quality-gate.ts run` | once at the task quality boundary (`test`) | today's chain: `bun run lint` + `bun run test-pre-check` + `bun run test` + `bun run test-post-check` (=`bun run spur-check`), with bounded findings, SQLite-busy retry, and the `recheck` probe |
+
+Soft-fail contract: both tiers always exit 0; the verdict lives in files (`*-test-gate.status`,
+receipt `status`), never in the exit code.
+
+## Receipt
+
+`.spur/run/<wbs>-check-receipt.json`, schema `check-receipt/v1`:
+
+```json
+{
+  "schemaVersion": "check-receipt/v1",
+  "wbs": "0939",
+  "runId": "pipeline-0939",
+  "tier": "full",
+  "inputDigest": "<proof-input digest>",
+  "checks": [{ "id": "test", "cmd": "…", "status": "PASS", "durationMs": 0, "logPath": "…" }],
+  "status": "PASS",
+  "completedAt": "2026-09-25T00:00:00.000Z"
+}
+```
+
+- `inputDigest` is the shared `ProofInputFingerprint` (task markdown + git tree of tracked
+  sources). The plugin never computes it — the pipeline captures it with the `proof.fingerprint`
+  action into `env.proofDigest` (ADR-124: no second fingerprint, no `@gobing-ai/*` import);
+  standalone callers use `inline-run-setup.ts --fingerprint`.
+- Only `run`/`full` writes a reusable receipt. Without a digest, `run` writes no receipt and says
+  so in the gate log. The gate executes `qualityGateCmd` as one unit, so the full receipt carries a
+  single `test` row for the whole chain; `lint`, `typecheck`, `test-pre-check`,
+  `test-post-check` name the chain steps the full tier covers.
+- `light` merges its rows under `tier: light` and skips any sub-check already `PASS` in a light
+  receipt at the same `{id, inputDigest}` (accumulation). Light rows never make a receipt
+  reusable for review.
+
+## Reuse rule
+
+Check `status` mode before re-running a gate. Resolve the shipped script through the superskill
+runtime (shipped surfaces never hard-code repo paths):
+
+```bash
+QG="$(superskill script path sp quality-gate.mjs)"
+bun "$QG" status   # env: wbs, proofDigest → prints {"reuse":…,"reason":…}
+```
+
+`reuse: true` only when the receipt is `status: PASS`, `tier: full`, and `inputDigest` equals the
+current digest. Otherwise the reason is one of `missing | failed | stale | light-only`:
+
+- `missing` — no readable receipt (or foreign schema version)
+- `failed` — last full run failed
+- `stale` — digest mismatch (or no current digest supplied)
+- `light-only` — a valid PASS receipt that came from the light tier
+
+Only `full` may satisfy a review/verify/record boundary: "review only after a green full gate" is
+preserved by construction. `recheck` stays the no-progress probe path for fix loops.
+
+## Composition
+
+- **Pipeline:** `sp:spur-dev` runs `run` at `test` and `recheck` at `test-recheck`; light mode
+  belongs to implement/fix edits, not to the gate state.
+- **Fix loops:** `/sp:dev-fixall --gate-log` consumes `<wbs>-test-gate.log` (and the bounded
+  `<wbs>-test-gate.findings` anchors) after a red gate; it never writes receipts. A green fixall
+  output still requires a fresh `run` receipt before review.
+- **Verification:** `sp:code-verification` and the review checklists read the receipt (status
+  mode) instead of re-running `bun run test`.
+- **Feature scope:** `spur-check-feature` remains the ADR-119 repo-wide pass; this primitive is
+  task-local. A public `spur check` verb is out of scope without separate consent.
+
+## Gotchas
+
+1. **Never value-import `@gobing-ai/*` into the script** — the plugin standalone contract fails
+   the install; the digest arrives via `env.proofDigest`.
+2. **Never run light tests from the repo root** — the workspace `bunfig.toml` preload (coverage,
+   thresholds) only applies inside the workspace; `cd <ws> && bun test …` is the contract.
+3. **Light is a filter, not a boundary** — unmapped files (root-level scripts, non-src layouts)
+   are simply not covered by light; the full tier is the safety net. Do not widen the mapping
+   without an ADR.

package/plugins/sp/skills/spur-cli/references/features.md

@@ -28,7 +28,7 @@ what* or *how to write a scenario*, this skill.
 | `list` | List features, filtered | `--status <s>` `--priority <p>` `--folder` `--json` |
 | `move <id>` | Re-parent a subtree (cascade-rename of descendants) | `--parent <id>` `--dry-run` `--folder` `--json` |
 | `refresh` | Rebuild INDEX + each feature `## Tasks` table from task edges (**docs only**; no status change) | `--feature <id>` `--all` `--folder` `--json` |
-| `check [id]` | Validate one feature / the tree; the 4-layer gate; `--fix` repairs structural findings in place | `--strict` `--fix` `--folder` `--json` |
+| `check [id]` | Validate one feature / the tree; the 4-layer gate; `--fix` repairs structural findings in place | `--strict` `--fix` `--as <status>` `--folder` `--json` |
 | `sync [id]` | Align feature **lifecycle status** with linked task states (real transitions + guards) | `--all` `--dry-run` `--force` `--folder` `--json` |
 
 **`refresh` vs `sync` (do not conflate):**

package/plugins/sp/skills/spur-cli/references/projects.md

@@ -19,6 +19,7 @@ shapes live in `apps/cli/src/commands/projects.ts`.
 | ---- | ------- | --------- |
 | `add <path>` | Upsert an existing path in the registry | `--name <name>` `--json` |
 | `remove <target>` | Remove an entry by display name or path | `--json` |
+| `clean` | Purge missing project folders and terminate lingering processes (alias: `refresh`) | `--no-terminate-processes` `--json` |
 | `list` | List entries with live running status | `--json` `--fleet` |
 | `start <target>` | Start or reuse a detached project server | `--port <n>` `--json` |
 | `stop <target>` | Best-effort stop the listener and clear its recorded port | `--json` |
@@ -35,7 +36,8 @@ exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
 - `add` requires an existing path, resolves a relative path from the current working directory, and
   defaults the display name to its basename. It upserts; it does not start a server. The current
   source does not enforce a `.spur/` marker or directory type.
-- `list` probes recorded ports and heals stale entries to `port: 0` before reporting `running`.
+- `list` automatically heals tilde paths, verifies project directories exist on disk (purging missing entries and terminating lingering processes), and heals stale entries to `port: 0` before reporting `running`.
+- `clean` (alias `refresh`) explicitly purges non-existent project directories from `projects.json`, probes live ports for removed entries, and cleanly terminates orphaned listening processes (SIGTERM with bounded wait and SIGKILL escalation). Supports `--no-terminate-processes` to skip process kills.
 - `list --fleet` (0835/0858) additionally resolves each project's `agent.fleet` section from that
   project's `.spur/config.yaml` under the existing verb (no new noun). Per project it prints one line
   per member: instance id (the spec id / mailbox identity), `role`, resolved `executor`,

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -110,11 +110,11 @@ The skill's logic divides by **whether the LLM adds value**:
 | --------- | --------- | ----- | ------------------ |
 | `validate` | `spur workflow validate` (CLI) | `<file> [--no-schema]` | Schema + semantic verdict |
 | `run` | `spur workflow run` (CLI) | `<file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer]` | Terminal state reached (sync) or run started (async); trace readable |
-| `continue` | `spur workflow continue` (CLI) | `[run-id] [--yes] [--answer <yes\|no\|cancel>] [--async] [--no-log]` | Resume a paused or interrupted run (omit id -> most recent resumable); `--answer` injects a gate answer before guard re-evaluation and is required headless (0901 R3); `--async` detaches the resume (0901 R4) |
+| `continue` | `spur workflow continue` (CLI) | `[run-id] [--yes] [--answer <yes\|no\|cancel>] [--answer-text <text>] [--async] [--no-log]` | Resume a paused or interrupted run (omit id -> most recent resumable); `--answer` injects a confirm/select gate answer and `--answer-text` answers an input gate with free text (H1 R27), both before guard re-evaluation; one of them is required headless (0901 R3) and each is validated against the pending gate kind; `--async` detaches the resume (0901 R4) |
 | `cancel` | `spur workflow cancel` (CLI) | `<run-id>` | Single non-terminal run marked failed (SIGTERM async worker when live) |
 | `clean` | `spur workflow clean` (CLI) | `[--older-than <min>] [--force] [--logs] [--dry-run]` | Bulk-finalize stale `running`/`pending` runs as failed **and** reclaim retained run logs older than `workflow.logRetentionDays` (30d default) |
 | `list` | `spur workflow list` (CLI) | — | Available workflow **YAML definition files** (not run records) |
-| `trace` | `spur workflow trace` (CLI) | `[run-id] [--workflow <n>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output]` | Run history list or per-run timeline |
+| `trace` | `spur workflow trace` (CLI) | `[run-id] [--workflow <n>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--timeout <ms>]` | Run history list or per-run timeline |
 | `progress` | `spur workflow progress` (CLI) | `<run-id>` | The `projectWorkflowProgress` projection for that run — current state, per-action attempts, candidate next transitions, diagnostics. Read-only; the verb renders, `packages/app` derives. Unknown run id exits 1 with `Run <id> not found.` |
 | `add` | agent procedure | `"<nl-description>" [--kind <state-machine\|transition-flow>] [--file <path>]` | **Mode chosen (confirmed)** → first reconciled against existing workflows (extend an existing flow rather than duplicate) → YAML authored in real schema shape → **validated AND dry-run** (reaches the expected terminal state) → [add](workflows/operations.md#add) |
 | `refine` | agent procedure | `<workflow-file> [--intent "<goal>"] [--dry-run]` | Smallest change meeting the intent, re-validated and re-dry-run; `--dry-run` emits a diff only → [refine](workflows/operations.md#refine) |
@@ -204,7 +204,7 @@ spur workflow run ./workflows/approval.yaml --silent               # errors only
 spur workflow run ./workflows/approval.yaml --verbose              # transitions + correlation diagnostics
 spur workflow run ./workflows/approval.yaml --detail minimal       # tersest human output
 spur workflow run ./workflows/approval.yaml --trace-file           # persist redacted JSONL trace
-spur workflow run ./workflows/approval.yaml --no-log               # opt out of the consolidated .spur/run/<RUNID>.log
+spur workflow run ./workflows/approval.yaml --no-log               # opt out of the run record .spur/run/<RUNID>.md + .state.json
 spur workflow run ./workflows/approval.yaml --steer                # interactive steering on stdin
 ```
 
@@ -214,8 +214,8 @@ spur workflow run ./workflows/approval.yaml --steer                # interactive
   per-step headers), `full` (transitions + correlation). `--verbose` is shorthand for `--detail full`.
 - **`--trace-file`** appends a redacted, schema-versioned JSONL trace under `.spur/workflow/`
   for post-run analysis - independent of human/JSON output.
-- **`--no-log`** opts out of writing the consolidated all-in-one run log (`.spur/run/<RUNID>.log`).
-  By default the log is written **and retained** after the run ends; this flag skips it entirely
+- **`--no-log`** opts out of writing the two-file run record (`.spur/run/<RUNID>.md` + `.state.json`).
+  By default the record is written **and retained** after the run ends; this flag skips it entirely
   (propagates to the `--async` detached worker). No `--keep-log` / delete-by-default exists.
 - **`--steer`** is synchronous and in-process: it cannot combine with `--json` or `--async` (exit `2`).
   It accepts steering commands on stdin at declared action boundaries for interactive control.
@@ -260,11 +260,11 @@ the operator accepts it, and never hot-edit a running workflow's shell in place.
 spur workflow validate <file> [--no-schema] [--json]
 spur workflow show      <file> [--format <mermaid|todo>] [--json]
 spur workflow run      <file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer] [--json]
-spur workflow continue [run-id] [--yes] [--answer <yes|no|cancel>] [--async] [--no-log] [--json]
+spur workflow continue [run-id] [--yes] [--answer <yes|no|cancel>] [--answer-text <text>] [--async] [--no-log] [--json]
 spur workflow cancel   <run-id> [--json]
 spur workflow clean    [--older-than <minutes>] [--force] [--logs] [--dry-run] [--json]
 spur workflow list     [--json]
-spur workflow trace    [run-id] [--workflow <name>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--json]
+spur workflow trace    [run-id] [--workflow <name>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--timeout <ms>] [--json]
 spur workflow progress <run-id> [--json]
 ```
 
@@ -285,7 +285,7 @@ not advertise `--json-envelope` because its JSON projection is a kept-raw docume
 | `--verbose` | Include transitions and correlation diagnostics in human progress (implies `--detail full`). |
 | `--detail <level>` | Human detail level: `minimal`, `invocation` (default), or `full`. |
 | `--trace-file` | Append a redacted schema-versioned JSONL trace under `.spur/workflow/`. |
-| `--no-log` | Opt out of writing the consolidated `.spur/run/<RUNID>.log` (retained by default; propagates to `--async` workers). |
+| `--no-log` | Opt out of writing the two-file run record `.spur/run/<RUNID>.md` + `.state.json` (retained by default; propagates to `--async` workers). |
 | `--steer` | Accept in-process steering commands on stdin at declared action boundaries (sync only; incompatible with `--json`/`--async`). |
 
 `validate` and `run` exit non-zero on failure (`run` exits non-zero when the final status is not
@@ -302,32 +302,51 @@ Follow a live run to terminal (human streaming mode):
 ```bash
 spur workflow trace <run-id> --follow            # stream until terminal (default 1000ms poll)
 spur workflow trace <run-id> --follow --poll 500 # poll every 500ms
-spur workflow trace <run-id> --follow --output   # stream .spur/run/<RUNID>.log instead of the DB timeline
+spur workflow trace <run-id> --follow --output   # stream .spur/run/<RUNID>.md instead of the DB timeline
+spur workflow trace <run-id> --follow --timeout 600000 # bound the watch; timeout → one checkpoint, run continues, exit 1
 ```
 
 - **`--follow`** replays a run timeline and polls persisted state until it becomes terminal. It
   requires a `run-id` (exit `2` without one) and cannot combine with `--json` (exit `2` - it is a
   human streaming mode).
 - **`--poll <ms>`** sets the follow polling interval (default `1000`, minimum `50`; exit `2` otherwise).
-- **`--output`** swaps the follow source from the structured DB timeline to the consolidated all-in-one
-  log (`.spur/run/<RUNID>.log`, tail -f equivalent), streaming new lines as they land and exiting at
-  terminal status. It requires `--follow` and a `run-id`, is a human stream (rejects `--json`), and is
-  a **distinct source** — it never interleaves with the DB timeline. If the log never appears (e.g. the
+- **`--timeout <ms>`** (requires `--follow`, positive integer; otherwise exit `1` with `VALIDATION_FAILED`)
+  bounds the watch (0930): when the deadline passes before the run is terminal — including the `Run not
+  found` registration retry window — the follow prints one checkpoint naming the run id and last observed
+  status and exits `1`. A watch timeout never cancels or relaunches the run; resume by re-running the same
+  follow command.
+- **`--output`** swaps the follow source from the structured DB timeline to the human run record
+  (`.spur/run/<RUNID>.md`, tail -f equivalent), streaming new lines as they land and exiting at
+  terminal status. A pre-0925 run with only a legacy `<RUNID>.log` is followed in place (read-only
+  fallback). It requires `--follow` and a `run-id`, is a human stream (rejects `--json`), and is
+  a **distinct source** — it never interleaves with the DB timeline. If no record file appears (e.g. the
   run was started with `--no-log`), a clear message is printed at terminal status rather than hanging.
-  No `spur workflow monitor` verb exists; `--output` is the log-streaming surface.
+  No `spur workflow monitor` verb exists; `--output` is the record-streaming surface.
 
 HITL pause/resume: a run that hits a HITL action pauses; resume with `spur workflow continue [run-id]`
 (`--yes` skips confirmation). A headless `hitl.confirm` persists a default `no` before pausing -
-use `--answer yes|no|cancel` to inject the operator's gate answer before guard re-evaluation (0433).
-`--answer` is distinct from `--yes`: `--yes` skips the CLI resume prompt, `--answer` sets the HITL
-gate answer. 0901: resumes accept interrupted runs too (rerun-enter re-executes the interrupted
+use `--answer yes|no|cancel` to inject the operator's gate answer before guard re-evaluation (0433),
+or `--answer-text <text>` to answer an input gate with free text (H1 R27). `--answer` is distinct from
+`--yes`: `--yes` skips the CLI resume prompt, the answer flags set the HITL gate answer. Answer flags
+are validated against the pending gate kind (`--answer` requires a confirm/select gate,
+`--answer-text` an input gate; both together are rejected; a mismatch exits 2 with the run still
+paused), and `--answer`/`--answer-text` honor the gate's `options.var` instead of assuming the
+default var. 0901: resumes accept interrupted runs too (rerun-enter re-executes the interrupted
 node and needs `resumeRerun: true` on the target state); a headless (`--json`/non-TTY) continue
-without `--answer` is refused (exit 2); `--async` detaches the resume and reports started/failed
+without `--answer` or `--answer-text` is refused (exit 2); `--async` detaches the resume and reports started/failed
 after the worker claims the run; resumed runs write the consolidated run log and pass shell
 streams through the secret redactor + 64 KiB tail unless `--no-log`. Cancel one live/paused run
 with `cancel <run-id>`; bulk-finalize orphans stuck in
 `running`/`pending` with `clean` (`--older-than` default 30 minutes, or `--force`).
 
+Replay posture (0916): no canonical workflow opts into rerun-enter today — every state relies on
+the engine's refusal default, so an interrupted resume into an unmarked state is refused and the
+next safe action is the printed status (resume `paused` runs directly; recover crashed `running`
+runs via `clean`, which sweeps them to `interrupted`). Enabling `resumeRerun: true` on a canonical
+state requires demonstrated repeatability evidence and a conscious update to the replay matrix in
+`packages/app/tests/workflow/replay-matrix.test.ts`; mutating steps behind `pause: true` gates are
+safe by construction because paused resumes skip-enter.
+
 **Schema resolution parity (0431):** `validate` and `run` both load the workflow through
 `WorkflowAppService` with the same `embeddedSchemaOptions()` map the CLI injects for
 `@gobing-ai/spur/schemas/...` refs. `run` pre-loads then calls the engine with the loaded def
@@ -344,7 +363,8 @@ redirecting `agent.run` stages (ADR-047).
 - **Run-log reclamation** (0429): removes retained `.spur/run/<RUNID>.log` files whose mtime is older
   than `workflow.logRetentionDays` in `.spur/config.yaml` (default 30 days; integer days, not minutes).
   Age is the only gate; best-effort deletes never abort the rest. Never touches
-  `.spur/workflow/<RUNID>.jsonl` or `*-partial.md`.
+  `.spur/workflow/<RUNID>.jsonl` or `*-partial.md`. Scope stays legacy `.log` names only (0925 R4):
+  the two-file record (`.md` + `.state.json`) is not reclaimed until a pair retention policy exists.
 - **`--logs`** scopes to log reclamation only (skips stale-run finalization). `--dry-run` applies to
   both scopes (lists what would be removed, writes nothing). `--json` returns
   `{ olderThanMinutes, dryRun, cleaned, logs: { retentionDays, dryRun, reclaimed, failures } }` (with