@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-constraint-scan.mjs.ejs

@@ -0,0 +1,681 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// INV-115 enforcement (generated by arbiter): extracts hard prohibitions
+// (NEVER / MUST NOT / DO NOT / 🛑 / `No <tok>` / `never <tok>`) from this project's
+// governance docs and classifies each as COVERED (verified enforcer), ENFORCED-BY-SCAN
+// (derivable token, live-grepped), or UNENFORCEABLE (triage). Mirrors the self-repo gate
+// (scripts/check-constraint-scan.mjs); extends CANON-09 to free-text governance.
+// Usage: node scripts/check-constraint-scan.mjs [--docs=a,b] [--src=dir] [--map=path]
+//        [--enforce[=true|false]] [--baseline=path] [--update-baseline] [--help]
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { createHash } from 'node:crypto'
+import { isMainModule } from './lib/run-helpers.mjs'
+
+// Generated default: WARN on un-covered derivable prohibitions (start-warn-promote-later).
+// Curate `constraint-map.json`, then run with --enforce=true to hard-fail in CI.
+const ENFORCE_DEFAULT = false
+
+// Is a readable baseline REQUIRED for the ratchet to be considered armed? FALSE here and true in
+// arbiter's own copy, deliberately: `arbiter init` emits no coverage baseline, so requiring one
+// would hard-fail a generated project's very first gate run on a file it was never given. A
+// consumer arms the ratchet when ready, with `--update-baseline`; until then the RATCHET-UNSET
+// notice below says plainly that coverage is not yet pinned.
+const RATCHET_REQUIRED = false
+
+// AC-3 ratchet (#2384): the covered/unenforceable ratio is pinned in a committed
+// baseline so triage cannot silently drift back. Same one-way shape as
+// scripts/debt-baseline.json — --update-baseline only ever tightens.
+const BASELINE_DEFAULT = 'scripts/data/constraint-coverage-baseline.json'
+const PROSE_PREFIX = 'prose:'
+// An acceptance is a claim that no mechanism can carry this rule. It costs a written
+// reason, or it is a loophole: too-short rationales are MAP-INVALID, never ACCEPTED.
+const MIN_RATIONALE = 40
+
+const HELP = `Usage: node scripts/check-constraint-scan.mjs [options]
+
+Extracts hard prohibitions from governance docs and classifies each:
+  COVERED          — mapped to an existing, verified enforcer (gate/hook/inv/lint/template)
+  ENFORCED-BY-SCAN — derivable code token, live-grepped against --src every run
+  ACCEPTED         — judgment-level prose, explicitly triaged with a written rationale
+  UNENFORCEABLE    — prose / path / non-code token, NOT yet triaged (the backlog)
+A map entry naming a non-existent enforcer is MAP-FICTION and always fails; a
+"prose:<verbatim line>" entry matching no extracted prohibition is MAP-DEAD; an
+"accepted" entry without a written rationale is MAP-INVALID. Both also fail.
+
+Options:
+  --docs=<a,b,c>   Comma-separated governance docs (default: AGENTS.md,docs/SYSTEM/CANON.md,.claude/CLAUDE.md)
+  --src=<dir>      Source root to scan for live hits (default: src)
+  --map=<path>     Constraint map JSON (default: scripts/constraint-map.json)
+  --enforce[=bool] Hard-fail on ENFORCED-BY-SCAN live hits (default: ${ENFORCE_DEFAULT})
+  --baseline=<p>   Coverage ratchet baseline (default: ${BASELINE_DEFAULT})
+  --update-baseline  Tighten the baseline; REFUSES to record a regression
+  --help, -h       Show this help and exit
+`
+
+function parseArgs(argv) {
+  const get = (name) => {
+    const flag = argv.find((a) => a === `--${name}` || a.startsWith(`--${name}=`))
+    if (!flag) return undefined
+    const eq = flag.indexOf('=')
+    return eq === -1 ? '' : flag.slice(eq + 1)
+  }
+  const docs = get('docs')
+  const src = get('src')
+  const map = get('map')
+  const enforceRaw = get('enforce')
+  const baseline = get('baseline')
+  return {
+    help: argv.includes('--help') || argv.includes('-h'),
+    baseline: baseline || BASELINE_DEFAULT,
+    updateBaseline: argv.includes('--update-baseline'),
+    // The ratchet measures THIS project's governance corpus against THIS project's map.
+    // A run pointed at fixture docs or a fixture map measures something else, so it is
+    // not ratcheted unless the caller named a baseline explicitly.
+    ratchetScoped: baseline !== undefined || (docs === undefined && map === undefined),
+    docs: docs
+      ? docs.split(',').map((s) => s.trim()).filter(Boolean)
+      : ['AGENTS.md', 'docs/SYSTEM/CANON.md', '.claude/CLAUDE.md'],
+    src: src || 'src',
+    map: map || 'scripts/constraint-map.json',
+    enforce: enforceRaw === undefined ? ENFORCE_DEFAULT : enforceRaw !== 'false',
+  }
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+const NEVER_BLOCK_HEADER = /^\s*\*\*(Never|Don't|Do ?not)\b[^*]*\*\*\s*$/i
+const EXCLUDED_FIELD =
+  /^\s*(>|(?:[-*]\s+)?(?:\*\*|_)(Why|Source|Sources|Enforcement|Promoted|Extended|Tradeoff)\b)/i
+const BULLET = /^\s*[-*]\s+/
+const INLINE_MARKERS = [
+  /MUST\s+NOT\b/i,
+  /MUST\s+NEVER\b/i,
+  /DO\s+NOT\b/i,
+  /🛑/,
+  /^\s*[-*]?\s*No\s+(?=`)/,
+  /\bnever\b/i,
+]
+// #2582: the passive/adjectival register — "X is forbidden", "Y are prohibited", "prohibited: Z",
+// "not permitted", "not allowed", "disallowed". The banned thing usually PRECEDES the marker, so
+// tokens are derived from the clause before it (or after a lead "prohibited:" colon). Counted only
+// at entry level: a nested sub-bullet under an entry is that entry's elaboration (mechanics, scope,
+// enforcement notes), where this register describes context rather than states a rule (AC-4).
+const PASSIVE_MARKER = /\b(?:forbidden|prohibited|disallowed|not\s+(?:permitted|allowed))\b/i
+const NESTED_BULLET = /^\s{2,}[-*]\s+/
+// A negated passive ("nothing is prohibited", "not forbidden") states the absence of a rule.
+const NEGATED_PASSIVE = /\b(?:nothing|not|no longer)\s+(?:is\s+|are\s+)?(?:forbidden|prohibited|disallowed)\b/i
+
+function tokensIn(text) {
+  const out = []
+  const re = /`([^`]+)`/g
+  let m
+  while ((m = re.exec(text))) out.push(m[1])
+  return out
+}
+
+// Every backtick token AFTER the marker is a prohibited symbol — `MUST NOT use `a` or `b``
+// bans both. Tokens BEFORE the marker (e.g. the approved wrapper in "use `x`, never `y`") are
+// excluded by construction. Returns [] when no token follows (→ UNENFORCEABLE).
+function tokensAfter(line, markerRe) {
+  const m = markerRe.exec(line)
+  if (!m) return []
+  let tail = line.slice(m.index + m[0].length)
+  const boundary = tail.indexOf('. ')
+  if (boundary !== -1) tail = tail.slice(0, boundary + 1)
+  return tokensIn(tail)
+}
+
+// Tokens for the passive register: after a lead "prohibited:" colon, otherwise the clause before
+// the marker, clipped to its own sentence so an earlier clause's tokens are not swept in.
+function tokensAround(line, markerRe) {
+  const m = markerRe.exec(line)
+  if (!m) return []
+  const after = line.slice(m.index + m[0].length)
+  if (/^\s*:/.test(after)) return tokensAfter(line, markerRe)
+  let before = line.slice(0, m.index)
+  // Clause boundary: the approved alternative in "use `x`; `y` is forbidden" must not be swept in.
+  const boundary = Math.max(before.lastIndexOf('. '), before.lastIndexOf('; '))
+  if (boundary !== -1) before = before.slice(boundary + 2)
+  return tokensIn(before)
+}
+
+function pushProhibition(out, doc, line, text, toks) {
+  if (toks.length === 0) out.push({ doc, line, text: text.trim(), token: null })
+  else for (const tk of toks) out.push({ doc, line, text: text.trim(), token: tk })
+}
+
+function extractProhibitions(docPath, body) {
+  const lines = body.split('\n')
+  const out = []
+  let inBlock = false
+  let blockHasBullet = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (NEVER_BLOCK_HEADER.test(line)) {
+      inBlock = true
+      blockHasBullet = false
+      continue
+    }
+    if (inBlock) {
+      if (line.trim() === '') {
+        if (blockHasBullet) inBlock = false
+        continue
+      }
+      if (BULLET.test(line)) {
+        blockHasBullet = true
+        let toks = []
+        let markerFound = false
+        for (const marker of INLINE_MARKERS) {
+          if (marker.test(line)) {
+            toks = tokensAfter(line, marker)
+            markerFound = true
+            break
+          }
+        }
+        if (!markerFound) toks = tokensIn(line)
+        if (toks.length === 0) out.push({ doc: docPath, line: i + 1, text: line.trim(), token: null })
+        else for (const tk of toks) out.push({ doc: docPath, line: i + 1, text: line.trim(), token: tk })
+        continue
+      }
+      inBlock = false
+    }
+    if (EXCLUDED_FIELD.test(line)) continue
+    const marker = INLINE_MARKERS.find((re) => re.test(line))
+    if (marker) {
+      pushProhibition(out, docPath, i + 1, line, tokensAfter(line, marker))
+    } else if (
+      !NESTED_BULLET.test(line) &&
+      PASSIVE_MARKER.test(line) &&
+      !NEGATED_PASSIVE.test(line)
+    ) {
+      pushProhibition(out, docPath, i + 1, line, tokensAround(line, PASSIVE_MARKER))
+    }
+  }
+  return out
+}
+
+const DERIVABLE_KEYWORDS = new Set(['var', 'any', 'eval'])
+function isDerivable(tok) {
+  const t = tok.trim()
+  if (DERIVABLE_KEYWORDS.has(t)) return true
+  if (t.length < 3) return false
+  if (t.includes('/')) return false
+  if (/\.(json|mjs|cjs|ts|tsx|js|jsx|md|txt|ya?ml|toml|lock)\b/i.test(t)) return false
+  if (/\s/.test(t)) return false
+  if (t.includes('(')) return true
+  if (/[_]/.test(t) || /[A-Z]/.test(t)) {
+    if (t.includes('-')) return false
+    return true
+  }
+  return false
+}
+
+function tokenToRegExp(tok) {
+  const esc = escapeRegExp(tok)
+  return /^[A-Za-z_$][\w$]*$/.test(tok) ? new RegExp(`\\b${esc}\\b`) : new RegExp(esc)
+}
+
+const CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs)$/
+let scanIncomplete = false
+function walk(dir, acc) {
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch (err) {
+    process.stderr.write(`[SCAN-INCOMPLETE] cannot read dir ${dir}: ${err.message}\n`)
+    scanIncomplete = true
+    return acc
+  }
+  for (const e of entries) {
+    if (e === 'node_modules' || e === '.git' || e === 'dist' || e === 'coverage') continue
+    const full = join(dir, e)
+    let st
+    try {
+      st = statSync(full)
+    } catch (err) {
+      process.stderr.write(`[SCAN-INCOMPLETE] cannot stat ${full}: ${err.message}\n`)
+      scanIncomplete = true
+      continue
+    }
+    if (st.isDirectory()) walk(full, acc)
+    else if (CODE_EXT.test(e)) acc.push(full)
+  }
+  return acc
+}
+
+function enforcerExists(enforcer, kind, root) {
+  switch (kind) {
+    case 'hook':
+      return existsSync(join(root, '.claude/hooks', enforcer))
+    case 'script':
+      return existsSync(join(root, 'scripts', enforcer))
+    case 'gate': {
+      const gate = join(root, 'scripts/check-all.mjs')
+      return existsSync(gate) && readFileSync(gate, 'utf8').includes(enforcer)
+    }
+    case 'inv': {
+      const cat = join(root, 'src/invariants/catalog.ts')
+      return existsSync(cat) && readFileSync(cat, 'utf8').includes(enforcer)
+    }
+    case 'lint': {
+      // Require the rule to be ACTIVE (error/2), not merely present — a disabled rule
+      // (`"no-var": "off"`) must not read as COVERED. Works for both JSON (.eslintrc*) and
+      // flat-config (eslint.config.js) since both spell it `<rule>: 'error'` / `: 2` / `['error'`.
+      const configs = readdirSync(root).filter((f) => /eslint/i.test(f) && /\.(json|js|cjs|mjs|yaml|yml)$/i.test(f))
+      const activeRe = new RegExp(`${escapeRegExp(enforcer)}["']?\\s*[:=]\\s*\\[?\\s*["']?(error|2)\\b`)
+      return configs.some((c) => {
+        try {
+          return activeRe.test(readFileSync(join(root, c), 'utf8'))
+          // FAIL-OPEN-INTENT: unreadable config just means THIS candidate can't vouch for the rule — other readable candidates in `configs` are still checked, nothing here drops a real violation.
+        } catch {
+          return false
+        }
+      })
+    }
+    case 'githook':
+      return existsSync(join(root, '.githooks', enforcer))
+    case 'template':
+      return existsSync(join(root, enforcer))
+    default:
+      return false
+  }
+}
+
+// ─── Coverage ratchet (AC-3, #2384; retirement-safe + tamper-closed, #2520) ──────────────
+// #2520 root cause: `covered` was ratcheted as an absolute "may only rise" floor, but the
+// denominator (how many prohibitions even exist) is not fixed — a prohibition can be
+// LEGITIMATELY RETIRED (removed from the docs and its map entry together), which shrinks
+// `covered` without anything losing enforcement. The old floor could not tell that apart
+// from a real regression, so retiring a covered prohibition made the ratchet unsatisfiable
+// by any honest means (hand-edit the baseline, leave the gate permanently red, or never
+// retire a prohibition again).
+//
+// Fix: `covered` is recorded for visibility only (like `accepted` already was) and is no
+// longer itself a ratchet floor. The ONLY regression signal is `unenforceable` (the
+// uncovered/untriaged backlog) rising — unchanged from before, lower-is-better. This
+// correctly distinguishes the two cases a bare `covered` count could not:
+//   - retire a COVERED prohibition (removed from docs + map together): `unenforceable` is
+//     untouched, so nothing is flagged — exactly the legitimate case.
+//   - drop or break a prohibition's MAPPING while the prohibition itself still stands (the
+//     doc corpus is unchanged): the prohibition falls out of `covered` and into
+//     `unenforceable`, `unenforceable` rises, and the ratchet still refuses — exactly the
+//     regression case, caught the same way a direct rise always was.
+// `--update-baseline` still REFUSES to write when `unenforceable` rose.
+//
+// Tamper-closed (#2520): a hand-edited baseline is, on its face, indistinguishable from a
+// real one. Every WRITE stamps an `integrityHash` — a sha256 digest over the exact
+// `{version, capturedAt, metrics}` payload — and every READ verifies it. A baseline missing
+// the hash, or carrying one that does not match its own recorded values, was not produced
+// by this tool and is untrusted: fail-closed at exit 2, never merely exit 1.
+export function computeBaselineIntegrityHash(payload) {
+  return createHash('sha256')
+    .update(JSON.stringify({ version: payload.version, capturedAt: payload.capturedAt, metrics: payload.metrics }))
+    .digest('hex')
+}
+
+function metricValue(metrics, key, fallback) {
+  const raw = metrics && typeof metrics === 'object' ? metrics[key] : undefined
+  const value = raw && typeof raw === 'object' ? raw.value : undefined
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+// A baseline the tool did not write is untrusted, full stop — a missing hash and a
+// mismatched hash are the same failure (not-tool-authored), reported identically.
+function verifyBaselineIntegrity(base) {
+  if (base == null || typeof base !== 'object' || Array.isArray(base)) return false
+  const { integrityHash } = base
+  if (typeof integrityHash !== 'string' || integrityHash === '') return false
+  return integrityHash === computeBaselineIntegrityHash(base)
+}
+
+// #2384: a well-formed, correctly-signed baseline recording no floor for the metric the ratchet
+// enforces used to fall back to the permissive +Infinity, so `{"version":1,"metrics":{}}` was a
+// silent full disarm that still passed the integrity check. A floor that is not recorded is not
+// a floor. Generated projects leave RATCHET_REQUIRED false until they seed a baseline, so this
+// refusal is inert for them and the RATCHET-UNSET path stays their behaviour.
+//
+// Scoped to `unenforceable` alone, deliberately: #2520 retired the `covered` floor (written as
+// `direction: 'informational'` and read by nothing), because a covered-count floor breaks every
+// time a rule is legitimately retired. Demanding a floor the tool no longer enforces would be
+// demanding a fiction — the invariant kept here is that the ENFORCED floor must be present.
+function refuseFloorlessBaseline(path, baseUnenf) {
+  if (!RATCHET_REQUIRED) return
+  if (baseUnenf !== null) return
+  process.stdout.write(
+    `[RATCHET-MISSING] ${path} records no unenforceable floor — a baseline without metrics ` +
+      `disarms the ratchet silently; re-seed it with --update-baseline\n`,
+  )
+  process.exit(1)
+}
+
+// Reads the committed baseline's ratchet floor. `trusted: false` (unreadable, malformed, or
+// missing/mismatched integrityHash) is the caller's decision to act on: a plain read (no
+// --update-baseline) must fail closed at exit 2 — a ratchet that cannot verify its floor
+// must never silently pass. `--update-baseline` instead treats it as no verifiable floor at
+// all and self-heals by re-signing fresh (same as the file-absent seed path) — that is
+// exactly the deliberate, reviewed action meant to fix it, mirroring how a missing baseline
+// is seeded rather than refused.
+function readBaselineBounds(path) {
+  let base
+  try {
+    base = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (err) {
+    process.stderr.write(`[constraint-scan] invalid baseline JSON at ${path}: ${err.message}\n`)
+    return { trusted: false }
+  }
+  if (!verifyBaselineIntegrity(base)) return { trusted: false }
+  const baseUnenf = metricValue(base.metrics, 'unenforceable', null)
+  refuseFloorlessBaseline(path, baseUnenf)
+  return {
+    trusted: true,
+    baseUnenf: baseUnenf ?? Number.POSITIVE_INFINITY,
+  }
+}
+
+function ratchetOk(args, root, covered, accepted, unenforceable) {
+  if (!args.ratchetScoped) return true
+  const path = resolve(root, args.baseline)
+  const payload = {
+    version: 1,
+    capturedAt: new Date().toISOString(),
+    metrics: {
+      covered: { value: covered, unit: 'count', direction: 'informational' },
+      accepted: { value: accepted, unit: 'count', direction: 'informational' },
+      unenforceable: { value: unenforceable, unit: 'count', direction: 'lower-is-better' },
+    },
+  }
+  const write = (p) => {
+    const integrityHash = computeBaselineIntegrityHash(p)
+    writeFileSync(path, `${JSON.stringify({ ...p, integrityHash }, null, 2)}\n`)
+  }
+  if (!existsSync(path)) {
+    if (args.updateBaseline) {
+      write(payload)
+      process.stdout.write(
+        `[RATCHET-UPDATED] ${args.baseline} seeded at ${covered} covered / ${unenforceable} uncovered\n`,
+      )
+      return true
+    }
+    if (RATCHET_REQUIRED) {
+      process.stdout.write(
+        `[RATCHET-MISSING] no baseline at ${args.baseline} — the ratchet is unarmed; seed it with ` +
+          `--update-baseline (deleting the baseline must not be a way to pass)\n`,
+      )
+      return false
+    }
+    process.stdout.write(
+      `[RATCHET-UNSET] no baseline at ${args.baseline} — coverage is not ratcheted yet\n`,
+    )
+    return true
+  }
+  const bounds = readBaselineBounds(path)
+  if (!bounds.trusted) {
+    if (args.updateBaseline) {
+      write(payload)
+      process.stdout.write(
+        `[RATCHET-UPDATED] ${args.baseline} was not produced by this tool (missing/mismatched ` +
+          `integrityHash) — re-signed fresh at ${covered} covered / ${unenforceable} uncovered\n`,
+      )
+      return true
+    }
+    process.stderr.write(
+      `[constraint-scan] baseline at ${path} has a missing or mismatched integrityHash — it ` +
+        `was not produced by this tool, so its recorded values cannot be trusted. Regenerate ` +
+        `it with:\n  node scripts/check-constraint-scan.mjs --update-baseline\n`,
+    )
+    process.exit(2)
+  }
+  const { baseUnenf } = bounds
+  let regressed = false
+  if (unenforceable > baseUnenf) {
+    process.stdout.write(
+      `[RATCHET] uncovered (unenforceable) rose ${baseUnenf} -> ${unenforceable} (${args.baseline})\n`,
+    )
+    regressed = true
+  }
+  if (args.updateBaseline) {
+    if (regressed) {
+      process.stdout.write(
+        '[RATCHET] refusing to update the baseline with a regression — triage the prohibitions instead\n',
+      )
+      return false
+    }
+    payload.metrics.unenforceable.value = Math.min(unenforceable, baseUnenf)
+    write(payload)
+    process.stdout.write(
+      `[RATCHET-UPDATED] ${args.baseline}: ${payload.metrics.covered.value} covered, ` +
+        `${payload.metrics.unenforceable.value} uncovered\n`,
+    )
+    return true
+  }
+  return !regressed
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    process.stdout.write(HELP)
+    process.exit(0)
+  }
+  const root = process.cwd()
+
+  const arbiterJsonPath = resolve(root, 'arbiter.json')
+  if (existsSync(arbiterJsonPath)) {
+    let arbiterCfg
+    try {
+      arbiterCfg = JSON.parse(readFileSync(arbiterJsonPath, 'utf8'))
+    } catch (err) {
+      process.stderr.write(`[check-constraint-scan] invalid arbiter.json: ${err.message}\n`)
+      process.exit(2)
+    }
+    if (arbiterCfg?.governance?.constraintScan === 'off') {
+      process.stdout.write(
+        '[check-constraint-scan] SKIP — governance.constraintScan is "off" in arbiter.json\n',
+      )
+      // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+      process.stdout.write('[SKIP] governance.constraintScan is "off" in arbiter.json\n')
+      process.exit(0)
+    }
+  }
+
+  let map = {}
+  const mapPath = resolve(root, args.map)
+  if (existsSync(mapPath)) {
+    try {
+      map = JSON.parse(readFileSync(mapPath, 'utf8'))
+    } catch (err) {
+      process.stderr.write(`[constraint-scan] invalid map JSON at ${mapPath}: ${err.message}\n`)
+      process.exit(2)
+    }
+    if (map === null || typeof map !== 'object' || Array.isArray(map)) {
+      process.stderr.write(
+        `[constraint-scan] invalid map JSON at ${mapPath}: expected an object, got ` +
+          `${Array.isArray(map) ? 'array' : map === null ? 'null' : typeof map}\n`,
+      )
+      process.exit(2)
+    }
+    map = Object.fromEntries(Object.entries(map).filter(([key]) => !key.startsWith('//')))
+    for (const [tok, entry] of Object.entries(map)) {
+      if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        process.stderr.write(
+          `[constraint-scan] invalid map JSON at ${mapPath}: entry "${tok}" must be an ` +
+            `object with enforcer/kind, got ${entry === null ? 'null' : typeof entry}\n`,
+        )
+        process.exit(2)
+      }
+    }
+  } else {
+    process.stderr.write(
+      `[check-constraint-scan] FAIL — ${args.map} missing; run \`arbiter update\` to scaffold it, ` +
+        `or set governance.constraintScan:"off" in arbiter.json\n`,
+    )
+    process.exit(1)
+  }
+
+  const prohibitions = []
+  let docsScanned = 0
+  for (const d of args.docs) {
+    const p = resolve(root, d)
+    if (!existsSync(p)) continue
+    docsScanned++
+    prohibitions.push(...extractProhibitions(d, readFileSync(p, 'utf8')))
+  }
+
+  // Fail-closed against vacuous green: a constraint gate that finds NO governance docs is
+  // misconfigured, not compliant. Zero docs found must never read as "all prohibitions enforced".
+  if (docsScanned === 0) {
+    process.stderr.write(
+      `[check-constraint-scan] no governance docs found (looked for: ${args.docs.join(', ')}) — misconfigured\n`,
+    )
+    process.exit(1)
+  }
+
+  let srcFiles = null
+  const srcRoot = resolve(root, args.src)
+  function liveHit(tok) {
+    if (srcFiles === null) srcFiles = existsSync(srcRoot) ? walk(srcRoot, []) : []
+    const re = tokenToRegExp(tok)
+    for (const f of srcFiles) {
+      let content
+      try {
+        content = readFileSync(f, 'utf8')
+      } catch (err) {
+        process.stderr.write(`[SCAN-INCOMPLETE] cannot read ${f}: ${err.message}\n`)
+        scanIncomplete = true
+        continue
+      }
+      if (re.test(content)) return f.startsWith(root) ? f.slice(root.length + 1) : f
+    }
+    return null
+  }
+
+  let fiction = 0
+  let invalid = 0
+  let violations = 0
+  const seenCovered = new Set()
+  const seenAccepted = new Set()
+  const seenUnenf = new Set()
+  const usedProseKeys = new Set()
+
+  for (const pr of prohibitions) {
+    const tok = pr.token
+    if (tok && Object.prototype.hasOwnProperty.call(map, tok)) {
+      const { enforcer, kind } = map[tok]
+      if (enforcerExists(enforcer, kind, root)) {
+        if (!seenCovered.has(tok)) {
+          process.stdout.write(`[COVERED] ${tok} → ${kind}:${enforcer}\n`)
+          seenCovered.add(tok)
+        }
+      } else {
+        process.stdout.write(
+          `[MAP-FICTION] ${tok} → ${kind}:${enforcer} (enforcer not found) — ${pr.doc}:${pr.line}\n`,
+        )
+        fiction++
+      }
+      continue
+    }
+    // A prose entry triages one WHOLE LINE by its verbatim text — the only stable key a
+    // token-less prohibition has. It is consulted before token derivation because an explicit
+    // human triage decision for the line supersedes any token scan on that same line.
+    const proseKey = PROSE_PREFIX + pr.text
+    if (Object.prototype.hasOwnProperty.call(map, proseKey)) {
+      usedProseKeys.add(proseKey)
+      const { enforcer, kind, rationale } = map[proseKey]
+      const label = pr.text.slice(0, 60)
+      if (kind === 'accepted') {
+        if (typeof rationale !== 'string' || rationale.trim().length < MIN_RATIONALE) {
+          process.stdout.write(
+            `[MAP-INVALID] ${label} — accepted needs a rationale of >=${MIN_RATIONALE} chars ` +
+              `(${pr.doc}:${pr.line})\n`,
+          )
+          invalid++
+        } else if (!seenAccepted.has(proseKey)) {
+          process.stdout.write(`[ACCEPTED] ${label} — ${pr.doc}:${pr.line} — ${rationale}\n`)
+          seenAccepted.add(proseKey)
+        }
+      } else if (enforcerExists(enforcer, kind, root)) {
+        if (!seenCovered.has(proseKey)) {
+          process.stdout.write(`[COVERED] ${label} → ${kind}:${enforcer} — ${pr.doc}:${pr.line}\n`)
+          seenCovered.add(proseKey)
+        }
+      } else {
+        process.stdout.write(
+          `[MAP-FICTION] ${label} → ${kind}:${enforcer} (enforcer not found) — ` +
+            `${pr.doc}:${pr.line}\n`,
+        )
+        fiction++
+      }
+      continue
+    }
+    if (tok && isDerivable(tok)) {
+      const hit = liveHit(tok)
+      if (hit) {
+        if (args.enforce) {
+          process.stdout.write(`[VIOLATION] ${tok} @ ${hit} (prohibited by ${pr.doc}:${pr.line})\n`)
+          violations++
+        } else {
+          process.stdout.write(`[WARN-SCAN] ${tok} @ ${hit} (prohibited by ${pr.doc}:${pr.line})\n`)
+        }
+      }
+      continue
+    }
+    const sig = tok || pr.text.slice(0, 60)
+    if (!seenUnenf.has(sig)) {
+      process.stdout.write(`[UNENFORCEABLE] ${sig} — ${pr.doc}:${pr.line}\n`)
+      seenUnenf.add(sig)
+    }
+  }
+
+  // A prose entry matching nothing is rot: the line it triaged was reworded or deleted, and
+  // the entry now silently vouches for a prohibition the docs no longer make.
+  for (const key of Object.keys(map)) {
+    if (!key.startsWith(PROSE_PREFIX) || usedProseKeys.has(key)) continue
+    process.stdout.write(
+      `[MAP-DEAD] ${key.slice(PROSE_PREFIX.length).slice(0, 60)} — matches no prohibition\n`,
+    )
+    invalid++
+  }
+
+  if (fiction > 0) {
+    process.stdout.write(`[check-constraint-scan] FAIL: ${fiction} map-fiction entry(ies)\n`)
+    process.exit(1)
+  }
+  if (invalid > 0) {
+    process.stdout.write(`[check-constraint-scan] FAIL: ${invalid} invalid/dead map entry(ies)\n`)
+    process.exit(1)
+  }
+  if (violations > 0) {
+    process.stdout.write(`[check-constraint-scan] FAIL: ${violations} unenforced prohibition violation(s)\n`)
+    process.exit(1)
+  }
+  if (scanIncomplete && args.enforce) {
+    process.stdout.write('[check-constraint-scan] FAIL: scan incomplete — some source files could not be read\n')
+    process.exit(1)
+  }
+  const summary =
+    `${seenCovered.size} covered, ${seenAccepted.size} accepted, ` +
+    `${seenUnenf.size} unenforceable (triage)`
+  if (!ratchetOk(args, root, seenCovered.size, seenAccepted.size, seenUnenf.size)) {
+    process.stdout.write(`[check-constraint-scan] FAIL: coverage ratchet — ${summary}
+`)
+    process.exit(1)
+  }
+  process.stdout.write(
+    `[check-constraint-scan] OK — ${docsScanned} doc(s), ${prohibitions.length} prohibition(s): ` +
+      `${summary}
+`,
+  )
+  process.exit(0)
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main()
+  } catch (err) {
+    process.stderr.write(`[check-constraint-scan] unexpected error: ${err instanceof Error ? err.stack : String(err)}\n`)
+    process.exit(1)
+  }
+}