@getarbiter/cli 0.5.0

package/scripts/check-doc-style.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+//
+// CATALOG: P8 consistency gate. Verifies frontmatter shape + H1 presence +
+// last_review ISO date on every hand-authored .md doc. Distinct from
+// check-doc-links.mjs (link integrity) and check-docs.mjs (src↔docs co-change).
+//
+// Checks (per file):
+//   - frontmatter block present with required keys (title, doc_version,
+//     status, last_review, owner, canonical_id, tags, related)
+//   - `last_review` matches /^\d{4}-\d{2}-\d{2}$/
+//   - `status` ∈ {draft, active, deprecated, archived}
+//   - `doc_version` matches /^\d+\.\d+\.\d+$/
+//   - exactly one top-level H1 (`# ...`) in body
+//   - if frontmatter `title` is non-empty, the H1 text matches it (case-sensitive)
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, sep, relative } from 'node:path'
+import { walkRepo } from './lib/glob-walk.mjs'
+import { isMainModule } from './lib/run-helpers.mjs'
+import { loadDocGateAllowlist, allowlistSummary } from './lib/doc-gate-allowlist.mjs'
+
+const CWD = process.cwd()
+
+const SCAN_ROOTS = ['docs', '.claude', '.agents', '.codex', 'examples']
+const ROOT_FILES = [
+  'AGENTS.md',
+  'README.md',
+  'CODE_OF_CONDUCT.md',
+  'CONTRIBUTING.md',
+  'SECURITY.md',
+  'GLOBAL_INVARIANTS.md',
+  'OBSIDIAN.md',
+]
+export const SKIP_PATH_SEGMENTS = [
+  `${sep}node_modules${sep}`,
+  `${sep}dist${sep}`,
+  `${sep}.git${sep}`,
+  `${sep}.changeset${sep}`,
+  `${sep}api${sep}`,
+  `${sep}.coverage-tmp${sep}`,
+  `${sep}.evidence${sep}`,
+  `${sep}report${sep}`,
+  // #2408: `internal` used to sit here, which exempted the entire SSOT backbone
+  // (FEATURE_MATRIX, PROCESS, TESTING, CANONICAL_PATHS, every ADR) from the one
+  // gate that checks frontmatter — a doc tree the gates skip is a doc tree that
+  // drifts. What cannot be fixed as a one-liner now lives, dated, in
+  // scripts/data/doc-gate-allowlist.json instead.
+  `${sep}.claude${sep}plans${sep}`,
+  `${sep}.claude${sep}.task${sep}`,
+  // #1840 F4 (examples/ viventi): `examples/<name>/` directories are `arbiter
+  // init` OUTPUT for a downstream project, regenerated verbatim by
+  // scripts/regenerate-examples.mjs — their .md files are governed by the
+  // TARGET project's own doc conventions, not arbiter's. The hand-authored
+  // walkthroughs directly under examples/ (examples/README.md,
+  // examples/go-library.md, …) are NOT skipped — only the generated subtrees.
+  `${sep}examples${sep}ts-library${sep}`,
+  `${sep}examples${sep}python-library${sep}`,
+  `${sep}examples${sep}go-library${sep}`,
+]
+// Auto-generated files that bypass frontmatter requirements
+export const SKIP_FILENAMES = new Set([
+  'INDEX.md',
+  'DECISIONS.md', // generated digest (gen-adr-readme.mjs) — uses status: generated
+])
+
+const REQUIRED_KEYS = [
+  'title',
+  'doc_version',
+  'status',
+  'last_review',
+  'owner',
+  'canonical_id',
+  'tags',
+  'related',
+]
+const VALID_STATUS = new Set(['draft', 'active', 'deprecated', 'archived'])
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const SEMVER = /^\d+\.\d+\.\d+$/
+
+function shouldSkip(absPath) {
+  return SKIP_PATH_SEGMENTS.some((s) => absPath.includes(s))
+}
+
+/**
+ * Collect every hand-authored `.md` file under `dir` (recursively). Traversal is delegated to the
+ * shared cycle-safe walkRepo (#1521/#1544); this gate's own SKIP_PATH_SEGMENTS + SKIP_FILENAMES are
+ * re-applied to each returned path so the visited set is identical to the old hand-rolled walk
+ * (minus the symlink-cycle bug), plus walkRepo's widened SKIP_DIRS (build/coverage/.coverage).
+ */
+export function walk(dir) {
+  if (!existsSync(dir) || shouldSkip(dir + sep)) return []
+  const out = []
+  for (const rel of walkRepo(dir)) {
+    const full = join(dir, rel)
+    if (shouldSkip(full)) continue
+    const name = rel.slice(rel.lastIndexOf('/') + 1)
+    if (name.endsWith('.md') && !SKIP_FILENAMES.has(name)) out.push(full)
+  }
+  return out
+}
+
+function collectFiles() {
+  const out = []
+  for (const r of SCAN_ROOTS) out.push(...walk(join(CWD, r)))
+  for (const f of ROOT_FILES) {
+    const abs = join(CWD, f)
+    if (existsSync(abs) && statSync(abs).isFile()) out.push(abs)
+  }
+  return out
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return { present: false }
+  const lines = content.split('\n')
+  if (lines[0] !== '---') return { present: false }
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      const block = lines.slice(1, i)
+      const kv = new Map()
+      for (const ln of block) {
+        const m = ln.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/)
+        if (m) kv.set(m[1], m[2].replace(/^['"]|['"]$/g, '').trim())
+      }
+      return { present: true, kv, bodyStart: i + 1 }
+    }
+  }
+  return { present: false }
+}
+
+function findH1s(content, bodyStart) {
+  const lines = content.split('\n').slice(bodyStart)
+  const h1s = []
+  let inFence = false
+  for (const ln of lines) {
+    if (ln.startsWith('```')) inFence = !inFence
+    if (inFence) continue
+    const m = ln.match(/^#\s+(.+?)\s*$/)
+    if (m) h1s.push(m[1].trim())
+  }
+  return h1s
+}
+
+function main() {
+  const allow = loadDocGateAllowlist('doc-style')
+  process.stdout.write(allowlistSummary('check-doc-style', allow))
+
+  const files = collectFiles()
+  const errors = []
+  const warnings = []
+
+  for (const file of files) {
+    const rel = relative(CWD, file)
+    if (allow.has(rel)) continue
+    const content = readFileSync(file, 'utf-8')
+    const fm = parseFrontmatter(content)
+    if (!fm.present) {
+      errors.push(`${rel}: missing frontmatter block`)
+      continue
+    }
+    // HARD: required keys must be present.
+    const missing = REQUIRED_KEYS.filter((k) => !fm.kv.has(k))
+    if (missing.length > 0) {
+      errors.push(`${rel}: missing frontmatter key(s): ${missing.join(', ')}`)
+    }
+    // HARD: last_review must be ISO date when set.
+    if (
+      fm.kv.has('last_review') &&
+      fm.kv.get('last_review') &&
+      !ISO_DATE.test(fm.kv.get('last_review'))
+    ) {
+      errors.push(`${rel}: last_review "${fm.kv.get('last_review')}" is not ISO date (YYYY-MM-DD)`)
+    }
+    // HARD: doc_version must be semver when set.
+    if (
+      fm.kv.has('doc_version') &&
+      fm.kv.get('doc_version') &&
+      !SEMVER.test(fm.kv.get('doc_version'))
+    ) {
+      errors.push(`${rel}: doc_version "${fm.kv.get('doc_version')}" is not semver (X.Y.Z)`)
+    }
+    // SOFT: status should be one of the canonical lifecycle values.
+    if (fm.kv.has('status') && fm.kv.get('status') && !VALID_STATUS.has(fm.kv.get('status'))) {
+      warnings.push(
+        `${rel}: non-canonical status "${fm.kv.get('status')}" (canonical: ${[...VALID_STATUS].join(', ')})`,
+      )
+    }
+    // SOFT: every doc should have an H1; multi-H1 should be reviewed.
+    const h1s = findH1s(content, fm.bodyStart ?? 0)
+    if (h1s.length === 0) {
+      warnings.push(`${rel}: no H1 heading found in body`)
+    } else if (h1s.length > 1) {
+      warnings.push(`${rel}: ${h1s.length} H1 headings — exactly one preferred`)
+    }
+  }
+
+  if (errors.length === 0) {
+    if (warnings.length > 0) {
+      process.stdout.write(
+        `  check-doc-style: ${files.length} files OK; ${warnings.length} soft warning(s)\n`,
+      )
+      for (const w of warnings.slice(0, 20)) process.stdout.write(`    [warn] ${w}\n`)
+      if (warnings.length > 20)
+        process.stdout.write(`    [warn] ... +${warnings.length - 20} more\n`)
+    } else {
+      process.stdout.write(`  check-doc-style: all ${files.length} files OK\n`)
+    }
+    process.exit(0)
+  }
+
+  process.stdout.write(
+    `  check-doc-style: ${errors.length} hard error(s) across ${files.length} files\n`,
+  )
+  for (const e of errors) process.stdout.write(`    ${e}\n`)
+  if (warnings.length > 0) {
+    process.stdout.write(
+      `  check-doc-style: ${warnings.length} additional soft warning(s) (not failure)\n`,
+    )
+    for (const w of warnings.slice(0, 10)) process.stdout.write(`    [warn] ${w}\n`)
+    if (warnings.length > 10) process.stdout.write(`    [warn] ... +${warnings.length - 10} more\n`)
+  }
+  process.exit(1)
+}
+
+// Only run main when invoked as CLI (not imported in tests).
+if (isMainModule(import.meta.url)) {
+  main()
+}

package/scripts/gold-audit.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// arbiter — native-TS gold-audit engine (#1373). Reimplements the upstream reference gold-audit
+// registry evaluator natively in node (zero Python dependency for consumer projects). The score is
+// computed by code, never by an AI (owner hard requirement). Same repo + same registry ⇒
+// byte-identical output (determinism). Wired into scripts/check-all.mjs as a no-regress gate.
+//
+// Reads a per-stack registry (standards/gold-registry.yml) → per-check verdict Y/P/N/NA/NV with
+// evidence (file [+ line]) → an aggregate score + dimension table. Adds a monotonic ratchet
+// baseline (.gold-audit-baseline.json), a no-regress merge gate (--check), and a false-gap
+// meta-gate (--strict, RISKY>0 fails). The shared evaluator lives in scripts/lib/gold-audit-lib.mjs
+// so the CLI, the gold-report consumer, and the tests share one code path.
+//
+// Exit codes (INV-53 contract): 0 PASS/advisory, 1 FAIL (regression / RISKY / stale), 2 IO error.
+//
+// Usage:
+//   node scripts/gold-audit.mjs [--json [path]] [--check] [--strict] [--update-baseline]
+//                               [--registry P] [--profile P] [--baseline P] [--help]
+//     --json [P]         emit the scored payload as JSON (to stdout, or to file P)
+//     --check            no-regress gate: exit 1 if score/Y dropped below the baseline
+//                        (bootstraps a missing baseline and exits 0)
+//     --require-baseline  N1 fail-closed disarm: with --check, a missing baseline is a HARD FAIL
+//                        (refuse to silently re-bootstrap — deleting the baseline must not pass)
+//     --strict           false-gap meta-gate: exit 1 if any check is RISKY
+//     --update-baseline  monotonically ratchet the baseline (never lowers a field)
+//     --stack S          select per-stack registry standards/gold-registry.<S>.yml (unless
+//                        --registry is given); also a presentation hint
+//     --class C          brownfieldClass for the level band: gold|light|medium|heavy (default gold)
+//     --registry P       registry path (default standards/gold-registry.yml)
+//     --profile P        overlay profile path (default standards/gold-profile)
+//     --baseline P       baseline path (default .gold-audit-baseline.json)
+//     --thresholds P     brownfield-class threshold SSOT (default standards/thresholds.yml) —
+//                        resolves value-op threshold_ref per --class
+//     --help, -h         show this help
+//
+// The default/--json output carries a deterministic LEVEL band (L0–L3 keyed by brownfieldClass)
+// and a "what's missing" gap report (the N/P checks + evidence, grouped by dimension). These are
+// presentation-only keys appended to the payload; the no-regress baseline (score/yCount/dimensions)
+// is unaffected (#1414).
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import {
+  evaluate,
+  checkNoRegress,
+  ratchet,
+  baselineOf,
+  levelBand,
+  gapReport,
+  freshness,
+} from './lib/gold-audit-lib.mjs'
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    [
+      'Usage: node scripts/gold-audit.mjs [options]',
+      '',
+      'Deterministic registry→Y/P/N gold-audit engine (the score is code-computed, never AI).',
+      '',
+      '  --json [P]         emit the scored payload as JSON (stdout, or file P)',
+      '  --check            no-regress gate: exit 1 if score/Y dropped vs baseline',
+      '  --require-baseline N1 disarm guard: with --check, a missing baseline is a HARD FAIL',
+      '  --strict           false-gap meta-gate: exit 1 if any RISKY check exists',
+      '  --check-fresh      freshness gate: exit 1 if value-check reports are STALE (none present)',
+      '  --stale-hours N    freshness window in hours for --check-fresh / the banner (default 24)',
+      '  --update-baseline  monotonically ratchet the baseline (never lowers a field)',
+      '  --stack S          select per-stack registry standards/gold-registry.<S>.yml',
+      '  --class C          brownfieldClass for the level band: gold|light|medium|heavy',
+      '  --registry P       registry path (default standards/gold-registry.yml)',
+      '  --profile P        overlay profile path (default standards/gold-profile)',
+      '  --baseline P       baseline path (default .gold-audit-baseline.json)',
+      '  --thresholds P     brownfield-class threshold SSOT (resolves value-op threshold_ref)',
+      '  --help, -h         show this help',
+      '',
+    ].join('\n'),
+  )
+  process.exit(0)
+}
+
+const flag = (name) => args.includes(name)
+const opt = (name, def) => {
+  const i = args.indexOf(name)
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : def
+}
+
+const CWD = process.cwd()
+// --stack S selects a per-stack registry (standards/gold-registry.<S>.yml) unless --registry is
+// given explicitly. --class C overrides the brownfieldClass used for the level band (#1414).
+const STACK = opt('--stack', null)
+const CLASS = opt('--class', 'gold')
+const REGISTRY = opt(
+  '--registry',
+  STACK ? `standards/gold-registry.${STACK}.yml` : 'standards/gold-registry.yml',
+)
+const PROFILE = opt('--profile', 'standards/gold-profile')
+const BASELINE = opt('--baseline', '.gold-audit-baseline.json')
+// --thresholds P: the brownfield-class SSOT used to resolve value-op `threshold_ref` per --class
+// (#1413). The value op reads pre-generated tool reports; the bar differs by brownfield class.
+const THRESHOLDS = opt('--thresholds', 'standards/thresholds.yml')
+// #1473: freshness window (hours) for --check-fresh and the advisory banner.
+const STALE_HOURS = Number(opt('--stale-hours', 24))
+
+/**
+ * Enrich the raw scored payload with the #1414 presentation fields (level band + gap report).
+ * Appended as NEW keys so the no-regress baseline (score/yCount/dimensions) is untouched; the
+ * level band is keyed by --class (deterministic — no fs-dependent auto-detection in the engine).
+ */
+function withPresentation(result) {
+  return { ...result, level: levelBand(result.score, CLASS), gaps: gapReport(result) }
+}
+
+function loadOverlays() {
+  const abs = resolve(CWD, PROFILE)
+  if (!existsSync(abs)) return new Set()
+  try {
+    const doc = parseYaml(readFileSync(abs, 'utf-8')) || {}
+    return new Set(Array.isArray(doc.overlays) ? doc.overlays : [])
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Load the brownfield-class threshold SSOT (standards/thresholds.yml): threshold_ref → per-class bar.
+ * Absent/malformed ⇒ {} (value checks with an unresolvable threshold then score N, never silent-Y).
+ */
+function loadThresholds() {
+  const abs = resolve(CWD, THRESHOLDS)
+  if (!existsSync(abs)) return {}
+  try {
+    const doc = parseYaml(readFileSync(abs, 'utf-8')) || {}
+    return doc && typeof doc.thresholds === 'object' && doc.thresholds !== null
+      ? doc.thresholds
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+function readBaseline() {
+  const abs = resolve(CWD, BASELINE)
+  if (!existsSync(abs)) return null
+  try {
+    return JSON.parse(readFileSync(abs, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`gold-audit: ERROR — malformed ${BASELINE}: ${err.message}\n`)
+    process.exit(2)
+  }
+}
+
+function writeBaseline(payload) {
+  const abs = resolve(CWD, BASELINE)
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, JSON.stringify(payload, null, 2) + '\n', 'utf-8')
+}
+
+function main() {
+  const regAbs = resolve(CWD, REGISTRY)
+  if (!existsSync(regAbs)) {
+    process.stdout.write(`gold-audit: SKIP — no registry at ${REGISTRY}\n`)
+    return 0
+  }
+  let registry
+  try {
+    registry = parseYaml(readFileSync(regAbs, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`gold-audit: ERROR — malformed ${REGISTRY}: ${err.message}\n`)
+    return 2
+  }
+
+  const overlays = loadOverlays()
+  // #1413: value-op checks resolve threshold_ref per --class from the thresholds SSOT.
+  const result = evaluate(registry, overlays, CWD, {
+    thresholds: loadThresholds(),
+    brownfieldClass: CLASS,
+  })
+
+  // --strict false-gap meta-gate: never score on a fragile (RISKY) registry.
+  if (flag('--strict') && result.riskyCount > 0) {
+    const risky = result.checks.filter((c) => c.risk === 'RISKY').map((c) => c.id)
+    process.stderr.write(
+      `gold-audit: FAIL — false-gap meta-gate: ${result.riskyCount} RISKY check(s): ${risky.join(', ')}\n`,
+    )
+    return 1
+  }
+
+  // --check-fresh freshness gate (#1473): fail-closed exit 1 when the value-check reports are STALE
+  // (declared but NONE present — the tools never ran). Out-of-band: the wall-clock never touches the
+  // scored payload or the no-regress baseline. PARTIAL/FRESH are advisory (exit 0).
+  if (flag('--check-fresh')) {
+    // #1580: pass the active overlay set so freshness ignores reports for checks the engine NA's.
+    const f = freshness(registry, CWD, { staleHours: STALE_HOURS, overlays })
+    const c = f.counts
+    if (f.status === 'STALE') {
+      process.stderr.write(
+        `gold-audit: FAIL — freshness STALE: ${c.present}/${c.total} value-check report(s) present ` +
+          `(the tools never ran). Regenerate the reports or remove the value checks.\n`,
+      )
+      return 1
+    }
+    process.stdout.write(
+      `gold-audit: freshness ${f.status} (${c.fresh}/${c.total} report(s) within ${f.staleHours}h)\n`,
+    )
+    return 0
+  }
+
+  // --update-baseline: monotonic ratchet (can only tighten).
+  if (flag('--update-baseline')) {
+    const next = ratchet(result, readBaseline())
+    writeBaseline(next)
+    process.stdout.write(
+      `gold-audit: baseline ratcheted → ${BASELINE} (score=${next.score}, Y=${next.yCount})\n`,
+    )
+    return 0
+  }
+
+  // --check no-regress gate.
+  if (flag('--check')) {
+    const baseline = readBaseline()
+    if (baseline === null) {
+      // N1 (fail-closed disarm, #1412): with --require-baseline, a configured engine whose
+      // baseline is absent is a HARD FAIL — silently re-bootstrapping would erase the regression
+      // record (delete the baseline ⇒ any regression vanishes). The committed gate uses this flag.
+      if (flag('--require-baseline')) {
+        process.stderr.write(
+          `gold-audit: FAIL — N1 disarm guard: --require-baseline set but ${BASELINE} is missing.\n` +
+            `    A configured gold engine must carry a committed baseline; refusing to silently re-bootstrap.\n` +
+            `    Bootstrap once with: node scripts/gold-audit.mjs --check (without --require-baseline).\n`,
+        )
+        return 1
+      }
+      writeBaseline(baselineOf(result))
+      process.stdout.write(
+        `gold-audit: baseline initialized → ${BASELINE} (score=${result.score}, Y=${result.yCount})\n`,
+      )
+      return 0
+    }
+    if (process.env.ALLOW_GOLD_REGRESS === '1') {
+      process.stdout.write('gold-audit: ALLOW_GOLD_REGRESS=1 — skipping no-regress gate\n')
+      return 0
+    }
+    const verdict = checkNoRegress(result, baseline)
+    if (!verdict.ok) {
+      process.stderr.write(`gold-audit: FAIL — no-regress gate:\n`)
+      for (const r of verdict.reasons) process.stderr.write(`    ${r}\n`)
+      return 1
+    }
+    process.stdout.write(
+      `gold-audit: no-regress OK (score=${result.score} >= ${baseline.score}, Y=${result.yCount} >= ${baseline.yCount})\n`,
+    )
+    return 0
+  }
+
+  // Default / --json: emit the scored payload enriched with the #1414 level band + gap report.
+  const enriched = withPresentation(result)
+
+  // --cockpit-data (#1475): the data envelope the TS `--cockpit` renderer consumes — the SAME scored
+  // payload PLUS the out-of-band freshness object (wall-clock). Kept SEPARATE from `--json` so the
+  // scored artifact (no-regress baseline, bake snapshots) stays byte-deterministic + freshness-free.
+  if (flag('--cockpit-data')) {
+    const fresh = freshness(registry, CWD, { staleHours: STALE_HOURS, overlays })
+    process.stdout.write(JSON.stringify({ payload: enriched, freshness: fresh }) + '\n')
+    return 0
+  }
+
+  if (flag('--json')) {
+    const out = opt('--json', null)
+    const text = JSON.stringify(enriched, null, 2) + '\n'
+    if (out) {
+      mkdirSync(dirname(resolve(CWD, out)), { recursive: true })
+      writeFileSync(resolve(CWD, out), text, 'utf-8')
+      process.stdout.write(`gold-audit: wrote ${out}\n`)
+    } else {
+      process.stdout.write(text)
+    }
+    return 0
+  }
+
+  // Advisory freshness banner (out-of-band; never in the --json scored payload). Only shown when the
+  // registry declares value-check reports — otherwise there is nothing to be fresh/stale about.
+  const fresh = freshness(registry, CWD, { staleHours: STALE_HOURS, overlays })
+  if (fresh.counts.total > 0) {
+    process.stdout.write(
+      `gold-audit: freshness ${fresh.status} ` +
+        `(${fresh.counts.fresh}/${fresh.counts.total} report(s) within ${fresh.staleHours}h)\n`,
+    )
+  }
+
+  const band = enriched.level
+  const toNext = band.nextLevel === null ? '' : ` · ${band.toNextLevel} to ${band.nextLevel}`
+  process.stdout.write(
+    `gold-audit: ${band.level} (${band.brownfieldClass}) · score ${result.score}${toNext} · ` +
+      `Y ${result.yCount}/${result.totals.checks} · RISKY ${result.riskyCount} ` +
+      `(N ${result.totals.n}, P ${result.totals.p}, NA ${result.totals.na}, NV ${result.totals.nv})\n`,
+  )
+  if (enriched.gaps.length > 0) {
+    process.stdout.write(`gold-audit: what's missing (${enriched.gaps.length} family/families):\n`)
+    for (const g of enriched.gaps) {
+      process.stdout.write(`  ${g.dimension}:\n`)
+      for (const c of g.checks) {
+        const ev = c.evidence
+          ? ` [${c.evidence.file ?? ''}${c.evidence.detail ? `: ${c.evidence.detail}` : ''}]`
+          : ''
+        process.stdout.write(`    ${c.verdict} ${c.id} ${c.title}${ev}\n`)
+      }
+    }
+  }
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (err) {
+  // Fail-closed: an unexpected crash is a hard gate failure, never a silent pass.
+  process.stderr.write(`gold-audit: unexpected error — ${err?.message ?? err}\n`)
+  process.exit(1)
+}

package/scripts/lib/doc-gate-allowlist.mjs

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// #2408: the dated allowlist shared by the three doc gates (check-doc-links,
+// check-doc-style, check-phantom-command-scan). Removing `internal` from the
+// link/style SKIP lists and teaching the phantom scan to read fenced blocks
+// surfaces defects whose FIX is a prose/product decision owned by a sibling
+// M-A/M-B issue — those files get a dated entry here instead of a silent skip,
+// so the gate is green AND the debt is on a clock.
+//
+// Entry shape: { path, rule, reason, issue, expires }
+//   path    repo-relative POSIX path of the file being excused
+//   rule    which gate the excuse applies to (see RULES)
+//   reason  why it cannot be fixed as a path/frontmatter one-liner right now
+//   issue   the batch issue that owns the real fix
+//   expires ISO date; the gate goes RED the day after
+//
+// FAIL-CLOSED by construction: a missing file, a malformed file, a
+// malformed entry or an expired entry all exit non-zero. There is no
+// "could not read the allowlist, so allow everything" branch — that would
+// turn the escape hatch into a bypass.
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Resolved from THIS module's location, not process.cwd(): the gates are also
+// run against synthetic fixture trees (cwd=<tmpdir>), where a cwd-relative
+// lookup would silently find nothing and quietly fail open.
+const DEFAULT_PATH = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'data',
+  'doc-gate-allowlist.json',
+)
+
+export const RULES = new Set(['doc-links', 'doc-style', 'phantom-command'])
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const REQUIRED_KEYS = ['path', 'rule', 'reason', 'issue', 'expires']
+
+function fail(message) {
+  process.stdout.write(`  doc-gate-allowlist: ${message}\n`)
+  process.exit(1)
+}
+
+/**
+ * Shape-validate ONE entry. Every failure is fatal: a malformed excuse is a
+ * silent hole in three gates at once.
+ */
+function validateEntry(entry, index, path) {
+  const missing = REQUIRED_KEYS.filter((k) => typeof entry?.[k] !== 'string' || !entry[k])
+  if (missing.length > 0) fail(`${path} entry #${index} missing key(s): ${missing.join(', ')}`)
+  if (!RULES.has(entry.rule)) fail(`${path} entry #${index} has unknown rule "${entry.rule}"`)
+  if (!ISO_DATE.test(entry.expires))
+    fail(`${path} entry #${index} expires "${entry.expires}" is not an ISO date (YYYY-MM-DD)`)
+}
+
+/** Resolve the allowlist path: `--allowlist=<path>` on argv (fixture seam) or the default. */
+function resolveAllowlistPath() {
+  const override = process.argv.find((a) => a.startsWith('--allowlist='))
+  return override ? resolve(override.slice('--allowlist='.length)) : DEFAULT_PATH
+}
+
+/** Read + JSON-parse the allowlist, exiting non-zero on anything unreadable. */
+function readAllowlistEntries(path) {
+  if (!existsSync(path)) fail(`${path} not found — the allowlist is required (fail-closed)`)
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  } catch (err) {
+    // Surfaced and exited inline rather than through fail(): an unreadable or
+    // unparseable allowlist must visibly stop the gate at the catch site.
+    process.stdout.write(
+      `  doc-gate-allowlist: ${path} failed to parse: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    process.exit(1)
+  }
+  if (!Array.isArray(parsed?.entries)) fail(`${path} has no \`entries\` array`)
+  return parsed.entries
+}
+
+/**
+ * Load the allowlist and return the excused-path set for one `rule`.
+ *
+ * Expiry is validated across EVERY entry, not just the requested rule's: an
+ * entry that has run out of time is stale debt no matter which gate happens to
+ * load the file first.
+ *
+ * The path may be overridden with `--allowlist=<path>` on the calling gate's
+ * argv (fixture seam, same shape as check-phantom-command-scan's `--ledger=`).
+ *
+ * @param {string} rule one of RULES
+ * @param {string} [todayIso] ISO date to compare `expires` against (defaults to today)
+ * @returns {{ has: (relPath: string) => boolean, size: number, path: string }}
+ */
+export function loadDocGateAllowlist(rule, todayIso = new Date().toISOString().slice(0, 10)) {
+  if (!RULES.has(rule)) fail(`unknown rule "${rule}" (known: ${[...RULES].join(', ')})`)
+
+  const path = resolveAllowlistPath()
+  const entries = readAllowlistEntries(path)
+
+  const excused = new Set()
+  const expired = []
+  for (const [i, entry] of entries.entries()) {
+    validateEntry(entry, i, path)
+    if (entry.expires < todayIso) expired.push(`${entry.path} (${entry.rule}, ${entry.issue})`)
+    if (entry.rule === rule) excused.add(entry.path)
+  }
+
+  if (expired.length > 0) {
+    fail(
+      `${expired.length} entry/entries expired — fix the file or re-date the entry with its owner:\n` +
+        expired.map((e) => `    expired: ${e}`).join('\n'),
+    )
+  }
+
+  return { has: (relPath) => excused.has(relPath), size: excused.size, path }
+}
+
+/** Human-readable one-liner every gate prints, on every exit path. */
+export function allowlistSummary(gate, allow) {
+  const rel = relative(process.cwd(), allow.path)
+  return `  ${gate}: ${allow.size} file(s) allowlisted (${rel.startsWith('..') ? allow.path : rel})\n`
+}