@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-bundle-size.mjs.ejs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: Bundle size budget gate (#1127 Slice 6).
+// Reads bundle-budget.json and checks dist/ output against budgets.
+// Exit 1 if any file exceeds its maxSize budget (HARD gate).
+
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs'
+import { join, basename } from 'node:path'
+
+const ROOT = process.cwd()
+const BUDGET_FILE = join(ROOT, 'bundle-budget.json')
+const DIST_DIR = join(ROOT, 'dist')
+
+if (!existsSync(BUDGET_FILE)) {
+  process.stdout.write('[check-bundle-size] no bundle-budget.json found — skip\n')
+  process.exit(0)
+}
+
+if (!existsSync(DIST_DIR)) {
+  process.stdout.write('[check-bundle-size] dist/ not found — run npm run build first\n')
+  process.exit(0)
+}
+
+let budget
+try {
+  budget = JSON.parse(readFileSync(BUDGET_FILE, 'utf-8'))
+} catch (err) {
+  process.stderr.write(`[check-bundle-size] failed to parse bundle-budget.json: ${err.message}\n`)
+  process.exit(1)
+}
+
+function parseSize(sizeStr, context) {
+  if (sizeStr == null) return Infinity // caller decides if null is fatal
+  const match = sizeStr.match(/^(\d+(?:\.\d+)?)\s*(kb|mb|b)$/i)
+  if (!match) {
+    // Malformed size string → hard fail. Silently returning Infinity would unenforce the budget.
+    process.stderr.write(
+      `[check-bundle-size] FATAL: unrecognized size format "${sizeStr}" in ${context}\n` +
+        `  Accepted formats: "200kb", "1.5mb", "4096b" (case-insensitive, no space required)\n`,
+    )
+    process.exit(1)
+  }
+  const num = parseFloat(match[1])
+  const unit = match[2].toLowerCase()
+  if (unit === 'mb') return Math.round(num * 1024 * 1024)
+  if (unit === 'kb') return Math.round(num * 1024)
+  return Math.round(num)
+}
+
+function matchGlob(pattern, filePath) {
+  // Simplified glob: replace * with .* for matching
+  const regex = new RegExp(
+    '^' +
+      pattern
+        .replace(/\\/g, '/')
+        .replace(/[.+^${}()|[\]]/g, '\\$&')
+        .replace(/\*\*/g, '__DOUBLESTAR__')
+        .replace(/\*/g, '[^/]*')
+        .replace(/__DOUBLESTAR__/g, '.*') +
+      '$',
+  )
+  return regex.test(filePath.replace(/\\/g, '/'))
+}
+
+function walkDir(dir) {
+  const files = []
+  if (!existsSync(dir)) return files
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return files
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+    if (st.isDirectory()) {
+      files.push(...walkDir(full))
+    } else {
+      files.push({ path: full, size: st.size })
+    }
+  }
+  return files
+}
+
+const distFiles = walkDir(DIST_DIR)
+let violations = 0
+
+for (const b of budget.budgets ?? []) {
+  if (b.maxSize == null) {
+    process.stderr.write(`[check-bundle-size] FATAL: budget entry "${b.name}" missing maxSize\n`)
+    process.exit(1)
+  }
+  const maxBytes = parseSize(b.maxSize, `bundle-budget.json budgets[].maxSize ("${b.name}")`)
+  const pattern = b.path.replace(/^dist\//, '')
+  const matching = distFiles.filter((f) => {
+    const rel = f.path.replace(ROOT + '/', '').replace(/\\/g, '/')
+    return matchGlob(b.path, rel)
+  })
+  for (const f of matching) {
+    if (f.size > maxBytes) {
+      const actualKb = (f.size / 1024).toFixed(1)
+      process.stderr.write(
+        `[check-bundle-size] OVER BUDGET: ${basename(f.path)}: ${actualKb}kb > ${b.maxSize} (budget: ${b.name})\n`,
+      )
+      violations++
+    }
+  }
+}
+
+// Check totals
+if (budget.totals) {
+  const totalJs = distFiles
+    .filter((f) => f.path.endsWith('.js'))
+    .reduce((sum, f) => sum + f.size, 0)
+  const totalCss = distFiles
+    .filter((f) => f.path.endsWith('.css'))
+    .reduce((sum, f) => sum + f.size, 0)
+
+  const maxTotalJs = parseSize(budget.totals.maxTotalJsSize, 'bundle-budget.json totals.maxTotalJsSize')
+  const maxTotalCss = parseSize(budget.totals.maxTotalCssSize, 'bundle-budget.json totals.maxTotalCssSize')
+
+  if (totalJs > maxTotalJs) {
+    process.stderr.write(
+      `[check-bundle-size] OVER TOTAL JS BUDGET: ${(totalJs / 1024).toFixed(1)}kb > ${budget.totals.maxTotalJsSize}\n`,
+    )
+    violations++
+  }
+  if (totalCss > maxTotalCss) {
+    process.stderr.write(
+      `[check-bundle-size] OVER TOTAL CSS BUDGET: ${(totalCss / 1024).toFixed(1)}kb > ${budget.totals.maxTotalCssSize}\n`,
+    )
+    violations++
+  }
+}
+
+if (violations > 0) {
+  process.stderr.write(
+    `\n[check-bundle-size] ${violations} bundle budget violation(s).\n` +
+      `  Reduce bundle size or update bundle-budget.json with justification.\n` +
+      `  See docs/GOVERNANCE/FE_DESIGN_PRINCIPLES.md for budget rationale.\n`,
+  )
+  process.exit(1)
+}
+
+process.stdout.write('[check-bundle-size] all bundle budgets OK\n')

package/dist/templates/scripts/check-canonical-paths.mjs.ejs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// <%= projectName %> — canonical-paths gate (INV-50)
+// Gate: verify every redirect target in CANONICAL_PATHS.md exists on disk.
+// Exits 0: all redirect targets exist, or no CANONICAL_PATHS.md found.
+// Exits 1: one or more redirect targets are missing (dangling aliases).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CWD = process.cwd();
+const CANONICAL_PATHS_FILE = join(CWD, 'docs', 'METHOD', 'CANONICAL_PATHS.md');
+
+if (!existsSync(CANONICAL_PATHS_FILE)) {
+  console.log('  check-canonical-paths: no CANONICAL_PATHS.md found — skipping');
+  process.exit(0);
+}
+
+const content = readFileSync(CANONICAL_PATHS_FILE, 'utf-8');
+
+const ROW_PATTERN = /^\|[^|]*\|\s*`([^`]+)`\s*\|/gm;
+
+const dangling = [];
+for (const match of content.matchAll(ROW_PATTERN)) {
+  const target = match[1].trim();
+  const abs = join(CWD, target);
+  if (!existsSync(abs)) {
+    dangling.push(target);
+  }
+}
+
+if (dangling.length === 0) {
+  console.log('  check-canonical-paths: all redirect targets exist');
+  process.exit(0);
+}
+
+console.log(`  check-canonical-paths: ${dangling.length} dangling alias(es) in CANONICAL_PATHS.md:`);
+for (const target of dangling) {
+  console.log(`    dangling: ${target}`);
+}
+process.exit(1);

package/dist/templates/scripts/check-ci-tiers.mjs.ejs

@@ -0,0 +1,111 @@
+<%
+// #1319.2 — INV-73: the required CI-tier set is the EXACT inverse of the
+// generation predicates in src/generators/github.ts. The config is known at
+// generation time, so we resolve the set HERE (render-time EJS) instead of
+// guessing at runtime via existsSync heuristics.
+//
+//   required = [01, 02, 03]                                  (always)
+//   + 05-release                if style !== 'starter'
+//   + 06-nightly,07-weekly,08-monthly
+//                               if style !== 'starter' && L3+ && cm !== 'trunk-solo'
+//   + 06-nightly-lite           if cm === 'trunk-solo' && L2+
+//   + 09-heartbeat              if L3+
+//
+// style === 'starter' iff resolvePipelineStyle(cm, level) === 'starter'
+// (or ciTierMode === 'baseline'); cm is resolved with the enableSoloDevMode alias.
+const _level = governanceLevel;
+const _isL2Plus = _level === 'L2' || _level === 'L3' || _level === 'L4';
+const _isL3Plus = _level === 'L3' || _level === 'L4';
+const _cm =
+  typeof collaborationMode !== 'undefined' && collaborationMode
+    ? collaborationMode
+    : (typeof enableSoloDevMode !== 'undefined' && enableSoloDevMode) ? 'trunk-solo' : 'peer-review';
+// PIPELINE_STYLE_TABLE (src/config/collaboration-mode-defaults.ts) — only the
+// 'starter' verdict matters here.
+const _styleTable = {
+  'trunk-solo': { L1: 'starter', L2: 'starter', L3: 'standard', L4: 'standard' },
+  'peer-review': { L1: 'starter', L2: 'standard', L3: 'standard', L4: 'standard' },
+  'gated-review': { L1: 'standard', L2: 'standard', L3: 'industrial', L4: 'industrial' },
+};
+let _style;
+if (typeof pipelineStyle !== 'undefined' && pipelineStyle) {
+  _style = pipelineStyle;
+} else if (typeof ciTierMode !== 'undefined' && ciTierMode === 'baseline') {
+  _style = 'starter';
+} else {
+  _style = (_styleTable[_cm] && _styleTable[_cm][_level]) || 'standard';
+}
+const _required = ['01-pr-fast.yml', '02-pr-extended.yml', '03-human-approval.yml'];
+if (_style !== 'starter') _required.push('05-release.yml');
+if (_style !== 'starter' && _isL3Plus && _cm !== 'trunk-solo') {
+  _required.push('06-nightly.yml', '07-weekly.yml', '08-monthly.yml');
+}
+if (_cm === 'trunk-solo' && _isL2Plus) _required.push('06-nightly-lite.yml');
+// PORT A2 (#1502): trunk-solo L3+ gets the lite weekly sweep (07-weekly-lite).
+if (_cm === 'trunk-solo' && _isL3Plus) _required.push('07-weekly-lite.yml');
+if (_isL3Plus) _required.push('09-heartbeat.yml');
+-%>
+#!/usr/bin/env node
+// <%= projectName %> — CI tier presence gate (INV-73)
+// Gate: verify the required CI workflow files exist in .github/workflows/.
+// The required set is fixed at generation time as the inverse of the workflow
+// generation predicates (collaboration mode <%= _cm %> × governance <%= _level %>).
+// Exits 0: all required present.
+// Exits 1: one or more missing.
+// Part of the anti-drift validator family (W6).
+// Usage: node scripts/check-ci-tiers.mjs [--help]
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write('Usage: node scripts/check-ci-tiers.mjs [--help]\nVerify all required CI tier workflow files exist.\n');
+  process.exit(0);
+}
+
+const CWD = process.cwd();
+const WORKFLOWS_DIR = join(CWD, '.github', 'workflows');
+
+// Required CI-tier files for this project (collaboration mode + governance level
+// resolved at generation time — INV-73).
+const REQUIRED_TIERS = [
+<% _required.forEach((f) => { -%>
+  '<%= f %>',
+<% }); -%>
+];
+
+const missing = REQUIRED_TIERS.filter((f) => !existsSync(join(WORKFLOWS_DIR, f)));
+
+<% if (_isL3Plus) { -%>
+// ─── INV-73 content strictness (#1720) ───────────────────────────────────────
+// Existence alone missed a real regression: a hand-rolled template guard bug
+// (05-release.yml.ejs's `_slsaL3` boolean) silently rendered a WEAKER release
+// workflow at L4 than at L3 while the file still existed — this gate stayed
+// green throughout. At L3+, when 05-release.yml is required and present, also
+// assert its CONTENT declares L3 hermetic SLSA provenance, not merely that the
+// file is there.
+let contentViolation = null;
+if (REQUIRED_TIERS.includes('05-release.yml') && !missing.includes('05-release.yml')) {
+  const releaseContent = readFileSync(join(WORKFLOWS_DIR, '05-release.yml'), 'utf-8');
+  if (!releaseContent.includes('L3 hermetic')) {
+    contentViolation = '05-release.yml is present but missing L3 hermetic SLSA provenance (INV-73 content check)';
+  }
+}
+<% } -%>
+
+if (missing.length === 0<% if (_isL3Plus) { %> && !contentViolation<% } %>) {
+  console.log(`  check-ci-tiers: all ${REQUIRED_TIERS.length} required CI tier workflow(s) present<% if (_isL3Plus) { %> and content-verified<% } %>`);
+  process.exit(0);
+}
+
+if (missing.length > 0) {
+  console.log(`  check-ci-tiers: ${missing.length} missing workflow file(s):`);
+  for (const f of missing) {
+    console.log(`    missing: .github/workflows/${f}`);
+  }
+}
+<% if (_isL3Plus) { -%>
+if (contentViolation) {
+  console.log(`  check-ci-tiers: content violation: ${contentViolation}`);
+}
+<% } -%>
+process.exit(1);

package/dist/templates/scripts/check-claude-md-lint.mjs.ejs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// <%= projectName %> — claude-md-lint: thin context-file linter (INV-89)
+// Lints AI context files (CLAUDE.md / AGENTS.md, incl. nested .claude/CLAUDE.md) for
+// hardcoded absolute paths, a required @import of the shared layer in delegating files,
+// a soft line budget, and verbatim duplication of imported shared-layer content.
+// Part of the anti-drift validator family (W6). Exits 0 when no hard violations; 1 otherwise.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write([
+    'Usage: node scripts/check-claude-md-lint.mjs [options]',
+    '',
+    'Lints AI context files (CLAUDE.md / AGENTS.md) for hardcoded paths, a required',
+    '@import of the shared layer in delegating files, a line budget (soft), and',
+    'verbatim duplication of imported shared-layer content.',
+    'Exits 0 when no hard violations; exits 1 otherwise. (INV-89)',
+    '',
+    'Options:',
+    '  --help, -h      Show this help and exit',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+const CWD = process.cwd();
+const LINE_BUDGET = 600;
+const DUP_BLOCK_LINES = 12;
+
+const ABS_POSIX = /(^|[\s"'`(=])(\/(home|Users|root|etc|var|opt|tmp|usr\/local)\/)/;
+const ABS_WINDOWS = /(^|[\s"'`(=])([A-Za-z]:[\\/])/;
+
+function discover() {
+  const out = [];
+  for (const f of ['AGENTS.md', 'CLAUDE.md']) {
+    const p = join(CWD, f);
+    if (existsSync(p)) out.push(p);
+  }
+  const dotClaude = join(CWD, '.claude');
+  if (existsSync(dotClaude)) {
+    const p = join(dotClaude, 'CLAUDE.md');
+    if (existsSync(p)) out.push(p);
+  }
+  return out;
+}
+
+function isDelegating(absPath) {
+  return basename(absPath) === 'CLAUDE.md' && dirname(absPath) !== CWD;
+}
+
+function sharedLayerPath() {
+  const p = join(CWD, 'AGENTS.md');
+  return existsSync(p) ? p : null;
+}
+
+function significantLines(content) {
+  return content
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !/^#{1,6}\s/.test(l) && !/^[-=*_]{3,}$/.test(l) && !/^```/.test(l));
+}
+
+function hasVerbatimBlock(childContent, parentContent) {
+  const child = significantLines(childContent);
+  const parentSet = new Set(significantLines(parentContent));
+  let run = 0;
+  for (const line of child) {
+    run = parentSet.has(line) ? run + 1 : 0;
+    if (run >= DUP_BLOCK_LINES) return true;
+  }
+  return false;
+}
+
+function main() {
+  const files = discover();
+  if (files.length === 0) {
+    process.stdout.write('check-claude-md-lint: SKIP — no context files found (INV-89)\n');
+    // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+    process.stdout.write('[SKIP] no context files found (INV-89)\n');
+    return 0;
+  }
+
+  const errors = [];
+  const warnings = [];
+  const layerPath = sharedLayerPath();
+  const layerContent = layerPath ? readFileSync(layerPath, 'utf-8') : null;
+
+  for (const file of files) {
+    const rel = file.slice(CWD.length + 1);
+    const content = readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+
+    lines.forEach((line, i) => {
+      if (ABS_POSIX.test(line) || ABS_WINDOWS.test(line)) {
+        errors.push(`${rel}:${i + 1}: hardcoded absolute path — context files must be portable`);
+      }
+    });
+
+    if (isDelegating(file)) {
+      const hasImport = /^@[\w./-]+/m.test(content);
+      if (!hasImport) {
+        errors.push(`${rel}: delegating context file must @import its shared layer (e.g. @AGENTS.md)`);
+      } else if (layerContent && file !== layerPath && hasVerbatimBlock(content, layerContent)) {
+        errors.push(
+          `${rel}: duplicates a verbatim >=${DUP_BLOCK_LINES}-line block from the imported shared layer — delegate via @import instead of copying`,
+        );
+      }
+    }
+
+    if (lines.length > LINE_BUDGET) {
+      warnings.push(`${rel}: ${lines.length} lines exceeds soft line budget (${LINE_BUDGET})`);
+    }
+  }
+
+  if (errors.length === 0) {
+    if (warnings.length > 0) {
+      process.stdout.write(
+        `check-claude-md-lint: ${files.length} file(s) OK; ${warnings.length} soft warning(s) (INV-89)\n`,
+      );
+      for (const w of warnings) process.stdout.write(`    [warn] ${w}\n`);
+    } else {
+      process.stdout.write(`check-claude-md-lint: all ${files.length} context file(s) OK (INV-89)\n`);
+    }
+    return 0;
+  }
+
+  process.stdout.write(
+    `check-claude-md-lint: ${errors.length} hard error(s) across ${files.length} file(s) (INV-89)\n`,
+  );
+  for (const e of errors) process.stdout.write(`    ${e}\n`);
+  for (const w of warnings) process.stdout.write(`    [warn] ${w}\n`);
+  return 1;
+}
+
+// Fail-closed (INV-96): any unexpected error exits 1 rather than passing silently.
+try {
+  process.exit(main());
+} catch (err) {
+  process.stderr.write(`check-claude-md-lint: unexpected error — ${err?.message ?? err} (INV-89)\n`);
+  process.exit(1);
+}

package/dist/templates/scripts/check-collab-mode-wired.mjs.ejs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// INV-100 enforcement (generated by arbiter): verify arbiter.json declares a
+// valid collaborationMode ('trunk-solo' | 'peer-review' | 'gated-review').
+// Mirrors the self-repo gate (scripts/check-collab-mode-wired.mjs) so generated
+// projects enforce the same primary workflow axis (ADR-051, #1093).
+// Usage: node scripts/check-collab-mode-wired.mjs [--config=<path>]
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const VALID_MODES = new Set(['trunk-solo', 'peer-review', 'gated-review'])
+
+function resolveConfigPath(args) {
+  const flag = args.find((a) => a.startsWith('--config='))
+  if (flag) return resolve(flag.slice('--config='.length))
+  return resolve(process.cwd(), 'arbiter.json')
+}
+
+try {
+  const configPath = resolveConfigPath(process.argv.slice(2))
+
+  if (!existsSync(configPath)) {
+    process.stderr.write(`[INV-100] arbiter.json not found at ${configPath}\n`)
+    process.exit(0) // not an arbiter project — skip
+  }
+
+  let config
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'))
+  } catch {
+    process.stderr.write(`[INV-100] Failed to parse ${configPath}\n`)
+    process.exit(1)
+  }
+
+  const mode = config.collaborationMode
+  if (mode === undefined || mode === null) {
+    process.stderr.write(
+      `[INV-100] collaborationMode is absent from arbiter.json.\n` +
+        `  Set it to one of: trunk-solo, peer-review, gated-review.\n` +
+        `  Run \`arbiter update\` to auto-migrate from soloDevMode.\n`,
+    )
+    process.exit(1)
+  }
+
+  if (!VALID_MODES.has(mode)) {
+    process.stderr.write(
+      `[INV-100] collaborationMode="${mode}" is not a valid value.\n` +
+        `  Must be one of: trunk-solo, peer-review, gated-review.\n`,
+    )
+    process.exit(1)
+  }
+
+  process.stdout.write(`[INV-100] collaborationMode="${mode}" — OK\n`)
+} catch (err) {
+  process.stderr.write(
+    `[INV-100] Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(1)
+}

package/dist/templates/scripts/check-commit-footer-rationale.mjs.ejs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// <%= projectName %> — commit-footer audit-evidence validator (INV-119, §11.10(e))
+// CATALOG: INV-119 enforcement. Scans `origin/main..HEAD` commit range for commits that touch
+// CATALOG:   suppression/bypass files (trivyignore, pitest-override). Verifies
+// CATALOG:   each such commit carries a well-formed immutable commit-footer trailer from the set:
+// CATALOG:   Suppression-Rationale, Pitest-Override-Rationale, Trivy-Expiry-Extension, Sigstore-Bypass.
+// CATALOG: Rejected fold-in into check-suppression-rationale.mjs (that gate checks file content, not
+// CATALOG:   commit history — different invariant axis). Hard-blocks (exit 1) on missing/malformed trailer.
+// CATALOG: Writes evidence artifact to .arbiter/evidence/commit-footer-audit/<timestamp>.json (INV-evidence).
+// Exit codes per INV-53: 0=PASS, 1=FAIL, 2=ERROR
+// Usage: node scripts/check-commit-footer-rationale.mjs [--range=<ref>] [--evidence-dir=<path>] [--dry-run] [--test-trailer=<value>] [--help]
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const CWD = process.cwd();
+
+const HELP = [
+  'Usage: node scripts/check-commit-footer-rationale.mjs [options]',
+  '',
+  'Validates that commits touching suppression/bypass files carry recognized footer trailers (INV-119).',
+  '',
+  'Options:',
+  '  --range=<ref>         Git range to scan (default: origin/main..HEAD)',
+  '  --evidence-dir=<path> Directory to write evidence artifact',
+  '  --dry-run             Skip git scan; validate --test-trailer value only',
+  '  --test-trailer=<val>  Validate a trailer string (use with --dry-run)',
+  '  --help, -h            Show this help and exit',
+  '',
+  'Recognized footer trailers:',
+  '  Suppression-Rationale: <CVE-ID> | <justification> | expires:<YYYY-MM-DD>',
+  '  Pitest-Override-Rationale: <justification> | follow-up:<issue#> | approver:<handle>',
+  '  Trivy-Expiry-Extension: <CVE-ID> | new-expiry:<YYYY-MM-DD> | reason:<text>',
+  '  Sigstore-Bypass: <reason> | retry-after:<YYYY-MM-DD>',
+].join('\n');
+
+const RECOGNIZED_TRAILERS = [
+  'Suppression-Rationale',
+  'Pitest-Override-Rationale',
+  'Trivy-Expiry-Extension',
+  'Sigstore-Bypass',
+];
+
+const SUPPRESSION_FILE_PATTERNS = [
+  /\.trivyignore$/,
+  /pitest.*override/i,
+  /sigstore.*bypass/i,
+  /^suppressions\//,
+  /\/suppressions\//,
+];
+
+function isSuppressionFile(filePath) {
+  return SUPPRESSION_FILE_PATTERNS.some((pat) => pat.test(filePath));
+}
+
+function isRecognizedTrailer(trailer) {
+  if (!trailer || !trailer.trim()) return false;
+  return RECOGNIZED_TRAILERS.some((key) => trailer.trim().startsWith(key + ':'));
+}
+
+function parseArgs() {
+  const raw = process.argv.slice(2);
+  let range = 'origin/main..HEAD';
+  let evidenceDir = join(CWD, '.arbiter', 'evidence', 'commit-footer-audit');
+  let dryRun = false;
+  let testTrailer = null;
+  let help = false;
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i];
+    if (arg === '--help' || arg === '-h') { help = true; }
+    else if (arg === '--dry-run') { dryRun = true; }
+    else if (arg.startsWith('--range=')) { range = arg.slice('--range='.length); }
+    else if (arg === '--range' && i + 1 < raw.length) { range = raw[++i]; }
+    else if (arg.startsWith('--evidence-dir=')) { evidenceDir = resolve(arg.slice('--evidence-dir='.length)); }
+    else if (arg === '--evidence-dir' && i + 1 < raw.length) { evidenceDir = resolve(raw[++i]); }
+    else if (arg.startsWith('--test-trailer=')) { testTrailer = arg.slice('--test-trailer='.length); }
+    else if (arg === '--test-trailer' && i + 1 < raw.length) { testTrailer = raw[++i]; }
+  }
+  return { range, evidenceDir, dryRun, testTrailer, help };
+}
+
+function getCurrentBranch(cwd) {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf-8' }).trim();
+  } catch { return 'unknown'; }
+}
+
+function getCommitsInRange(range, cwd) {
+  try {
+    const hashList = execFileSync('git', ['log', '--format=%H', range], { cwd, encoding: 'utf-8' })
+      .trim().split('\n').filter(Boolean);
+    if (hashList.length === 0) return [];
+    const commits = [];
+    for (const hash of hashList) {
+      let body = '';
+      try { body = execFileSync('git', ['log', '--format=%B', '-1', hash], { cwd, encoding: 'utf-8' }).trim(); } catch { body = ''; }
+      let files = [];
+      try {
+        files = execFileSync('git', ['diff-tree', '--no-commit-id', '-r', '--name-only', hash], { cwd, encoding: 'utf-8' })
+          .trim().split('\n').filter(Boolean);
+      } catch { files = []; }
+      const trailers = body.split('\n').filter((line) => /^[A-Z][A-Za-z-]+:\s/.test(line)).map((l) => l.trim());
+      commits.push({ hash: hash.slice(0, 12), files, trailers, body });
+    }
+    return commits;
+  } catch { return null; }
+}
+
+function writeEvidence(evidenceDir, data) {
+  try {
+    mkdirSync(evidenceDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    writeFileSync(join(evidenceDir, `${ts}.json`), JSON.stringify(data, null, 2) + '\n');
+  } catch (err) {
+    process.stderr.write(`[commit-footer] WARN: could not write evidence: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
+function main() {
+  const { range, evidenceDir, dryRun, testTrailer, help } = parseArgs();
+  if (help) { process.stdout.write(HELP + '\n'); process.exit(0); }
+  if (dryRun && testTrailer !== null) {
+    if (isRecognizedTrailer(testTrailer)) {
+      process.stdout.write('[commit-footer] VALID: trailer recognized\n'); process.exit(0);
+    } else {
+      process.stderr.write('[commit-footer] FOOTER-MISSING: trailer not recognized or empty\n'); process.exit(1);
+    }
+  }
+  if (dryRun) { process.stdout.write('[commit-footer] dry-run: no git history scanned\n'); process.exit(0); }
+  const branch = getCurrentBranch(CWD);
+  const commits = getCommitsInRange(range, CWD);
+  if (commits === null) {
+    process.stderr.write(`[commit-footer] WARN: git log failed for range '${range}' — origin/main may be unavailable. Skipping check.\n`);
+    writeEvidence(evidenceDir, {
+      schema: 'arbiter-commit-footer-audit-v1', generated_at: new Date().toISOString(),
+      branch, range, commits_scanned: 0, commits_requiring_footer: 0, commits_with_valid_footer: 0,
+      violations: [], result: 'SKIP', note: 'git log unavailable — origin/main unreachable',
+    });
+    process.exit(0);
+  }
+  const violations = [];
+  let commitsRequiringFooter = 0;
+  let commitsWithValidFooter = 0;
+  for (const commit of commits) {
+    const suppressionFiles = commit.files.filter(isSuppressionFile);
+    if (suppressionFiles.length === 0) continue;
+    commitsRequiringFooter++;
+    if (commit.trailers.some(isRecognizedTrailer)) {
+      commitsWithValidFooter++;
+    } else {
+      violations.push({ commit: commit.hash, suppression_files: suppressionFiles, trailers_found: commit.trailers, error: 'No recognized footer trailer found for suppression-touching commit' });
+      process.stderr.write(`[commit-footer] FOOTER-MISSING: commit ${commit.hash} touches suppression file(s) but has no recognized footer trailer\n`);
+      for (const f of suppressionFiles) { process.stderr.write(`  suppression file: ${f}\n`); }
+    }
+  }
+  const result = violations.length === 0 ? 'PASS' : 'FAIL';
+  writeEvidence(evidenceDir, {
+    schema: 'arbiter-commit-footer-audit-v1', generated_at: new Date().toISOString(),
+    branch, range, commits_scanned: commits.length, commits_requiring_footer: commitsRequiringFooter,
+    commits_with_valid_footer: commitsWithValidFooter, violations, result,
+  });
+  if (violations.length > 0) {
+    process.stderr.write(`[commit-footer] FAIL — ${violations.length} commit(s) missing required footer trailers\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`[commit-footer] PASS — ${commits.length} commits scanned, ${commitsRequiringFooter} required footer, ${commitsWithValidFooter} validated\n`);
+  process.exit(0);
+}
+
+main();