@gobing-ai/spur 0.3.76 → 0.3.77

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/inline-pipeline-driver.md

@@ -48,11 +48,28 @@ command, skill, script, or second workflow.
    chooses the subprocess workflow path.
 2. Allocate a collision-resistant inline run id (`uuidgen`, with a timestamp/pid fallback), create
    `.spur/run/`, and use `.spur/run/<run-id>.log` as the run log.
-3. Resolve the host session id from `.spur/context/.session.json`, accepting the normalized hook key
+3. **Authoritative run identity (task 0804 R1, fail-closed).** Persist the run row through the
+   internal delegate before any stage executes — this is what makes bound `run.artifact` record
+   accept the inline run (0785 R3):
+
+   ```bash
+   SETUP_SCRIPT="plugins/sp/scripts/inline-run-setup.ts";
+   [ -f "$SETUP_SCRIPT" ] || SETUP_SCRIPT="$(superskill script path sp inline-run-setup.ts 2>/dev/null)";
+   [ -n "$SETUP_SCRIPT" ] && [ -f "$SETUP_SCRIPT" ] && \
+     bun "$SETUP_SCRIPT" --run-id "$RUN_ID" --file <selected-pipeline-yaml> \
+     || { echo "inline run setup failed closed — checker not found; run 'superskill install sp'" >&2; exit 1; }
+   ```
+
+   The delegate resolves the app service from the SPUR_BIN chain, creates-or-attaches the row,
+   and writes `.spur/run/<run-id>-inline-setup.json`. Seed `__runId` and `__definitionDigest`
+   from that file so proof capture and bound registration verify against the persisted identity.
+   A non-zero exit (missing row identity, changed definition, bundle-only install) stops the run —
+   never continue unbound and never fabricate a PASS.
+4. Resolve the host session id from `.spur/context/.session.json`, accepting the normalized hook key
    `session` and the Codex key `session_id` (in that order). If neither is available, allocate
    `host-session-<run-id>` and record that fallback in the log; provenance must never be blank or
    guessed from an executor subprocess.
-4. Render the two-layer plan into the host todo list (task 0596):
+5. Render the two-layer plan into the host todo list (task 0596):
    - **Layer 1** = `spur workflow show <pipeline-yaml> --format todo --json` → its `steps[]`: the
      declared state inventory in declaration order with `initial` / `terminal` / `failure` /
      `pause` / `loopBack` / `conditional` markers. Mark the active state. Never re-derive this
@@ -69,7 +86,7 @@ command, skill, script, or second workflow.
      ended 0/11 with precheck and implement still open).
    - **Source of truth** = the CLI projection for layer 1; the YAML parsed in step 1 for layer 2.
      Never hand-copy or hand-derive the state list into the driver, a command, a skill, or a script.
-5. For task execution only, record lifecycle provenance before entering the FSM:
+6. For task execution only, record lifecycle provenance before entering the FSM:
 
    ```bash
    spur task run-link <wbs> --source inline-full --run-id <run-id> --json
@@ -101,6 +118,16 @@ Action semantics come from the YAML and the workflow action contract:
   `answerFile`; assert `expectFile`; enforce `requireDiff` against a pre-action git snapshot,
   including the task-scope guard; honor declared error policy. `timeoutMs` is recorded as not
   applicable because the host session has no independent kill boundary.
+- `run.artifact` — the engine's ledger registration has **no inline execution surface** (0808 R4).
+  The inline equivalent is a documented **registration-equivalent convention**: before the record
+  state mutates the task, the host validates the same refusal conditions inline — the declared
+  artifact exists at the resolved path and is canonical-valid for the run's wbs (for
+  `verify-verdict`: verdict `PASS`), `proofBinding: current` is honored against a freshly captured
+  proof digest, and the run-scoped review-completion marker exists — then appends one provenance
+  line to `.spur/run/<run-id>.log` naming the equivalence (artifact kind, path, verdict, digest) and
+  proceeds to `spur task record`. A failed validation stops at the state and follows the failure
+  contract; the step is never silently skipped. Artifact-provenance consumers read that run-log
+  line on the inline path — there is no ledger row.
 
 **Native-subagent dispatch (R2 eligibility, evaluated before each action):**
 
@@ -204,10 +231,11 @@ tasks (0617, 0619) because the sections were hand-written **before** the verdict
    and `L3.required-section-placeholder` before the transition, not after.
 3. **Solution change-map anchor rule (L4.anchor-subject-mismatch).** A Solution change-map table must
    list **one `file:line` per row**. A ·-joined paragraph makes every anchor's "subject" the other
-   anchors and trips the L4 subject check. Paths containing `_` (e.g. `docs/help/cmd_*.md`,
-   `spur-cli-matrix.md`) can **never** match their cited line — the snake_case filename token is
-   extracted as the subject and cannot appear in the line content — so drop those rows from the table
-   (prose still covers them).
+   anchors and trips the L4 subject check. Since 0804 R9, subject extraction ignores complete parsed
+   citation spans, so a path's underscores no longer manufacture a subject: an underscore path row
+   (`docs/help/cmd_example.md:12`) is checked exactly like any other row — cite an **existing file**
+   with a **valid line or line range** whose content names the requirement's subject. A real absent
+   symbol, nonexistent file or invalid range still reports; never replace a citable row with prose.
 
 ## Failure contract