@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/scripts/coverage-checklist.mjs

@@ -0,0 +1,494 @@
+// coverage-checklist — the method-tagged coverage checklist for the Review Contract.
+//
+//   node coverage-checklist.mjs generate [--diff <base>] [--ci <files>] [--ledger] [--sweep <results.json>] [--smoke <results.json>]
+//        [--parity <manifest> --parity-observed <results.json>]
+//        → emits the checklist markdown with GATE rows AUTO-FILLED (decision+evidence)
+//          from the tools, and lead/judgment rows as a skeleton to complete.
+//   node coverage-checklist.mjs validate <checklist.md> [--root <dir>] [--diff <base>] [--no-resolve]
+//        → the anti-ritual guard: fails if any PASS/FAIL row lacks an evidence
+//          locator (file:line / a `command` / #issue), or a gate row is left TODO,
+//          or a cited file:line does not RESOLVE in the tree, or a gate row cites
+//          its command without the result. Pass `--diff <base>` so deletions are
+//          exempt and outside-the-diff locators are warned; `--no-resolve` falls
+//          back to the shape-only check.
+//
+// The point (one rule for machine and model alike): EVERY row resolves to a
+// decision backed by checkable evidence. The only thing that varies is who
+// produces the evidence —
+//   gate-lint : a tool decides + blocks (evidence = its command/output)
+//   lead      : a tool surfaces candidates; a human adjudicates each (evidence = lead + verdict + file:line)
+//   judgment  : a human reasons from code (evidence = file:line + argument)
+// The method per row is fixed HERE (doctrine), never chosen per-PR — otherwise a
+// hard row gets self-classified as "lint ✓". A judgment row whose evidence later
+// becomes mechanizable is promoted to gate-lint (and to a lint-tests/ledger rule).
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+const HERE = path.dirname(new URL(import.meta.url).pathname)
+
+// ---- The catalog (doctrine-fixed; method per row is not negotiable per-PR) ----
+export const CHECKLIST = [
+  // Breadth — the surface set and its ownership.
+  { id: 'breadth.inventory-fresh', axis: 'Breadth', check: 'Surface inventory + route manifest regenerated; no drift', method: 'gate-lint', cmd: 'gen-inventory + `git diff --exit-code` (CI gate 1)' },
+  { id: 'breadth.ownership', axis: 'Breadth', check: 'Every changed surface is owned and proven at its floor (no Missing/Orphan)', method: 'gate-lint', cmd: '`coverage-ledger.mjs validate`' },
+  { id: 'breadth.right-surfaces', axis: 'Breadth', check: 'No un-specced capability missed — the surfaces no AC mentions', method: 'judgment' },
+  { id: 'breadth.reachability', axis: 'Breadth', check: 'Reachability/mutation classification is correct for changed surfaces', method: 'judgment' },
+  // Depth — test level, mocks, meaningfulness.
+  { id: 'depth.no-skip', axis: 'Depth', check: 'No test skipped/focused/xfail added', method: 'gate-lint', cmd: '`lint-tests.mjs --rules no-skip --diff <base>`' },
+  { id: 'depth.no-fixed-timeout', axis: 'Depth', check: 'No fixed sleep added (waitForTimeout / numeric cy.wait / time.sleep)', method: 'gate-lint', cmd: '`lint-tests.mjs --rules no-fixed-timeout --diff <base>`' },
+  { id: 'depth.no-empty-test', axis: 'Depth', check: 'No empty/placeholder test body added (passes vacuously, asserts nothing)', method: 'gate-lint', cmd: '`lint-tests.mjs --rules no-empty-test --diff <base>`' },
+  { id: 'depth.asserts-something', axis: 'Depth', check: 'Each added test actually asserts a behavior (not a no-op or helper-only render-health mislabeled as a journey)', method: 'lead', cmd: '`review-pr/scan-diff.mjs` / read the test' },
+  { id: 'depth.level-meets-floor', axis: 'Depth', check: 'Declared @level meets each surface floor (no Wrong Level)', method: 'gate-lint', cmd: '`coverage-ledger.mjs validate`' },
+  { id: 'depth.interception', axis: 'Depth', check: 'First-party interception in a behaviour/journey test is justified, not counted as real coverage', method: 'lead', cmd: '`review-pr/scan-diff.mjs` / ledger Over-mocked' },
+  // The decidable subset of over-mocking (a test that mocks a first-party seam module)
+  // is a default-on, zero-tolerance gate-lint: no opt-in, no waiver, no grandfathering.
+  // The cross-file "is there a real-boundary sibling?" judgment stays the
+  // depth.interception lead above.
+  { id: 'depth.no-mock-internal-seam', axis: 'Depth', check: 'No mock of a first-party internal seam module (real internals, faked externals) — zero-tolerance: PR-lane (new) AND whole-tree (inherited); no `@mock-ok` waiver; resolve by making it real, faking the external, or DELETING the test (over-mock is worse than no test); a false positive is fixed by correcting topology in coverage.config.json', method: 'gate-lint', cmd: '`lint-tests.mjs --rules mock-internal-seam --diff <base>` (PR lane) + `lint-tests.mjs --rules mock-internal-seam` (whole-tree)' },
+  { id: 'depth.mock-acceptable', axis: 'Depth', check: 'Mock use respects the boundary; money/auth/idempotency never mock-only', method: 'judgment' },
+  { id: 'depth.assertions-meaningful', axis: 'Depth', check: 'Assertions are behavior-first; none pass on a 404 / empty / error page', method: 'judgment' },
+  { id: 'depth.branch-coverage', axis: 'Depth', check: 'Every new branch / error path has a driving test', method: 'lead' },
+  { id: 'depth.characterization', axis: 'Depth', check: 'Diffs that modify existing behavior are pinned by a characterization test (prior behavior) before the change — or an intended change is declared with its AC', method: 'lead', cmd: '`review-pr/scan-diff.mjs` modifies-existing-behavior' },
+  // Runtime smoke — the built thing actually runs. The non-browser counterpart to
+  // pres.sweep (which is the browser runtime gate). The repo/agent runs the surface
+  // however it boots (a run command, a curl, a CLI invocation) and writes a results
+  // file; this gate ingests it. Agent-agnostic: enforcement is the results file + CI,
+  // not any harness "run the app" feature.
+  { id: 'depth.runtime-smoke', axis: 'Depth', check: 'Runtime smoke: each changed non-browser surface (service/API/CLI/job) was actually run via the repo run command and its happy path responded (boots, no 500/crash on first call) — green tests alone do not prove the thing runs; browser surfaces use the presentation sweep instead', method: 'gate-lint', cmd: 'runtime-smoke results (`--smoke <results.json>`)' },
+  // Presentation — real render.
+  { id: 'pres.render-health-floor', axis: 'Presentation', check: 'render-health is in the floor for every changed browser route', method: 'gate-lint', cmd: '`coverage-ledger.mjs validate`' },
+  { id: 'pres.sweep', axis: 'Presentation', check: 'Presentation sweep ran (runtime gate): no pageerror/overflow/overlap/shift; nothing blocked', method: 'gate-lint', cmd: 'presentation-sweep results (e2e-test)' },
+  { id: 'pres.no-first-party-intercept', axis: 'Presentation', check: 'Sweep specs do not intercept first-party traffic', method: 'lead', cmd: '`review-pr/scan-diff.mjs` / ledger' },
+  { id: 'pres.perceivability', axis: 'Presentation', check: 'Perceivability edge cases the instruments cannot score are checked', method: 'judgment' },
+  // Fidelity is the one presentation question that is NOT self-referential: every
+  // other row (and `presentation:visual`) takes the implementation as its own
+  // authority, so a page built wrong from a right design passes all of them.
+  // N/A when the unit cites no design source — mark it so, with the reason.
+  { id: 'pres.fidelity', axis: 'Presentation', check: 'When the unit cites a design source (prototype/mockup/design doc): the parity manifest is complete, its citations resolve, and every pinned property holds against the rendered page', method: 'gate-lint', cmd: '`design-parity.mjs validate <manifest> --observed <results.json>`' },
+  { id: 'pres.source-render', axis: 'Presentation', check: 'Design source and deliverable rendered side by side at the floor viewports — the check that fails when the parity manifest itself is incomplete', method: 'judgment' },
+  // Enforcement — the gates themselves.
+  { id: 'enforce.gates-wired', axis: 'Enforcement', check: 'CI wires all required gates and keeps them blocking', method: 'gate-lint', cmd: '`ci-audit.mjs --files <ci>`' },
+]
+
+const AXES = ['Breadth', 'Depth', 'Presentation', 'Enforcement']
+
+// ---- Pure: evidence locator check (the anti-ritual guard) ----
+// A decision is only real if a second reader can re-check it: a file:line, an
+// inline `command`, an http link, or a #issue. Prose alone is not evidence.
+export function hasLocator(s = '') {
+  return /[\w./-]+\.\w+:\d+/.test(s)   // path/to/file.ext:line
+    || /`[^`]+`/.test(s)               // inline command / code
+    || /https?:\/\//.test(s)           // link
+    || /#\d+/.test(s)                  // issue/PR ref
+}
+
+// ---- Pure: locator RESOLUTION (the shape guard is not a truth guard) ----
+//
+// `hasLocator` above asks whether the evidence LOOKS like a locator. It cannot
+// ask whether the locator is TRUE, so three shaped-but-false rows sail through
+// it — and each one is an evidence-class review finding, which under
+// `resolve-issues` costs a full fix + re-review round:
+//
+//   PASS | `_run_ \`coverage-ledger.mjs validate\``          the skeleton, never run
+//   PASS | `src/gone.ts:9999 — looks fine`                    file/line does not exist
+//   PASS | `see #1`                                           a ref to anything at all
+//
+// So `validate` now RESOLVES what it can decide. The checks below are the
+// decidable subset only; each has a named incident behind it (see
+// resolve-issues → references/why.md#the-checklist-screens-resolve-locators):
+//
+//   A  a cited path:line must exist in the tree, at a line inside the file
+//      (incident: a reviewer blocking solely on a checklist citing a pre-restack
+//      base, then spending the next round rejecting the checklist fix)
+//   B  a gate-lint row must carry the gate's RESULT, not just its command
+//      (incident: a hand-written attestation claiming `leadCount=0` for a diff
+//      whose real scan had 1,749 leads — a full review round on a transcription)
+//   C  a row citing only paths outside the net diff is WARNED, never blocked —
+//      the stale-locator smell, too false-positive-prone to be a violation
+//
+// Deleted-by-this-PR paths are exempt from A: "removed the over-mocked test at
+// tests/foo.spec.ts:40" is a true locator that resolves to nothing on purpose.
+// That exemption needs the diff, so WITHOUT `--diff` a missing file is downgraded
+// to a warning — stale and deleted are indistinguishable there, and a screen that
+// blocks honest evidence costs the round it exists to save. Paths are resolved
+// against the git toplevel (not the cwd) and retried against the cwd, for the same
+// reason: every wrong block is more expensive than a wrong pass here, because the
+// reviewer is still downstream and catches what this misses.
+
+// URLs carry `host.tld:port`, which is shaped exactly like `path.ext:line`.
+// Strip them before extracting or every `https://ci:8080/x` reads as a dead file.
+const LOCATOR_RE = /(^|[\s(<[`'",])([\w.][\w./-]*\.\w{1,12}):(\d+)/g
+
+export function extractLocators(s = '') {
+  const text = String(s).replace(/https?:\/\/\S+/g, ' ')
+  const out = []
+  for (const m of text.matchAll(LOCATOR_RE)) {
+    const line = Number(m[3])
+    if (line > 0) out.push({ path: m[2], line })
+  }
+  return out
+}
+
+// A gate row's evidence has to say what the gate RETURNED, not just which gate it
+// was. The thing actually being caught is the generated SKELETON with a decision
+// typed over it — so match on that rather than on how a result is phrased.
+//
+// An earlier version enumerated outcome markers (`→`, `exit N`, "0 findings"). That
+// list rejected `\`coverage-ledger.mjs validate\` — clean` and `... passed`, which
+// are ordinary honest results, and no list would ever be finished. The property
+// that separates a skeleton from a result needs no vocabulary: strip the command
+// (an inline code span) and the skeleton's own emphasis annotation (`_run_`,
+// `_cite ..._`), and a skeleton has NOTHING left, while any real result does.
+//
+// Rows reaching here already passed `hasLocator`, so a gate row with no code span
+// at all was caught upstream — this cannot be fooled by dropping the backticks.
+//
+// `cmd` is the row's catalog command when the caller knows it. With it, "is this
+// the skeleton?" stops being a heuristic and becomes exact: the skeleton IS
+// `_run_ ${cmd}` by construction, so subtracting the cmd leaves nothing. Without
+// it the rule still works for the common `_run_ \`cmd\`` shape, but a catalog
+// command carrying un-backticked text (`gen-inventory + \`git diff\` (CI gate 1)`)
+// would leak its own prose through as if it were a result — which is exactly what
+// the catalog-derived test in this suite exists to keep catching.
+export function hasGateOutcome(s = '', cmd = '') {
+  const text = String(s)
+  if (extractLocators(text).length > 0) return true  // a failing lint gate's hits ARE its result
+  // A verdict glyph is a terse but complete result, and the symbol-stripping below
+  // would otherwise eat it. This is a closed set of marks, not an open vocabulary
+  // of English words — which is the thing that made the first version unmaintainable.
+  if (/[✓✔✗✘❌✅]/u.test(text)) return true
+  let residue = text
+  if (cmd) residue = residue.split(String(cmd)).join(' ')  // literal, never a regex — cmd contains + ( ) etc.
+  const cleaned = residue
+    .replace(/`[^`]*`/g, ' ')           // the command itself
+    .replace(/_[^_]*_|\*[^*]*\*/g, ' ') // the skeleton's own _run_ / _cite …_ annotation
+    .replace(/[\s\p{P}\p{S}]+/gu, ' ')  // punctuation and separators are not a result
+    .trim()
+  return cleaned.length > 0
+}
+
+// The catalog command for a parsed row, matched on its check text — `parseChecklist`
+// keeps the check column verbatim, so this is a lookup rather than a guess.
+function catalogCmd(check, catalog) {
+  return catalog.find((r) => r.check === check)?.cmd || ''
+}
+
+// ---- Pure: render the checklist (gate rows filled from results, rest skeleton) ----
+function skeletonEvidence(row) {
+  if (row.method === 'gate-lint') return `_run_ ${row.cmd || '(tool)'}`
+  if (row.method === 'lead') return `_adjudicate the lead — cite \`file:line\` + verdict_`
+  return `_cite \`file:line\` + reasoning_`
+}
+
+export function renderChecklist(catalog, results = {}) {
+  const out = ['## Coverage Checklist', '', '_Every row = a decision (PASS / FAIL / N/A) backed by a checkable evidence locator (`file:line`, a rerunnable `command`, or #issue). Gate rows are auto-filled by `coverage-checklist.mjs generate`; lead/judgment rows are completed by the reviewer. `coverage-checklist.mjs validate` fails a PASS/FAIL row with no locator, a gate row left TODO, **a cited `file:line` that does not resolve in the tree**, and **a gate row citing its command without the result** — cite the outcome (exit code, `→ N findings`, or the hits), never the command alone._', '']
+  for (const axis of AXES) {
+    const rows = catalog.filter((r) => r.axis === axis)
+    if (!rows.length) continue
+    out.push(`### ${axis}`, '', '| Check | Method | Decision | Evidence |', '|---|---|---|---|')
+    for (const r of rows) {
+      const filled = results[r.id]
+      const decision = filled?.decision || 'TODO'
+      const evidence = filled?.evidence || skeletonEvidence(r)
+      out.push(`| ${r.check} | ${r.method} | ${decision} | ${evidence} |`)
+    }
+    out.push('')
+  }
+  return out.join('\n')
+}
+
+// ---- Pure: parse a (completed) checklist back into rows ----
+export function parseChecklist(md) {
+  const rows = []
+  for (const line of (md || '').split(/\r?\n/)) {
+    if (!line.trim().startsWith('|')) continue
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim())
+    if (cells.length < 4) continue
+    const [check, method, decision, evidence] = cells
+    if (/^-+$/.test(check) || method.toLowerCase() === 'method') continue // separator / header
+    if (!['gate-lint', 'lead', 'judgment'].includes(method)) continue
+    rows.push({ check, method, decision, evidence })
+  }
+  return rows
+}
+
+// ---- Pure: the anti-ritual guard ----
+//
+// opts (all optional — with none of them this is the pre-resolution shape check,
+// which is what every existing caller gets):
+//   resolveFile(path) → { lines } | null   how to look a cited path up in the tree
+//   deletedFiles: string[]                 paths this PR deletes (exempt from check A)
+//   changedFiles: string[]                 the net diff's paths (enables warning C)
+// Returns violations; `warnings` ride on the array as a property so the
+// exit-code contract (violations block, warnings do not) stays one call.
+export function validateRows(rows, opts = {}) {
+  const { resolveFile, deletedFiles = [], changedFiles = null, catalog = CHECKLIST } = opts
+  const deleted = new Set(deletedFiles)
+  const changed = changedFiles && new Set(changedFiles)
+  // Whether the caller could supply the diff at all. It is what makes an
+  // unresolvable path decidable rather than ambiguous — see check A below.
+  const diffKnown = Array.isArray(changedFiles)
+  const violations = []
+  const warnings = []
+  for (const r of rows) {
+    const d = (r.decision || '').toUpperCase().replace(/[\[\]\s]/g, '')
+    const pass = d === 'PASS' || d === 'X' || d === '✓'
+    const fail = d === 'FAIL' || d === '✗'
+    const na = d === 'N/A' || d === 'NA'
+    if (pass || fail) {
+      if (!hasLocator(r.evidence)) {
+        violations.push({ check: r.check, problem: `${d} with no evidence locator — need a file:line, a rerunnable \`command\`, or #issue` })
+        continue
+      }
+      // B — a gate row that names its command but not its result is the skeleton
+      // with a decision typed over it. Nothing downstream can tell those apart.
+      if (r.method === 'gate-lint' && !hasGateOutcome(r.evidence, catalogCmd(r.check, catalog))) {
+        violations.push({ check: r.check, problem: `${d} cites the gate's command but not its result — paste the outcome (exit code, "→ N findings", or the file:line hits), not the command alone` })
+      }
+      // A — every cited path:line must resolve, unless this PR deleted the file.
+      //
+      // A MISSING file is only decidable with diff context. "removed the over-mocked
+      // test at tests/foo.spec.ts:40" is a true locator that resolves to nothing on
+      // purpose, and without the deletion set it is indistinguishable from a stale
+      // one. Blocking on it would cost the round this screen exists to save, so with
+      // no diff supplied it warns. A line PAST EOF needs no such care: the file is
+      // right there and is too short, which no deletion can explain.
+      const locators = extractLocators(r.evidence)
+      if (resolveFile) {
+        for (const loc of locators) {
+          if (deleted.has(loc.path)) continue
+          const found = resolveFile(loc.path)
+          if (!found) {
+            const problem = `evidence cites ${loc.path}:${loc.line}, which does not exist in the tree — a stale locator is not evidence`
+            if (diffKnown) violations.push({ check: r.check, problem })
+            else warnings.push({ check: r.check, problem: `${problem.replace(' — a stale locator is not evidence', '')}; with no --diff supplied this check cannot tell a stale locator from a deleted one, so it warns rather than blocks — re-run with --diff <merge-base> to decide it` })
+          } else if (loc.line > found.lines) {
+            violations.push({ check: r.check, problem: `evidence cites ${loc.path}:${loc.line}, but ${loc.path} has ${found.lines} line(s) — the locator points past the end of the file` })
+          }
+        }
+      }
+      // C — smell, not a defect: every path this row cites sits outside the diff.
+      if (changed && locators.length && locators.every((l) => !changed.has(l.path) && !deleted.has(l.path))) {
+        warnings.push({ check: r.check, problem: `every cited path (${locators.map((l) => l.path).join(', ')}) is outside the net diff — check it is not a pre-rebase locator` })
+      }
+    } else if (na) {
+      if (!r.evidence || !r.evidence.replace(/[_*]/g, '').trim()) violations.push({ check: r.check, problem: 'N/A with no reason' })
+    } else {
+      violations.push({ check: r.check, problem: r.method === 'gate-lint' ? 'gate row left TODO — auto-fill it (coverage-checklist.mjs generate)' : 'undecided (TODO) — decide and cite evidence' })
+    }
+  }
+  // Non-enumerable on purpose: callers (and their assert.deepEqual) still see a
+  // plain array of violations, and the exit code stays a function of that array.
+  Object.defineProperty(violations, 'warnings', { value: warnings })
+  return violations
+}
+
+// ---- CLI gathering (best-effort; a tool that errors → row stays skeleton) ----
+function tryJSON(file, args) {
+  try { return JSON.parse(execFileSync('node', [path.join(HERE, file), ...args, '--json'], { encoding: 'utf8' })) }
+  catch (e) { try { return JSON.parse(e.stdout || '') } catch { return null } } // non-zero exit still prints JSON
+}
+function tryExit(file, args) {
+  try { execFileSync('node', [path.join(HERE, file), ...args], { encoding: 'utf8' }); return { code: 0 } }
+  catch (e) { return { code: e.status ?? 1, out: (e.stdout || '').trim() } }
+}
+
+function gather(flags) {
+  const results = {}
+  // lint-tests (no-skip + no-fixed-timeout), diff or files
+  const scope = flags.diff ? ['--diff', flags.diff] : flags.files ? ['--files', flags.files] : null
+  if (scope) {
+    const lint = tryJSON('lint-tests.mjs', scope)
+    if (lint) {
+      for (const [rid, rule] of [['depth.no-skip', 'no-skip'], ['depth.no-fixed-timeout', 'no-fixed-timeout']]) {
+        const hits = lint.findings.filter((f) => f.rule === rule)
+        results[rid] = hits.length
+          ? { decision: 'FAIL', evidence: hits.map((f) => `${f.file}:${f.line}`).join(', ') }
+          : { decision: 'PASS', evidence: `\`lint-tests.mjs --rules ${rule} ${scope.join(' ')}\` → 0 findings` }
+      }
+    }
+  }
+  // ci-audit
+  if (flags.ci) {
+    const audit = tryJSON('ci-audit.mjs', ['--files', flags.ci])
+    if (audit) results['enforce.gates-wired'] = {
+      decision: audit.ok ? 'PASS' : 'FAIL',
+      evidence: `\`ci-audit.mjs --files ${flags.ci}\` → ${audit.gates.map((g) => `${g.key}:${g.status}`).join(', ')}`,
+    }
+  }
+  // ledger validate (exit-code based) → fills the three ledger-backed rows
+  if (flags.ledger) {
+    const r = tryExit('coverage-ledger.mjs', ['validate'])
+    const summary = (r.out || '').split('\n').filter(Boolean).pop() || ''
+    const dec = r.code === 0 ? 'PASS' : 'FAIL'
+    const ev = `\`coverage-ledger.mjs validate\` (exit ${r.code})${summary ? ` — ${summary}` : ''}`
+    for (const rid of ['breadth.ownership', 'depth.level-meets-floor', 'pres.render-health-floor']) results[rid] = { decision: dec, evidence: ev }
+  }
+  // runtime-smoke results file (non-browser surfaces) — same shape as the sweep:
+  // a list of { surface|id|cmd, status } where status fail/blocked/error = not-ran.
+  if (flags.smoke && fs.existsSync(flags.smoke)) {
+    try {
+      const smoke = JSON.parse(fs.readFileSync(flags.smoke, 'utf8'))
+      const list = Array.isArray(smoke) ? smoke : smoke.results || []
+      const bad = list.filter((x) => x.status === 'fail' || x.status === 'blocked' || x.status === 'error')
+      results['depth.runtime-smoke'] = bad.length
+        ? { decision: 'FAIL', evidence: `${flags.smoke}: ${bad.map((b) => `${b.surface || b.id || b.cmd}:${b.status}`).slice(0, 5).join(', ')}` }
+        : { decision: 'PASS', evidence: `\`${flags.smoke}\` → ${list.length} surface(s), 0 fail` }
+    } catch { /* leave skeleton */ }
+  }
+  // design-parity: fidelity against the cited design source. Deliberately fills
+  // only when BOTH the manifest and the observed results are supplied — a
+  // manifest-only run is design-parity's own "reduced form" (it never looks at the
+  // page), and auto-filling a gate row from it would launder that into a PASS.
+  if (flags.parity && fs.existsSync(flags.parity)) {
+    const args = ['validate', flags.parity]
+    if (flags.parityObserved) args.push('--observed', flags.parityObserved)
+    const r = tryExit('design-parity.mjs', args)
+    if (!flags.parityObserved) {
+      results['pres.fidelity'] = { decision: 'TODO', evidence: `\`design-parity.mjs validate ${flags.parity}\` ran WITHOUT --observed (reduced form: manifest checked, page not). Re-run with --parity-observed <results.json>.` }
+    } else {
+      const tail = (r.out || '').split('\n').filter(Boolean).slice(-3).join(' · ')
+      results['pres.fidelity'] = {
+        decision: r.code === 0 ? 'PASS' : 'FAIL',
+        evidence: `\`design-parity.mjs validate ${flags.parity} --observed ${flags.parityObserved}\` (exit ${r.code})${tail ? ` — ${tail}` : ''}`,
+      }
+    }
+  }
+  // presentation sweep results file
+  if (flags.sweep && fs.existsSync(flags.sweep)) {
+    try {
+      const sweep = JSON.parse(fs.readFileSync(flags.sweep, 'utf8'))
+      const list = Array.isArray(sweep) ? sweep : sweep.results || []
+      const bad = list.filter((x) => x.status === 'fail' || x.status === 'blocked')
+      results['pres.sweep'] = bad.length
+        ? { decision: 'FAIL', evidence: `${flags.sweep}: ${bad.map((b) => `${b.route || b.id}:${b.status}`).slice(0, 5).join(', ')}` }
+        : { decision: 'PASS', evidence: `\`${flags.sweep}\` → ${list.length} routes, 0 fail/blocked` }
+    } catch { /* leave skeleton */ }
+  }
+  return results
+}
+
+// Checklist locators are REPO-relative — that is what every generator emits
+// (`lint-tests` hits, ledger rows, sweep results). Anchoring them at `process.cwd()`
+// means the same honest checklist passes from the repo root and fails from
+// `apps/web/`, reporting real files as "does not exist in the tree": a screen that
+// blocks a true claim, which is the failure mode this whole check is written
+// around. So the default anchor is the git toplevel, and each path is tried
+// against the cwd as well before it is called missing — on ambiguity this fails
+// open, because the cost of a wrong block is a round and the cost of a wrong pass
+// is one reviewer comment.
+function repoRoot(explicit) {
+  if (explicit) return explicit
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim() || process.cwd()
+  } catch { return process.cwd() }  // not a git checkout — cwd is the only anchor there is
+}
+
+// Resolve a cited path against the tree the producer is about to push — the
+// working tree, not a git object: that is the code the reviewer will read.
+function fileResolver(root) {
+  const cache = new Map()
+  const anchors = [...new Set([root, process.cwd()])]
+  return (p) => {
+    if (cache.has(p)) return cache.get(p)
+    const candidates = path.isAbsolute(p) ? [p] : anchors.map((a) => path.join(a, p))
+    let out = null
+    for (const abs of candidates) {
+      try {
+        if (!fs.statSync(abs).isFile()) continue
+        const text = fs.readFileSync(abs, 'utf8')
+        // A trailing newline does not make a final empty line citable.
+        out = { lines: text.length ? text.replace(/\n$/, '').split('\n').length : 0 }
+        break
+      } catch { /* try the next anchor */ }
+    }
+    cache.set(p, out)
+    return out
+  }
+}
+
+// `git diff --name-status <base>...HEAD` → what this PR changed, and what it
+// deleted. Deletions are the one class of unresolvable locator that is honest.
+function diffFiles(base, root) {
+  try {
+    const out = execFileSync('git', ['diff', '--name-status', `${base}...HEAD`], { cwd: root, encoding: 'utf8' })
+    const changed = []
+    const deleted = []
+    for (const line of out.split('\n')) {
+      const [status, ...paths] = line.split('\t')
+      const p = paths[paths.length - 1]
+      if (!status || !p) continue
+      if (status.startsWith('D')) deleted.push(p)
+      else changed.push(p)
+    }
+    return { changed, deleted }
+  } catch (e) {
+    console.error(`coverage-checklist: could not read the diff against ${base} (${e.message.split('\n')[0]}) — resolving locators without deletion/diff context`)
+    return null
+  }
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2)
+  if (cmd === 'validate') {
+    const file = rest.find((a) => !a.startsWith('--'))
+    if (!file || !fs.existsSync(file)) { console.error('usage: coverage-checklist.mjs validate <checklist.md> [--root <dir>] [--diff <base>] [--no-resolve]'); process.exit(2) }
+    const root = repoRoot(rest.includes('--root') ? rest[rest.indexOf('--root') + 1] : null)
+    const base = rest.includes('--diff') ? rest[rest.indexOf('--diff') + 1] : null
+    const diff = base ? diffFiles(base, root) : null
+    const opts = rest.includes('--no-resolve') ? {} : {
+      resolveFile: fileResolver(root),
+      deletedFiles: diff?.deleted || [],
+      changedFiles: diff?.changed || null,
+    }
+    // Without `--diff` this command answers a WEAKER question than its exit code
+    // suggests, and nothing said so. A missing locator downgrades from violation to
+    // warning (see warning B above) because a deletion and a stale reference are
+    // indistinguishable with no diff context, so the run exits 0 on rows a diffed run
+    // blocks. Measured on 1above-official issue #35 (2026-08-03): the producer ran
+    // `validate <checklist> --root .` → pass; the reviewer ran the same file with
+    // `--diff` → 9 PASS rows with no resolving locator, and the unit bought an
+    // evidence round for the difference. Two runs of one command, opposite verdicts,
+    // and no way to tell from the output which question had been asked. So the
+    // reduced form announces itself — on stderr, so a caller piping stdout still sees
+    // it, and on BOTH paths, since the pass is the one that misleads.
+    const reduced = opts.resolveFile && !opts.changedFiles
+    if (reduced) {
+      console.error('coverage-checklist: NOTE — running without --diff: this is the reduced form. A row whose cited file is MISSING warns instead of blocking, because with no diff a stale locator cannot be told from one this PR deleted. Re-run with `--diff <merge-base>` to decide those rows; a green run here is not the green the reviewer will get.')
+    }
+    const violations = validateRows(parseChecklist(fs.readFileSync(file, 'utf8')), opts)
+    for (const w of violations.warnings) console.log(`  ! ${w.check}: ${w.problem}`)
+    if (!violations.length) {
+      const how = opts.resolveFile ? 'a decision + an evidence locator that resolves' : 'a decision + evidence locator'
+      const caveat = reduced ? ' — reduced form, no --diff: missing-file rows warned rather than blocked' : ''
+      console.log(`coverage-checklist: ✓ every row has ${how}${caveat}${violations.warnings.length ? ` (${violations.warnings.length} warning(s) above)` : ''}`)
+      process.exit(0)
+    }
+    console.log(`coverage-checklist: ✗ ${violations.length} row(s) without a real decision/evidence:\n`)
+    for (const v of violations) console.log(`  • ${v.check}: ${v.problem}`)
+    process.exit(1)
+  }
+  if (cmd === 'generate' || cmd === undefined) {
+    const flags = {}
+    const a = cmd === undefined ? process.argv.slice(2) : rest
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] === '--diff') flags.diff = a[++i]
+      else if (a[i] === '--files') flags.files = a[++i]
+      else if (a[i] === '--ci') flags.ci = a[++i]
+      else if (a[i] === '--ledger') flags.ledger = true
+      else if (a[i] === '--sweep') flags.sweep = a[++i]
+      else if (a[i] === '--smoke') flags.smoke = a[++i]
+      else if (a[i] === '--parity') flags.parity = a[++i]
+      else if (a[i] === '--parity-observed') flags.parityObserved = a[++i]
+    }
+    console.log(renderChecklist(CHECKLIST, gather(flags)))
+    process.exit(0)
+  }
+  console.error('usage: coverage-checklist.mjs <generate|validate>')
+  process.exit(2)
+}
+
+if (isMainModule(import.meta.url)) main()