@1aboveio/skills 0.10.0

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

@@ -0,0 +1,663 @@
+#!/usr/bin/env node
+// Coverage Ledger reference tool for the ensure-coverage skill.
+//
+//   node coverage-ledger.mjs aggregate   # build the computed coverage-index
+//   node coverage-ledger.mjs validate    # run reconciliation checks, exit non-zero on errors
+//   node coverage-ledger.mjs report       # render a human-readable index + ADR matrix view
+//
+// It is framework-agnostic: it consumes a generated surface inventory (see
+// references/breadth/inventory-contract.md) plus the curated per-requirement
+// `*.coverage.yml` tree, and resolves evidence from `@covers` annotations in
+// tests. Surface DISCOVERY is repo-specific and is NOT done here — supply the
+// inventory via your own adapter (a reference Next.js one ships in adapters/).
+//
+// Curated files may be .yml/.yaml (needs `js-yaml`) or .json (zero-dep).
+
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---------- config ----------
+
+const DEFAULTS = {
+  inventory: 'docs/tests/_generated/surface-inventory.json',
+  coverageDir: 'docs/tests',
+  testRoots: ['.'],
+  indexOut: 'docs/tests/_generated/coverage-index.json',
+  reportOut: 'docs/tests/_generated/coverage-index.md',
+  // Optional acceptance-gate inputs. Left empty -> gate is skipped with a notice.
+  requirementGlobs: {}, // e.g. { adr: 'docs/adr', prd: 'docs/prd' }
+  acceptedMarker: /status:\s*accepted/i,
+  // A statically-adequate but un-attested test lands at `Unverified`. Doctrine
+  // makes that a BLOCKING state (a yellow that fails CI until a human attests
+  // via `verified: true`). Set false to phase in (downgrade Unverified to warn).
+  unverifiedBlocks: true,
+}
+
+const IGNORE_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', 'coverage'])
+const TEST_RE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/
+// Internal interception / first-party mocking that makes a surface LOOK covered
+// while proving only proxy wiring. Playwright route faking plus MSW server/worker
+// setup (MSW handlers for first-party paths are the non-Playwright vector).
+const INTERCEPT_RE = /\broute\.fulfill\b|\bpage\.route\s*\(|\bsetupServer\s*\(|\bsetupWorker\s*\(|from\s+['"]msw['"]/
+// Real-rendered-page evidence: a Presentation invariant must be proven against a
+// browser that actually lays out and paints the page. These markers signal a real
+// browser drive (Playwright). Their ABSENCE on a presentation-level test means the
+// claim rests on the DOM/accessibility tree only — the axis's over-mock.
+const BROWSER_RE = /@playwright\/test|\bplaywright\b|\bpage\.(goto|locator|evaluate|getByRole|getByText|getByLabel|setViewportSize|click|fill|type|press|check)\b|\bboundingBox\b|\btoHaveScreenshot\b/
+// JSDOM / Testing-Library render: a non-painting DOM. Useful as an explicit
+// negative signal for the DOM-only over-mock note.
+const DOMONLY_RE = /\bjsdom\b|@testing-library|environment['"\s:]+jsdom/
+
+// ---------- surface baseline contract ----------
+//
+// Every inventory surface carries a minimum required-level FLOOR keyed on its
+// (kind, class). `class` is mechanically derived by the adapter (read/detail/
+// mutation); humans may only RAISE the floor (curated requiredLevels, sensitive)
+// or EXCLUDE a surface (gated below). Internal surfaces carry no floor — they are
+// proven transitively and only dead-surface-warned when nothing reaches them.
+// Presentation axis (third coverage axis — can a human perceive/act on the page,
+// not just does the DOM exist). Every live browser route auto-carries a presentation
+// floor on top of its functional browser-journey floor.
+//
+// This file GRADES presentation levels (does a qualifying real-render test exist,
+// is it non-intercepting, is it attested) — it does NOT render the page. The
+// instruments that actually open a browser and observe these invariants live in
+// the e2e-test skill's presentation sweep; ensure-coverage owns the CONTRACT
+// (references/presentation/runner-contract.md), not the runner.
+//
+// Levels, spine first:
+//   render-health  — the page renders without a pageerror / console.error /
+//                    error boundary / HTTP >=500. The cheapest, most foundational
+//                    catch (an uncaught TypeError on mount fails here first), so it
+//                    is the SPINE of the axis.
+//   spatial        — no unintended horizontal overflow / element overlap.
+//   perceivability — contrast / invisible controls; negative: wrong-role/absent.
+//   reachability   — navigational reachability + actionable affordance cues.
+//   temporal       — layout shift (first-party hermetic; third-party sandbox lane).
+const PRESENTATION_ROUTE_FLOOR = ['presentation:render-health', 'presentation:spatial', 'presentation:perceivability', 'presentation:reachability', 'presentation:temporal']
+// The condition-matrix floor the presentation instruments run at. Feature-derived
+// escalation adds cells (dark theme, RTL, …); see the Presentation axis section of
+// SKILL.md. Kept here so the floor is one source of truth for the e2e instrument.
+const PRESENTATION_VIEWPORT_FLOOR = [375, 1280]
+
+const BASELINE = {
+  // browser routes: every live page must be driven (browser-journey floor);
+  // class only changes WHAT the journey must additionally assert (durable state
+  // for mutation, seeded entity for detail) — enforced via depth refutation.
+  // Every route also carries the Presentation floor (see PRESENTATION_ROUTE_FLOOR).
+  route: {
+    read: ['browser-journey', ...PRESENTATION_ROUTE_FLOOR],
+    detail: ['browser-journey', ...PRESENTATION_ROUTE_FLOOR],
+    mutation: ['browser-journey', ...PRESENTATION_ROUTE_FLOOR],
+    _default: ['browser-journey', ...PRESENTATION_ROUTE_FLOOR],
+  },
+  // bare API endpoints (no browser route): contract floor; writes also need durable-state.
+  api: { read: ['api'], mutation: ['api', 'integration'], _default: ['api'] },
+  permission: { _default: ['integration'] },
+  integration: { _default: ['integration'] },
+  // internal surfaces — no independent baseline obligation.
+  table: { _default: [] },
+  event: { _default: [] },
+  job: { _default: [] },
+}
+const INTERNAL_KINDS = new Set(['table', 'event', 'job'])
+
+function baselineFor(kind, cls) {
+  const k = BASELINE[kind]
+  if (!k) return []
+  return k[cls] || k._default || []
+}
+
+// `sensitive` (human-declared escalation): credential/admin/settings surfaces
+// add a contract + auth obligation on top of the mechanical floor.
+function sensitiveExtra(kind) {
+  if (kind === 'route') return ['api'] // page journey + API contract; auth asserted at depth
+  return []
+}
+
+function strictest(...levelLists) {
+  return [...new Set(levelLists.flat().filter(Boolean))]
+}
+
+// Exclusion is gated by adapter-confirmed signals, never by a human reason alone:
+// a reachable write surface can NEVER be excluded below its journey floor.
+function exclusionAllowed(kind, cls, reachability) {
+  if (kind === 'route') {
+    if (cls === 'read') return { ok: true } // static/content read pages may drop to render-health
+    if (reachability === 'blocked' || reachability === 'unreachable') return { ok: true }
+    return { ok: false, why: `reachable ${cls} route cannot be excluded (reachability=${reachability || 'unknown'}); a reachable write surface must keep its journey floor` }
+  }
+  if (kind === 'api') {
+    if (cls === 'mutation') return { ok: false, why: 'mutation API cannot be excluded' }
+    return { ok: true }
+  }
+  return { ok: true } // internal kinds are excludable
+}
+
+// A required level is "behavior" (not satisfiable by unit/mock alone).
+const BEHAVIOR_LEVELS = new Set([
+  'pg-api', 'api', 'integration', 'browser-journey', 'journey', 'ui-e2e', 'e2e',
+  'no-secret-assertion',
+])
+// Presentation levels are proven against a REAL rendered page (not the DOM tree).
+// They get a stricter "clean test" rule than ordinary behavior levels: the proving
+// test must drive a real browser (BROWSER_RE); a DOM-only/JSDOM test is Over-mocked.
+// `render-health` is the spine (page renders without pageerror/console.error/error
+// boundary/5xx); spatial, perceivability, reachability, temporal sit on top. These
+// are the GRADED tokens; the e2e-test presentation sweep is the runner that emits
+// pass/fail per (route, level) — see references/presentation/runner-contract.md.
+const PRESENTATION_LEVELS = new Set([
+  'presentation:render-health',
+  'presentation:spatial',
+  'presentation:perceivability',
+  'presentation:reachability',
+  'presentation:temporal',
+  // `presentation:visual` is a graded presentation token like the rest, but it is
+  // OPT-IN, not part of the route floor (PRESENTATION_ROUTE_FLOOR above): a surface
+  // carries it only by declaring it in its curated requiredLevels. A pixel baseline
+  // is a maintenance liability, so which routes earn one is a per-surface breadth
+  // call — see references/presentation/runner-contract.md ("the opt-in level").
+  'presentation:visual',
+  // `presentation:fidelity` is the other opt-in token, and the only one that is not
+  // SELF-referential: every level above (visual included) takes the implementation
+  // as its own authority, so a page built wrong from a right design passes all of
+  // them — a pixel baseline shot of the wrong page is green forever. Fidelity asks
+  // whether the surface matches the design source it was DERIVED from, so a surface
+  // carries it only when its work item cites one (prototype/mockup/layout-fixing
+  // doc). Proven by a real-browser spec that drives `design-parity.mjs probe` and
+  // asserts via `design-parity.mjs validate --observed` — see
+  // references/presentation/axis.md ("presentation:fidelity").
+  'presentation:fidelity',
+])
+
+// Any `presentation:*` level (incl. cell-qualified ones like
+// `presentation:perceivability@dark`) is a presentation level — proven against a
+// real rendered page. Prefix-based so feature-derived escalation can mint new
+// condition cells without enumerating every combination here.
+function isPresentationLevel(level) {
+  return typeof level === 'string' && level.startsWith('presentation:')
+}
+
+// Feature-derived escalation (Dimension B of the condition matrix). The adapter
+// emits deterministic per-surface `signals`; each signal RAISES the floor by adding
+// cell-qualified presentation levels. Pure + deterministic: same signals → same
+// levels (sorted), so two agents on the same code compute identical obligations.
+//   - themeToggle → perceivability must also hold in dark theme
+//   - i18n        → spatial must also hold under a long locale and RTL
+function presentationEscalation(signals = {}) {
+  const out = []
+  if (signals.themeToggle) out.push('presentation:perceivability@dark')
+  if (signals.i18n) out.push('presentation:spatial@long-locale', 'presentation:spatial@rtl')
+  return [...new Set(out)].sort()
+}
+
+// Gated removal of an escalated cell (Dimension B exclusion). A cell may be dropped
+// only with a `category` + `reason`; the mechanical base floor (unqualified levels)
+// can NEVER be removed this way, and every removal is recorded for the census.
+// `cellExclusions` is a map: { 'presentation:perceivability@dark': { category, reason } }.
+function applyCellExclusions(levels, cellExclusions = {}) {
+  const kept = [], census = [], rejected = []
+  for (const lvl of levels) {
+    const ex = cellExclusions[lvl]
+    if (!ex) { kept.push(lvl); continue }
+    if (!lvl.includes('@')) { rejected.push({ level: lvl, why: 'cannot exclude a base (unqualified) floor level' }); kept.push(lvl); continue }
+    if (!ex.category || !ex.reason) { rejected.push({ level: lvl, why: 'cell exclusion needs category + reason' }); kept.push(lvl); continue }
+    census.push({ level: lvl, category: ex.category, reason: ex.reason })
+  }
+  return { kept, census, rejected }
+}
+
+// Synonyms: a test level satisfies a required level if it intersects this set.
+const SYNONYMS = {
+  'pg-api': ['pg-api', 'integration', 'api', 'db'],
+  'api': ['api', 'pg-api', 'integration'],
+  'integration': ['integration', 'pg-api', 'api', 'db'],
+  'browser-journey': ['browser-journey', 'journey', 'e2e', 'ui-e2e'],
+  'journey': ['journey', 'browser-journey', 'e2e', 'ui-e2e'],
+  'ui-e2e': ['ui-e2e', 'e2e', 'browser-journey', 'journey'],
+  'e2e': ['e2e', 'journey', 'browser-journey', 'ui-e2e'],
+  'unit': ['unit'],
+  // `render-health` is a minimal BROWSER reachability/render floor (NOT a behavior
+  // level — see BEHAVIOR_LEVELS — and deliberately NOT satisfiable by `api`: a real
+  // browser must load the page and render it, not just return HTTP 200). A fuller
+  // browser journey also satisfies it. This is the breadth-floor sibling of the
+  // presentation spine `presentation:render-health` and of e2e-test's Tier-1
+  // (Render-health). `smoke` is kept as a back-compat alias (same floor, old name).
+  'render-health': ['render-health', 'smoke', 'browser-journey', 'journey', 'ui-e2e', 'e2e'],
+  'smoke': ['render-health', 'smoke', 'browser-journey', 'journey', 'ui-e2e', 'e2e'],
+  'no-secret-assertion': ['no-secret-assertion'],
+  // Presentation levels are exact-match: a `presentation:spatial` obligation is
+  // only satisfied by a test that declares `@level presentation:spatial`. A
+  // functional browser-journey does NOT satisfy it (a journey clicks the DOM; it
+  // does not assert the page is laid out without overflow).
+  'presentation:spatial': ['presentation:spatial'],
+  'presentation:perceivability': ['presentation:perceivability'],
+  'presentation:reachability': ['presentation:reachability'],
+  'presentation:temporal': ['presentation:temporal'],
+  // Opt-in pixel baseline — exact-match like its siblings (a functional journey or
+  // any other presentation level does not satisfy it). Only present on a surface
+  // whose curated requiredLevels raised it in.
+  'presentation:visual': ['presentation:visual'],
+  // Exact-match for the same reason, and one more: `presentation:visual` is the
+  // level most likely to be offered as a substitute ("we have a baseline, isn't
+  // that the same check?"). It is not — a baseline captured from the built page
+  // ratifies whatever shipped, which is precisely the failure fidelity exists to
+  // catch. Neither satisfies the other.
+  'presentation:fidelity': ['presentation:fidelity'],
+}
+
+// ---------- small fs helpers ----------
+
+function* walk(dir) {
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+  for (const e of entries) {
+    if (e.name.startsWith('.') && e.name !== '.') continue
+    const full = path.join(dir, e.name)
+    if (e.isDirectory()) {
+      if (IGNORE_DIRS.has(e.name)) continue
+      yield* walk(full)
+    } else {
+      yield full
+    }
+  }
+}
+
+async function loadStructured(file) {
+  const raw = fs.readFileSync(file, 'utf8')
+  if (file.endsWith('.json')) return JSON.parse(raw)
+  let yaml
+  try { ({ default: yaml } = await import('js-yaml')) }
+  catch { throw new Error(`Reading ${file} needs YAML support. Run \`npm install js-yaml\` in scripts/, or use .json coverage files.`) }
+  return yaml.load(raw)
+}
+
+// ---------- loaders ----------
+
+function loadInventory(cfg) {
+  if (!fs.existsSync(cfg.inventory)) {
+    throw new Error(`Inventory not found: ${cfg.inventory}. Generate it first (see references/breadth/inventory-contract.md).`)
+  }
+  const data = JSON.parse(fs.readFileSync(cfg.inventory, 'utf8'))
+  const surfaces = new Map() // id -> { kind, class, reachability }
+  if (Array.isArray(data.surfaces)) {
+    for (const s of data.surfaces) surfaces.set(s.id, { kind: s.kind || 'unknown', class: s.class || null, reachability: s.reachability || null, signals: s.signals || null })
+  } else {
+    // lenient grouped form: { routes:[...], apis:[...], tables:[...], events:[...] }
+    // (no class/reachability; entry surfaces fall back to the _default floor)
+    for (const [group, list] of Object.entries(data)) {
+      if (!Array.isArray(list)) continue
+      const kind = group.replace(/s$/, '')
+      for (const id of list) surfaces.set(id, { kind, class: null, reachability: null })
+    }
+  }
+  return surfaces
+}
+
+async function loadCurated(cfg) {
+  const files = []
+  for (const f of walk(cfg.coverageDir)) {
+    if (!/\.coverage\.(ya?ml|json)$/.test(f)) continue
+    const source = path.basename(path.dirname(f)) // adr | prd | design | ...
+    const base = path.basename(f).replace(/\.coverage\.(ya?ml|json)$/, '')
+    const id = base.split('-')[0]
+    const ref = `${source}:${id}`
+    let doc
+    try { doc = await loadStructured(f) } catch (e) { throw new Error(`${f}: ${e.message}`) }
+    const surfaces = doc?.surfaces || {}
+    files.push({ file: f, source, id, ref, criteria: doc?.criteria || null, surfaces })
+  }
+  return files
+}
+
+function scanTests(cfg) {
+  const index = new Map() // surfaceId -> [{file, levels:Set, intercepts}]
+  for (const root of cfg.testRoots) {
+    for (const f of walk(root)) {
+      if (!TEST_RE.test(f)) continue
+      const text = fs.readFileSync(f, 'utf8')
+      const covers = [...text.matchAll(/@covers\s+(\S+)/g)].map((m) => m[1].replace(/^route:/, ''))
+      if (covers.length === 0) continue
+      const levels = new Set([...text.matchAll(/@level\s+(\S+)/g)].map((m) => m[1]))
+      if (levels.size === 0) inferLevels(f).forEach((l) => levels.add(l))
+      const intercepts = INTERCEPT_RE.test(text)
+      const realBrowser = BROWSER_RE.test(text)
+      const domOnly = DOMONLY_RE.test(text)
+      for (const id of covers) {
+        if (!index.has(id)) index.set(id, [])
+        index.get(id).push({ file: f, levels, intercepts, realBrowser, domOnly })
+      }
+    }
+  }
+  return index
+}
+
+function inferLevels(file) {
+  const p = file.replace(/\\/g, '/')
+  if (/\/e2e\//.test(p)) return ['e2e']
+  if (/\/integration\//.test(p)) return ['integration']
+  if (/\/unit\//.test(p)) return ['unit']
+  return ['unit']
+}
+
+// ---------- aggregation ----------
+
+function satisfies(testLevels, required) {
+  const syn = SYNONYMS[required] || [required]
+  for (const tl of testLevels) if (syn.includes(tl)) return true
+  return false
+}
+
+function depthStatus(requiredLevels, tests, opts = {}) {
+  if (tests.length === 0) return { status: 'Missing', note: 'no test annotated @covers this surface' }
+  const required = requiredLevels.length ? requiredLevels : ['unit']
+  let unmet = []
+  let blockedByInterception = false
+  let presentationDomOnly = [] // presentation levels proven without real-render evidence
+  for (const rl of required) {
+    const proving = tests.filter((t) => satisfies(t.levels, rl))
+    if (proving.length === 0) { unmet.push(rl); continue }
+    if (isPresentationLevel(rl)) {
+      // Presentation invariants must be proven against a real rendered page; a
+      // DOM-only / JSDOM test (no real browser drive) is the axis's over-mock.
+      const rendered = proving.filter((t) => t.realBrowser && !t.intercepts)
+      if (rendered.length === 0) { presentationDomOnly.push(rl); unmet.push(rl) }
+    } else if (BEHAVIOR_LEVELS.has(rl)) {
+      const clean = proving.filter((t) => !t.intercepts)
+      if (clean.length === 0) { blockedByInterception = true; unmet.push(rl) }
+    }
+  }
+  if (blockedByInterception) return { status: 'Over-mocked', note: `behavior level met only by internal interception / first-party mocking (route.fulfill/page.route/msw): ${unmet.join(', ')}` }
+  if (presentationDomOnly.length) return { status: 'Over-mocked', note: `presentation level proven without real rendered-page evidence (DOM-only/JSDOM — drive a real browser): ${presentationDomOnly.join(', ')}` }
+  if (unmet.length) return { status: 'Wrong Level', note: `required level(s) not proven: ${unmet.join(', ')}` }
+  // A self-declared @level can never reach Covered on its own. With reviewer
+  // attestation (`verified: true` in the curated file) it promotes; otherwise it
+  // lands at a BLOCKING Unverified.
+  if (opts.attested) return { status: 'Covered', note: 'required level(s) proven by clean tests and reviewer-attested (verified)' }
+  return { status: 'Unverified', note: 'level satisfied statically but not reviewer-attested — assertion/execution quality unconfirmed; add `verified: true` (with evidence) to the curated file to promote to Covered' }
+}
+
+// Turn a depth status into a finding. Missing/Over-mocked/Wrong Level always
+// fail; Unverified blocks the gate by default (see cfg.unverifiedBlocks).
+function emitDepth(findings, cfg, sid, ds) {
+  if (ds.status === 'Missing' || ds.status === 'Over-mocked' || ds.status === 'Wrong Level') {
+    findings.push({ severity: 'error', kind: ds.status, surface: sid, detail: ds.note })
+  } else if (ds.status === 'Unverified') {
+    findings.push({ severity: cfg.unverifiedBlocks === false ? 'warn' : 'error', kind: 'Unverified', surface: sid, detail: ds.note })
+  }
+}
+
+async function build(cfg) {
+  const inventory = loadInventory(cfg)
+  const curated = await loadCurated(cfg)
+  const tests = scanTests(cfg)
+
+  const index = new Map() // surfaceId -> row
+  const findings = []
+
+  // owned surfaces from curated files
+  const owners = new Map() // surfaceId -> { refs, requiredLevels, files, sensitive, verified, exclude }
+  for (const cf of curated) {
+    if (cf.criteria && !fs.existsSync(cf.criteria)) {
+      findings.push({ severity: 'error', kind: 'Stale link', surface: '(criteria)', detail: `${cf.ref} criteria missing: ${cf.criteria}` })
+    }
+    for (const [sid, meta] of Object.entries(cf.surfaces)) {
+      if (!owners.has(sid)) owners.set(sid, { refs: new Set(), requiredLevels: new Set(), files: [], sensitive: false, verified: false, exclude: null, excludeCells: {} })
+      const o = owners.get(sid)
+      o.refs.add(cf.ref)
+      for (const l of meta?.requiredLevels || []) o.requiredLevels.add(l)
+      if (meta?.sensitive) o.sensitive = true
+      if (meta?.verified) o.verified = true
+      if (meta?.exclude) o.exclude = meta.exclude
+      if (meta?.excludeCells) Object.assign(o.excludeCells, meta.excludeCells)
+      o.files.push(cf.file)
+    }
+  }
+
+  // Unrealized: curated surface absent from inventory
+  for (const [sid, o] of owners) {
+    if (!inventory.has(sid)) {
+      index.set(sid, { surface: sid, requirementRefs: [...o.refs], requiredLevels: [...o.requiredLevels], alignment: 'Unrealized requirement', depthStatus: null, evidence: [] })
+      findings.push({ severity: 'error', kind: 'Unrealized requirement', surface: sid, detail: `owned by ${[...o.refs].join(', ')} but not in inventory` })
+    }
+  }
+
+  // Inventory surfaces. Orphan is no longer a hard error: ownership (traceability
+  // to a requirement) is decoupled from the TEST obligation. The baseline floor
+  // auto-applies and is graded at depth whether or not a requirement owns it.
+  for (const [sid, surf] of inventory) {
+    const { kind, class: cls, reachability } = surf
+    const o = owners.get(sid)
+    const ts = tests.get(sid) || []
+
+    // Exclusion (human-declared, gated by adapter signals).
+    if (o?.exclude) {
+      const ex = o.exclude
+      const allowed = exclusionAllowed(kind, cls, reachability)
+      if (!ex.category || !ex.reason) {
+        findings.push({ severity: 'error', kind: 'Exclusion invalid', surface: sid, detail: 'exclude requires both `category` and `reason`' })
+      } else if (!allowed.ok) {
+        findings.push({ severity: 'error', kind: 'Exclusion rejected', surface: sid, detail: allowed.why })
+      } else {
+        // `static` keeps a minimal render-health floor (no surface ships with zero
+        // test); seed/deprecated/internal drop to manifest-only.
+        const residual = ex.category === 'static' ? ['render-health'] : []
+        if (residual.length) {
+          const ds = depthStatus(residual, ts, { attested: !!o.verified })
+          index.set(sid, { surface: sid, kind, class: cls, requirementRefs: [...o.refs].sort(), requiredLevels: residual, alignment: o ? 'Aligned' : 'Orphan surface', depthStatus: ds.status, depthNote: ds.note, evidence: ts.map((t) => t.file) })
+          findings.push({ severity: 'warn', kind: 'Excluded', surface: sid, detail: `${ex.category} → render-health floor: ${ex.reason}${ex.gapIssue ? ` (${ex.gapIssue})` : ''}` })
+          emitDepth(findings, cfg, sid, ds)
+        } else {
+          index.set(sid, { surface: sid, kind, class: cls, requirementRefs: [...o.refs].sort(), requiredLevels: [], alignment: 'Excluded', depthStatus: 'Excluded', evidence: ts.map((t) => t.file) })
+          findings.push({ severity: 'warn', kind: 'Excluded', surface: sid, detail: `${ex.category}: ${ex.reason}${ex.gapIssue ? ` (${ex.gapIssue})` : ''}` })
+        }
+        continue
+      }
+    }
+
+    // Internal surfaces carry no baseline; warn only when nothing reaches them.
+    if (INTERNAL_KINDS.has(kind)) {
+      const reached = ts.length > 0
+      index.set(sid, { surface: sid, kind, class: cls, requirementRefs: [...(o?.refs || [])].sort(), requiredLevels: [], alignment: o ? 'Aligned' : 'Orphan surface', depthStatus: reached ? 'Reached' : 'Dead', evidence: ts.map((t) => t.file) })
+      if (!reached) findings.push({ severity: 'warn', kind: 'Dead surface', surface: sid, detail: `${kind} reached by no test/entry evidence — likely dead or untracked` })
+      continue
+    }
+
+    // Entry surfaces: floor = strictest(baseline, curated raise, sensitive
+    // escalation, feature-derived presentation cells), minus any gated cell
+    // exclusions. The base mechanical floor can never be removed; only escalated
+    // (`@`-qualified) cells may be excluded with a category + reason.
+    const sensitive = !!o?.sensitive
+    const escalation = presentationEscalation(surf.signals || {})
+    const fullFloor = strictest(baselineFor(kind, cls), [...(o?.requiredLevels || [])], sensitive ? sensitiveExtra(kind) : [], escalation)
+    const { kept: required, census: cellCensus, rejected: cellRejected } = applyCellExclusions(fullFloor, o?.excludeCells || {})
+    for (const c of cellCensus) findings.push({ severity: 'warn', kind: 'Cell excluded', surface: sid, detail: `${c.level}: ${c.category} — ${c.reason}` })
+    for (const r of cellRejected) findings.push({ severity: 'error', kind: 'Cell exclusion rejected', surface: sid, detail: `${r.level}: ${r.why}` })
+    const ds = depthStatus(required, ts, { attested: !!o?.verified })
+    index.set(sid, {
+      surface: sid, kind, class: cls,
+      requirementRefs: [...(o?.refs || [])].sort(),
+      requiredLevels: required,
+      alignment: o ? 'Aligned' : 'Orphan surface',
+      depthStatus: ds.status,
+      depthNote: ds.note,
+      evidence: ts.map((t) => t.file),
+    })
+
+    // Ownership gap is a WARN (decoupled), and notes the baseline still applies.
+    if (!o) findings.push({ severity: 'warn', kind: 'Orphan surface', surface: sid, detail: `${kind} owned by no requirement; baseline ${required.join(' ') || '-'} still enforced` })
+
+    // Test obligation is the hard gate.
+    emitDepth(findings, cfg, sid, ds)
+  }
+
+  // Acceptance gate (optional)
+  gateFindings(cfg, curated, findings)
+
+  return { cfg, index, findings }
+}
+
+function gateFindings(cfg, curated, findings) {
+  const sources = Object.entries(cfg.requirementGlobs || {})
+  if (sources.length === 0) {
+    findings.push({ severity: 'info', kind: 'Gate skipped', surface: '-', detail: 'no requirementGlobs configured; acceptance gate not enforced' })
+    return
+  }
+  const haveCriteria = new Set(curated.map((c) => c.ref))
+  for (const [source, dir] of sources) {
+    for (const f of walk(dir)) {
+      if (!/\.mdx?$/.test(f)) continue
+      const text = fs.readFileSync(f, 'utf8')
+      if (!cfg.acceptedMarker.test(text)) continue
+      const id = path.basename(f).split('-')[0].replace(/\.mdx?$/, '')
+      const ref = `${source}:${id}`
+      const noRuntime = /no runtime behavior/i.test(text)
+      if (!haveCriteria.has(ref) && !noRuntime) {
+        findings.push({ severity: 'error', kind: 'Gate', surface: ref, detail: `accepted ${ref} has no ${source}/${id}-*.coverage.* file` })
+      }
+    }
+  }
+}
+
+// ---------- outputs ----------
+
+function indexToObject(index) {
+  const out = {}
+  for (const [sid, row] of [...index].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const { surface, ...rest } = row
+    out[sid] = rest
+  }
+  return out
+}
+
+// Over-mock rate (depth-axis honesty metric). A raw over-mock *count* rises just
+// because the suite grew; a *rate* trends whether the tests that exist are honest.
+// Denominator is surfaces that owe a depth check AND have tests — over-mock is a
+// property of a test that exists but fakes its own internals, so a `Missing`
+// surface (no test at all) is not over-mocked, just absent, and `Excluded`
+// surfaces owe nothing. Numerator is the `Over-mocked` depthStatus the ledger
+// already assigns (behavior level met only by interception, or a presentation
+// level proven DOM-only). Split by axis via the note so a regression points at
+// the right axis. `overMockRate` is 0 when nothing is tested (no honesty to
+// measure), never NaN — a trend consumer can read it unconditionally.
+const DEPTH_GRADED = new Set(['Missing', 'Over-mocked', 'Wrong Level', 'Covered', 'Unverified', 'Partial'])
+function computeMetrics(index) {
+  const rows = [...index.values()]
+  // Only depth-graded surfaces count — not the `Reached`/`Dead` reachability
+  // states (events/jobs), `Excluded`, or `null` (unrealized requirements).
+  const graded = rows.filter((r) => DEPTH_GRADED.has(r.depthStatus))
+  const tested = graded.filter((r) => r.depthStatus !== 'Missing')
+  const overMocked = graded.filter((r) => r.depthStatus === 'Over-mocked')
+  const overMockedPresentation = overMocked.filter((r) => /presentation level/i.test(r.depthNote || '')).length
+  const overMockedBehavior = overMocked.length - overMockedPresentation
+  const rate = tested.length ? overMocked.length / tested.length : 0
+  return {
+    surfaces: index.size,
+    depthGraded: graded.length,
+    tested: tested.length,
+    overMocked: overMocked.length,
+    overMockedBehavior,
+    overMockedPresentation,
+    overMockRate: Math.round(rate * 1e4) / 1e4,
+    overMockRatePct: Math.round(rate * 1000) / 10,
+  }
+}
+
+const fmtOverMock = (m) => `${m.overMocked}/${m.tested} tested surfaces over-mocked (${m.overMockRatePct}%)`
+
+function renderReport(index) {
+  const rows = [...index.values()].sort((a, b) => a.surface.localeCompare(b.surface))
+  const line = (r) => `| \`${r.surface}\` | ${r.kind || '-'} | ${r.alignment} | ${r.depthStatus || '-'} | ${(r.requirementRefs || []).join(', ') || '-'} | ${(r.requiredLevels || []).join(' ') || '-'} | ${(r.evidence || []).length} |`
+  const out = []
+  out.push('# Coverage Index (generated — do not hand-edit)\n')
+  out.push(`**Over-mock rate:** ${fmtOverMock(computeMetrics(index))} — the share of tested surfaces whose depth level is met only by faking first-party internals (behavior interception or DOM-only presentation). Lower is healthier; the gate requires 0.\n`)
+  out.push('| Surface | Kind | Alignment | Depth | Requirements | Required levels | Evidence files |')
+  out.push('|---|---|---|---|---|---|---|')
+  for (const r of rows) out.push(line(r))
+  const adr = rows.filter((r) => (r.requirementRefs || []).some((x) => x.startsWith('adr:')))
+  if (adr.length) {
+    out.push('\n## ADR Coverage Matrix (view: rows with `adr:` refs)\n')
+    out.push('| Surface | Alignment | Depth | ADRs | Required levels |')
+    out.push('|---|---|---|---|---|')
+    for (const r of adr) out.push(`| \`${r.surface}\` | ${r.alignment} | ${r.depthStatus || '-'} | ${(r.requirementRefs).filter((x) => x.startsWith('adr:')).join(', ')} | ${(r.requiredLevels || []).join(' ') || '-'} |`)
+  }
+  return out.join('\n') + '\n'
+}
+
+// ---------- CLI ----------
+
+function parseArgs(argv) {
+  const cmd = argv[2]
+  const cfg = { ...DEFAULTS }
+  const flags = {}
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--strict') flags.strict = true
+    else if (a === '--warn-only') flags.warnOnly = true
+    else if (a.startsWith('--')) { flags[a.slice(2)] = argv[++i] }
+  }
+  if (flags.config && fs.existsSync(flags.config)) Object.assign(cfg, JSON.parse(fs.readFileSync(flags.config, 'utf8')))
+  if (flags.inventory) cfg.inventory = flags.inventory
+  if (flags['coverage-dir']) cfg.coverageDir = flags['coverage-dir']
+  if (flags['test-roots']) cfg.testRoots = flags['test-roots'].split(',')
+  if (flags.out) cfg.indexOut = cfg.reportOut = flags.out
+  if (cfg.acceptedMarker && typeof cfg.acceptedMarker === 'string') cfg.acceptedMarker = new RegExp(cfg.acceptedMarker, 'i')
+  return { cmd, cfg, flags }
+}
+
+function ensureDir(p) { fs.mkdirSync(path.dirname(p), { recursive: true }) }
+
+async function main() {
+  const { cmd, cfg, flags } = parseArgs(process.argv)
+  if (!['aggregate', 'validate', 'report'].includes(cmd)) {
+    console.error('usage: coverage-ledger <aggregate|validate|report> [--config f] [--inventory f] [--coverage-dir d] [--test-roots a,b] [--out f] [--strict] [--warn-only]')
+    process.exit(2)
+  }
+  const { index, findings } = await build(cfg)
+
+  if (cmd === 'aggregate') {
+    ensureDir(cfg.indexOut)
+    fs.writeFileSync(cfg.indexOut, JSON.stringify(indexToObject(index), null, 2) + '\n')
+    // Emit the metrics as a sibling artifact (not a key in the surface-keyed
+    // index, which consumers iterate) so CI / review-pr can trend the rate over
+    // time instead of only gating on zero.
+    const metrics = computeMetrics(index)
+    const metricsOut = path.join(path.dirname(cfg.indexOut), 'coverage-metrics.json')
+    fs.writeFileSync(metricsOut, JSON.stringify(metrics, null, 2) + '\n')
+    console.log(`wrote ${cfg.indexOut} (${index.size} surfaces) · ${metricsOut} (${fmtOverMock(metrics)})`)
+    return
+  }
+  if (cmd === 'report') {
+    ensureDir(cfg.reportOut)
+    fs.writeFileSync(cfg.reportOut, renderReport(index))
+    console.log(`wrote ${cfg.reportOut}`)
+    return
+  }
+
+  // validate
+  const errors = findings.filter((f) => f.severity === 'error' || (flags.strict && f.severity === 'warn'))
+  const warns = findings.filter((f) => f.severity === 'warn' && !flags.strict)
+  const infos = findings.filter((f) => f.severity === 'info')
+  const fmt = (f) => `  [${f.kind}] ${f.surface}: ${f.detail}`
+  if (errors.length) { console.log(`\nERRORS (${errors.length}):`); errors.forEach((f) => console.log(fmt(f))) }
+  if (warns.length) { console.log(`\nWARNINGS (${warns.length}):`); warns.forEach((f) => console.log(fmt(f))) }
+  if (infos.length) infos.forEach((f) => console.log(`\nnote: ${f.detail}`))
+  const aligned = [...index.values()].filter((r) => r.alignment === 'Aligned').length
+  console.log(`\n${index.size} surfaces · ${aligned} aligned · ${fmtOverMock(computeMetrics(index))} · ${errors.length} errors · ${warns.length} warnings`)
+  if (errors.length && !flags.warnOnly) process.exit(1)
+}
+
+// Run the CLI only when invoked directly; importing this module (e.g. from tests)
+// must not execute main().
+if (isMainModule(import.meta.url)) {
+  main().catch((e) => { console.error(`coverage-ledger: ${e.message}`); process.exit(2) })
+}
+
+export {
+  build, depthStatus, baselineFor, sensitiveExtra, strictest, satisfies,
+  isPresentationLevel, presentationEscalation, applyCellExclusions, computeMetrics,
+  BASELINE, SYNONYMS, BEHAVIOR_LEVELS, PRESENTATION_LEVELS,
+  PRESENTATION_ROUTE_FLOOR, PRESENTATION_VIEWPORT_FLOOR,
+}