@getarbiter/cli 0.5.0

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

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// <%= projectName %> — action SHA-pin gate (INV-76)
+// Gate: verify all GitHub Actions references in .github/ are SHA-pinned.
+// L1: tag references generate warnings but do not fail.
+// L2/L3: any tag reference is a hard failure.
+// Part of the anti-drift validator family (W6).
+// Usage: node scripts/check-action-pins.mjs [--help]
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write('Usage: node scripts/check-action-pins.mjs [--help]\nVerify all GitHub Actions references in .github/ are SHA-pinned.\n');
+  process.exit(0);
+}
+<%
+const _level = governanceLevel;
+%>
+const LEVEL = '<%= _level %>';
+const CWD = process.cwd();
+
+function collectYamlFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    // Skip symlinks to avoid traversal outside the workflows tree.
+    if (entry.isSymbolicLink()) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectYamlFiles(full));
+    } else if (entry.isFile() && (entry.name.endsWith('.yml') || entry.name.endsWith('.yaml'))) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const yamlFiles = [
+  ...collectYamlFiles(join(CWD, '.github', 'workflows')),
+  ...collectYamlFiles(join(CWD, '.github', 'actions')),
+];
+
+// SHA-pinned: exactly 40 hex characters after @
+// Tag-pinned / branch-pinned: anything else (v4, main, latest, etc.)
+const SHA_PATTERN = /^[0-9a-f]{40}$/i;
+// Matches both YAML sequence members ('- uses: foo/bar@ref') and direct keys ('uses: foo/bar@ref').
+// Captures action path (group 1) and ref (group 2). Quoted refs are unwrapped post-match.
+const USES_PATTERN = /^\s+(?:-\s+)?uses:\s+["']?([^@\s"']+)@([^\s#"']+)["']?/gm;
+// Comment-truthfulness scan (#1666, mirrored from the self gate / #1614): a single immutable sha
+// resolves to exactly ONE upstream release, so two pins of the SAME sha must not advertise
+// DIFFERENT MAJOR versions. Captures action (1), 40-hex sha (2), and the `# vN…` label (3).
+// `# v6` vs `# v6.0.3` is precision (same major), tolerated; `# v9` vs `# v7` for one sha lies.
+const USES_WITH_COMMENT = /^\s+(?:-\s+)?uses:\s+["']?([^@\s"']+)@([0-9a-fA-F]{40})["']?\s*#\s*(v\d+\S*)/gm;
+const majorOf = (versionLabel) => {
+  const m = /^v(\d+)/.exec(versionLabel);
+  return m ? m[1] : null;
+};
+
+// Divergent-SHA scan (#1666, mirrored from the self gate). Captures action (1), 40-hex sha (2),
+// and the OPTIONAL trailing comment (3). One immutable sha is ONE release: pinning an action to
+// >1 distinct sha WITHIN one MAJOR is a dup-sha bug; a split ACROSS majors is allowed only when
+// declared in CROSS_MAJOR_ALLOWLIST (the splits arbiter's own generated workflows legitimately ship).
+const USES_WITH_OPTIONAL_COMMENT = /^\s+(?:-\s+)?uses:\s+["']?([^@\s"']+)@([0-9a-fA-F]{40})["']?\s*(?:#\s*([^\n]+?))?\s*$/gm;
+// `action -> { effectiveMajor -> exact 40-hex sha }`. For 0ver actions the effective major is
+// `0.<minor>` (semver-0 treats the minor as the breaking axis). Within-major dups are never
+// allowlistable; only an intentional cross-major split belongs here.
+const CROSS_MAJOR_ALLOWLIST = {
+  'actions/download-artifact': { 4: 'd3f86a106a0bac45b974a628896c90dbdf5c8093', 8: '3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c' },
+  'actions/github-script': { 7: 'f28e40c7f34bde8b3046d885e986cb6290c5673b', 9: '3a2844b7e9c422d3c10d287c895573f7108da1b3' },
+  'actions/setup-node': { 4: '39370e3970a6d050c480ffad4ff0ed4d3fdee5af', 7: '820762786026740c76f36085b0efc47a31fe5020' },
+  'actions/upload-artifact': { 4: 'ea165f8d65b6e75b540449e92b4886f43607fa02', 7: '043fb46d1a93c77aae656e7c1c64a875d1fc6a0a' },
+  'gradle/actions/setup-gradle': { 3: 'd9c87d481d55275bb5441eef3fe0e46805f9ef70', 4: 'ed408507eac070d1f99cc633dbcf757c94c7933a', 6: '9c971963bec38e04b3d30dcc455b5382be2fdbfb' },
+  'anchore/sbom-action': { '0.9': 'f6c3d0fe42c3cf876e3462574e4c9416b5e0f07a', '0.24': 'e22c389904149dbc22b58101806040fa8d37a610' },
+};
+const effectiveMajor = (label) => {
+  const m = /^v(\d+)(?:\.(\d+))?/.exec(label);
+  if (!m) return null;
+  if (m[1] === '0') return m[2] !== undefined ? `0.${m[2]}` : '0';
+  return m[1];
+};
+// Bucket per-SHA (not per-occurrence) so the same sha seen with and without a comment is one bucket.
+const bucketOfSha = (labels) => {
+  for (const l of labels) {
+    const major = effectiveMajor(l);
+    if (major !== null) return major;
+  }
+  for (const l of labels) return `ref:${l.replace(/^branch:/, '')}`;
+  return 'unlabeled';
+};
+
+function stripQuotes(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+const violations = [];
+// action@sha -> Map<versionLabel, Set<file>>; populated across the whole scanned set so a
+// contradiction split across two workflow files is still caught.
+const shaComments = new Map();
+// action -> Map<sha, Set<label>>; tracks every distinct sha pinned for an action (#1666).
+const actionPins = new Map();
+for (const file of yamlFiles) {
+  const content = readFileSync(file, 'utf-8');
+  for (const match of content.matchAll(USES_PATTERN)) {
+    const action = stripQuotes(match[1]);
+    const ref = stripQuotes(match[2]);
+    if (action.startsWith('.')) continue;   // local composite actions
+    if (action.startsWith('docker://')) continue;
+    if (!SHA_PATTERN.test(ref)) {
+      violations.push({ file: file.replace(CWD + '/', ''), action, ref });
+    }
+  }
+  for (const match of content.matchAll(USES_WITH_COMMENT)) {
+    const action = match[1];
+    if (action.startsWith('.') || action.startsWith('docker://')) continue;
+    const key = `${action}@${match[2]}`;
+    const versionLabel = match[3];
+    if (!shaComments.has(key)) shaComments.set(key, new Map());
+    const labels = shaComments.get(key);
+    if (!labels.has(versionLabel)) labels.set(versionLabel, new Set());
+    labels.get(versionLabel).add(file.replace(CWD + '/', ''));
+  }
+  for (const match of content.matchAll(USES_WITH_OPTIONAL_COMMENT)) {
+    const action = match[1];
+    if (action.startsWith('.') || action.startsWith('docker://')) continue;
+    const sha = match[2].toLowerCase();
+    const lbl = (match[3] ?? '').trim();
+    if (!actionPins.has(action)) actionPins.set(action, new Map());
+    const shaMap = actionPins.get(action);
+    if (!shaMap.has(sha)) shaMap.set(sha, new Set());
+    if (lbl) shaMap.get(sha).add(lbl);
+  }
+}
+
+// A sha whose pins disagree on the MAJOR version is mislabelled — exactly one label is false.
+// Differing patch/minor precision on a shared major is not a contradiction.
+const commentViolations = [];
+for (const [key, labels] of shaComments) {
+  const majors = new Set([...labels.keys()].map(majorOf).filter((v) => v !== null));
+  if (majors.size > 1) commentViolations.push({ key, labels });
+}
+
+// #1666 — divergent-sha: bucket each action's distinct shas by effective major.
+//   RULE A: >1 sha WITHIN one major = dup-sha bug, NON-allowlistable.
+//   RULE B: a split ACROSS majors is allowed only when declared (exact sha) in CROSS_MAJOR_ALLOWLIST.
+const divergentSameMajor = [];
+const undeclaredCrossMajor = [];
+for (const [action, shaMap] of actionPins) {
+  const buckets = new Map();
+  for (const [sha, labels] of shaMap) {
+    const bucket = bucketOfSha(labels);
+    if (!buckets.has(bucket)) buckets.set(bucket, new Set());
+    buckets.get(bucket).add(sha);
+  }
+  for (const [bucket, shas] of buckets) {
+    if (shas.size > 1) divergentSameMajor.push({ action, bucket, shas: [...shas] });
+  }
+  if (buckets.size > 1) {
+    const allow = CROSS_MAJOR_ALLOWLIST[action];
+    for (const [bucket, shas] of buckets) {
+      if (shas.size !== 1) continue;
+      const [sha] = [...shas];
+      if (!allow || allow[bucket] !== sha) {
+        undeclaredCrossMajor.push({ action, bucket, sha, declared: allow ? allow[bucket] : null });
+      }
+    }
+  }
+}
+
+if (
+  violations.length === 0 &&
+  commentViolations.length === 0 &&
+  divergentSameMajor.length === 0 &&
+  undeclaredCrossMajor.length === 0
+) {
+  console.log('  check-action-pins: all action references are SHA-pinned with truthful version comments');
+  process.exit(0);
+}
+
+const label = LEVEL === 'L1' ? 'WARN' : 'FAIL';
+if (violations.length > 0) {
+  console.log(`  check-action-pins: ${violations.length} non-SHA action reference(s) [${label}]:`);
+  for (const v of violations) {
+    console.log(`    ${v.file}: ${v.action}@${v.ref}`);
+  }
+}
+if (commentViolations.length > 0) {
+  console.log(`  check-action-pins: ${commentViolations.length} action SHA(s) with contradictory version comments [${label}] — a sha maps to ONE release:`);
+  for (const v of commentViolations) {
+    const detail = [...v.labels.entries()]
+      .map(([versionLabel, files]) => `# ${versionLabel} (${[...files].join(', ')})`)
+      .join(' vs ');
+    console.log(`    ${v.key}: ${detail}`);
+  }
+}
+if (divergentSameMajor.length > 0) {
+  console.log(`  check-action-pins: ${divergentSameMajor.length} action(s) with divergent SHAs within one major [${label}] — unify to a single sha:`);
+  for (const v of divergentSameMajor) {
+    console.log(`    ${v.action} (major ${v.bucket}): ${v.shas.join(' vs ')}`);
+  }
+}
+if (undeclaredCrossMajor.length > 0) {
+  console.log(`  check-action-pins: ${undeclaredCrossMajor.length} undeclared cross-major action pin(s) [${label}] — add to CROSS_MAJOR_ALLOWLIST or unify:`);
+  for (const v of undeclaredCrossMajor) {
+    console.log(`    ${v.action}@${v.sha} (major ${v.bucket}) — ${v.declared ? `declared ${v.declared}` : 'not in allowlist'}`);
+  }
+}
+
+if (LEVEL === 'L1') {
+  console.log('  check-action-pins: violations are warnings at L1 — fix before upgrading to L2/L3');
+  process.exit(0);
+}
+
+process.exit(1);

package/dist/templates/scripts/check-agent-return.mjs.ejs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: E1 (#1943, M8 core + M12 citation) — agent-return envelope gate. Validates every
+// CATALOG: envelope file under .arbiter/evidence/agent-returns/** against schemas/agent-return.schema.json,
+// CATALOG: enforces the M12 rule (a structural finding without a resolvable file:line citation is
+// CATALOG: rejected at the tool layer), and under --enforce cross-checks the dispatch sidecar
+// CATALOG: (.arbiter/agents-dispatched.json) so dispatched agents whose returns evaporated into
+// CATALOG: the context window (the R1 signature) cannot pass silently.
+// CATALOG: Rejected fold-in into check-evidence-bundle.mjs: that validates the per-task TDD
+// CATALOG: evidence-bundle shape (gateResult/redTest/greenTest), a different envelope with its own
+// CATALOG: schema and lifecycle; the agent-return envelope carries verdict/findings/citations and
+// CATALOG: a citation-resolution step that has no analog in the bundle validator. Different shape,
+// CATALOG: different failure surface — merging would conflate two drift models (CANON-21).
+//
+//INV-138 (advisory at land-time per design §0; promoted on owner ratification).
+// Exit codes (INV-53): 0 PASS, 1 FAIL (envelope violations / evaporated returns), 2 ERROR (self).
+//
+// Usage:
+//   node scripts/check-agent-return.mjs [--evidence-dir=<path>] [--schema=<path>]
+//                                       [--repo-root=<path>] [--sidecar=<path>] [--enforce]
+// Vacuous pass when no envelopes exist (nothing to validate). --enforce promotes the dispatch
+// cross-check from advisory to hard.
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateSchema, enforceCitations, loadSchema } from './lib/agent-return-validate.mjs'
+import { arg } from './lib/gate-args.mjs'
+import { isForeignSidecar } from './lib/evidence-binding.mjs'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const repoDefault = resolve(__dirname, '..')
+
+const argv = process.argv.slice(2)
+const EVIDENCE_DIR = arg('evidence-dir', argv)
+  ? resolve(arg('evidence-dir', argv))
+  : join(repoDefault, '.arbiter', 'evidence', 'agent-returns')
+const SCHEMA_PATH = arg('schema', argv)
+  ? resolve(arg('schema', argv))
+  : join(repoDefault, 'schemas', 'agent-return.schema.json')
+const REPO_ROOT = arg('repo-root', argv) ? resolve(arg('repo-root', argv)) : repoDefault
+const SIDECAR = arg('sidecar', argv)
+  ? resolve(arg('sidecar', argv))
+  : join(repoDefault, '.arbiter', 'agents-dispatched.json')
+const ENFORCE = argv.includes('--enforce')
+const NON_ENVELOPE_MARKER = 'refutation-required.json'
+
+/**
+ * Task the cross-check below belongs to: `--task` when given, else the task state on disk.
+ * FAIL-OPEN-INTENT: `undefined` ("unknown task") is the STRICT side — nothing can be proven
+ * foreign, so the R1 cross-check runs exactly as it did before #2399. Only a sidecar that
+ * PROVABLY belongs to another task is skipped.
+ */
+function activeTaskId() {
+  if (arg('task', argv)) return arg('task', argv)
+  try {
+    const parsed = JSON.parse(readFileSync(join(REPO_ROOT, '.claude', '.task', 'status.json'), 'utf-8'))
+    return typeof parsed?.taskId === 'string' ? parsed.taskId : undefined
+    // FAIL-OPEN-INTENT: an unreadable task document means "unknown task" - the STRICT side, since nothing can then be proven foreign and every R1 cross-check below still runs.
+  } catch {
+    return undefined
+  }
+}
+
+function main() {
+  if (!existsSync(EVIDENCE_DIR)) {
+    process.stdout.write('[check-agent-return] OK — evidence dir not found, vacuous pass\n')
+    return 0
+  }
+  let schema
+  try {
+    schema = loadSchema(SCHEMA_PATH)
+  } catch (err) {
+    process.stderr.write(
+      `[check-agent-return] ERROR: cannot load schema: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return 2
+  }
+
+  /** @type {string[]} */
+  const envelopeFiles = []
+  try {
+    const walk = (dir) => {
+      for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry)
+        const st = statSync(full)
+        if (st.isDirectory()) walk(full)
+        else if (entry.endsWith('.json') && entry !== NON_ENVELOPE_MARKER) envelopeFiles.push(full)
+      }
+    }
+    walk(EVIDENCE_DIR)
+  } catch (err) {
+    process.stderr.write(
+      `[check-agent-return] ERROR: cannot walk evidence dir: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return 2
+  }
+
+  let violations = 0
+  let checked = 0
+  for (const file of envelopeFiles) {
+    checked++
+    /** @type {unknown} */
+    let parsed
+    try {
+      parsed = JSON.parse(readFileSync(file, 'utf-8'))
+    } catch (err) {
+      process.stdout.write(
+        `[check-agent-return] FAIL: invalid JSON in ${file}: ${err instanceof Error ? err.message : String(err)}\n`,
+      )
+      violations++
+      continue
+    }
+    const schemaErrors = validateSchema(parsed, schema, schema, file)
+    for (const e of schemaErrors) process.stdout.write(`[check-agent-return] FAIL: ${e}\n`)
+    if (schemaErrors.length > 0) {
+      violations++
+      continue
+    }
+    const citationErrors = enforceCitations(
+      /** @type {Record<string, unknown>} */ (parsed),
+      REPO_ROOT,
+      file,
+    )
+    for (const e of citationErrors) process.stdout.write(`[check-agent-return] FAIL: ${e}\n`)
+    if (citationErrors.length > 0) violations++
+  }
+
+  // Dispatch cross-check (--enforce): sidecar records dispatched agents for the branch;
+  // zero envelopes for a task that dispatched >0 ⇒ the R1 signature (returns evaporated).
+  if (ENFORCE && existsSync(SIDECAR)) {
+    try {
+      const sidecar = JSON.parse(readFileSync(SIDECAR, 'utf-8'))
+      // #2399: the tracked sidecar is shared by every branch — one recorded for another
+      // task says nothing about THIS task's returns, so it counts as absent (an unknown
+      // active task proves nothing and keeps the cross-check armed).
+      const foreign = isForeignSidecar(sidecar, activeTaskId())
+      if (foreign) {
+        process.stdout.write(
+          `[check-agent-return] dispatch sidecar belongs to task ${sidecar.taskId ?? sidecar.task} — ignored for this task\n`,
+        )
+      }
+      const count =
+        typeof sidecar === 'object' && sidecar && typeof sidecar['count'] === 'number'
+          ? sidecar['count']
+          : 0
+      if (!foreign && count > 0 && checked === 0) {
+        process.stdout.write(
+          `[check-agent-return] FAIL: sidecar records ${count} dispatched agent(s) but zero return envelopes exist — findings evaporated into the context window (R1)\n`,
+        )
+        violations++
+      }
+    } catch (err) {
+      process.stderr.write(
+        `[check-agent-return] ERROR: cannot read sidecar ${SIDECAR}: ${err instanceof Error ? err.message : String(err)}\n`,
+      )
+      return 2
+    }
+  }
+
+  if (violations > 0) {
+    process.stdout.write(
+      `[check-agent-return] FAIL: ${violations} envelope(s) failed (${checked} checked)\n`,
+    )
+    return 1
+  }
+  process.stdout.write(`[check-agent-return] OK — ${checked} agent-return envelope(s) passed\n`)
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (err) {
+  process.stderr.write(
+    `[check-agent-return] ERROR: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(2)
+}