@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-frontend-lane.mjs.ejs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// #1330 — per-lane frontend gate (generated by arbiter).
+//
+// Gates the `frontend/` SUBTREE lane in a polyglot repo whose PRIMARY language is
+// NOT the frontend (e.g. a Go/Python/Java/Rust backend with a `frontend/` SPA beside
+// it). The primary-language gate in check-all.mjs only covers the backend; without
+// this script the FE lane's typecheck/test/build would never run in any generated gate.
+//
+// Lanes-axis driven: emitted only when arbiter.json declares a `frontend` lane on a
+// non-frontend-spa archetype (a root-level frontend-spa app keeps its own root wiring).
+//
+// Usage: node scripts/check-frontend-lane.mjs [L1|full]
+//   L1   (default): typecheck + unit tests inside frontend/.
+//   full          : also runs the production build (vite/webpack/etc.).
+//
+// Every step is GATE-ON-PRESENT: a missing `frontend/` subtree, a missing
+// frontend/package.json, or un-installed frontend/node_modules SKIPs cleanly (exit 0)
+// rather than false-failing a partial setup. A present step that genuinely fails is a
+// HARD failure (exit 1) — no soft-fail for the FE lane.
+
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+const mode = process.argv[2] === 'full' ? 'full' : 'L1'
+let failed = 0
+
+function run(name, cmd, args, opts = {}) {
+  process.stdout.write(`[FE-LANE] ${name} ... `)
+  const r = spawnSync(cmd, args, { encoding: 'utf-8', shell: false, ...opts })
+  if (r.error?.code === 'ENOENT') {
+    console.log(`SKIP (binary not found: ${cmd})`)
+    return
+  }
+  if (r.status === 0) {
+    console.log('PASS')
+  } else {
+    console.log('FAIL')
+    process.stdout.write((r.stdout ?? '') + (r.stderr ?? ''))
+    failed++
+  }
+}
+
+// ── Gate-on-present: the subtree (and its manifest) must exist ────────────────
+if (!existsSync('frontend/package.json')) {
+  console.log('[FE-LANE] SKIP — no frontend/package.json (frontend lane has no subtree to gate)')
+  process.exit(0)
+}
+
+// ── Gate-on-present: subtree deps must be installed ──────────────────────────
+// Locally the developer may not have run `npm ci --prefix frontend`; the CI
+// workflow (18-frontend-lane.yml) installs them first. Skip rather than ENOENT-fail.
+if (!existsSync('frontend/node_modules')) {
+  console.log(
+    '[FE-LANE] SKIP — frontend/node_modules absent (run: npm ci --prefix frontend)',
+  )
+  process.exit(0)
+}
+
+// ── L1: typecheck + unit tests, executed inside the subtree (cwd: 'frontend') ──
+run('typecheck', 'npx', ['tsc', '--noEmit'], { cwd: 'frontend' })
+run('unit tests', 'npx', ['vitest', 'run'], { cwd: 'frontend' })
+
+// ── full: production build ───────────────────────────────────────────────────
+if (mode === 'full') {
+  run('build', 'npm', ['run', 'build'], { cwd: 'frontend' })
+}
+
+if (failed > 0) {
+  console.error(`\n[FE-LANE] FAILED: ${failed} check(s)`)
+  process.exit(1)
+}
+console.log('\n[FE-LANE] ALL PASSED')

