@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-local-ci-parity.mjs.ejs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// check-local-ci-parity.mjs — local <-> CI gate parity check (INV-59, #1977).
+// Generated by arbiter for collaborationMode='trunk-solo': trunk-solo means
+// 'no PR ceremony, FULL gate locally, CI as verification mirror' — that promise
+// only holds if `run.sh gate full` and CI actually agree. Without a PR there is
+// no independent net before trunk, so this check is wired at L2 in check-all.mjs.
+//
+// 1. Static check: parses Makefile .PHONY targets and .github/workflows/ job
+//    names, compares the set. Skip-neutral when either source is absent.
+// 2. Runtime check: reads .arbiter/gate/local-result.json and the latest CI
+//    gate-result artifact (via `gh run download`), compares parityContentHash.
+//    Skip-neutral when `gh` is unavailable or no matching CI run exists.
+//
+// Exit codes:
+//   0 — parity confirmed, or neutral skip (no CI artifact / gh unavailable)
+//   1 — drift detected (static or runtime)
+//   2 — invocation error (parse failure, bad artifact schema)
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { spawnSync } from 'node:child_process'
+
+const ROOT = process.cwd()
+
+// Targets expected to be local-only (no CI job counterpart required) — mirrors
+// the Makefile emitted by arbiter's local-wrapper generator (INV-87).
+const STATIC_PARITY_EXCLUDE = new Set([
+  'help',
+  'clean',
+  'evidence',
+  'simulate-nightly',
+  'simulate-weekly',
+  'check',
+  'full',
+  'ci',
+])
+
+function checkStaticParity(root) {
+  const makefilePath = join(root, 'Makefile')
+  if (!existsSync(makefilePath)) {
+    process.stdout.write('[skip] static parity: Makefile absent\n')
+    return 0
+  }
+  const wfDir = join(root, '.github', 'workflows')
+  if (!existsSync(wfDir)) {
+    process.stdout.write('[skip] static parity: .github/workflows absent\n')
+    return 0
+  }
+  let wfFiles
+  try {
+    wfFiles = readdirSync(wfDir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+  } catch (err) {
+    if (err.code === 'ENOENT') return 0
+    process.stderr.write(`check-local-ci-parity: ERROR — cannot read .github/workflows: ${err.message}\n`)
+    return 2
+  }
+  if (wfFiles.length === 0) {
+    process.stdout.write('[skip] static parity: no workflow files found\n')
+    return 0
+  }
+  const makeContent = readFileSync(makefilePath, 'utf-8')
+  const phonyMatch = makeContent.match(/^\.PHONY:\s*(.+)$/m)
+  if (!phonyMatch) {
+    process.stdout.write('[skip] static parity: Makefile has no .PHONY declaration\n')
+    return 0
+  }
+  const makeTargets = new Set(
+    phonyMatch[1].trim().split(/\s+/).filter((t) => !STATIC_PARITY_EXCLUDE.has(t)),
+  )
+  const wfJobs = new Set()
+  for (const wfFile of wfFiles) {
+    const content = readFileSync(join(wfDir, wfFile), 'utf-8')
+    const lines = content.split('\n')
+    let inJobs = false
+    for (const line of lines) {
+      if (line === 'jobs:') {
+        inJobs = true
+        continue
+      }
+      if (inJobs && /^\S/.test(line) && line !== '') {
+        inJobs = false
+        continue
+      }
+      if (inJobs) {
+        const m = line.match(/^  ([\w][\w-]*):/)
+        if (m) wfJobs.add(m[1])
+      }
+    }
+  }
+  const makeOnly = [...makeTargets].filter((t) => !wfJobs.has(t))
+  if (makeOnly.length > 0) {
+    process.stderr.write('check-local-ci-parity: FAIL — static Makefile <-> workflow drift\n')
+    process.stderr.write('  Makefile targets not in any workflow job:\n')
+    for (const t of makeOnly.sort()) process.stderr.write(`    ${t}\n`)
+    process.stderr.write('  Fix: add matching jobs to .github/workflows/, or extend STATIC_PARITY_EXCLUDE.\n')
+    return 1
+  }
+  process.stdout.write('check-local-ci-parity: static parity OK\n')
+  return 0
+}
+
+// ─── ci-required <-> local-twin parity (#2435, AC-6) ─────────────────────────
+//
+// "Reproduce the failed gate locally before push" is a floor invariant at every autonomy
+// level (docs/REFERENCE/fix-on-red.md). `ci-required` is the sole required check, so a job
+// it depends on with no local counterpart makes that floor unsatisfiable: when it goes red,
+// the mandated reproduce step does not exist. Every needed job must resolve to a Makefile
+// .PHONY target of the same name, an explicit local command in REQUIRED_JOB_LOCAL_TWIN, or a
+// CI_ONLY_REQUIRED_JOBS declaration — the ONE place a job is exempted from the floor, with
+// the reason it cannot have a twin. The two tables are a SUPERSET of what the workflow
+// generator can emit (the `needs:` list varies with language and governance level), so an
+// entry with no matching job is expected here and is not an error.
+
+/** Jobs that cannot have a local twin, and why. The single exemption list. */
+const CI_ONLY_REQUIRED_JOBS = new Map([
+  ['dependency-review', 'GitHub dependency-review-action — it diffs the pull request base and head dependency graphs through the GitHub API, so there is nothing to run against a local checkout.'],
+  ['iac-scan', 'Checkov and tflint over the IaC tree — third-party binaries the scaffold neither vendors nor installs, so no gate id or Makefile target can honestly stand in for them.'],
+  ['sonar-scan', 'SonarCloud server-side analysis — the verdict is computed by the hosted service against a project token, not by anything runnable in the checkout.'],
+  ['docs-check', 'Compares the pull_request event base and head SHAs to require a docs change beside a code change — a property of the PR diff, not of the working tree.'],
+  ['classify-changes', 'Classifies the pull_request diff to drive docs-only job skipping — it consumes the GitHub event payload and has no working-tree meaning.'],
+  ['cross-stack-guard', 'Aggregates the per-lane results of the multi-stack matrix — it reads other jobs\' outcomes, which exist only inside a workflow run.'],
+  ['human-approval-required', 'A GitHub deployment-environment approval — a human decision recorded by the platform, not a check any command can compute.'],
+])
+
+/** Jobs whose local twin is a command rather than a same-named Makefile target. */
+const REQUIRED_JOB_LOCAL_TWIN = new Map([
+  ['gate-full', 'node scripts/check-all.mjs L2'],
+  ['debt-gates', 'node scripts/check-all.mjs L2'],
+  ['security-early-fail', 'node scripts/check-all.mjs L1'],
+  ['unit-tests', 'node scripts/check-all.mjs L1'],
+  ['contract-verify', 'node scripts/check-all.mjs L2'],
+  ['archunit-tests', 'node scripts/check-all.mjs L2'],
+  ['build-reactor', 'node scripts/check-all.mjs L1'],
+  ['generated-gate-min', 'node scripts/check-all.mjs L2'],
+])
+
+/** `.PHONY` targets declared by the Makefile, or an empty set when there is none. */
+function makefilePhonyTargets(root) {
+  const makefilePath = join(root, 'Makefile')
+  if (!existsSync(makefilePath)) return new Set()
+  const phonyMatch = readFileSync(makefilePath, 'utf-8').match(/^\.PHONY:\s*(.+)$/m)
+  if (!phonyMatch) return new Set()
+  return new Set(phonyMatch[1].trim().split(/\s+/))
+}
+
+/** `[a, b, c]` -> the trimmed, non-empty entries. */
+function parseInlineList(body) {
+  return new Set(body.split(',').map((s) => s.trim()).filter((s) => s.length > 0))
+}
+
+/** The consecutive `- item` lines starting at `from`. */
+function parseYamlListItems(lines, from) {
+  const items = new Set()
+  for (let j = from; j < lines.length; j += 1) {
+    const item = lines[j].match(/^\s*-\s*(\S+)\s*$/)
+    if (!item) break
+    items.add(item[1])
+  }
+  return items
+}
+
+/** The `needs:` of the `ci-required` job in ONE workflow file, or null when it has none. */
+function ciRequiredNeedsIn(lines) {
+  const start = lines.findIndex((l) => /^ {2}ci-required:\s*$/.test(l))
+  if (start === -1) return null
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^ {2}\S/.test(lines[i])) return null
+    const inline = lines[i].match(/^\s*needs:\s*\[(.*)\]\s*$/)
+    if (inline) return parseInlineList(inline[1])
+    if (/^\s*needs:\s*$/.test(lines[i])) return parseYamlListItems(lines, i + 1)
+  }
+  return null
+}
+
+/**
+ * The job ids `ci-required` lists under `needs:`, across every workflow file.
+ * Returns null (neutral — caller skips) when no `ci-required` job is declared.
+ */
+// Distinct from null on purpose (INV-96, #2418): null means "no `ci-required` job is
+// declared", a legitimate skip; this means "could not look". Collapsing the two let an
+// unreadable workflows directory report the same neutral result as a repository that
+// genuinely declares no required job — uncertainty must BLOCK, never SKIP.
+const NEEDS_UNREADABLE = Symbol('ci-required-needs-unreadable')
+
+function readCiRequiredNeeds(root) {
+  const wfDir = join(root, '.github', 'workflows')
+  if (!existsSync(wfDir)) return null
+  let wfFiles
+  try {
+    wfFiles = readdirSync(wfDir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+  } catch (err) {
+    // ENOENT: the directory existed a moment ago and is gone now — the same benign case
+    // the existsSync above covers. Anything else is a real IO failure and is surfaced.
+    if (err.code === 'ENOENT') return null
+    process.stderr.write(
+      `check-local-ci-parity: ERROR — cannot read .github/workflows: ${err.message}\n`,
+    )
+    return NEEDS_UNREADABLE
+  }
+  for (const wfFile of wfFiles) {
+    const needs = ciRequiredNeedsIn(readFileSync(join(wfDir, wfFile), 'utf-8').split('\n'))
+    if (needs !== null) return needs
+  }
+  return null
+}
+
+function checkRequiredJobLocalTwins(root) {
+  const needs = readCiRequiredNeeds(root)
+  if (needs === NEEDS_UNREADABLE) return 2
+  if (needs === null) {
+    process.stdout.write('[skip] ci-required twins: no `ci-required` job declared\n')
+    return 0
+  }
+  const makeTargets = makefilePhonyTargets(root)
+  const unreproducible = [...needs].filter(
+    (job) =>
+      !makeTargets.has(job) && !REQUIRED_JOB_LOCAL_TWIN.has(job) && !CI_ONLY_REQUIRED_JOBS.has(job),
+  )
+  if (unreproducible.length === 0) {
+    process.stdout.write(`check-local-ci-parity: ci-required local-twin parity OK (${needs.size} required job(s))\n`)
+    return 0
+  }
+  process.stderr.write('check-local-ci-parity: FAIL — ci-required local-twin drift\n')
+  process.stderr.write('  Required CI jobs with no local counterpart:\n')
+  for (const job of unreproducible.sort()) process.stderr.write(`    ${job}\n`)
+  process.stderr.write('  Fix: add a Makefile target of that name, add the local command to REQUIRED_JOB_LOCAL_TWIN, or declare it in CI_ONLY_REQUIRED_JOBS with the reason no local twin can exist.\n')
+  return 1
+}
+
+if (process.env.PARITY_REQUIRED_JOBS_ONLY === '1') {
+  process.exit(checkRequiredJobLocalTwins(ROOT))
+}
+
+const staticCode = checkStaticParity(ROOT)
+if (staticCode !== 0) process.exit(staticCode)
+
+const requiredJobsCode = checkRequiredJobLocalTwins(ROOT)
+if (requiredJobsCode !== 0) process.exit(requiredJobsCode)
+
+// ─── Runtime hash-parity check ───────────────────────────────────────────────
+const LOCAL_RESULT_PATH = join(ROOT, '.arbiter', 'gate', 'local-result.json')
+
+function skip(reason) {
+  process.stdout.write(`check-local-ci-parity: ${reason}\n`)
+  process.stdout.write('check-local-ci-parity: SKIP (neutral)\n')
+  // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+  process.stdout.write(`[SKIP] ${reason}\n`)
+  process.exit(0)
+}
+
+if (!existsSync(LOCAL_RESULT_PATH)) {
+  skip('no local gate result — run `node scripts/check-all.mjs L2` first')
+}
+
+let localResult
+try {
+  localResult = JSON.parse(readFileSync(LOCAL_RESULT_PATH, 'utf-8'))
+} catch (err) {
+  process.stderr.write(`check-local-ci-parity: cannot parse ${LOCAL_RESULT_PATH}: ${err.message}\n`)
+  process.exit(2)
+}
+
+if (localResult.schema !== 'arbiter-gate-v1') {
+  process.stderr.write(`check-local-ci-parity: unexpected schema '${localResult.schema}' — re-run check-all.mjs\n`)
+  process.exit(2)
+}
+
+const ghCheck = spawnSync('gh', ['--version'], { encoding: 'utf-8', shell: false })
+if (ghCheck.error || ghCheck.status !== 0) skip('gh CLI not available — skipping CI artifact fetch')
+
+const branchOut = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf-8', shell: false })
+if (branchOut.error || branchOut.status !== 0) skip('could not determine current branch')
+const branch = branchOut.stdout.trim()
+
+const runsOut = spawnSync(
+  'gh',
+  ['run', 'list', '--branch', branch, '--status', 'completed', '--limit', '1', '--json', 'databaseId,headSha'],
+  { encoding: 'utf-8', shell: false },
+)
+let runs
+try {
+  runs = JSON.parse(runsOut.stdout ?? '[]')
+} catch {
+  runs = []
+}
+if (runsOut.status !== 0 || !Array.isArray(runs) || runs.length === 0) {
+  skip('no completed CI run found for this branch')
+}
+const latestRunId = String(runs[0].databaseId)
+const ciHeadSha = runs[0].headSha
+
+const localHeadOut = spawnSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf-8', shell: false })
+const localHeadSha = (localHeadOut.stdout ?? '').trim()
+if (localHeadOut.status === 0 && localHeadSha && ciHeadSha && ciHeadSha !== localHeadSha) {
+  skip(
+    `latest completed CI run is for commit ${ciHeadSha.slice(0, 12)}, but local HEAD is ` +
+      `${localHeadSha.slice(0, 12)} — not yet verified by CI (push and re-check after CI completes)`,
+  )
+}
+
+const tmpDir = mkdtempSync(join(tmpdir(), 'arbiter-parity-'))
+
+function cleanupAndSkip(reason) {
+  try {
+    rmSync(tmpDir, { recursive: true, force: true })
+  } catch {
+    // ignore cleanup errors
+  }
+  skip(reason)
+}
+
+const dlResult = spawnSync('gh', ['run', 'download', latestRunId, '--name', 'gate-result', '--dir', tmpDir], {
+  encoding: 'utf-8',
+  shell: false,
+})
+if (dlResult.status !== 0) cleanupAndSkip('gate-result artifact not found in CI run')
+
+const ciResultPath = join(tmpDir, 'gate-result.json')
+if (!existsSync(ciResultPath)) cleanupAndSkip('gate-result.json not in downloaded artifact')
+
+let ciResult
+try {
+  ciResult = JSON.parse(readFileSync(ciResultPath, 'utf-8'))
+} catch (err) {
+  try {
+    rmSync(tmpDir, { recursive: true, force: true })
+  } catch {
+    // ignore
+  }
+  process.stderr.write(`check-local-ci-parity: cannot parse CI gate result: ${err.message}\n`)
+  process.exit(2)
+}
+
+try {
+  rmSync(tmpDir, { recursive: true, force: true })
+} catch {
+  // ignore cleanup errors
+}
+
+if (!localResult.parityContentHash || !ciResult.parityContentHash) {
+  skip('gate result missing parityContentHash — regenerate with check-all.mjs L2')
+}
+
+if (localResult.parityContentHash === ciResult.parityContentHash) {
+  process.stdout.write(`check-local-ci-parity: OK (hash ${localResult.parityContentHash.slice(0, 12)}...)\n`)
+  process.exit(0)
+}
+
+// Hashes differ. A gate present on only ONE side is a gate-SET change (e.g. a
+// newly added check the CI artifact predates), not a result drift — only a gate
+// present on both sides with a DIFFERENT pass value blocks the push (#1602).
+const localMap = new Map((localResult.parityGates ?? []).map((g) => [g.name, g.pass]))
+const ciMap = new Map((ciResult.parityGates ?? []).map((g) => [g.name, g.pass]))
+const allNames = new Set([...localMap.keys(), ...ciMap.keys()])
+const diffs = []
+for (const name of [...allNames].sort()) {
+  const lv = localMap.get(name)
+  const cv = ciMap.get(name)
+  if (lv !== cv) diffs.push({ name, local: lv, ci: cv })
+}
+
+const fmt = (v) => (v === undefined ? 'absent' : v ? 'PASS' : 'FAIL')
+const realDrifts = diffs.filter((d) => d.local !== undefined && d.ci !== undefined)
+const staleOnly = diffs.filter((d) => d.local === undefined || d.ci === undefined)
+
+if (realDrifts.length === 0) {
+  process.stdout.write(
+    'check-local-ci-parity: hash differs only by gate-set membership ' +
+      `(stale CI artifact; ${staleOnly.length} gate(s) present on one side only) — no result drift. Neutral.\n`,
+  )
+  for (const d of staleOnly) process.stdout.write(`    ${d.name}: local=${fmt(d.local)}, ci=${fmt(d.ci)}\n`)
+  process.exit(0)
+}
+
+process.stderr.write('check-local-ci-parity: FAIL — local <-> CI parity drift detected\n\n')
+process.stderr.write(`  local:  ${localResult.parityContentHash}\n`)
+process.stderr.write(`  ci:     ${ciResult.parityContentHash}\n\n`)
+process.stderr.write('  Differing gates (result drift):\n')
+for (const d of realDrifts) process.stderr.write(`    ${d.name}: local=${fmt(d.local)}, ci=${fmt(d.ci)}\n`)
+process.stderr.write('\n  Fix: resolve the differing gates locally and in CI, then re-run.\n\n')
+process.exit(1)

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

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// CATALOG: #2103 M16 handoff-contract gate — verifies a fixed corpus of dispatch-brief
+// CATALOG: sources (wave-drain/drain SKILL.md, agent-orchestration-and-context-hygiene.md)
+// CATALOG: carries the literal M16_HANDOFF_MARKER string ("subagents never own waits"),
+// CATALOG: catching a brief that still tells a worker to wait on the gate itself.
+// CATALOG: rejected fold-in into check-handoff-doc.mjs because that lints the dynamically
+// CATALOG: discovered HANDOFF.template.md task-section contract (What/Where/AC/Verify/tier);
+// CATALOG: this checks a fixed literal marker string across a fixed corpus — different shape.
+// CATALOG: rejected fold-in into check-phantom-command-scan.mjs because that cross-checks
+// CATALOG: `arbiter <cmd>` citations in prose against the CLI SSOT — an unrelated concern.
+//
+// check-m16-handoff.mjs (#2103) — SOFT gate: dispatch-template files must carry the
+// M16 handoff-contract marker ("subagents never own waits").
+//
+// M16 terminal handoff — subagents never own waits: a dispatched worker ends its brief
+// at commit + launch + structured handoff {SHA, worktree, PID, exit-file, log} with an
+// explicit END-TURN; ALL watches belong to the coordinator (bg-run.sh + pid-watch.sh).
+// Every dispatch template (ship-queue / wave-drain briefs) must carry the marker below
+// so a brief that still tells the worker to "wait for the gate" is caught at the door.
+//
+// Corpus (repo-relative, fixed per the wave-3 plan — NOT .claude/plans/, to avoid
+// self-recursion of the wave plan itself):
+//   .claude/skills/wave-drain/SKILL.md
+//   .claude/skills/drain/SKILL.md
+//   docs/methodology/agent-orchestration-and-context-hygiene.md
+// A corpus file that does not exist in this repo is SKIPPED (the skill may not be
+// installed); an EXISTING file without the marker FAILS, naming the file.
+//
+// Usage:
+//   node scripts/check-m16-handoff.mjs               # check the repo corpus (0/1)
+//   node scripts/check-m16-handoff.mjs --root <dir>  # alternate repo root
+//   node scripts/check-m16-handoff.mjs --self-test   # pure fixtures, no repo needed
+// Exit codes (INV-53): 0 PASS, 1 FAIL, 2 invocation/IO error.
+import { existsSync, readFileSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+export const M16_HANDOFF_MARKER = 'M16 handoff-contract: subagents never own waits'
+
+export const M16_CORPUS = [
+  '.claude/skills/wave-drain/SKILL.md',
+  '.claude/skills/drain/SKILL.md',
+  'docs/methodology/agent-orchestration-and-context-hygiene.md',
+]
+
+/** Files in the corpus that EXIST but lack the marker. Empty ⇒ pass. */
+export function missingMarkers(root) {
+  const missing = []
+  for (const rel of M16_CORPUS) {
+    const p = join(root, rel)
+    if (!existsSync(p)) continue
+    if (!readFileSync(p, 'utf-8').includes(M16_HANDOFF_MARKER)) missing.push(rel)
+  }
+  return missing
+}
+
+function selfTest() {
+  const dir = mkdtempSync(join(tmpdir(), 'm16-handoff-self-test-'))
+  const marked = `# Wave Drain\n\n${M16_HANDOFF_MARKER}\n`
+  const unmarked = '# Wave Drain\n\nBrief agents in parallel.\n'
+  try {
+    const ok = join(dir, '.claude', 'skills', 'wave-drain')
+    const bad = join(dir, '.claude', 'skills', 'drain')
+    mkdirSync(ok, { recursive: true })
+    mkdirSync(bad, { recursive: true })
+    writeFileSync(join(ok, 'SKILL.md'), marked)
+    writeFileSync(join(bad, 'SKILL.md'), unmarked)
+    const missing = missingMarkers(dir)
+    if (missing.length !== 1 || !missing[0].endsWith('drain/SKILL.md')) {
+      process.stderr.write(
+        `check-m16-handoff self-test FAILED: expected exactly drain/SKILL.md missing, got ${JSON.stringify(missing)}\n`,
+      )
+      return 1
+    }
+    writeFileSync(join(bad, 'SKILL.md'), marked)
+    if (missingMarkers(dir).length !== 0) {
+      process.stderr.write('check-m16-handoff self-test FAILED: fully-marked corpus must pass\n')
+      return 1
+    }
+    process.stdout.write('check-m16-handoff self-test OK (marker-less corpus fails, marked passes)\n')
+    return 0
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+try {
+  const args = process.argv.slice(2)
+  if (args.includes('--self-test')) {
+    process.exit(selfTest())
+  }
+  let root = process.cwd()
+  const rootIdx = args.indexOf('--root')
+  if (rootIdx >= 0 && args[rootIdx + 1] !== undefined) {
+    root = resolve(args[rootIdx + 1])
+  } else if (rootIdx >= 0) {
+    process.stderr.write('check-m16-handoff: --root requires a directory argument\n')
+    process.exit(2)
+  }
+  const missing = missingMarkers(root)
+  if (missing.length > 0) {
+    process.stderr.write(
+      `check-m16-handoff: M16 handoff-contract marker missing from:\n  ${missing.join('\n  ')}\n` +
+        `Add the line "${M16_HANDOFF_MARKER}" to each dispatch template (see docs/methodology/agent-orchestration-and-context-hygiene.md M16).\n`,
+    )
+    process.exit(1)
+  }
+  process.stdout.write('check-m16-handoff: OK — every dispatch-template corpus file carries the M16 handoff-contract marker\n')
+} catch (err) {
+  process.stderr.write(`check-m16-handoff: ${err instanceof Error ? err.message : String(err)}\n`)
+  process.exit(1)
+}

package/dist/templates/scripts/check-merge-method.mjs.ejs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: INV-101 enforcement for the exact-SHA landing contract.
+// CATALOG: validates the canonical policy plus applicator and watcher wiring.
+// CATALOG: rejected fold-in because merge mutation safety is independent of config schema checks.
+// Usage: node scripts/check-merge-method.mjs [--config=<path>]
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const POLICY_PATTERNS = {
+  allow_merge_commit: /allow_merge_commit\s*:\s*true/,
+  allow_squash_merge: /allow_squash_merge\s*:\s*false/,
+  allow_rebase_merge: /allow_rebase_merge\s*:\s*false/,
+  required_linear_history: /required_linear_history\s*:\s*false/,
+  allow_force_pushes: /allow_force_pushes\s*:\s*false/,
+  allow_deletions: /allow_deletions\s*:\s*false/,
+}
+const WATCHER_REQUIRED = {
+  updateRefs: /\bupdateRefs\b/,
+  beforeOid: /\bbeforeOid\b/,
+  afterOid: /\bafterOid\b/,
+  non_force: /force\s*:\s*false/,
+  live_policy: /\bvalidateLiveExactShaPolicy\b/,
+  // #2150: assert the landing contract is USED, not merely imported. A bare
+  // /\bresolveLandingContract\b/ is satisfied by the import line alone, so it
+  // cannot see a consumer deleting the enforcement call — the one failure this
+  // entry exists to catch. Proven by inversion: with the assertLandingSupported()
+  // statement removed, the name-only pattern still matches and these two do not.
+  landing_contract: /resolveLandingContract\s*\(/,
+  landing_guard_invoked: /^\s*assertLandingSupported\(\)/m,
+}
+const WATCHER_FORBIDDEN = {
+  gh_pr_merge: /['"]pr['"]\s*,\s*['"]merge['"]|gh\s+pr\s+merge/,
+  rebase: /--rebase/,
+  squash: /--squash/,
+}
+
+function configPath(args) {
+  const flag = args.find((arg) => arg.startsWith('--config='))
+  return flag ? resolve(flag.slice('--config='.length)) : resolve('arbiter.json')
+}
+
+function requireFile(path, label, errors) {
+  if (!existsSync(path)) {
+    errors.push(`${label} missing: ${path}`)
+    return ''
+  }
+  return readFileSync(path, 'utf8')
+}
+
+try {
+  if (!existsSync(configPath(process.argv.slice(2)))) process.exit(0)
+  const root = resolve()
+  const errors = []
+  const policy = requireFile(
+    join(root, 'scripts/lib/exact-sha-policy.mjs'),
+    'canonical policy',
+    errors,
+  )
+  const watcher = requireFile(join(root, 'scripts/pr-merge-watch.mjs'), 'merge watcher', errors)
+  const applicator = requireFile(
+    join(root, 'scripts/apply-branch-protection.mjs'),
+    'branch-protection applicator',
+    errors,
+  )
+
+  for (const [name, pattern] of Object.entries(POLICY_PATTERNS)) {
+    if (!pattern.test(policy)) errors.push(`canonical policy missing ${name} with exact value`)
+  }
+  for (const [name, pattern] of Object.entries(WATCHER_REQUIRED)) {
+    if (!pattern.test(watcher)) errors.push(`merge watcher missing ${name} exact-SHA wiring`)
+  }
+  for (const [name, pattern] of Object.entries(WATCHER_FORBIDDEN)) {
+    if (pattern.test(watcher)) errors.push(`merge watcher contains forbidden ${name} path`)
+  }
+  if (!/exact-sha-policy\.mjs/.test(applicator)) {
+    errors.push('branch-protection applicator does not import the canonical policy')
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) process.stderr.write(`[INV-101] ${error}\n`)
+    process.exit(1)
+  }
+  process.stdout.write('exact-SHA landing policy and watcher wiring present\n')
+  process.exit(0)
+} catch (error) {
+  process.stderr.write(
+    `[INV-101] ERROR: ${error instanceof Error ? error.message : String(error)}\n`,
+  )
+  process.exit(2)
+}