@gobing-ai/spur 0.3.40 → 0.3.42

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

@@ -0,0 +1,211 @@
+---
+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."
+see_also:
+  - dogfood-testing
+  - report-template
+protocol: sp:dogfood-testing@1.2
+---
+
+# Monitor + Ledger
+
+The ledger is the **single source of truth** for the report. It is recorded **live on disk** — one
+row per step, written the moment the step resolves — never reconstructed from memory at the end.
+Reconstruction produces fiction: it cannot honestly distinguish a step that passed first-try from
+one that took three attempts, and it loses the per-step signal that drives testee refinement.
+
+**Disk SSOT (protocol @1.2).** Working-memory-only ledgers are a contract violation. The ledger
+lives in the dual artifacts (see [report-template.md](report-template.md) → Always-on dual
+artifacts):
+
+| File | Path |
+|------|------|
+| Live | `.spur/run/dogfood/<run_id>.md` |
+| Report | `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md` |
+
+## The live-ledger rule
+
+1. **Open both artifacts in Phase 1**, before the first step runs (frontmatter `status: running` +
+   empty ledger table in each).
+2. **Write a row the instant a step resolves** (pass, fixed, unresolved, or N/A) — not after the run.
+3. **Dual-write every step:** append/update the row on the **live** file first, then mirror to the
+   **report** path. Do not batch rows until Phase 4. If the report write fails, continue with live
+   as SSOT, emit a P2 finding, and retry promote on finalize.
+4. **The report reads the on-disk ledger, not your memory.** Every number in the report traces to a
+   ledger row on disk. If it is not in the ledger file, it does not go in the report.
+5. **Cardinality (@1.2).** The ledger's data-row count MUST equal the `**Steps:** N derived, N executed` declared
+   in the report's §2 Execution Summary. N/A steps are not dropped — each gets its own row with
+   `Outcome: N/A`. A count mismatch refuses `status: complete` at finalize (see
+6. **R2 drift row (task 0296).** A ledger row tagged `drift:external` in the `Step` column documents
+   workspace drift detected during the run — files changed by an external writer that neither the
+   driver nor testee ledger rows name. The row carries `Outcome: drift`, `Fix Applied: <drifted paths>`,
+   `Finding: P2 — workspace drift detected during run; attribution to external writer`,
+   and `Basis: <fingerprint diff>`. A drift row never changes a step's outcome and never results in
+   a `FIXED` / `PASS` outcome — it is purely documentary. Cache columns carry `—` (not estimated).
+   See [SKILL.md §Workspace-drift guard](../SKILL.md#workspace-drift-guard-r2--task-0296).
+
+### Fast-run exemption (task 0294 R6a)
+
+The per-step live-write mandate (rules 1–4) exists to bound information loss when a mid-run crash
+terminates the driver before finalize. That risk is real for long runs (multi-step pipelines,
+mutating testees); it is **marginal for fast runs** where wall-clock is short enough that an
+operator would naturally watch the run to completion.
+
+**Codified exemption.** A run with **total wall-clock < 3 minutes** MAY batch-write all ledger
+rows at finalize, provided **both** of the following hold:
+
+1. The report's §2 Execution Summary carries an explicit note:
+   `Ledger write mode: batch-finalize (fast-run exemption, total wall-clock < 3 min)`.
+2. The driver is still prepared to reconstruct per-step ordering honestly — batched does not mean
+   fictional. If the driver cannot reconstruct attempts/outcomes per step from its own tool-call
+   history, the exemption does NOT apply and the strict per-step rule is back in force (rule 4:
+   "if it is not in the ledger file, it does not go in the report").
+
+This matches how the 0280 fast-run actually behaved (batch-finalize, still validated `complete`)
+and preserves the strict mandate for long runs where mid-run crash loss is the real risk. A run
+≥ 3 min that batch-writes is a **protocol violation the driver must self-report** as a P3 finding
+in the report's §6 Findings (no exemption applies).
+
+## Column contract
+
+```
+| Step | Attempts | Outcome | Fix Applied | Finding | Fresh Tokens | Cached Tokens | Cache % | Basis | Wall-clock |
+```
+
+| Column | Meaning |
+|--------|---------|
+| `Step` | The derived step label (Phase 1) or `N` for a single-step testee. |
+| `Attempts` | How many times the step was run (1 = first-try; >1 = retried under the fix budget). |
+| `Outcome` | `PASS` / `FIXED` / `UNRESOLVED` / `N/A`. (`FIXED` = failed then passed within budget.) |
+| `Fix Applied` | `file:line` + one-line summary, or `—`. |
+| `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. |
+| `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
+
+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:
+
+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;
+   - generated prose/code/report text: `ceil(characters / 4)`, rounded to the nearest 100;
+   - short command/control overhead: add `~100` per tool invocation that produced non-empty output.
+2. Estimate **Cached Tokens** only for material already present in the current session and actively
+   reused by reference in this step. Use the same `ceil(characters / 4)` basis and round to the
+   nearest 100. Do not count fresh command output, newly read files, or regenerated scaffolding as
+   cached.
+3. Compute each row: `Cache % = round(Cached Tokens / (Fresh Tokens + Cached Tokens) * 100)`.
+4. Compute the report aggregate from row sums:
+   `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.
+
+> Never print a precise token number you cannot substantiate. The numbers exist to show a *trend*,
+> not to bill anyone.
+
+### Multi-source Cost block (report §2)
+
+Ledger estimates alone are **confidence: LOW**. When assembling the report Cost block
+([report-template.md](report-template.md) §2):
+
+| Source | When to use | Confidence | Scope label |
+|--------|-------------|------------|-------------|
+| Ledger `chars/4` heuristic | Always | LOW | per-step trend |
+| `ccusage` daily/session | If CLI available and returns data | MEDIUM | day or session — **not** per-step |
+| Agent usage fields in tool results | If present (never invent) | MEDIUM | as reported by the tool |
+
+If no external meter is available, print `Meter: n/a`. Never merge a day-level meter into a
+per-step ledger cell as if it were measured per step.
+
+### Chained-step rows (implement-heavy derived steps)
+
+When a derived step is implement-heavy (it runs a pipeline leg, writes code, or otherwise mutates more
+than its own arguments), its row is tagged `chained:<step>` in the Step column and its Fresh/Cached
+columns reflect the **chained leg's** cost, not the driver's. The driver's monitoring cost for that
+step stays on the driver's own row.
+
+- Observable chained usage (subagent output in driver context, or the operator explicitly provided
+  the artifact) → estimate Fresh/Cached from that output normally.
+- Unobservable chained usage (subagent ran in a different session, usage data never surfaced) →
+  label Fresh `~unknown`, Cached `~0`, Basis `chained-leg usage not observable from driver`. **MUST**
+  emit a P3 finding: `P3 — chained-step cost not observable` (task 0278 R3). Do not invent totals.
+
+Never fold a chained row into the driver's row; the whole point of dogfooding a pipeline-driving
+testee is to see the testee's own cost separately from the driver's monitoring cost. See
+[SKILL.md §Cost segmentation for implement-heavy steps](../SKILL.md#cost-segmentation-for-implement-heavy-steps).
+
+## Anti-fiction rule
+
+Never reuse a convenient cache percentage such as `45%` because it "feels right." A cache percentage
+is valid only when it can be recomputed from the ledger row sums. If the basis is missing, mark the
+row pessimistically (`Cached Tokens = ~0`) and explain the missing basis.
+
+## 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)).
+
+## Cache-conservation discipline (how to keep cache% high)
+
+The cache-health rule above *detects* waste; 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:
+
+| # | Action | Why |
+|---|--------|-----|
+| 1 | Reuse the Step-1 `spur task show --json` capture for the rest of the run | Avoids re-tokenizing the full task body |
+| 2 | Do not re-Read SKILL.md / report-template after Phase 1 loaded them | Skill body is large; keep one copy in context |
+| 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 |
+
+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
+   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
+   testee's own argument-hint are loaded once into your context — they do not need to be re-read or
+   re-quoted for each step. Re-sending unchanged preamble registers as fresh tokens, not cached.
+3. **Prefer `--json` + targeted fields over full human output.** When you must fetch, ask for the
+   smallest shape that answers the question (`--json` and read one field), not the full
+   human-formatted dump.
+4. **Estimate `~cached` honestly against this discipline.** If *you* re-read a file or re-sent
+   scaffolding this step, that portion is **not** cached — mark cache% down. The estimate is only
+   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.
+
+## Worked ledger example
+
+```
+| Step | Attempts | Outcome | Fix Applied | Finding | Fresh Tokens | Cached Tokens | Cache % | Basis | Wall-clock |
+|------|----------|---------|-------------|---------|--------------|---------------|---------|-------|------------|
+| 1 resolve | 1 | PASS | — | — | ~600 | ~400 | 40% | task JSON output + prior command docs reused | ~3s |
+| 2 analyze | 1 | PASS | — | over-specified for refine | ~1100 | ~700 | 39% | task file read + prior task summary reused | ~5s |
+| 3 synthesize | 2 | FIXED | spur-dev/SKILL.md:88 thread --agent | — | ~1500 | ~600 | 29% | edit diff + prior plan reused | ~8s |
+| 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.

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

@@ -0,0 +1,351 @@
+---
+name: report-template
+description: "The dogfood report section contract + dual-path always-on delivery + mandatory summary footer + the --task sink L3 rule. The report is assembled from the on-disk live ledger and is designed to be actionable — a reader should be able to fine-tune the testee from the report alone."
+see_also:
+  - dogfood-testing
+  - monitor-ledger
+protocol: sp:dogfood-testing@1.2
+---
+
+# Dogfood Report Template
+
+The report is the deliverable. It is assembled from the **on-disk** live ledger (never reconstructed
+from memory) and is designed so a reader can **fine-tune the testee from the report alone** — every
+finding carries a location and a recommended action, not just an observation.
+
+**Protocol version:** `sp:dogfood-testing@1.2` — dual-path always-on delivery, status model, Cost
+block with multi-source honesty. Bump this field when the contract changes. **@1.2 changes:**
+finalize hard structure (unique §1–§6 headings; Issues requires `#### Fixed` + `#### Unresolved`);
+mandatory summary footer mirrored at the report end (footer missing ⇒ `status: complete` refused);
+ledger cardinality (data rows == declared executed steps); protocol string normalized to the
+colon form — the dash form `sp-dogfood-testing@…` is rejected in new runs.
+
+## Always-on dual artifacts (delivery contract)
+
+Every dogfood run **always** writes **two** files — with or without `--save`:
+
+| Artifact | Path | Role |
+|----------|------|------|
+| **Live** | `.spur/run/dogfood/<run_id>.md` | Mid-run SSOT; opened in Phase 1; ledger rows appended on every step resolve |
+| **Report** | `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md` | Operator artifact; same content promoted on open + every step + finalize |
+
+`--save` is **back-compat no-op** for delivery: it still documents/prints the report path but is
+**not required** to create the file. A run that ends with no file under `docs/dogfood/` (and no live
+file under `.spur/run/dogfood/`) has failed the dogfood delivery contract.
+
+### Frontmatter (canonical — every artifact MUST open with this)
+
+```yaml
+---
+run_id: <uuid-or-timestamp-slug>
+status: running | aborted | complete
+testee: "<exact invocation string>"
+classification: slash-command | agent-skill | cli
+mode: observe-only | fix
+max_retry: <n>
+testee_agent: omitted | <name>
+started_at: <ISO-8601>
+finished_at: <ISO-8601 or null while running>
+live_path: .spur/run/dogfood/<run_id>.md
+report_path: docs/dogfood/YYYY-MM-DD-<slug>-dogfood.md
+protocol: sp:dogfood-testing@1.2
+workspace_fingerprint:    ← optional — recorded in Phase 1 for fix-mode and mutating-`--fix` dogfoods
+  head: <`git rev-parse HEAD`>
+  porcelain_hash: <sha256 of `git status --porcelain`>
+  taken_at: <ISO-8601>
+---
+```
+
+### Status model (partial-OK)
+
+| `status` | When |
+|----------|------|
+| `running` | Phase 1 opened; steps still in progress |
+| `aborted` | Finalize-or-abort after mid-run stop / incomplete narrative |
+| `complete` | Phase 4 finished a normal end-of-run report |
+
+A mid-run death that left only a live file with `status: running` and ledger rows is still valid
+partial evidence. On any intentional stop, the driver MUST run finalize-or-abort and set
+`complete` or `aborted` — never leave a deliberate stop at `running`.
+
+Unfinished narrative sections (What We Did / Issues / Findings) use:
+
+```
+⚠ incomplete — not reached
+```
+
+Never invent narrative for steps that did not run.
+
+## Section contract
+
+Emit these sections in order. Headings are fixed (machine-parseable); never rename or drop one.
+Skeleton is written in Phase 1; filled as the run progresses; finalized in Phase 4.
+
+### 1. Testee
+
+```
+## Dogfood Report — `<testee invocation>`
+
+### 1. Testee
+
+- **Command:** `<slash command or CLI invocation>`
+- **Classification:** `slash command` | `agent skill` | `CLI invocation`
+- **Exact invocation:** the underlying `Skill()` call or shell command
+- **Repro:** `<exact string an operator can re-run>`
+- **Testee agent:** `<value forwarded via --agent>` | `omitted (testee runs in current session)`
+- **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>`
+```
+
+When `status` is `aborted` or the report is partial, add under §1:
+
+```
+- **Delivery status:** aborted | partial  ⚠ incomplete run
+```
+
+### 2. Execution Summary
+
+```
+### 2. Execution Summary
+
+- **Result:** PASS / PARTIAL / FAIL  `(N fixed, N unresolved, N findings)`
+- **Wall-clock:** ~N min  `[~estimate]`
+- **Steps:** N derived, N executed, N N/A
+- **Fix attempts:** N (one brief label per fix)
+
+#### Cost
+- **Ledger estimate:** ~N total | ~N cached (~X% hit rate)  `[~estimate]`
+- **Method:** chars/4 heuristic (monitor-ledger.md); confidence: LOW
+- **Meter:** n/a
+```
+
+**Cost honesty rules:**
+
+- Always include ledger-derived `~estimate` total / cached / cache% 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.
+- Never present an unsubstantiated precise integer as billed/metered cost.
+- Aggregate cache% MUST equal the ledger formula (see §3); otherwise the report is invalid.
+- **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
+  subagent/session whose usage the driver cannot read, label the row `~unknown` and emit a P3 finding.
+  See [SKILL.md §Cost segmentation for implement-heavy steps](../SKILL.md#cost-segmentation-for-implement-heavy-steps).
+
+**Verdict rule** — `PASS` = every step ran and no unresolved issue; `PARTIAL` = ran to the end but
+≥1 unresolved issue; `FAIL` = the run could not complete (a step blocked all downstream steps). A
+finding alone never lowers the verdict — findings are improvements, not failures.
+
+**The verdict grades the TESTEE, not the surrounding task.** If the testee is a
+pipeline/command and it failed, the verdict is `FAIL` (or `PARTIAL` per the rule above) even
+when the task was completed by other means; record the recovery under Issues/What-We-Did,
+never in the verdict value. Only `PASS` / `PARTIAL` / `FAIL` are legal values.
+
+### 3. Monitor Ledger
+
+The report MUST include the live ledger table before the narrative. Do not summarize the ledger away:
+it is the audit trail for step outcomes, fix attempts, findings, and cache math. Rows are written to
+**disk** (both artifacts) when each step resolves — see [monitor-ledger.md](monitor-ledger.md).
+
+```
+### 3. Monitor Ledger
+
+| Step | Attempts | Outcome | Fix Applied | Finding | Fresh Tokens | Cached Tokens | Cache % | Basis | Wall-clock |
+|------|----------|---------|-------------|---------|--------------|---------------|---------|-------|------------|
+| resolve | 1 | PASS | — | — | ~800 | ~300 | 27% | 1 command + reused task summary | ~3s |
+
+**Cache calculation:** aggregate cache% = round((sum(Cached Tokens) / sum(Fresh Tokens + Cached Tokens)) * 100).
+```
+
+Ledger rules:
+
+- Every executed step gets exactly one row, recorded when the step resolves (**on disk**, both files).
+- `Fresh Tokens` and `Cached Tokens` must be numbers with `~` prefixes; `Cache %` must be computed
+  from those two cells, not guessed.
+- `Basis` is mandatory. It names the observable inputs used for the estimate: command output,
+  previously-read file reused from context, generated report text, or similar.
+- The aggregate cache line in `#### Cost` under §2 must equal the ledger formula above. If it
+  does not, the report is invalid.
+- **Cardinality (@1.2):** the number of ledger data rows MUST equal the `**Steps:** N derived, N executed`
+  declared in §2. Steps marked N/A are documented explicitly as their own rows (`Outcome: N/A`);
+  an unaccounted step or an extra row refuses `status: complete` at finalize.
+- If the driver cannot make a defensible estimate for a row, write `~0` cached and explain the
+  missing basis in `Basis`; do not invent a stable percentage.
+
+### 4. What We Did
+
+Narrative, one numbered entry per logical action (a step, a fix, a gate check). Include `path:line`
+references. Someone should understand the run without reading the ledger.
+
+```
+### 4. What We Did
+
+1. **Action label** — what happened, what was observed, the decision made.
+2. **Action label** — …
+```
+
+If the run aborted before narrative was written: `⚠ incomplete — not reached`.
+
+### 5. Issues
+
+Always include both sub-headings, with `(none)` when empty — consistent structure matters for parsing.
+
+```
+### 5. Issues
+
+#### Fixed
+
+1. **Issue title** — description.
+   - Root cause: why it happened.
+   - Fix: `file:line` + one-line summary of the change.
+
+#### Unresolved
+
+- (none)  |  each with diagnosis + everything tried.
+```
+
+### 6. Findings
+
+Findings are the **fine-tuning payload**. Each carries a severity, a `file:line`, and a concrete
+**recommended action** — what to change, not just what's wrong. Default lists P1+P2; `--full` adds
+P3+P4.
+
+```
+### 6. Findings
+
+- **P1** — <what's wrong>. → **Action:** <concrete change>.  (`file:line`, ~effort)  `[feasible]`
+- **P2** — …
+```
+
+Each finding MUST carry a **verification-feasibility tag** in brackets at the end of the line, so
+downstream task creation does not inherit an unactionable acceptance criterion:
+
+- `[feasible]` — the recommendation is verifiable (a test, a CLI check, an observable behavior).
+  This is the default; most findings are feasible.
+- `[stale]` — on re-check the finding no longer holds (the code already does the right thing, the
+  condition was misread). Do **not** file as a task — close inline with evidence. Catching this at
+  report time saves a no-op implementation task downstream.
+- `[unverifiable]` — the recommendation cannot be confirmed with existing tooling (e.g. a
+  cache-hit finding with no per-step telemetry; a perf claim with no measurement loop). If filed as
+  a task, its acceptance criterion must be reframed to what *can* be verified (e.g. "ship the
+  lever; measured proof deferred"), or the task should be deferred until the missing tooling exists.
+  Do not let it become a normal implementation task — it will ship an unverifiable "improvement."
+
+The tag is a prompt to whoever turns findings into tasks: `[stale]` → drop, `[unverifiable]` →
+reframe or defer, `[feasible]` → proceed. A finding without a tag is treated as `[feasible]`.
+Severity scale:
+- **P1** — blocks correct use or causes drift/wrong output; fix before shipping the testee.
+- **P2** — real friction or a latent correctness gap; fix soon. **Includes mandatory workspace-drift
+  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).
+- **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).
+
+**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
+command names with a live-surface grep over the command and agent roots before filing a stale-routing
+finding. A deliberate rejection note in a reference file is not a live surface.
+
+## Phase 4 — finalize-or-abort (non-skippable terminal gate)
+
+Before the skill may stop (success, partial, fail, observe-only end, or abort), the driver MUST:
+
+1. Set frontmatter `status: complete` or `status: aborted` (and `finished_at`).
+2. **Structure scrub (@1.2):** all six mandatory section headings exist **exactly once each**
+   (`### 1.` … `### 6.` — a duplicated heading refuses `complete`); §5 Issues carries both
+   `#### Fixed` and `#### Unresolved` (`(none)` when empty); unfinished narrative uses
+   `⚠ incomplete — not reached`; no leftover "run in progress" markers survive finalization.
+3. **Ledger cardinality (@1.2):** Monitor Ledger data rows == the `**Steps:** N derived, N executed` declared in
+   §2 (N/A steps documented explicitly as rows; drift rows count separately, not toward executed
+   steps — include `drift:external` rows in the table but subtract them from the executed count in
+   §2). A mismatch refuses `complete`.
+4. Write the Cost block (method + confidence + Meter).
+5. **R2 drift check at finalize.** If a workspace fingerprint was recorded, re-take snapshot
+   and diff against baseline minus run-touched files. Detected drift → append `drift:external`
+   ledger row + mandatory P2 finding. See [SKILL.md §Workspace-drift guard](../SKILL.md#workspace-drift-guard-r2--task-0296).
+6. Sync final content to **both** live and report paths.
+7. **Footer mandatory (@1.2):** print the mandatory summary footer with **both** paths always,
+   and mirror the footer block at the **end of the report file**. A report whose body lacks the
+   footer cannot set `status: complete`.
+8. **Self-validate (task 0278 R6):** run
+   `bun plugins/sp/scripts/dogfood-testing/validate-report.ts --file <report-path>` before
+   claiming `status: complete`. Exit 2 → `status: aborted` + list error codes under
+   `#### Unresolved` (never force complete on a non-@1.2 shape).
+9. **Refusal rule (@1.2):** when any check above fails, set `status: aborted` and list every
+   failed check under §5 `#### Unresolved` — never force `complete`.
+
+Any early-exit path still runs this checklist. Stopping without it is a **driver contract violation**.
+
+## Mandatory Summary Footer
+
+Print **after every run, inline, always** — it is the last thing the user sees.
+
+```
+── Dogfood Summary ──
+Result: PASS   (N fixed, N unresolved, N findings)
+Tokens: ~N total  |  ~N cached (~X% hit rate)  [~estimate]
+
+Fixed issues:
+  • <label>   (or: (none))
+
+Unresolved issues:
+  • <label>   (or: (none))
+
+Findings (P1+P2):
+  • P? — <label>   (or: (none))
+
+[Live: .spur/run/dogfood/<run_id>.md]
+[Report: docs/dogfood/YYYY-MM-DD-<slug>-dogfood.md]
+[Task: <wbs>]      ← only with --task
+```
+
+Rules:
+- **Result** and **Tokens** lines are mandatory; always tag token numbers `[~estimate]`.
+- List Fixed / Unresolved / Findings; print `(none)` when empty — never omit a sub-list.
+- With `--full`, Findings include P3+P4.
+- If PASS with zero issues and zero findings: collapse to one line `Result: PASS — no issues, no
+  findings.` (still print the Tokens line).
+- **`[Live:]` and `[Report:]` are always printed** after a normal stop (not gated on `--save`).
+- Print `--task` WBS only when that sink ran.
+
+## Task sink — the `task check` L3 contract
+
+`--task` files findings as a `review`-template task:
+
+```bash
+spur task create "<testee> dogfood findings" --template review --json
+```
+
+Write the **Unresolved issues** and **Findings** into the task's `#### Review Findings` table — one
+row per item: `Severity` (`P1`–`P4`), `File`, `Finding`, `Recommendation`. That heading is a
+sub-section of `### Background`, so:
+
+```bash
+spur task update <wbs> --section "Background" --from-file <path>   # body starts with "#### Review Findings"
+```
+
+**Where the P-rows live, and how the L3 Review rule behaves.** The review template ships two tables:
+`#### Review Findings` (under `### Background`) is the *input* you populate from the dogfood findings;
+`### Review` is the *post-fix reflection* table, shipped as an **empty-cell scaffold**
+(`| P1 | | | |`). `spur task check`'s L3 Review rule keys off `### Review`, not `#### Review Findings`:
+
+- Write the dogfood findings into **`#### Review Findings`** (that is the `--task` sink target).
+- Leave **`### Review`** as the shipped empty-cell scaffold. The hardened L3 rule tolerates the empty
+  scaffold **wherever `### Review` is optional** (review variant: `backlog`/`todo` — the freshly
+  created state) and only requires a *populated* P-table once `### Review` becomes **required**
+  (`wip`+). So a freshly created `review` task at `backlog`/`todo` passes `task check` with the
+  scaffold untouched — no hand-written P-row is needed, and a bare prose note in `### Review` is the
+  thing that errors (it is neither the scaffold nor a populated table).
+
+Always verify with `spur task check <wbs> --json` before handoff; the sink path below writes only
+`#### Review Findings` and leaves `### Review` as the scaffold.