@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-api-e2e.mjs.ejs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: INV-126 enforcement. Reads api-e2e.json at repo root; for SERVICE archetypes
+// CATALOG:   (required:true) it FAILS when the live-API e2e suite is absent or empty —
+// CATALOG:   the suite must boot the real binary and assert on live HTTP responses.
+// CATALOG:   required:false (non-service) or absent manifest -> SKIP (exit 0). This is the
+// CATALOG:   INVERTED absent-semantics vs INV-124: a declared service MUST ship the suite.
+// CATALOG:   Boundary: file PRESENCE + non-empty only — live-run-pass is the CI/L2 runner
+// CATALOG:   (tests/api/run.sh), assertion quality is INV-118 (anti-proforma).
+// Exit codes: 0=PASS/SKIP, 1=policy violation (absent/empty suite), 2=schema/path-traversal error
+// Usage: node scripts/check-api-e2e.mjs [--help]
+import { readFileSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { globMatch, validateGlob, walkRepo } from './lib/glob-walk.mjs'
+
+const ROOT = resolve(process.cwd())
+const MANIFEST_PATH = join(ROOT, 'api-e2e.json')
+
+const HELP = `Usage: node scripts/check-api-e2e.mjs [--help]
+
+Enforces that a SERVICE archetype (api-e2e.json required:true) ships a non-mocked
+live-API e2e suite that boots the real binary/server (INV-126).
+
+Rules:
+  required:true   — the manifest glob must match >=1 NON-EMPTY suite file; otherwise FAIL.
+  required:false  — SKIP (non-service archetype, e.g. library/cli/frontend).
+  manifest absent — SKIP (ungoverned repo). Re-init with arbiter init to generate it.
+
+Exit codes:
+  0 — pass or SKIP
+  1 — policy violation (required suite absent or empty)
+  2 — schema error or path-traversal glob detected`
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(`${HELP}\n`)
+  process.exit(0)
+}
+
+function fileIsNonEmpty(abs) {
+  try {
+    return readFileSync(abs, 'utf-8').trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  if (!existsSync(MANIFEST_PATH)) {
+    process.stdout.write('[check-api-e2e] SKIP — api-e2e.json not found\n')
+    // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+    process.stdout.write('[SKIP] api-e2e.json not found\n')
+    process.exit(0)
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`[check-api-e2e] ERROR — invalid JSON: ${err.message}\n`)
+    process.exit(2)
+  }
+
+  if (manifest.required !== true) {
+    process.stdout.write(
+      '[check-api-e2e] SKIP — required:false (non-service archetype, no live-API suite mandated)\n',
+    )
+    // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+    process.stdout.write('[SKIP] required:false (non-service archetype)\n')
+    process.exit(0)
+  }
+
+  const glob = manifest.glob
+  if (typeof glob !== 'string' || glob.length === 0 || !validateGlob(glob)) {
+    process.stderr.write(
+      `[check-api-e2e] ERROR — manifest.glob "${glob}" is absent, absolute, or contains ` +
+        `path traversal — only relative, non-traversal globs are allowed\n`,
+    )
+    process.exit(2)
+  }
+
+  const allFiles = walkRepo(ROOT)
+
+  const matches = allFiles.filter((rel) => globMatch(glob, rel))
+  const nonEmpty = matches.filter((rel) => fileIsNonEmpty(join(ROOT, rel)))
+
+  if (nonEmpty.length === 0) {
+    const reason =
+      matches.length === 0 ? 'no suite file matched' : 'matched suite file(s) are empty'
+    process.stderr.write(
+      `[check-api-e2e] FAIL — service archetype "${manifest.archetype}" declares a required ` +
+        `live-API e2e suite but ${reason} (glob: ${glob}). A non-mocked suite that boots the ` +
+        `real binary and asserts on live HTTP responses is mandatory — see ${manifest.suiteDir}/.\n`,
+    )
+    process.exit(1)
+  }
+
+  process.stdout.write(`[check-api-e2e] OK — ${nonEmpty.length} live-API suite file(s) present\n`)
+  process.exit(0)
+}
+
+try {
+  await main()
+} catch (err) {
+  process.stderr.write(`[check-api-e2e] ERROR — unexpected: ${err.message}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-arc42-slots.mjs.ejs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-arc42-slots.mjs — generated by arbiter (INV-144).
+// arc42 slot-completeness runner for this project. Delegates to the root-local Arbiter CLI
+// (no `yaml` dep — the engine runs inside the installed local Arbiter CLI against this
+// repo, same shape as check-doc-set.mjs.ejs and check-doc-freshness.mjs.ejs).
+//
+// The skeletons the audit compares against live in arbiter, not here: this project is held to the
+// arc42 skeleton its own tier column receives, so a section deleted from the architecture document
+// is reported as the structural gap it is rather than passing unnoticed.
+//
+// Usage: node scripts/check-arc42-slots.mjs [--json] [--update-baseline]
+//
+// Exit codes (INV-53): 0=every required slot present and the hollow-section count within baseline,
+// 1=violation, 2=ERROR. On the FIRST clean run, with no scripts/data/arc42-baseline.json, the gate
+// WRITES the hollow-section count it measured (creating scripts/data/) instead of failing — a
+// freshly generated arc42 is hollow by construction, and a gate that made `arbiter init` produce a
+// red repo would only teach people to delete it. Every run after that is a ratchet: the count may
+// fall, never rise. Persisting matters: an earlier version only tolerated the count in memory, so
+// no generated project ever grew a baseline and the ratchet never armed anywhere.
+import { runLocalArbiter } from './lib/run-helpers.mjs'
+
+const args = process.argv.slice(2)
+
+process.exit(runLocalArbiter(['doc-set', '--arc42', ...args]))

package/dist/templates/scripts/check-assertion-delta.mjs.ejs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-assertion-delta.mjs — generated by arbiter (anti-fake-green, #2161).
+//
+// CATALOG: diffs the current commit range for test files that remove an assertion with none
+// CATALOG:   added, or raise the skip-marker count, without an Assertion-Delta-Override trailer.
+// CATALOG: rejected fold-in into check-muted-test.mjs because that inspects the CURRENT tree for a
+// CATALOG:   skip marker; this inspects a DIFF for a removed assertion or a rising skip delta — a
+// CATALOG:   different axis (snapshot content vs change-over-range).
+// CATALOG: rejected fold-in into check-commit-footer-rationale.mjs because that walks commit-touched
+// CATALOG:   FILE PATTERNS (trivyignore/suppressions/*); this walks DIFF CONTENT of test files —
+// CATALOG:   the trailer-override shape is reused, the detection surface is not.
+//
+// Assertion-delta guard. ImpossibleBench (arxiv 2510.20270) found that the reward-hacking exploit
+// models reach for most often is editing the test itself — removing an assertion, or adding a
+// skip — while the surrounding CI turns green. A regex over the diff is cheaper and harder to game
+// than an LLM judge for this specific shape: on the current commit range, if a touched test file's
+// diff REMOVES an assertion line with NO assertion line added anywhere in the same range, or the
+// skip-marker count (@Disabled/.skip/xit/fixme) goes UP, that is reward-hacking-shaped and the gate
+// fails asking for an explicit justification. A refactor that moves/rewrites assertions (net delta
+// >= 0) is unaffected — this is a delta gate, not a line-count minimum.
+//
+// Override: an `Assertion-Delta-Override: <reason>` trailer on the tip commit of the range makes the
+// gate pass (logged, not silent) — same commit-footer-trailer shape as INV-119, so the override
+// lands in ordinary commit-message audit trail rather than a separate suppression file.
+//
+// Range determination mirrors check-commit-footer-rationale.mjs (INV-119): defaults to
+// `origin/main..HEAD`, fails OPEN (exit 0, explicit WARN) only when the range itself cannot be
+// resolved (e.g. no `origin` remote in a fresh clone) — never a silent swallow, always logged.
+//
+// Exit codes (INV-53): 0=PASS/override/vacuous/no-range, 1=FAIL, 2=ERROR (self).
+// Usage: node scripts/check-assertion-delta.mjs [--range=<ref>] [--repo-root=<path>] [--evidence-dir=<path>] [--help]
+import { execFileSync } from 'node:child_process'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+
+const HELP = [
+  'Usage: node scripts/check-assertion-delta.mjs [options]',
+  '',
+  'Fails when a diff removes test assertions with none added, or increases the skip-marker count,',
+  'without an Assertion-Delta-Override trailer on the tip commit.',
+  '',
+  'Options:',
+  '  --range=<ref>          Git range to scan (default: origin/main..HEAD)',
+  '  --repo-root=<path>     Repository root to run git in (default: cwd)',
+  '  --evidence-dir=<path>  Directory to write the evidence artifact',
+  '  --help, -h             Show this help and exit',
+].join('\n')
+
+// Assertion patterns per stack (AC-3: a data table, not hardcoded in the walk logic).
+const ASSERTION_PATTERNS = [
+  { stack: 'vitest-jest-playwright', re: /\bexpect\s*\(/ },
+  {
+    stack: 'junit-assertj',
+    re: /\bassert(?:That|Equals|True|False|Null|NotNull|ArrayEquals|Throws)\s*\(|\bAssertions\.\w+\s*\(/,
+  },
+]
+
+// Skip-marker patterns — a rising count is the other reward-hacking shape (increasing xit/@Disabled).
+const SKIP_MARKER_RE = /@Disabled\b|\.skip\s*\(|\bxit\s*\(|\bxtest\s*\(|\bxdescribe\s*\(|\bfixme\b/
+
+// Test files this guard considers in scope.
+const TEST_FILE_RE = /\.(?:spec|test)\.(?:ts|tsx|js|jsx|mjs)$|(?:Test|Tests)\.java$/
+
+// name -> [key in the parsed result, value transform]
+const FLAG_SPECS = [
+  ['--range', 'range', (v) => v],
+  ['--repo-root', 'repoRoot', (v) => resolve(v)],
+  ['--evidence-dir', 'evidenceDir', (v) => resolve(v)],
+]
+
+/** `--flag=value` or `--flag value` for one flag spec; returns null if `arg` doesn't match. */
+function matchFlag(spec, arg, raw, i) {
+  const [name, key, transform] = spec
+  if (arg.startsWith(`${name}=`)) return { key, value: transform(arg.slice(name.length + 1)), consumed: 0 }
+  if (arg === name && i + 1 < raw.length) return { key, value: transform(raw[i + 1]), consumed: 1 }
+  return null
+}
+
+function parseArgs() {
+  const raw = process.argv.slice(2)
+  const out = { range: 'origin/main..HEAD', repoRoot: process.cwd(), evidenceDir: null, help: false }
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i]
+    if (arg === '--help' || arg === '-h') {
+      out.help = true
+      continue
+    }
+    const hit = FLAG_SPECS.map((spec) => matchFlag(spec, arg, raw, i)).find(Boolean)
+    if (!hit) continue
+    out[hit.key] = hit.value
+    i += hit.consumed
+  }
+  if (!out.evidenceDir) out.evidenceDir = join(out.repoRoot, '.arbiter', 'evidence', 'assertion-delta')
+  return out
+}
+
+function git(repoRoot, args) {
+  return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf-8' })
+}
+
+/** Test files touched in `range`, filtered to TEST_FILE_RE. Returns null if the range can't be resolved. */
+function changedTestFiles(repoRoot, range) {
+  try {
+    return git(repoRoot, ['diff', '--name-only', range])
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .filter((f) => TEST_FILE_RE.test(f))
+    // FAIL-OPEN-INTENT: range unresolvable (no origin remote) — caller logs a WARN + exits 0 (SKIP).
+  } catch {
+    return null
+  }
+}
+
+const DIFF_HEADER_RE = /^(?:\+\+\+|---|@@)/
+
+/** 'added' | 'removed' | null (header line or context line) for one unified-diff line. */
+function classifyDiffLine(line) {
+  if (DIFF_HEADER_RE.test(line)) return null
+  if (line.startsWith('+')) return 'added'
+  if (line.startsWith('-')) return 'removed'
+  return null
+}
+
+/** Count assertion/skip-marker lines added vs removed for one file's diff in `range`. */
+function fileDelta(repoRoot, range, file) {
+  let diff
+  try {
+    diff = git(repoRoot, ['diff', '--unified=0', range, '--', file])
+    // FAIL-OPEN-INTENT: one file's diff failing degrades to a zero delta for THAT file only.
+  } catch {
+    return { assertionsAdded: 0, assertionsRemoved: 0, skipAdded: 0, skipRemoved: 0 }
+  }
+  const counts = { assertionsAdded: 0, assertionsRemoved: 0, skipAdded: 0, skipRemoved: 0 }
+  for (const line of diff.split('\n')) {
+    const kind = classifyDiffLine(line)
+    if (!kind) continue
+    const body = line.slice(1)
+    if (ASSERTION_PATTERNS.some((p) => p.re.test(body))) {
+      counts[kind === 'added' ? 'assertionsAdded' : 'assertionsRemoved']++
+    }
+    if (SKIP_MARKER_RE.test(body)) {
+      counts[kind === 'added' ? 'skipAdded' : 'skipRemoved']++
+    }
+  }
+  return counts
+}
+
+/**
+ * Every commit message in `range`, so an override trailer on ANY commit of the range is honored —
+ * not just the tip. Mirrors check-commit-footer-rationale.mjs (INV-119), which scans the whole
+ * range rather than only HEAD: a reviewer amending/rewording only the tip to add a trailer is not
+ * how commit history normally works, and requiring it would make the override impossible to use
+ * without a rebase.
+ */
+function rangeMessages(repoRoot, range) {
+  try {
+    return git(repoRoot, ['log', '--format=%B%x00', range])
+    // FAIL-OPEN-INTENT: unresolvable range → no messages read → no override found (fail-CLOSED).
+  } catch {
+    return ''
+  }
+}
+
+const OVERRIDE_RE = /^Assertion-Delta-Override:\s*\S.*$/m
+
+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(
+      `check-assertion-delta: WARN — could not write evidence: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+  }
+}
+
+function skipUnresolvedRange(evidenceDir, range) {
+  process.stderr.write(
+    `check-assertion-delta: WARN — range '${range}' could not be resolved (origin unreachable?). Skipping.\n`,
+  )
+  writeEvidence(evidenceDir, {
+    schema: 'arbiter-assertion-delta-v1',
+    generated_at: new Date().toISOString(),
+    range,
+    result: 'SKIP',
+    note: 'git range unavailable',
+  })
+  return 0
+}
+
+function passNoTestFilesTouched(evidenceDir, range) {
+  process.stdout.write('check-assertion-delta: OK — no test files touched in range.\n')
+  writeEvidence(evidenceDir, {
+    schema: 'arbiter-assertion-delta-v1',
+    generated_at: new Date().toISOString(),
+    range,
+    files_scanned: 0,
+    result: 'PASS',
+  })
+  return 0
+}
+
+/** Sum per-file deltas across every changed test file. */
+function collectDeltas(repoRoot, range, files) {
+  const totals = { assertionsAdded: 0, assertionsRemoved: 0, skipAdded: 0, skipRemoved: 0 }
+  for (const f of files) {
+    const d = fileDelta(repoRoot, range, f)
+    totals.assertionsAdded += d.assertionsAdded
+    totals.assertionsRemoved += d.assertionsRemoved
+    totals.skipAdded += d.skipAdded
+    totals.skipRemoved += d.skipRemoved
+  }
+  return totals
+}
+
+function detectViolations({ assertionsAdded, assertionsRemoved, skipAdded, skipRemoved }, fileCount) {
+  const violations = []
+  if (assertionsRemoved > 0 && assertionsAdded === 0) {
+    violations.push(`${assertionsRemoved} assertion(s) removed across ${fileCount} test file(s), none added`)
+  }
+  if (skipAdded > skipRemoved) {
+    violations.push(`skip-marker count increased (+${skipAdded} / -${skipRemoved})`)
+  }
+  return violations
+}
+
+/** Emit the stdout/stderr verdict for a resolved (non-SKIP) run and return the process exit code. */
+function reportResult(result, violations, fileCount) {
+  if (result === 'PASS') {
+    process.stdout.write(`check-assertion-delta: OK — ${fileCount} test file(s) scanned, no reward-hacking shape.\n`)
+    return 0
+  }
+  if (result === 'OVERRIDDEN') {
+    process.stdout.write(
+      `check-assertion-delta: OVERRIDDEN — ${violations.join('; ')} — Assertion-Delta-Override trailer present.\n`,
+    )
+    return 0
+  }
+  process.stderr.write(`check-assertion-delta: FAIL — ${violations.join('; ')}\n`)
+  process.stderr.write(
+    '  If this is a legitimate refactor, add a trailer to the tip commit: ' +
+      'Assertion-Delta-Override: <reason>\n',
+  )
+  return 1
+}
+
+function main() {
+  const { range, repoRoot, evidenceDir, help } = parseArgs()
+  if (help) {
+    process.stdout.write(HELP + '\n')
+    return 0
+  }
+
+  const files = changedTestFiles(repoRoot, range)
+  if (files === null) return skipUnresolvedRange(evidenceDir, range)
+  if (files.length === 0) return passNoTestFilesTouched(evidenceDir, range)
+
+  const deltas = collectDeltas(repoRoot, range, files)
+  const violations = detectViolations(deltas, files.length)
+  const overridden = violations.length > 0 && OVERRIDE_RE.test(rangeMessages(repoRoot, range))
+  const result = violations.length === 0 ? 'PASS' : overridden ? 'OVERRIDDEN' : 'FAIL'
+
+  writeEvidence(evidenceDir, {
+    schema: 'arbiter-assertion-delta-v1',
+    generated_at: new Date().toISOString(),
+    range,
+    files_scanned: files.length,
+    assertions_added: deltas.assertionsAdded,
+    assertions_removed: deltas.assertionsRemoved,
+    skip_added: deltas.skipAdded,
+    skip_removed: deltas.skipRemoved,
+    violations,
+    result,
+  })
+
+  return reportResult(result, violations, files.length)
+}
+
+try {
+  process.exit(main())
+} catch (e) {
+  process.stderr.write(`check-assertion-delta: ERROR — ${e?.message ?? e}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-audit-dry-pass.mjs.ejs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: E3 (#1943, M14) — audit dry-pass termination gate. A discovery loop of unknown
+// CATALOG: size (audit, backlog drain, dead-code hunt) may conclude only after TWO consecutive
+// CATALOG: passes with zero new findings, produced by differently-seeded scans. Converts "I think
+// CATALOG: we got everything" (a claim, R2) into a checkable predicate. Reads the pass-ledger
+// CATALOG: (.arbiter/evidence/audit/<audit-id>/pass-ledger.jsonl) and refuses a conclusion
+// CATALOG: artifact (report.md/concluded.json) present while the ledger is still wet.
+// CATALOG: Rejected fold-in into check-evidence-bundle.mjs: that validates the per-task TDD
+// CATALOG: bundle shape, a different envelope; the dry-pass ledger is a JSONL audit trail with a
+// CATALOG: two-dry-pass termination rule that has no analog in the bundle validator.
+//
+// Exit codes (INV-53): 0 PASS, 1 FAIL (concluded-but-wet / same-seed double-dry / malformed), 2 ERROR.
+// Vacuous pass when no audit dirs exist.
+//
+// Usage:
+//   node scripts/check-audit-dry-pass.mjs [--dir <auditDir>] [--all] [--root <dir>]
+//     --dir   lint a single audit directory
+//     --all   scan every .arbiter/evidence/audit/* under --root (default)
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } 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 DIR_ARG = arg('dir', argv)
+const ALL = argv.includes('--all')
+const ROOT = arg('root', argv) ? resolve(arg('root', argv)) : repoDefault
+const AUDIT_ROOT = join(ROOT, '.arbiter', 'evidence', 'audit')
+const CONCLUSION_FILES = ['report.md', 'concluded.json', 'REPORT.md']
+
+/**
+ * Parse a JSONL pass-ledger. Returns { passes: object[], malformed: string[] }.
+ * @param {string} ledgerPath
+ */
+function parseLedger(ledgerPath) {
+  /** @type {Record<string, unknown>[]} */
+  const passes = []
+  /** @type {string[]} */
+  const malformed = []
+  let raw
+  try {
+    raw = readFileSync(ledgerPath, 'utf-8')
+    // FAIL-OPEN-INTENT: readFileSync failure is surfaced via the returned `unreadable:true` flag; the caller emits a FAIL for it (fail-closed at the caller).
+  } catch {
+    return { passes, malformed, unreadable: true }
+  }
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      const obj = JSON.parse(line)
+      if (typeof obj !== 'object' || obj === null) {
+        malformed.push(`non-object line: ${line.slice(0, 60)}`)
+        continue
+      }
+      passes.push(/** @type {Record<string, unknown>} */ (obj))
+      // FAIL-OPEN-INTENT: JSON parse error is recorded into the malformed[] array, which the caller surfaces as a FAIL (fail-closed).
+    } catch (err) {
+      malformed.push(`unparseable line: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  return { passes, malformed, unreadable: false }
+}
+
+/**
+ * Lint one audit dir. Returns array of violation messages (empty = pass).
+ * @param {string} auditDir
+ * @returns {string[]}
+ */
+function lintAudit(auditDir) {
+  /** @type {string[]} */
+  const violations = []
+  const concluded = CONCLUSION_FILES.some((f) => existsSync(join(auditDir, f)))
+  const ledgerPath = join(auditDir, 'pass-ledger.jsonl')
+  if (!existsSync(ledgerPath)) {
+    // No ledger: if no conclusion either → nothing to adjudicate (pass). If a conclusion
+    // exists with no ledger → fail (concluded with no dry-pass proof).
+    if (concluded) violations.push(`${auditDir}: conclusion present but no pass-ledger.jsonl`)
+    return violations
+  }
+  const { passes, malformed, unreadable } = parseLedger(ledgerPath)
+  if (unreadable) {
+    violations.push(`${auditDir}: cannot read pass-ledger.jsonl`)
+    return violations
+  }
+  if (malformed.length > 0) {
+    violations.push(`${auditDir}: malformed ledger — ${malformed.join('; ')}`)
+    return violations
+  }
+  // No conclusion → nothing to adjudicate yet (the skill invokes the gate before concluding,
+  // so a wet ledger with no conclusion is the normal in-flight state, not a fail).
+  if (!concluded) return violations
+  if (passes.length < 2) {
+    violations.push(`${auditDir}: conclusion present but ledger has <2 passes (${passes.length})`)
+    return violations
+  }
+  const last = passes[passes.length - 1]
+  const prev = passes[passes.length - 2]
+  const lastNew = Number(last['newFindings'] ?? -1)
+  const prevNew = Number(prev['newFindings'] ?? -1)
+  if (lastNew !== 0 || prevNew !== 0) {
+    violations.push(
+      `${auditDir}: concluded but last two passes are not both dry (newFindings: ${prevNew}, ${lastNew})`,
+    )
+    return violations
+  }
+  const lastSeed = String(last['seed'] ?? '')
+  const prevSeed = String(prev['seed'] ?? '')
+  if (lastSeed === prevSeed) {
+    violations.push(
+      `${auditDir}: two dry passes share the same seed "${lastSeed}" — one sample, not two`,
+    )
+    return violations
+  }
+  return violations
+}
+
+function listAuditDirs() {
+  if (!existsSync(AUDIT_ROOT)) return []
+  /** @type {string[]} */
+  const out = []
+  for (const entry of readdirSync(AUDIT_ROOT)) {
+    const full = join(AUDIT_ROOT, entry)
+    try {
+      if (statSync(full).isDirectory()) out.push(full)
+      // FAIL-OPEN-INTENT: statSync ENOENT race (dir entry removed between readdir+stat) — rethrow all others; the entry is just skipped.
+    } catch {
+      /* skip */
+    }
+  }
+  return out
+}
+
+function main() {
+  /** @type {string[]} */
+  let dirs
+  if (DIR_ARG) {
+    dirs = [resolve(DIR_ARG)]
+  } else if (ALL || !DIR_ARG) {
+    // default behavior (no --dir) = scan all under --root
+    dirs = listAuditDirs()
+  }
+  if (!dirs) dirs = []
+  let checked = 0
+  let totalViolations = 0
+  for (const d of dirs) {
+    if (!existsSync(d)) {
+      process.stderr.write(`[check-audit-dry-pass] ERROR: dir not found: ${d}\n`)
+      return 2
+    }
+    checked++
+    const v = lintAudit(d)
+    for (const msg of v) process.stdout.write(`[check-audit-dry-pass] FAIL: ${msg}\n`)
+    totalViolations += v.length
+  }
+  if (totalViolations > 0) {
+    process.stdout.write(
+      `[check-audit-dry-pass] FAIL: ${totalViolations} violation(s) across ${checked} audit dir(s)\n`,
+    )
+    return 1
+  }
+  process.stdout.write(`[check-audit-dry-pass] OK — ${checked} audit dir(s) passed\n`)
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (err) {
+  process.stderr.write(
+    `[check-audit-dry-pass] ERROR: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(2)
+}