@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-touched-vs-manifest.mjs.ejs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: E7 (#1943, M6 read-set + ADR-103 disjointness) — touched-vs-manifest gate. Context
+// CATALOG: economy made checkable: a wave group declares what it will WRITE (manifest `Files` row);
+// CATALOG: what a worker actually TOUCHED (git diff --name-only base...branch) must stay inside
+// CATALOG: that declared write set. This proves one group's write-set compliance.
+// CATALOG: Pairwise cross-group disjointness is declared but not computed by this check.
+// CATALOG: Rejected fold-in into check-agent-dispatch.mjs: that asserts the dispatch matrix vs the
+// CATALOG: compiled derivation (declaration parity), not the post-hoc touched⊆manifest predicate
+// CATALOG: (execution inside declaration). Different axis, different lifecycle (plan-time vs harvest).
+//
+// Exit codes (INV-53): 0 PASS, 1 FAIL (touched outside manifest / missing group section), 2 ERROR.
+// Read-set row absent ⇒ advisory stderr, PASS (reads bounded socially, writes mechanically).
+//
+// Usage (invoked by wave-drain harvest per group — NOT check-all, which has no --plan args):
+//   node scripts/check-touched-vs-manifest.mjs --plan <plan.md> --group <G>
+//                                        --base <ref> [--branch <b>] [--repo-root <dir>]
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { execSync } from 'node:child_process'
+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 PLAN = arg('plan', argv)
+const GROUP = arg('group', argv)
+const BASE = arg('base', argv)
+const BRANCH = arg('branch', argv) // defaults to HEAD
+const REPO_ROOT = arg('repo-root', argv) ? resolve(arg('repo-root', argv)) : repoDefault
+
+/**
+ * Extract the group's manifest section from the plan.
+ * Group section shape (wave-drain Phase 1):
+ *   ## Group: <G>
+ *   Files: src/a.ts, src/b.ts
+ *   Read-set: src/c.ts, docs/x.md
+ * @param {string} planSrc
+ * @param {string} group
+ * @returns {{ files: string[], readSet: string[], found: boolean }}
+ */
+function extractGroup(planSrc, group) {
+  const lines = planSrc.split('\n')
+  let inGroup = false
+  /** @type {string[]} */
+  let files = []
+  /** @type {string[]} */
+  let readSet = []
+  let found = false
+  let hasReadSet = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const grpMatch = line.match(/^##\s*Group:\s*(.+?)\s*$/i)
+    if (grpMatch) {
+      if (inGroup) break // next group starts
+      if (grpMatch[1].trim() === group) {
+        inGroup = true
+        found = true
+      } else {
+        inGroup = false
+      }
+      continue
+    }
+    if (/^##\s/.test(line) && inGroup) break
+    if (!inGroup) continue
+    const filesMatch = line.match(/^\s*Files?\s*:\s*(.+)$/i)
+    if (filesMatch) {
+      files = filesMatch[1]
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+      continue
+    }
+    const readMatch = line.match(/^\s*Read-?set\s*:\s*(.+)$/i)
+    if (readMatch) {
+      readSet = readMatch[1]
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+      hasReadSet = true
+    }
+  }
+  return { files, readSet, found, hasReadSet }
+}
+
+function gitDiff(base, branch, repoRoot) {
+  try {
+    const ref = branch ? `${base}...${branch}` : `${base}...HEAD`
+    const out = execSync(`git diff --name-only ${ref}`, {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 6000,
+    })
+    return out
+      .split('\n')
+      .map((s) => s.trim())
+      .filter(Boolean)
+  } catch (err) {
+    throw new Error(`git diff failed: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+function main() {
+  if (!PLAN || !GROUP || !BASE) {
+    process.stderr.write(
+      '[check-touched-vs-manifest] ERROR: --plan, --group and --base are required\n',
+    )
+    return 2
+  }
+  const planPath = resolve(PLAN)
+  if (!existsSync(planPath)) {
+    process.stderr.write(`[check-touched-vs-manifest] ERROR: plan not found: ${planPath}\n`)
+    return 2
+  }
+  let planSrc
+  try {
+    planSrc = readFileSync(planPath, 'utf-8')
+  } catch (err) {
+    process.stderr.write(
+      `[check-touched-vs-manifest] ERROR: cannot read plan: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return 2
+  }
+  const { files, found, hasReadSet } = extractGroup(planSrc, GROUP)
+  if (!found) {
+    process.stdout.write(
+      `[check-touched-vs-manifest] FAIL: plan has no "## Group: ${GROUP}" section — declaration is the point\n`,
+    )
+    return 1
+  }
+  // Advisory: read-set row absent (reads bounded socially, writes mechanically).
+  if (!hasReadSet) {
+    process.stderr.write(
+      `[check-touched-vs-manifest] advisory: group "${GROUP}" declares no Read-set row — reads are bounded socially, not mechanically\n`,
+    )
+  }
+  const writeSet = new Set(files)
+  let touched
+  try {
+    touched = gitDiff(BASE, BRANCH, REPO_ROOT)
+  } catch (err) {
+    process.stderr.write(
+      `[check-touched-vs-manifest] ERROR: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return 2
+  }
+  /** @type {string[]} */
+  const outside = []
+  for (const f of touched) {
+    if (!writeSet.has(f)) outside.push(f)
+  }
+  if (outside.length > 0) {
+    process.stdout.write(
+      `[check-touched-vs-manifest] FAIL: ${outside.length} file(s) touched outside the declared write set for group "${GROUP}":\n` +
+        outside.map((f) => `  - ${f}`).join('\n') +
+        '\n',
+    )
+    process.stdout.write(
+      `[check-touched-vs-manifest] FAIL: violated the declared write-set contract for group "${GROUP}"; this single-group check does not prove cross-group pairwise disjointness\n`,
+    )
+    return 1
+  }
+  process.stdout.write(
+    `[check-touched-vs-manifest] OK — ${touched.length} touched file(s) ⊆ manifest (${files.length} declared) for group "${GROUP}"\n`,
+  )
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (err) {
+  process.stderr.write(
+    `[check-touched-vs-manifest] ERROR: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(2)
+}

package/dist/templates/scripts/check-unwired-guards.mjs.ejs

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// <%= projectName %> — unwired guard-script detector (INV-89)
+//
+// CATALOG: reverse wiring-coherence for guard scripts, widening the class
+// CATALOG: check-emission-coherence.mjs's checkUnreferencedScripts (INV-123)
+// CATALOG: already catches. Rejected fold-in into that script: (1) its
+// CATALOG: candidate glob is check-*.mjs only — blind to check-*.sh,
+// CATALOG: verify-*.sh, and scripts/qa/check-* (the motivating incident: a
+// CATALOG: 375-line hand-authored verify-requirements-matrix.sh never seen by
+// CATALOG: a .mjs-only scan); (2) it never recognizes run.sh as a gate
+// CATALOG: entrypoint; (3) a malformed manifest here is its own exit-2 schema
+// CATALOG: class, not folded into the exit-1 problem list. Reference corpus is
+// CATALOG: the same surfaces (check-all.mjs, scripts/**, .claude/hooks/**,
+// CATALOG: settings.json, Makefile, githooks, workflows, commands) plus run.sh
+// CATALOG: and package.json — a superset, not a narrower scan. Allowlisting
+// CATALOG: (below) deliberately REUSES scripts/optional-emissions.json rather
+// CATALOG: than inventing a second exceptions file: it is the canonical,
+// CATALOG: already-emitted-to-every-target INV-123 manifest for precisely this
+// CATALOG: "emitted unconditionally, wired only sometimes" concept (its own
+// CATALOG: $comment documents the REVERSE #1518 direction this check exists
+// CATALOG: to enforce) — one shared list for both checks, not two that can
+// CATALOG: drift apart.
+//
+// Detects a "guard script" (scripts/check-*.mjs, scripts/check-*.sh,
+// scripts/verify-*.sh, scripts/qa/check-*, .claude/hooks/*.mjs) that exists
+// on disk but is never referenced from any recognized gate entrypoint.
+// Emitted-but-unwired gives a false sense of coverage: the script never runs,
+// yet its existence reads as "this class of drift is checked".
+//
+// Allowlist: scripts/optional-emissions.json (shared with check-emission-
+// coherence.mjs, INV-123) —
+//   { "optional": [{ "path": "scripts/qa/check-foo.sh", "rationale": "..." }] }
+// Absent file = empty allowlist (no error, day-1 safe). A malformed file (bad
+// JSON / missing "optional" array / entry missing path or rationale) is a
+// SCHEMA error (exit 2) — never silently downgraded to a normal FAIL, and
+// never a silent allowlist-without-reason.
+//
+// Exit codes (INV-53): 0 = every candidate referenced, allowlisted, or no
+// scripts/ directory or .claude/hooks/ directory at all (vacuous SKIP). 1 =
+// >=1 unreferenced guard script (not allowlisted). 2 = allowlist schema error.
+//
+// Usage: node scripts/check-unwired-guards.mjs [--help]
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SELF_NAME = 'check-unwired-guards.mjs';
+const ALLOWLIST_REL = 'scripts/optional-emissions.json';
+
+const HELP = `Usage: node scripts/check-unwired-guards.mjs [options]
+
+Detects a guard script (scripts/check-*.mjs, scripts/check-*.sh,
+scripts/verify-*.sh, scripts/qa/check-*, .claude/hooks/*.mjs) that is emitted
+but never referenced by any recognized gate entrypoint (scripts/check-all.mjs,
+run.sh, another scripts/** file, .claude/hooks/**, .claude/settings.json,
+.codex/config.toml, Makefile, .githooks/*, package.json, .claude/commands/*.md, or a
+.github/workflows/*.yml). Exits 1 naming the file(s) when found unreferenced.
+
+An entry in scripts/optional-emissions.json (shared with the INV-123
+emission-coherence gate) with a non-empty rationale silences one candidate
+(printed as ALLOWLISTED, still visible for auditability). A malformed
+manifest is a schema error (exit 2).
+
+Options:
+  --help, -h      Show this help and exit
+
+Exit codes:
+  0   every candidate referenced, allowlisted, or no scripts/ or .claude/hooks/ dir (vacuous SKIP)
+  1   >=1 unreferenced guard script
+  2   allowlist schema error
+`;
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+// Recursively collect every file path (relative to `dir`) under `dir/sub`.
+function collectFiles(dir, sub, acc) {
+  const abs = join(dir, sub);
+  if (!existsSync(abs)) return;
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    const rel = `${sub}/${entry.name}`;
+    if (entry.isDirectory()) collectFiles(dir, rel, acc);
+    else acc.push(rel);
+  }
+}
+
+// Read `dir/rel` into `corpus` keyed by `rel`, silently skipping an absent file.
+function addToCorpus(dir, rel, corpus) {
+  const abs = join(dir, rel);
+  if (existsSync(abs)) corpus.set(rel, readFileSync(abs, 'utf8'));
+}
+
+// Recursively collect every file under `dir/sub` whose relative path matches
+// `extRe`, adding each to `corpus`.
+function collectByExtension(dir, sub, extRe, corpus) {
+  const files = [];
+  collectFiles(dir, sub, files);
+  for (const rel of files) {
+    if (extRe.test(rel)) addToCorpus(dir, rel, corpus);
+  }
+}
+
+// Non-recursive: every direct child of `dir/sub` passing `nameTest`, added to
+// `corpus`. No-op when `dir/sub` does not exist.
+function collectShallowDir(dir, sub, nameTest, corpus) {
+  const abs = join(dir, sub);
+  if (!existsSync(abs)) return;
+  for (const name of readdirSync(abs)) {
+    if (nameTest(name)) addToCorpus(dir, `${sub}/${name}`, corpus);
+  }
+}
+
+// Build the reference corpus: every surface a guard script could plausibly be
+// invoked/mentioned from. Superset of check-emission-coherence.mjs's own
+// corpus (scripts/**, .claude/hooks/**, settings.json, Makefile, githooks,
+// workflows, commands) plus run.sh and package.json.
+function buildCorpus(dir) {
+  const corpus = new Map();
+  collectByExtension(dir, 'scripts', /\.(mjs|sh|cjs)$/, corpus);
+  collectByExtension(dir, '.claude/hooks', /\.mjs$/, corpus);
+  addToCorpus(dir, 'run.sh', corpus);
+  addToCorpus(dir, 'package.json', corpus);
+  addToCorpus(dir, 'Makefile', corpus);
+  addToCorpus(dir, '.claude/settings.json', corpus);
+  // #2257: codex-only projects have no .claude/settings.json — the 6 real-time-bridged
+  // hooks (HOOK_DESCRIPTORS' BRIDGED entries, codex-known-limitations.ts) are wired
+  // through .codex/config.toml -> codex-adapter.mjs instead. Without this, every one
+  // of those hooks false-FAILs as unreferenced on a virgin codex-only init.
+  addToCorpus(dir, '.codex/config.toml', corpus);
+  for (const h of ['pre-commit', 'pre-push', 'commit-msg']) {
+    addToCorpus(dir, `.githooks/${h}`, corpus);
+  }
+  collectShallowDir(dir, '.github/workflows', (f) => /\.ya?ml$/.test(f), corpus);
+  collectShallowDir(dir, '.claude/commands', (f) => f.endsWith('.md'), corpus);
+  return corpus;
+}
+
+const TOP_LEVEL_CANDIDATE_RE = /^(check-.*\.mjs|check-.*\.sh|verify-.*\.sh)$/;
+
+// A top-level scripts/ entry is a candidate unless it's the check-all.mjs
+// entrypoint or this script's own filename.
+function isTopLevelCandidate(name) {
+  return name !== 'check-all.mjs' && name !== SELF_NAME && TOP_LEVEL_CANDIDATE_RE.test(name);
+}
+
+// scripts/qa/check-* candidates (any extension). No-op when scripts/qa/ absent.
+function collectQaCandidates(scriptsDir, candidates) {
+  const qaDir = join(scriptsDir, 'qa');
+  if (!existsSync(qaDir)) return;
+  for (const entry of readdirSync(qaDir, { withFileTypes: true })) {
+    if (entry.isFile() && /^check-/.test(entry.name)) {
+      candidates.add(`scripts/qa/${entry.name}`);
+    }
+  }
+}
+
+// Candidate guard scripts: scripts/check-*.{mjs,sh}, scripts/verify-*.sh,
+// (any extension) scripts/qa/check-*, and direct-child .claude/hooks/*.mjs
+// except dispatcher hooks.mjs and shared helper lib.mjs.
+function collectCandidates(dir) {
+  const scriptsDir = join(dir, 'scripts');
+  const hooksDir = join(dir, '.claude/hooks');
+  if (!existsSync(scriptsDir) && !existsSync(hooksDir)) return null;
+  const candidates = new Set();
+  if (existsSync(scriptsDir)) {
+    collectTopLevelCandidates(scriptsDir, candidates);
+    collectQaCandidates(scriptsDir, candidates);
+  }
+  if (existsSync(hooksDir)) collectHookCandidates(hooksDir, candidates);
+  return [...candidates].sort();
+}
+
+// scripts/check-*/verify-* direct-child candidates (except check-all.mjs and
+// this script's own filename). No-op when scripts/ absent.
+function collectTopLevelCandidates(scriptsDir, candidates) {
+  for (const entry of readdirSync(scriptsDir, { withFileTypes: true })) {
+    if (entry.isFile() && isTopLevelCandidate(entry.name)) {
+      candidates.add(`scripts/${entry.name}`);
+    }
+  }
+}
+
+// Direct-child .claude/hooks/*.mjs candidates, except the dispatcher hooks.mjs
+// and shared helper lib.mjs. No-op when .claude/hooks/ absent.
+function collectHookCandidates(hooksDir, candidates) {
+  for (const entry of readdirSync(hooksDir, { withFileTypes: true })) {
+    if (
+      entry.isFile() &&
+      entry.name.endsWith('.mjs') &&
+      entry.name !== 'hooks.mjs' &&
+      entry.name !== 'lib.mjs'
+    ) {
+      candidates.add(`.claude/hooks/${entry.name}`);
+    }
+  }
+}
+
+// A candidate is referenced iff its full repo-relative path appears as a
+// substring in any OTHER corpus file (relative-path matching per Q2 — avoids
+// same-basename-different-dir collisions; string-contains, not shell parsing,
+// per Q3 — this is a lint, not a shell interpreter).
+function isReferenced(candidateRel, corpus) {
+  for (const [rel, content] of corpus) {
+    if (rel === candidateRel) continue;
+    if (content.includes(candidateRel)) return true;
+  }
+  return false;
+}
+
+// Return .mjs handler basenames registered in the optional hooks.mjs
+// dispatcher table. Its only .mjs string literals are handler filenames.
+function handlersTableWiredNames(corpus) {
+  const source = corpus.get('.claude/hooks/hooks.mjs');
+  const names = new Set();
+  if (!source) return names;
+  for (const match of source.matchAll(/['"]([^'"]+\.mjs)['"]/g)) {
+    names.add(match[1]);
+  }
+  return names;
+}
+
+// Compute the transitive wired set for direct-child hook candidates. A hook is
+// initially wired by a full-path reference or by the hooks.mjs HANDLERS table;
+// relative hook-import relationships then propagate that wiring to closure.
+function computeWiredHookBasenames(corpus, hookCandidates) {
+  const names = new Set(hookCandidates.map((rel) => rel.slice('.claude/hooks/'.length)));
+  const wired = new Set();
+  const handlers = handlersTableWiredNames(corpus);
+  for (const name of names) {
+    if (isReferenced(`.claude/hooks/${name}`, corpus) || handlers.has(name)) wired.add(name);
+  }
+  propagateWiringToClosure(wired, collectHookImports(corpus, names));
+  return wired;
+}
+
+// Direct hook-to-hook relative imports (`.mjs`-only, same directory) keyed by
+// importer basename. Used by the closure pass below to propagate wiring.
+function collectHookImports(corpus, names) {
+  const imports = new Map();
+  for (const name of names) {
+    const imported = new Set();
+    const source = corpus.get(`.claude/hooks/${name}`) ?? '';
+    for (const match of source.matchAll(/from\s+['"]\.\/([^'"]+)['"]/g)) {
+      const importedName = match[1].endsWith('.mjs') ? match[1] : `${match[1]}.mjs`;
+      if (names.has(importedName)) imported.add(importedName);
+    }
+    imports.set(name, imported);
+  }
+  return imports;
+}
+
+// Wiring propagates to closure: an already-wired hook wires everything it
+// imports, transitively, until no new hooks are reached.
+function propagateWiringToClosure(wired, imports) {
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [importer, importedNames] of imports) {
+      for (const imported of importedNames) {
+        if (wired.has(importer) && !wired.has(imported)) {
+          wired.add(imported);
+          changed = true;
+        }
+      }
+    }
+  }
+}
+
+function schemaError(msg) {
+  process.stderr.write(`check-unwired-guards: SCHEMA ERROR — ${msg}\n`);
+  process.exit(2);
+}
+
+// Parse the allowlist JSON and return its "optional" array. Any malformed
+// shape calls schemaError(), which exits 2 and never returns.
+function parseAllowlistJson(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    // Inlined (not via schemaError()) so the FAIL-CLOSED audit's per-catch-body
+    // scan sees the surface+exit tokens directly in this block (INV-96).
+    process.stderr.write(
+      `check-unwired-guards: SCHEMA ERROR — ${ALLOWLIST_REL} is not valid JSON: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(2);
+  }
+  if (!Array.isArray(parsed?.optional)) {
+    schemaError(`${ALLOWLIST_REL} must have an "optional" array`);
+  }
+  return parsed.optional;
+}
+
+// A valid entry has a non-empty "path" and a non-empty "rationale"; otherwise
+// schemaError() exits 2 and never returns.
+function validateAllowlistEntry(entry) {
+  if (typeof entry?.path !== 'string' || entry.path.length === 0) {
+    schemaError(`${ALLOWLIST_REL} entry missing a "path" string`);
+  }
+  if (typeof entry.rationale !== 'string' || entry.rationale.trim().length === 0) {
+    schemaError(`${ALLOWLIST_REL} entry "${entry.path}" has an empty/missing rationale`);
+  }
+}
+
+// Load the allowlist. Absent file => empty map (no error).
+function loadAllowlist(dir) {
+  const path = join(dir, ALLOWLIST_REL);
+  if (!existsSync(path)) return new Map();
+  const entries = parseAllowlistJson(readFileSync(path, 'utf8'));
+  const result = new Map();
+  for (const entry of entries) {
+    validateAllowlistEntry(entry);
+    result.set(entry.path, entry.rationale);
+  }
+  return result;
+}
+
+function main() {
+  const dir = process.cwd();
+  const allowlist = loadAllowlist(dir);
+  const candidates = collectCandidates(dir);
+  if (candidates === null) {
+    process.stdout.write('check-unwired-guards: SKIP — no scripts/ or .claude/hooks/ directory\n');
+    process.exit(0);
+  }
+  const corpus = buildCorpus(dir);
+  const hookCandidates = candidates.filter((rel) => rel.startsWith('.claude/hooks/'));
+  const wiredHookBasenames = computeWiredHookBasenames(corpus, hookCandidates);
+  const problems = [];
+  for (const rel of candidates) {
+    const isHook = rel.startsWith('.claude/hooks/');
+    if (isHook ? wiredHookBasenames.has(rel.slice('.claude/hooks/'.length)) : isReferenced(rel, corpus)) {
+      continue;
+    }
+    const rationale = allowlist.get(rel);
+    if (rationale) {
+      process.stdout.write(`[ALLOWLISTED] ${rel} — ${rationale}\n`);
+      continue;
+    }
+    problems.push(rel);
+  }
+  if (problems.length > 0) {
+    process.stdout.write(
+      `check-unwired-guards: FAIL — ${problems.length} unreferenced guard script(s) ` +
+        '(searched scripts/check-all.mjs, run.sh, scripts/**, .claude/hooks/**, ' +
+        '.claude/settings.json, .codex/config.toml, Makefile, .githooks/*, package.json, ' +
+        '.claude/commands/*.md, .github/workflows/*.yml):\n',
+    );
+    for (const p of problems) process.stdout.write(`  - ${p}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(
+    'check-unwired-guards: OK — every guard script is referenced or allowlisted\n',
+  );
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  process.stderr.write(
+    `check-unwired-guards: ERROR — ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(2);
+}