@gobing-ai/spur 0.3.76 → 0.3.78

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -257,29 +257,129 @@ function extractRequirementIds(taskContent: string): string[] {
     return [...ids];
 }
 
-function extractAcIdentities(taskContent: string, featureContent: string | null): string[] {
-    const identities = new Set<string>();
+// ─── Canonical AC identity resolution (task 0804 R4) ─────────────────────────
+
+/**
+ * Strip the tolerated AC-id wrappers (bracket tags, `Scenario:` prefix) until
+ * fixpoint — the shared first step of `normalizeAcTitle` and the `AC-N` alias
+ * path in `resolveAcIdentity`.
+ */
+function stripAcWrappers(title: string): string {
+    let out = title.trim();
+    let prev: string;
+    do {
+        prev = out;
+        out = out
+            .replace(/^\[[^\]]*\]\s*/, '')
+            .replace(/\s*\[[^\]]*\]\s*$/, '')
+            .replace(/^Scenario:\s*/i, '')
+            .trim();
+    } while (out !== prev);
+    return out;
+}
+
+/**
+ * Normalize an AC identity to its canonical key, mirroring the documented
+ * matching behavior of feature-check `rowMatchesScenario` + ac-style-guide
+ * "Four accepted id forms" (exact/bare title, `Scenario:` prefix, bracket
+ * tags, `AC-N` ordinal) without importing that private matcher or adopting
+ * its permissive trailing-Gherkin fallback (0804 R4). Comparison is
+ * case/quote/whitespace-insensitive. A paraphrase normalizes differently
+ * and still fails.
+ */
+function normalizeAcTitle(title: string): string {
+    return (
+        stripAcWrappers(title)
+            .replace(/^R\d+\s*[:\-—]?\s*/, '')
+            .toLowerCase()
+            // Exact pre-refactor removal set (0809 R5): ASCII apostrophe + the four curly
+            // quotes. Escaped form keeps U+0027 visible next to lookalike curly glyphs;
+            // U+02BC stays a meaningful character, never removable punctuation.
+            .replace(/[\u0027\u2018\u2019\u201c\u201d]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim()
+    );
+}
+
+/**
+ * Declared AC identities keyed by canonical normalized title, plus the two
+ * AC-N ordinal sources (task scenario list and linked-feature scenario list).
+ * A checklist-declared spelling always wins over the positional alias.
+ */
+interface AcIdentityIndex {
+    /** normalized canonical title → a declared spelling (label, token, or title). */
+    readonly byTitle: Map<string, string>;
+    /** AC-N → task scenario title at that 1-based ordinal. */
+    readonly taskScenarios: string[];
+    /** AC-N → feature scenario title at that 1-based ordinal. */
+    readonly featureScenarios: string[];
+}
+
+function buildAcIdentityIndex(taskContent: string, featureContent: string | null): AcIdentityIndex {
+    const byTitle = new Map<string, string>();
+    // Not named `declare`: Bun's TS transpiler treats a call to an identifier
+    // named `declare` as an ambient-declaration modifier and drops it.
+    const declareIdentity = (spelling: string): void => {
+        const key = normalizeAcTitle(spelling);
+        if (key !== '' && !byTitle.has(key)) byTitle.set(key, spelling);
+    };
     const section = sectionBetween(taskContent, 'Acceptance Criteria');
-    // Checkbox labels (`- [x] AC1 (R1): …`, 0726) and plain bullets (`- AC1: Given …`,
-    // 0713/0727) both yield the label text up to `:` plus its leading token.
     for (const m of section.matchAll(/^[-*]\s+(?:\[[ xX]\]\s+)?(.+?)\s*(?::|$)/gm)) {
         const label = (m[1] ?? '').trim();
         if (!label) continue;
-        identities.add(label);
+        declareIdentity(label);
         const leading = label.split(/\s+/)[0] ?? '';
-        if (leading && leading !== label) identities.add(leading);
+        if (leading && leading !== label) declareIdentity(leading);
     }
-    for (const m of section.matchAll(/^[ \t]*Scenario:\s*(.+)\s*$/gm)) {
-        const title = (m[1] ?? '').trim();
-        if (title) identities.add(title);
-    }
-    if (featureContent !== null) {
-        for (const m of featureContent.matchAll(/^[ \t]*Scenario:\s*(.+)\s*$/gm)) {
-            const title = (m[1] ?? '').trim();
-            if (title) identities.add(title);
+    const scenarioTitles = (content: string): string[] =>
+        [...content.matchAll(/^[ \t]*Scenario:\s*(.+)\s*$/gm)].map((m) => (m[1] ?? '').trim()).filter((t) => t !== '');
+    const taskScenarios = scenarioTitles(sectionBetween(taskContent, 'Acceptance Criteria'));
+    const featureScenarios = featureContent !== null ? scenarioTitles(featureContent) : [];
+    for (const title of [...taskScenarios, ...featureScenarios]) declareIdentity(title);
+    return { byTitle, taskScenarios, featureScenarios };
+}
+
+/** Resolution outcome for one AC row id. */
+type AcIdentityResolution = { ok: true; canonical: string } | { ok: false; error: string };
+
+/**
+ * Resolve an answer-file AC row id to one canonical task identity (0804 R4):
+ * exact/declared title forms first, then the documented `AC-N` positional
+ * alias — accepted only against a real scenario ordinal, and refused with an
+ * actionable diagnostic when task and feature ordinals disagree. Undeclared
+ * `ACn` tokens, paraphrases and invented ordinals never resolve.
+ */
+function resolveAcIdentity(rowId: string, index: AcIdentityIndex): AcIdentityResolution {
+    const canonical = index.byTitle.get(normalizeAcTitle(rowId));
+    if (canonical !== undefined) return { ok: true, canonical };
+    // Strip the tolerated wrappers, then try the documented `AC-N` alias.
+    const stripped = stripAcWrappers(rowId);
+    const ordinal = /^AC-(\d+)$/i.exec(stripped);
+    if (ordinal !== null) {
+        const n = Number(ordinal[1]);
+        const taskTitle = index.taskScenarios[n - 1];
+        const featureTitle = index.featureScenarios[n - 1];
+        const candidates = [...new Set([taskTitle, featureTitle].filter((t): t is string => t !== undefined))];
+        if (candidates.length === 0) {
+            return {
+                ok: false,
+                error:
+                    `AC id "${rowId}" uses the AC-${n} positional alias but no scenario exists at that ordinal ` +
+                    '(task scenario list and linked-feature scenario list) — cite the exact scenario title or checklist label',
+            };
+        }
+        if (candidates.length > 1) {
+            return {
+                ok: false,
+                error:
+                    `AC id "${rowId}" is ambiguous: task AC #${n} ("${taskTitle}") and feature scenario #${n} ` +
+                    `("${featureTitle}") are different scenarios with different ordering — cite the exact title`,
+            };
         }
+        const resolved = index.byTitle.get(normalizeAcTitle(candidates[0] ?? ''));
+        if (resolved !== undefined) return { ok: true, canonical: resolved };
     }
-    return [...identities];
+    return { ok: false, error: '' };
 }
 
 // ─── Main ────────────────────────────────────────────────────────────────────
@@ -341,7 +441,7 @@ function main(): void {
     }
 
     const reqIds = extractRequirementIds(taskContent);
-    const acIdentities = extractAcIdentities(taskContent, featureContent);
+    const acIndex = buildAcIdentityIndex(taskContent, featureContent);
 
     // Requirement rows: completeness, no unknowns, no duplicates, valid status, non-empty evidence.
     const seenReq = new Set<string>();
@@ -358,19 +458,31 @@ function main(): void {
         if (!seenReq.has(id)) add(`missing requirement row for "${id}"`);
     }
 
-    // AC rows: identity must exactly match a checklist label/token or a scenario title;
-    // status and evidence type must normalize; evidence non-empty. AC completeness is the
-    // verifier's authoring contract, not a lint rejection class (0726 R3).
-    const seenAc = new Set<string>();
+    // AC rows: identity must resolve to ONE canonical task AC identity — a
+    // checklist label/token or a scenario title in any ac-style-guide form
+    // (exact/bare title, `Scenario:` prefix, bracket tags, declared AC-N
+    // alias; 0804 R4). Alias-equivalent spellings of the same identity are
+    // duplicates even when the raw strings differ. Status and evidence type
+    // must normalize; evidence non-empty. AC completeness is the verifier's
+    // authoring contract, not a lint rejection class (0726 R3).
+    const seenAc = new Map<string, string>(); // canonical key → first raw row id
     for (const row of tables.acs) {
-        if (!acIdentities.includes(row.id)) {
+        const resolution = resolveAcIdentity(row.id, acIndex);
+        const canonicalKey = resolution.ok ? normalizeAcTitle(resolution.canonical) : null;
+        if (!resolution.ok) {
+            if (resolution.error !== '') add(`line ${row.line}: ${resolution.error}`);
+            else
+                add(
+                    `line ${row.line}: AC ID "${row.id.slice(0, 60)}" matches no task AC checklist label or scenario title ` +
+                        '(accepted forms: exact title, bare title, `Scenario:` prefix, bracket tags, declared AC-N alias)',
+                );
+        } else if (canonicalKey !== null && seenAc.has(canonicalKey)) {
+            const first = seenAc.get(canonicalKey) ?? '';
             add(
-                `line ${row.line}: AC ID "${row.id.slice(0, 60)}" matches no task AC checklist label or scenario title`,
+                `line ${row.line}: duplicate AC row "${row.id.slice(0, 60)}" — alias-equivalent to "${first.slice(0, 60)}"`,
             );
-        } else if (seenAc.has(row.id)) {
-            add(`line ${row.line}: duplicate AC row "${row.id.slice(0, 60)}"`);
         }
-        seenAc.add(row.id);
+        if (canonicalKey !== null && !seenAc.has(canonicalKey)) seenAc.set(canonicalKey, row.id);
         if (normalizeAcStatus(row.status) === null)
             add(`line ${row.line}: invalid AC status "${row.status}" (MET | PARTIAL | UNMET | N/A)`);
         if (normalizeEvidenceType(row.evidenceType) === null)
@@ -396,4 +508,5 @@ function main(): void {
     process.exit(0);
 }
 
-main();
+// CLI entry (guarded so the helpers stay importable for focused tests).
+if (import.meta.main) main();

package/plugins/sp/skills/code-verification/SKILL.md

@@ -117,8 +117,8 @@ assign a per-requirement status:
 | **PARTIAL** | Evidence for part of the requirement only |
 | **UNMET** | No implementation evidence found |
 
-Record the evidence string (repo-relative path `file:line`, e.g. `packages/app/src/services/task-check.ts:42`, command, or test name) per requirement — this is what lands
-in `## Testing`.
+Record the evidence string (repo-relative `file:line`, command, or test name) per requirement —
+this lands in `## Testing`.
 
 **Line-anchor verification (anti-stale-citation rule).** Every `file:line` evidence citation
 written into the Testing table MUST be re-read at the cited lines this run, and the re-read content
@@ -142,6 +142,8 @@ classifies it as external and never raises `L4.stale-line-anchor` for it (R1). D
 that lives in this repo — in-repo evidence MUST use the repo-relative backtick form
 `` `path:line` `` / `` `path:start-end` ``, and citing it in the external form still reports (R2).
 
+**Concrete anchors (0804 R9):** cite existing `file:line`s, never globs — `references/verdict-schema.md`.
+
 ### Step 5 — Acceptance Criteria guard
 
 If the task has a non-empty Acceptance Criteria section, evaluate every checklist item and every

package/plugins/sp/skills/code-verification/references/verdict-schema.md

@@ -110,12 +110,21 @@ For answer files, emit a matching parseable table:
 `Verdict: PARTIAL` first, append one complete row at a time, and replace the first verdict line only
 after every row is certified. `verify-answer-lint.ts` gates the file before `spur task verdict
 --from-answer` and rejects, with row-level diagnostics: missing/duplicate/unknown requirement IDs,
-AC ids that do not exactly match a task AC checklist label (or its leading token, e.g. `AC1`) or a
-linked feature scenario title, invalid status (`MET | PARTIAL | UNMET` for requirements;
+AC ids that do not resolve to one accepted identity — a task AC checklist label or its declared
+`AC-N`/checklist-token alias, or a linked feature scenario title, in the ac-style-guide forms
+(exact/bare title, `Scenario:` prefix, bracket tags, `AC-N`); paraphrases and ambiguous aliases
+fail — invalid status (`MET | PARTIAL | UNMET` for requirements;
 `N/A` additionally allowed for AC), invalid evidence type (`test | command | static-ref |
 manual-review | llm-judge | n/a`, or a `+` compound), and empty evidence. Interrupted runs keep the
 rows that pass the lint and complete only the missing IDs on retry.
 
+**Concrete anchors only (task 0804 R9).** An evidence anchor must be a concrete existing `file:line`
+(or `file:start-end`) path. A glob or directory summary (`src/services/*.ts`, `the retry
+classifiers in task-pipeline.yaml`) is not an anchor: expand it into the specific cited files/ranges
+the run actually verified. Since 0804 R9 the checker ignores complete parsed citation spans before
+scanning for subjects, so a citation's filename (including snake_case paths) can never become a
+false subject — a real absent symbol, nonexistent file, or invalid range still reports.
+
 ## Checks evidence
 
 Wave C verification can emit the following additive `checks[]` rows:

package/plugins/sp/skills/dogfood-testing/SKILL.md

@@ -39,7 +39,8 @@ sinks; this skill owns the protocol.
 testee (a /sp:... command, Skill(...), or shell CLI invocation)
   → PLAN     classify + derive steps + open dual artifacts (live + docs/dogfood) with status:running
   → EXECUTE  run each step as a user; on failure, bounded diagnose→fix→re-run (or observe-only)
-  → MONITOR  dual-write ledger row to disk on every step resolve — never reconstruct from memory
+  → MONITOR  live-ledger row to disk every step resolve; mirror frozen inside a proof window —
+             never reconstruct from memory
   → REPORT   finalize-or-abort (non-skippable): status complete|aborted, Cost block, both paths, footer
 ```
 
@@ -105,9 +106,8 @@ The command forwards these via `$ARGUMENTS`:
    ```
 
    - Exit **2** → print the stdout refuse line and **stop** (do not plan). The CLI refuses on either
-     of two independent mutation sources (task 0293); print whichever refuse message it emits:
-     - pipeline-driving: `⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)`.
-     - mutating `--fix`: `⚠ mutating --fix mode detected (--fix all | --fix blockers-first); pass --max-retry 0 (observe-only for the driver; the testee still mutates the tree) or --max-retry N (fix mode, driver + testee both mutate)`.
+     of two independent mutation sources (task 0293); its two refuse lines are the ones quoted
+     verbatim in the repo-mutation warning above.
    - Exit **0** → proceed. Do not auto-substitute `--max-retry 0`.
    - The matcher contract is unit-checked by `tests/dogfood-testing/pipeline-detect.test.ts`.
      See [§Pipeline-driving word-boundary contract](#pipeline-driving-word-boundary-contract) and
@@ -186,17 +186,18 @@ report — the report is assembled from the files, not from memory.
 On **every** step resolve:
 
 1. Append/update the ledger row on the **live** file first.
-2. Mirror the same row to the **report** path under `docs/dogfood/`.
+2. Mirror the same row to the **report** path under `docs/dogfood/` — unconditional **outside** a
+   pipeline proof window; **inside** one the mirror stays **frozen** (live rows only) until the
+   window closes, then sync/validate with live-based recovery (task 0804 R2 —
+   [monitor-ledger.md](references/monitor-ledger.md) live-ledger rule 3).
 3. Do **not** batch rows until Phase 4.
 
-The final report MUST include a `### 3. Monitor Ledger` section containing those rows, and the
-ledger's data-row count MUST equal the `**Steps:** N derived, N executed` declared in §2 of the report (N/A steps
-documented explicitly as rows) — the cardinality rule in
-[monitor-ledger.md](references/monitor-ledger.md). Full
-methodology, column contract, token/cache estimation, multi-source Cost honesty, the cache-health
-finding rule, and the **cache-conservation discipline** live in
-**[monitor-ledger.md](references/monitor-ledger.md)**. Apply the conservation discipline while
-monitoring — low cache% is usually the driver re-fetching data it already holds.
+The final report MUST include a `### 3. Monitor Ledger` section containing those rows (cardinality:
+row count == the declared executed steps). Cardinality, full methodology, column contract,
+token/cache estimation, multi-source Cost honesty, the cache-health finding rule, and the
+**cache-conservation discipline** live in
+**[monitor-ledger.md](references/monitor-ledger.md)** — apply conservation while monitoring; low
+cache% is usually the driver re-fetching data it already holds.
 
 ## Phase 4 — Report (finalize-or-abort — non-skippable)
 
@@ -214,8 +215,9 @@ contract violation**.
    declared in §2 (N/A steps documented explicitly as rows). A mismatch refuses `complete`.
 4. Write the **Cost** block under §2 (ledger `~estimate` + Method + confidence; `Meter: n/a` or
    optional ccusage/agent usage when real). For any `chained:<step>` ledger row whose meter is not
-   observable, Fresh/Cached MUST be `~unknown` (or Cached `~0` with Basis `unobservable`) **and**
-   emit finding `P3 — chained-step cost not observable` — never invent chained totals.
+   observable, Fresh/Cached MUST be `~unknown` — excluded from the cache% aggregate (or surfaced as
+   a separate unknown bucket), never counted as `Cached ~0` — **and** emit finding
+   `P3 — chained-step cost not observable`; never invent chained totals.
 5. **R2 drift check at finalize.** If a workspace fingerprint was recorded in Phase 1, re-take
    the snapshot and diff against baseline minus the run's own touched files. If drift is detected,
    append a `drift:external` warning row to the ledger and emit a mandatory P2 report finding
@@ -292,13 +294,15 @@ Do **not** use this skill for:
    mutating pipeline — pass `--max-retry 0` first and inspect the findings before letting it apply
    fixes.
 2. **The ledger is live on disk, not reconstructed.** Honest fixed-vs-unresolved accounting depends
-   on dual-writing each step *as it happens* to both artifacts. Reconstructing at the end produces
-   fiction. Working-memory-only ledgers are a contract violation.
+   on writing each step *as it happens* to the live file (mirror per Phase 3 — frozen inside a proof
+   window). Reconstructing at the end produces fiction. Working-memory-only ledgers are a contract
+   violation.
 3. **A hiding fix is a finding.** If "fixing" a step would mask the bug, log it as a finding and
    leave the step unresolved.
 4. **Token numbers are estimates, but cache math is not free-form.** A skill cannot read its own
    exact token meter, so label numbers `~estimate` and put Method + confidence in the Cost block;
-   however, cache% must be recomputable from Monitor Ledger row sums. Never invent or reuse a fixed
+   however, cache% must be recomputable from Monitor Ledger row sums of observable rows (`~unknown`
+   rows are excluded from the aggregate, never counted as `~0` cached). Never invent or reuse a fixed
    percentage. Optional meters (`ccusage`, agent usage) are session/day scope — never fake per-step.
 5. **Testee-scoped `--agent`.** Don't confuse the driver agent (always current) with the testee
    agent (the forwarded value).
@@ -431,11 +435,10 @@ baseline is drift.
 ### Worktree advisory (mutating dogfoods)
 
 For fix-mode dogfoods of **pipeline-driving** or **mutating-`--fix`** testees (the two refuse-gate
-cases above), the §Mutating `--fix` mode contract recommends running the dogfood in an **isolated
-`git worktree`** so concurrent external writers cannot collide with the run. This is **advisory,
-not a hard gate** — the refuse-gate semantics from task 0293 are unchanged. A worktree removes the
-drift case entirely (no concurrent writer can reach the isolated checkout), which is why it is the
-preferred setup for mutating dogfoods where the operator cares about clean attribution.
+cases above), run in an **isolated `git worktree`** — **advisory, not a hard gate**. Phase 1 must
+print this advisory whenever the driver or testee may mutate and the tree is dirty, **or** the
+testee drives a pipeline (incl. observe-only over a mutating testee). Rationale, trigger matrix
+and wording: `references/monitor-ledger.md`.
 
 ## Step-splitting recipe (implement-heavy pipeline dogfoods)
 
@@ -486,8 +489,9 @@ Rules:
 2. When the chained step ran in a subagent or session whose usage data the driver cannot read, label
    the chained row `~unknown` and emit a **P3** finding: "chained-step cost not observable — candidate
    for surfacing subagent usage in the driver context." Do not invent a number.
-3. The chained row still counts toward the aggregate cache% — but mark it pessimistically
-   (`Cached = ~0`) when the basis is missing, per the anti-fiction rule in
+3. An observable chained row counts toward the aggregate cache%. A `~unknown` chained row is
+   **excluded** from the aggregate (or surfaced as a separate unknown bucket) — never folded in as
+   `Cached = ~0` — per the anti-fiction rule in
    [monitor-ledger.md](references/monitor-ledger.md).
 
 ## `--next` chain stop-at-testing
@@ -518,18 +522,17 @@ Do NOT:
   driver permission to read the chained leg's named artifacts (`.spur/run/<wbs>-verdict.json`,
   task-file section diffs, review tables) after the leg completes and attribute normally. The flag
   licenses **reading** chained-leg evidence that already exists — it does NOT license the driver to
-  execute the chained leg itself. The legacy "operator may direct" prose direction is still honored
-  for back-compat; `--chain-follow` is the explicit, machine-recognizable form. Omitting the flag
-  keeps stop-at-testing as the **default**. The flag is a driver attribute only — it does not change
-  `detect-pipeline-driving` gate semantics (it is not a testee mutation source). See
-  [§Arguments](#arguments).
+  execute the chained leg itself. The legacy "operator may direct" prose direction stays honored for
+  back-compat; omitting the flag keeps stop-at-testing as the **default**. The flag is a driver
+  attribute only — it does not change `detect-pipeline-driving` gate semantics (it is not a testee
+  mutation source). See [§Arguments](#arguments).
 
 ## Additional Resources
 
-- [references/report-template.md](references/report-template.md) — the report section contract +
-  mandatory summary footer + task-sink L3 rule.
-- [references/monitor-ledger.md](references/monitor-ledger.md) — the live-ledger column contract,
-  token/cache estimation heuristic, and the cache-health finding rule.
+- [references/report-template.md](references/report-template.md) — report section contract,
+  mandatory footer, task-sink L3 rule.
+- [references/monitor-ledger.md](references/monitor-ledger.md) — live-ledger column contract,
+  token/cache estimation, cache-health finding rule.
 
 ## Platform Notes
 
@@ -565,8 +568,10 @@ shape just because `report-template.md` wasn't auto-loaded.
 - Report: `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md`
 
 Both start with YAML frontmatter including `status: running | aborted | complete`, `run_id`,
-`protocol: sp:dogfood-testing@1.2`, and paths. Dual-write a ledger row to both files on every step
-resolve. On stop, set `status` to `complete` or `aborted` (finalize-or-abort — non-skippable).
+`protocol: sp:dogfood-testing@1.2`, and paths. Write each ledger row to the live file on every step
+resolve; mirror it to the report only outside a proof window — frozen inside one, synced at
+finalize (Phase 3). On stop, set `status` to `complete` or
+`aborted` (finalize-or-abort — non-skippable).
 
 **The six mandatory section headings** (in order, each report MUST contain all six):
 

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

@@ -28,9 +28,14 @@ artifacts):
 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.
+3. **Dual-write every step — EXCEPT inside a proof window (task 0804 R2).** Append/update the row
+   on the **live** file first; the live file is SSOT. While a pipeline proof window is open (from
+   the first proof capture until the final proof-sensitive action, including done/provenance
+   checks), the tracked report mirror stays **frozen**: append each observation to the live ledger
+   only, and sync/validate the mirror after the window closes (or after abort). Tracked reports are
+   proof-input fingerprint inputs — writing them mid-window churns the fingerprint and voids the
+   proof. If the report write fails at finalize, recover by recreating the mirror from the valid
+   live content and re-validate; missing live evidence cannot manufacture complete.
 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
@@ -44,6 +49,19 @@ artifacts):
    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).
 
+### Worktree advisory — planning-time surfacing (task 0804 R5)
+
+The worktree advisory (SKILL.md §Worktree advisory) is surfaced at planning time, not only when
+drift is detected. Phase 1 prints it whenever the **driver or the testee may mutate** and the tree
+is dirty (`git status --porcelain` non-empty) **or** the testee itself drives a pipeline —
+including observe-only driver mode over a mutating testee. The advisory is **not a hard gate** (the
+refuse-gate semantics from task 0293 are unchanged); the isolated checkout is simply the preferred
+setup for mutating dogfoods because no concurrent writer can reach it, so attribution stays clean
+— which is why the §Mutating `--fix` mode contract recommends it for those two refuse-gate cases.
+Dirtiness alone is not proof of a concurrent writer and must not be reported as one; known
+concurrent writes still follow the project's one-writer rule. A clean, read-only run adds no
+warning.
+
 ### 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
@@ -81,7 +99,7 @@ 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. |
+| `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. |
 | `Basis` | Observable basis for the estimate: command output, prior file read reused, generated text, etc. |
 | `Wall-clock` | Elapsed time for the step. |
 
@@ -98,8 +116,10 @@ A skill **cannot read its own exact token meter** — derive an estimate and lab
    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:
+3. Compute each row: `Cache % = round(Cached Tokens / (Fresh Tokens + Cached Tokens) * 100)`. A row
+   whose basis is unknown carries `—`, never `0%`.
+4. Compute the report aggregate from **observable rows only** — `~unknown` rows are excluded from
+   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
@@ -132,8 +152,10 @@ 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.
+  label Fresh `~unknown`, Cached `~unknown`, Basis `chained-leg usage not observable from driver`,
+  and **exclude the row from the aggregate cache%** (or surface it as a separate unknown bucket) —
+  unknown cache use is not an observed zero. **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
@@ -142,8 +164,10 @@ testee is to see the testee's own cost separately from the driver's monitoring c
 ## 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.
+is valid only when it can be recomputed from the ledger row sums of observable rows. If the basis is
+missing, mark the row `~unknown`, exclude it from the aggregate (or surface it as a separate unknown
+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
 

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

@@ -27,7 +27,7 @@ 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 |
+| **Report** | `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md` | Operator artifact; same content promoted on open + every step + finalize — **except inside a pipeline proof window (task 0804 R2): the mirror stays frozen (live ledger only) until the window closes, then sync/validate, recovering from live if the write failed** — [monitor-ledger.md](monitor-ledger.md) → live-ledger rule 3 |
 
 `--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
@@ -158,14 +158,17 @@ it is the audit trail for step outcomes, fix attempts, findings, and cache math.
 |------|----------|---------|-------------|---------|--------------|---------------|---------|-------|------------|
 | 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).
+**Cache calculation:** aggregate cache% = round((sum(Cached Tokens) / sum(Fresh Tokens + Cached Tokens)) * 100),
+computed over **observable rows only** — `~unknown` rows are excluded from both sums (or surfaced as
+a separate unknown bucket), never counted as `~0` cached.
 ```
 
 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.
+- `Fresh Tokens` and `Cached Tokens` must be `~`-prefixed numbers, or `~unknown` when the basis is
+  unobservable (that row is then excluded from the aggregate, never counted as `~0` cached);
+  `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
@@ -173,8 +176,9 @@ Ledger rules:
 - **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.
+- If the driver cannot make a defensible estimate for a row, write `~unknown`, exclude it from the
+  aggregate cache% (or surface it as a separate unknown bucket), and explain the missing basis in
+  `Basis`; do not fold it in as `~0` cached or invent a stable percentage.
 
 ### 4. What We Did
 

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -209,6 +209,39 @@ executor is the current coding agent. Interactive pipelines retain a run log and
 through the inline driver; task pipelines additionally record a task run-link. If process isolation or an independently killable
 stage is required, select the subprocess path (`--agent auto` or `--agent <name>`).
 
+## Shared startup contract (task 0814 R1/R3/R4/R6/R7/R8)
+
+The workflow-backed dev commands (`dev-run`, `dev-runall`, `dev-refineall`, `dev-verifyall`) share one
+startup order. The order is load-bearing and applies on both the inline driver and the subprocess
+path; skill-only operations (refine/verify batches with no nested workflow) display their owned
+procedure and do not fabricate a workflow YAML.
+
+1. **Publish a compact bootstrap checklist immediately** (host-preparation rows, never copied
+   workflow states): `A, Quick readiness` · `B, Prepare Git` · `C, Publish workflow plan` ·
+   `D, Comprehensive checking`.
+2. **Quick deterministic readiness (R2), before isolation.** Evaluate `quickReadiness`
+   (`plugins/sp/scripts/batch-preflight.ts`) with the operation, status, filtered-set size, and the
+   selected matrix required/present sections + content-policy findings. This is an admission decision
+   (runnable / needs-refinement / blocked / skipped / invalid), never an implementation certificate.
+3. **Isolation (R3), only when `--worktree` is valid.** After quick readiness and the required Git
+   safety checks, create/adopt and switch to the execution tree; confirm absolute cwd, branch, base
+   SHA, and ownership. An invalid/empty target, unsupported mode, ambiguous ownership, or stale target
+   stops without creating a tree or discarding work. All subsequent tools, agents, corpus writes, and
+   run artifacts use the confirmed execution tree.
+4. **Publish the workflow inventory (R4), before reading the YAML.** `spur workflow show
+   <resolved-file> --no-logo --format todo --json`; validate with `parseWorkflowInventory` and bind to
+   the run's `__definitionDigest` with `assertInventoryIdentity`. Drift or projection failure stops the
+   run before any comprehensive/model work — never execute with a misleading plan.
+5. **Load execution detail and run comprehensive checks (R7).** Only after the plan is visible (and
+   after isolation when requested) load the full YAML for the active stage and run the owning
+   comprehensive gates at their boundaries. Prefer deterministic checks; invoke semantic model work
+   only for an identified unresolved requirement/design/evidence question and record its reason.
+
+Quick readiness and plan projection dispatch zero models and execute zero workflow actions. Record a
+timestamped event trace under `.spur/run/<run-id>-event-trace.md` (R8) — event ordering,
+time-to-first-visible-checklist, time-to-workflow-inventory, confirmed cwd, invocation counts — and
+record unavailable measurements as `unknown`, never as invented savings.
+
 ## Every write is CLI-gated
 
 Never edit a task or feature file directly. Every mutation goes through:

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -446,6 +446,23 @@ isolated git worktree instead of the operator's working directory. This section
 lifecycle for the sequential batch loop. Per-task worktrees and `--mode parallel` isolation stay out
 of scope (task 0142 Slice A); `--worktree --mode parallel` is rejected.
 
+**Startup ordering (task 0814 R3).** Resolve the selector/status filter and run the quick
+command-aware readiness (the `quickReadiness` contract in `batch-preflight.ts`) **before** creating
+or adopting the tree. The admission decision is what determines whether a tree should be cut at all;
+all subsequent tools, agents, task/feature writes, and run artifacts use the confirmed execution
+tree's cwd. A stale or empty selector, an unsupported mode, or an invalid target creates no tree and
+no marker (WT-2/WT-7), and the required Git safety checks (WT-1) still precede creation.
+
+> **Command wiring (task 0814 R3).** The four worktree-capable commands (`dev-run`, `dev-runall`,
+> `dev-refineall`, `dev-verifyall`) each call `quickReadiness` with their operation (`run`/`refine`/
+> `verify`), the resolved selector/status, and the filtered-set size **before** WT-1/WT-2. The
+> admission outcome gates the tree: an invalid/empty selector, unsupported mode, or a target that
+> quickReadiness marks `blocked`/`invalid` creates no tree and no marker (WT-2/WT-7); a
+> `needs-refinement` refine batch is still work to do (the tree is created, the gaps are the work).
+> The required Git safety checks (WT-1) still precede creation, and ownership/identity is confirmed
+> before any tool, agent, corpus write, or run artifact. A later failure retains the tree with
+> recovery information (WT-5).
+
 **Single-task `dev-run` (batch of one).** `/sp:dev-run <wbs> --worktree [<name>]` runs this same
 lifecycle with a one-task loop: WT-1…WT-6 apply unchanged, the marker's `command` is `dev-run` and
 its `selector` is the `<wbs>` (so WT-6's command+selector fallback resolves the resume), and the