package/dist/templates/scripts/check-grace-window.mjs.ejs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-grace-window.mjs — generated by arbiter (anti-fake-green, #1497).
+//
+// Grace-window guard. The ADR-028 grace period turns a freshly upgraded L1→L2 project's L2 gates
+// WARN-only for a bounded settling window. Two edits to arbiter.json could otherwise neuter the L2
+// gate indefinitely:
+//   (1) an over-long graceEndsAt (a hand-edited far-future date), and
+//   (2) a stale graceFromLevel=L1 carried into a project that has since climbed to L3/L4
+//       (grace from L1 must only ever soften L2, never a higher gate).
+// check-all.mjs already refuses to honor either at run time; THIS guard is the static regression
+// detector so a poisoned arbiter.json is caught even if the gate is bypassed. NO-DATA (no
+// arbiter.json / no active grace) is a PASS, never a manufactured fail.
+//
+// Exit codes (INV-53): 0=PASS, 1=FAIL (over-long / stale-level grace), 2=ERROR.
+// Usage: node scripts/check-grace-window.mjs [--dir <path>] [--max-days <n>] [--help]
+import { readFileSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    'Usage: node scripts/check-grace-window.mjs [--dir <path>] [--max-days <n>]\n' +
+      '  Fails when arbiter.json carries an over-long ADR-028 grace window (graceEndsAt more than\n' +
+      '  --max-days ahead of now) or a stale graceFromLevel=L1 on a project now above L2.\n' +
+      '  NO-DATA (no arbiter.json or no active grace) is a PASS.\n',
+  )
+  process.exit(0)
+}
+
+const dirIdx = args.indexOf('--dir')
+const ROOT = dirIdx >= 0 && args[dirIdx + 1] ? resolve(args[dirIdx + 1]) : process.cwd()
+const maxIdx = args.indexOf('--max-days')
+// Must match GRACE_MAX_DAYS in scripts/check-all.mjs (upgrade-level default 30 + 5 slack for one
+// --extend). Keep the two in lockstep.
+const MAX_DAYS = maxIdx >= 0 && args[maxIdx + 1] ? Number(args[maxIdx + 1]) : 35
+
+function main() {
+  const cfgPath = join(ROOT, 'arbiter.json')
+  if (!existsSync(cfgPath)) {
+    process.stdout.write('check-grace-window: NO-DATA (no arbiter.json) — PASS\n')
+    return 0
+  }
+
+  let cfg
+  try {
+    cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'))
+  } catch (e) {
+    process.stderr.write(
+      `check-grace-window: ERROR — arbiter.json is unreadable (${e?.message ?? e})\n`,
+    )
+    return 2
+  }
+
+  if (cfg.graceFromLevel !== 'L1' || !cfg.graceEndsAt) {
+    process.stdout.write('check-grace-window: NO-DATA (no active L1→L2 grace) — PASS\n')
+    return 0
+  }
+
+  const ends = Date.parse(cfg.graceEndsAt)
+  const now = Date.now()
+  if (!Number.isFinite(ends) || ends <= now) {
+    // Expired or malformed grace is inert (check-all ignores it) — nothing to flag.
+    process.stdout.write('check-grace-window: grace expired or inert — PASS\n')
+    return 0
+  }
+
+  const findings = []
+  // (2) Stale-level grace: graceFromLevel=L1 but project has climbed above L2.
+  if (cfg.governanceLevel && cfg.governanceLevel !== 'L2') {
+    findings.push(
+      `stale grace: graceFromLevel=L1 but governanceLevel=${cfg.governanceLevel} — an L1→L2 grace must ` +
+        `not soften an ${cfg.governanceLevel} gate. Clear graceFromLevel/graceEndsAt from arbiter.json.`,
+    )
+  }
+  // (1) Over-long window: graceEndsAt beyond the bound = hand-extended fake-green vector.
+  const daysAhead = Math.ceil((ends - now) / 86400000)
+  if (daysAhead > MAX_DAYS) {
+    findings.push(
+      `over-long grace: graceEndsAt is ${daysAhead} days ahead (bound ${MAX_DAYS}). A hand-edited ` +
+        `far-future date neuters the L2 gate. Re-run \`arbiter upgrade-level --extend\` instead.`,
+    )
+  }
+
+  if (findings.length > 0) {
+    process.stderr.write('check-grace-window: FAIL — grace window is a fake-green vector:\n')
+    for (const f of findings) process.stderr.write(`    ${f}\n`)
+    return 1
+  }
+
+  process.stdout.write(
+    `check-grace-window: grace ends in ${daysAhead} day(s), within the ${MAX_DAYS}-day bound — PASS\n`,
+  )
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (e) {
+  process.stderr.write(`check-grace-window: ERROR — ${e?.message ?? e}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-handoff-doc.mjs.ejs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: E6a (#1943, M1) — handoff-lint. Flags a handoff doc whose tasks carry no tier
+// CATALOG: suggestion (silently re-routes work to the expensive model — R7) or no executable
+// CATALOG: `Verify:` command (a cold model cannot execute the plan — R1). Lints the contract
+// CATALOG: the HANDOFF template already promises (src/templates/HANDOFF.template.md): each
+// CATALOG: numbered task section (`### N.`) must carry What / Where / AC / Verify / Suggested tier,
+// CATALOG: `Verify:` must contain a backtick command, and `Suggested tier:` must be non-empty and
+// CATALOG: not the template placeholder.
+// CATALOG: Rejected fold-in into check-doc-style.mjs: that lints prose style/SPDX/frontmatter,
+// CATALOG: not the handoff task-section contract (different shape, different failure surface).
+// CATALOG: Rejected fold-in into check-canonical-paths.mjs: path-target existence, not task shape.
+//
+// Exit codes (INV-53): 0 PASS, 1 FAIL (one+ handoff violates), 2 ERROR (self).
+// Vacuous pass when no handoff docs exist. Advisory at land-time (runWarnCheck); promote to
+// runCheck to hard-block.
+//
+// Usage:
+//   node scripts/check-handoff-doc.mjs [--file <path>] [--root <dir>]
+//     --file   lint a single file
+//     --root   scan **/HANDOFF*.md plus docs/**/Handoff:*.md and .claude/plans/** (default cwd)
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { arg } from './lib/gate-args.mjs'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const repoDefault = resolve(__dirname, '..')
+
+const argv = process.argv.slice(2)
+const FILE_ARG = arg('file', argv)
+const ROOT = arg('root', argv) ? resolve(arg('root', argv)) : process.cwd()
+const TEMPLATE_PATH = join(repoDefault, 'src', 'templates', 'HANDOFF.template.md')
+
+const PLACEHOLDER = /(…|_fill in_|<[^>]*>)/
+
+/** Is this file the template, or a copy of it (exempt — templates ARE placeholders by design)? */
+function isTemplate(absPath) {
+  try {
+    if (resolve(absPath) === resolve(TEMPLATE_PATH)) return true
+    // FAIL-OPEN-INTENT: resolve() threw on a bad path — fall through to the basename check.
+  } catch {
+    // resolve() threw — fall through to the basename check.
+  }
+  // Also exempt copies of the template by basename — the greenfield-dist
+  // generation copies the template to .arbiter/greenfield-dist-*/templates/,
+  // and exact-path matching missed those copies (arbiter#2066). A template
+  // copy is placeholders by design, so it must not be linted as a real handoff.
+  const base = absPath.split(sep).pop() ?? ''
+  return /^HANDOFF\.template\.md$/i.test(base)
+}
+
+/** Walk a directory recursively collecting markdown files. */
+function walkMarkdown(dir, out) {
+  let entries
+  try {
+    entries = readdirSync(dir)
+    // FAIL-OPEN-INTENT: readdirSync failure on a non-existent dir — nothing to walk; empty out is correct.
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === '.git' || entry === 'dist') continue
+    const full = join(dir, entry)
+    let st
+    try {
+      st = statSync(full)
+      // FAIL-OPEN-INTENT: statSync ENOENT race — skip the entry; rethrow would false-positive on a racing delete.
+    } catch {
+      continue
+    }
+    if (st.isDirectory()) walkMarkdown(full, out)
+    else if (entry.endsWith('.md')) out.push(full)
+  }
+}
+
+/** Collect handoff docs: files named HANDOFF*.md anywhere, plus markdown whose H1 starts with "Handoff:". */
+function collectHandoffs(root) {
+  /** @type {string[]} */
+  const out = []
+  const all = []
+  walkMarkdown(root, all)
+  for (const f of all) {
+    const base = f.split(sep).pop() ?? ''
+    if (/^HANDOFF.*\.md$/i.test(base)) {
+      out.push(f)
+      continue
+    }
+    // H1 starts with "Handoff:" and the file is under docs/ or .claude/plans/
+    const rel = relative(root, f)
+    if (/^(docs|\.claude\/plans)\b/.test(rel.replace(/\\/g, '/'))) {
+      try {
+        const head = readFileSync(f, 'utf-8').split('\n').slice(0, 5).join('\n')
+        if (/^#\s*Handoff:/im.test(head)) out.push(f)
+        // FAIL-OPEN-INTENT: readFileSync failure on a candidate file — skip it (unreadable files are not linted, matching check-doc-style posture).
+      } catch {
+        /* unreadable → skip */
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Lint one handoff doc. Returns array of violation messages (empty = pass).
+ * @param {string} absPath
+ * @returns {string[]}
+ */
+function lintHandoff(absPath) {
+  let src
+  try {
+    src = readFileSync(absPath, 'utf-8')
+    // FAIL-OPEN-INTENT: readFileSync failure is returned as a violation string (err.message surfaced to the caller — fail-closed).
+  } catch (err) {
+    return [`cannot read ${absPath}: ${err instanceof Error ? err.message : String(err)}`]
+  }
+  /** @type {string[]} */
+  const violations = []
+  // Split into numbered task sections: `### N.` headings.
+  const heads = [...src.matchAll(/^### \d+\b.*$/gm)]
+  if (heads.length === 0) {
+    // No numbered task sections → nothing to lint (handoff may be a different shape). Not a fail.
+    return []
+  }
+  const REQUIRED_ROWS = ['What', 'Where', 'AC', 'Verify', 'Suggested tier']
+  for (let i = 0; i < heads.length; i++) {
+    const start = heads[i].index
+    const end = i + 1 < heads.length ? heads[i + 1].index : src.length
+    const section = src.slice(start, end)
+    const title = heads[i][0].trim()
+    for (const row of REQUIRED_ROWS) {
+      const re = new RegExp(`\\*\\*${row}:\\*\\*`, 'i')
+      if (!re.test(section)) {
+        violations.push(`${absPath}: ${title} — missing "**${row}:**" row`)
+      }
+    }
+    // Verify must contain a backtick command.
+    const verifyMatch = section.match(/\*\*Verify:\*\*\s*([^\n]*)/i)
+    if (verifyMatch && !/`[^`]+`/.test(verifyMatch[1])) {
+      violations.push(`${absPath}: ${title} — "Verify:" must contain a backtick command`)
+    }
+    // Suggested tier must be non-empty and not a placeholder.
+    const tierMatch = section.match(/\*\*Suggested tier:\*\*\s*([^\n]*)/i)
+    if (tierMatch) {
+      const val = tierMatch[1].trim()
+      if (val === '' || PLACEHOLDER.test(val)) {
+        violations.push(`${absPath}: ${title} — "Suggested tier:" is empty or a placeholder`)
+      }
+    }
+  }
+  return violations
+}
+
+function main() {
+  /** @type {string[]} */
+  let files
+  if (FILE_ARG) {
+    files = [resolve(FILE_ARG)]
+  } else {
+    files = collectHandoffs(ROOT).filter((f) => !isTemplate(f))
+  }
+  let totalViolations = 0
+  let checked = 0
+  for (const f of files) {
+    if (!existsSync(f)) {
+      process.stderr.write(`[check-handoff-doc] ERROR: file not found: ${f}\n`)
+      return 2
+    }
+    if (isTemplate(f)) continue
+    checked++
+    const v = lintHandoff(f)
+    for (const msg of v) process.stdout.write(`[check-handoff-doc] FAIL: ${msg}\n`)
+    totalViolations += v.length
+  }
+  if (totalViolations > 0) {
+    process.stdout.write(
+      `[check-handoff-doc] FAIL: ${totalViolations} violation(s) across ${checked} handoff doc(s)\n`,
+    )
+    return 1
+  }
+  process.stdout.write(`[check-handoff-doc] OK — ${checked} handoff doc(s) passed\n`)
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (err) {
+  process.stderr.write(
+    `[check-handoff-doc] ERROR: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(2)
+}

package/dist/templates/scripts/check-hook-routing.mjs.ejs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// CATALOG: validates the complete emitted-hook → dispatcher → settings route.
+// CATALOG: stays separate from emission coherence because this script runs in governed targets.
+// CATALOG: catches brownfield and user-preservation drift after update at target runtime.
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = process.cwd()
+const hooksDir = join(root, '.claude', 'hooks')
+const dispatcherPath = join(hooksDir, 'hooks.mjs')
+const settingsPath = join(root, '.claude', 'settings.json')
+
+try {
+  const owned = readOwnedHooks(root, hooksDir)
+  const findings = isCodexOnly(root)
+    ? inspectCodexRoutes(
+        owned,
+        readRequired(join(root, '.codex', 'config.toml')),
+        join(root, '.codex', 'codex-adapter.mjs'),
+      )
+    : inspectRoutes(
+        owned,
+        parseHandlers(readRequired(dispatcherPath)),
+        parseWiring(readRequired(settingsPath)),
+        hooksDir,
+      )
+  if (findings.length > 0) {
+    for (const finding of findings) process.stderr.write(`[hook-routing] ${finding}\n`)
+    process.exit(1)
+  }
+  process.stdout.write(
+    `[hook-routing] PASS — ${owned.size} Arbiter-owned hooks are dispatched through wired events\n`,
+  )
+  process.exit(0)
+} catch (error) {
+  process.stderr.write(
+    `[hook-routing] ERROR — ${error instanceof Error ? error.message : String(error)}\n`,
+  )
+  process.exit(2)
+}
+
+function readRequired(path) {
+  if (!existsSync(path)) throw new Error(`required file missing: ${path}`)
+  return readFileSync(path, 'utf-8')
+}
+
+function readOwnedHooks(repoRoot, dir) {
+  if (!existsSync(dir)) throw new Error(`required hooks directory missing: ${dir}`)
+  const marked = markedOwnedHooks(dir)
+  const generatedPath = join(repoRoot, '.arbiter-generated-manifest.json')
+  if (existsSync(generatedPath)) return readGeneratedOwnedHooks(generatedPath, marked)
+
+  const hardnessPath = join(repoRoot, '.arbiter', 'hooks-manifest.json')
+  if (existsSync(hardnessPath)) return readHardnessOwnedHooks(hardnessPath)
+
+  return normalizeOwnedPaths(marked)
+}
+
+function readGeneratedOwnedHooks(path, marked) {
+  const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  validateGeneratedManifest(parsed)
+  return normalizeOwnedPaths([
+    ...Object.keys(parsed.files),
+    ...(parsed.withheldSafety ?? []),
+    ...marked,
+  ])
+}
+
+function validateGeneratedManifest(parsed) {
+  if (parsed?.$schemaVersion !== 1 || typeof parsed.files !== 'object' || parsed.files === null) {
+    throw new Error('.arbiter-generated-manifest.json has an invalid shape')
+  }
+  if (
+    parsed.withheldSafety !== undefined &&
+    (!Array.isArray(parsed.withheldSafety) ||
+      !parsed.withheldSafety.every((path) => typeof path === 'string'))
+  ) {
+    throw new Error('.arbiter-generated-manifest.json has invalid withheldSafety ownership')
+  }
+}
+
+function readHardnessOwnedHooks(path) {
+  const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  if (parsed?.version !== 1 || !Array.isArray(parsed.hooks)) {
+    throw new Error('.arbiter/hooks-manifest.json has an invalid shape')
+  }
+  return new Set(
+    parsed.hooks
+      .map((entry) => entry?.file)
+      .filter((file) => typeof file === 'string' && file.endsWith('.mjs'))
+      .filter((file) => file !== 'hooks.mjs' && file !== 'lib.mjs'),
+  )
+}
+
+function normalizeOwnedPaths(paths) {
+  return new Set(
+    paths
+      .filter((path) => /^\.claude\/hooks\/[^/]+\.mjs$/.test(path))
+      .map((path) => path.slice('.claude/hooks/'.length))
+      .filter((file) => file !== 'hooks.mjs' && file !== 'lib.mjs'),
+  )
+}
+
+function markedOwnedHooks(dir) {
+  return readdirSync(dir)
+    .filter((file) => file.endsWith('.mjs') && file !== 'hooks.mjs' && file !== 'lib.mjs')
+    .filter((file) => readFileSync(join(dir, file), 'utf-8').includes('Arbiter hook:'))
+    .map((file) => `.claude/hooks/${file}`)
+}
+
+function isCodexOnly(repoRoot) {
+  const path = join(repoRoot, 'arbiter.json')
+  if (!existsSync(path)) return false
+  const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  if (!Array.isArray(parsed?.tools)) throw new Error('arbiter.json tools must be an array')
+  return parsed.tools.includes('codex') && !parsed.tools.includes('claude')
+}
+
+function parseHandlers(source) {
+  const block = /const HANDLERS\s*=\s*\{([\s\S]*?)\n\}\s*;?/.exec(source)
+  if (!block) throw new Error('hooks.mjs has no parseable HANDLERS table')
+  const handlers = new Map()
+  const eventPattern = /(?:'([^']+)'|([A-Za-z_$][\w$]*))\s*:\s*\[([\s\S]*?)\],/g
+  for (const match of block[1].matchAll(eventPattern)) {
+    const files = [...match[3].matchAll(/'([^']+\.mjs)'/g)].map((item) => item[1])
+    handlers.set(match[1] ?? match[2], files)
+  }
+  if (handlers.size === 0) throw new Error('hooks.mjs HANDLERS table is empty or malformed')
+  return handlers
+}
+
+function parseWiring(source) {
+  const settings = JSON.parse(source)
+  if (typeof settings?.hooks !== 'object' || settings.hooks === null) {
+    throw new Error('settings.json has no hooks object')
+  }
+  const dispatcherEvents = new Set()
+  const directByEvent = new Map()
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) throw new Error(`settings hook event ${event} is not an array`)
+    for (const entry of entries)
+      registerSettingsEntry(event, entry, dispatcherEvents, directByEvent)
+  }
+  return { dispatcherEvents, directByEvent }
+}
+
+function registerSettingsEntry(event, entry, dispatcherEvents, directByEvent) {
+  if (typeof entry !== 'object' || entry === null || !Array.isArray(entry.hooks)) return
+  const expected =
+    typeof entry.matcher === 'string' && entry.matcher !== '*' ? `${event}:${entry.matcher}` : event
+  for (const hook of entry.hooks) {
+    registerWiringCommand(hook?.command, expected, dispatcherEvents, directByEvent)
+  }
+}
+
+function registerWiringCommand(value, expected, dispatcherEvents, directByEvent) {
+  const command = typeof value === 'string' ? value : ''
+  const dispatcher = /(?:^|[/ ])hooks\.mjs["']?\s+["']?([^"' ]+)["']?/.exec(command)
+  if (dispatcher?.[1] === expected) dispatcherEvents.add(expected)
+
+  const direct = /\.claude\/hooks\/([^/"' ]+\.mjs)(?:["' ]|$)/.exec(command)
+  if (!direct || direct[1] === 'hooks.mjs') return
+  const files = directByEvent.get(expected) ?? new Set()
+  files.add(direct[1])
+  directByEvent.set(expected, files)
+}
+
+function inspectRoutes(owned, handlers, wiring, dir) {
+  const findings = []
+  const routed = new Set()
+  for (const [event, files] of handlers) {
+    inspectHandlerRoute(event, files, owned, wiring, dir, findings, routed)
+  }
+  inspectDirectRoutes(wiring.directByEvent, dir, findings, routed)
+  inspectOwnedRoutes(owned, dir, findings, routed)
+  return [...new Set(findings)].sort()
+}
+
+function inspectHandlerRoute(event, files, owned, wiring, dir, findings, routed) {
+  const direct = wiring.directByEvent.get(event) ?? new Set()
+  const dispatcherWired = wiring.dispatcherEvents.has(event)
+  const ownedFiles = files.filter((file) => owned.has(file))
+  if (ownedFiles.length > 0 && !dispatcherWired && !ownedFiles.every((file) => direct.has(file))) {
+    findings.push(`UNROUTED event ${event}`)
+  }
+  for (const file of files)
+    inspectHandlerFile(event, file, owned, direct, dispatcherWired, dir, findings, routed)
+}
+
+function inspectHandlerFile(event, file, owned, direct, dispatcherWired, dir, findings, routed) {
+  const wired = dispatcherWired || direct.has(file)
+  if (wired) routed.add(file)
+  if ((wired || owned.has(file)) && !existsSync(join(dir, file))) {
+    findings.push(`MISSING handler ${file} for ${event}`)
+  }
+}
+
+function inspectDirectRoutes(directByEvent, dir, findings, routed) {
+  for (const [event, files] of directByEvent) {
+    for (const file of files) {
+      routed.add(file)
+      if (!existsSync(join(dir, file))) findings.push(`MISSING direct hook ${file} for ${event}`)
+    }
+  }
+}
+
+function inspectOwnedRoutes(owned, dir, findings, routed) {
+  for (const file of owned) {
+    if (!existsSync(join(dir, file))) findings.push(`MISSING Arbiter-owned hook ${file}`)
+    else if (!routed.has(file)) findings.push(`DEAD Arbiter-owned hook ${file}`)
+  }
+}
+
+function inspectCodexRoutes(owned, config, adapterPath) {
+  const findings = []
+  if (!existsSync(adapterPath)) findings.push('MISSING Codex adapter .codex/codex-adapter.mjs')
+  for (const file of owned) {
+    const path = `.claude/hooks/${file}`
+    if (!config.includes(`.codex/codex-adapter.mjs ${path}`)) {
+      findings.push(`DEAD Codex adapter hook ${file}`)
+    }
+  }
+  return [...new Set(findings)].sort()
+}

package/dist/templates/scripts/check-image-pins.mjs.ejs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// arbiter — container image digest-pin gate (#1442)
+// Fails closed when a third-party Dockerfile `FROM` base image is not @sha256-pinned,
+// so a mutable tag cannot be rewritten under the build (supply-chain hardening).
+// Exempt: `FROM scratch`, build-stage alias references (`FROM <prior-AS-alias>`), and any
+// FROM line carrying `# arbiter-allow-unpinned[: reason]`. Self-SKIPs (exit 0) when the
+// repo ships no Dockerfiles.
+// Exit codes (INV-53): 0 = all pinned / none found · 1 = unpinned image(s) · 2 = error.
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+function parseDir(argv) {
+  const i = argv.indexOf('--dir')
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : process.cwd()
+}
+const ROOT = parseDir(process.argv.slice(2))
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', 'target', '.next'])
+const isDockerfile = (name) =>
+  name === 'Dockerfile' || name.endsWith('.Dockerfile') || name.startsWith('Dockerfile.')
+
+function walk(dir, out = []) {
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e)) continue
+    const full = join(dir, e)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+    if (st.isDirectory()) walk(full, out)
+    else if (isDockerfile(e)) out.push(full)
+  }
+  return out
+}
+
+const SHA_RE = /@sha256:[0-9a-f]{64}/
+const ALLOW_RE = /#\s*arbiter-allow-unpinned/
+const FROM_RE = /^FROM\s+(\S+)(?:\s+AS\s+(\S+))?/i
+
+let files
+try {
+  files = walk(ROOT)
+} catch (err) {
+  process.stderr.write(`check-image-pins: error walking ${ROOT}: ${err.message}\n`)
+  process.exit(2)
+}
+
+let violations = 0
+for (const file of files) {
+  let content
+  try {
+    content = readFileSync(file, 'utf-8')
+  } catch {
+    continue
+  }
+  const aliases = new Set()
+  for (const raw of content.split('\n')) {
+    const m = FROM_RE.exec(raw.trim())
+    if (!m) continue
+    const ref = m[1]
+    if (m[2]) aliases.add(m[2].toLowerCase())
+    if (ref.toLowerCase() === 'scratch') continue // unpinnable
+    if (aliases.has(ref.toLowerCase())) continue // build-stage alias reference
+    if (ALLOW_RE.test(raw)) continue // explicit inline allowlist
+    if (SHA_RE.test(ref)) continue // digest-pinned
+    process.stderr.write(`[FAIL] unpinned base image: FROM ${ref} in ${file}\n`)
+    violations++
+  }
+}
+
+if (violations > 0) {
+  process.stderr.write(
+    `check-image-pins: FAIL — ${violations} unpinned third-party base image(s). ` +
+      'Pin to a @sha256: digest, or add `# arbiter-allow-unpinned: <reason>` to the FROM line.\n',
+  )
+  process.exit(1)
+}
+process.stdout.write(
+  `check-image-pins: OK — ${files.length} Dockerfile(s) scanned, all base images digest-pinned\n`,
+)
+process.exit(0)