@getarbiter/cli 0.5.0

package/dist/templates/claude/hooks/check-no-skipped-tests.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Arbiter hook: block skipped/disabled tests (NI-11)
+// Fires on: PostToolUse → Edit|Write
+import { readFileSync, existsSync } from 'node:fs'
+import { addedLinesVsHEAD, resolveToolInputPath } from './lib.mjs'
+
+const file = resolveToolInputPath()
+if (!file || !existsSync(file)) process.exit(0)
+
+// Binary / lock files — skip
+const SKIP_EXTENSIONS = [
+  '.lock',
+  '.lockb',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.svg',
+  '.wasm',
+  '.bin',
+]
+if (SKIP_EXTENSIONS.some((ext) => file.endsWith(ext))) process.exit(0)
+
+let content
+try {
+  content = readFileSync(file, 'utf-8')
+} catch {
+  process.exit(0)
+}
+
+// #2539: scan only the lines THIS edit added, not the whole file — a
+// pre-existing skip-shaped line on an untouched line (this checker's own
+// doc comment naming the aliases it looks for, or a fixture that deliberately
+// plants one as test data) must not block an unrelated edit elsewhere in the
+// same file. Untracked files and git errors fail OPEN to the whole-file scan
+// (never skip) — see addedLinesVsHEAD's doc comment.
+const { tracked, added } = addedLinesVsHEAD(file)
+const scanLines = tracked
+  ? added.map(({ line, content: text }) => [line - 1, text])
+  : content.split('\n').map((text, index) => [index, text])
+const ext = file.slice(file.lastIndexOf('.'))
+
+/** @param {RegExp} re @param {string} label */
+function findOffending(re, label) {
+  return scanLines.flatMap(([i, line]) =>
+    re.test(line) ? [`${i + 1}: [${label}] ${line.trim()}`] : [],
+  )
+}
+
+const offending = []
+
+// JS / TS — skip/only calls, plus the x-prefixed aliases (xit, xtest, xdescribe)
+if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+  offending.push(...findOffending(/\.(skip|only)\s*\(/, '.skip/.only'))
+  offending.push(...findOffending(/\b(xit|xtest|xdescribe)\s*\(/, 'xit/xtest/xdescribe'))
+}
+
+// Java — @Disabled, @Ignore
+if (ext === '.java') {
+  offending.push(...findOffending(/@(Disabled|Ignore)\b/, '@Disabled/@Ignore'))
+}
+
+// Python — @pytest.mark.skip, @pytest.mark.xfail
+if (ext === '.py') {
+  offending.push(...findOffending(/@pytest\.mark\.(skip|xfail)\b/, 'pytest.mark.skip/xfail'))
+}
+
+// Rust — #[ignore]
+if (ext === '.rs') {
+  offending.push(...findOffending(/#\[ignore\]/, '#[ignore]'))
+}
+
+if (offending.length > 0) {
+  process.stderr.write(
+    `[arbiter] NI-11: Skipped/disabled test found in ${file} — remove the skip or open a tracking issue:\n`,
+  )
+  offending.slice(0, 3).forEach((l) => process.stderr.write(`  ${l}\n`))
+  // Exit 2 feeds the violation back to the agent for a PostToolUse guard (#1631).
+  process.exit(2)
+}

package/dist/templates/claude/hooks/check-no-unused-exports.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Claude hook: blocks unused TypeScript value-level exports in files being written/edited.
+// Fires on: PostToolUse → Edit|Write (TypeScript projects only)
+import { existsSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { resolveToolInputPath, debounceHook } from './lib.mjs'
+
+const file = resolveToolInputPath()
+if (!file || !existsSync(file)) process.exit(0)
+const TS_EXTS = ['.ts', '.tsx', '.mts', '.cts']
+if (!TS_EXTS.some((ext) => file.endsWith(ext))) process.exit(0)
+
+// knip builds the WHOLE-project graph; it cannot be scoped to one file. Debounce
+// it so a burst of edits triggers at most one run instead of O(repo)/edit (#1515).
+// The L1 gate runs knip authoritatively before commit/push, so a skipped per-edit
+// run never lets an unused export reach a commit.
+if (debounceHook('knip-unused-exports')) process.exit(0)
+
+let raw = ''
+try {
+  raw = execSync('npx knip --include exports,types --reporter json --no-progress', {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 60_000,
+  })
+} catch (e) {
+  const err = e && typeof e === 'object' ? e : {}
+  if ('code' in err && err.code === 'ENOENT') {
+    process.stderr.write(
+      '[check-no-unused-exports] knip not found — skipping. Run: npm install knip\n',
+    )
+    process.exit(0)
+  }
+  raw = 'stdout' in err && err.stdout != null ? String(err.stdout) : ''
+}
+
+if (!raw.trim()) process.exit(0)
+
+let report
+try {
+  report = JSON.parse(raw)
+} catch {
+  process.exit(0)
+}
+
+if (!Array.isArray(report?.issues)) process.exit(0)
+
+const fileIssues = report.issues.filter(
+  (f) => resolve(f.file) === file && (f.exports?.length ?? 0) + (f.types?.length ?? 0) > 0,
+)
+if (fileIssues.length === 0) process.exit(0)
+
+process.stderr.write('Unused exports detected (knip):\n')
+for (const f of fileIssues) {
+  for (const exp of [...(f.exports ?? []), ...(f.types ?? [])]) {
+    process.stderr.write(`  ${f.file}:${exp.line ?? '?'} — ${exp.name}\n`)
+  }
+}
+process.stderr.write('\nRemove unused exports before saving.\n')
+// Exit 2 feeds the violation back to the agent for a PostToolUse guard (#1631).
+process.exit(2)

package/dist/templates/claude/hooks/closer-mode-guard.mjs.ejs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Arbiter hook: CLOSER mode enforcement (#A11) — mechanically-checkable subset of the 7 rules
+// in `.claude/rules/95-closer-mode.md`. Fires on: PreToolUse → Bash. Only active while the task
+// is in its `close` phase (post-implementation, pre-merge, entered via
+// `arbiter task advance --to close`) — inert on every other phase.
+// Exit 2: block — stderr is returned to Claude as error context.
+// Fail-closed contract: phase detection is fail-OPEN (if the task context can't be read the
+// guard stays inert, so it never wedges Bash outside a close), but once we know we ARE closing,
+// an unexpected error in rule evaluation fails CLOSED (exit 2) rather than waving the command
+// through — a safety guard that silently gives up is worse than useless.
+// Generated by arbiter for project: <%= projectName %>
+import { readTaskState, getRepoRoot, resolveToolInputCommand } from './lib.mjs';
+import { spawnSync } from 'node:child_process';
+
+const command = resolveToolInputCommand();
+if (command.length === 0) process.exit(0);
+
+// Phase detection — fail OPEN: an unreadable task context means "not demonstrably closing",
+// so the guard stays inert rather than blocking every command in a repo it can't reason about.
+let root;
+let phase;
+try {
+  root = getRepoRoot();
+  ({ phase } = readTaskState(root));
+  // FAIL-OPEN-INTENT: an unreadable task context means "not demonstrably closing" — stay inert.
+} catch {
+  process.exit(0);
+}
+if (phase !== 'close') process.exit(0); // CLOSER mode is only active in the close phase
+
+const block = (rule, reason) => {
+  process.stderr.write(
+    `[arbiter] CLOSER MODE: blocked \`${command}\`.\n` +
+      `${rule}: ${reason}\n` +
+      `See .claude/rules/95-closer-mode.md.\n`,
+  );
+  process.exit(2);
+};
+
+// Rule evaluation — fail CLOSED: while actively closing, any unexpected error blocks the
+// command (exit 2) so a crashing guard can't silently permit a forbidden action.
+try {
+  // Rule 1 (single named target): no switching branches/targets while closing. A switch in
+  // any form — named branch, `-` for the previous one, `-b`/`-c` for a new one — abandons
+  // the single target. The path-restore forms of `checkout` (`-- <path>`, `.`, `--ours`,
+  // `--theirs`, `-p`) are routine conflict resolution DURING a close and must stay allowed,
+  // or the guard wedges the phase it exists to protect.
+  const switchArgs = command.match(/\bgit\s+(?:checkout|switch)\b([^;&|]*)/)?.[1];
+  const pathRestore = /(^|\s)(--|--ours|--theirs|--merge|--conflict|-p|--patch|\.)(\s|$)/;
+  if (switchArgs !== undefined && !pathRestore.test(switchArgs)) {
+    block('Rule 1 (single named target)', 'no switching branches/targets while closing');
+  }
+
+  // Rule 2 (no discovery): opening a new issue mid-close is forbidden — findings go on the
+  // PARKING list (`arbiter note`) instead of spawning tracked work.
+  if (/\bgh\s+issue\s+create\b/.test(command)) {
+    block(
+      'Rule 2 (no discovery)',
+      'opening a new issue mid-close is forbidden — append the finding to the PARKING list ' +
+        '(`arbiter note`) instead',
+    );
+  }
+
+  // Rule 2 (no gate-appeasement deletions): `git clean -f...` can sweep an untracked file that
+  // exists to satisfy a gate (observed: an agent deleted a colleague's untracked deliverable to
+  // make a format check pass — report the obstruction instead).
+  if (/\bgit\s+clean\b.*-\w*f/.test(command)) {
+    block(
+      'Rule 2 (no gate-appeasement deletions)',
+      '`git clean -f` can delete an untracked file that exists to satisfy a gate — report the ' +
+        'obstruction instead of removing the evidence',
+    );
+  }
+
+  // Rule 2 (cont'd): `rm` targeting a path git currently reports as untracked (`??`) — the same
+  // anti-pattern, one file at a time. Tracked-file deletion (part of the diff) is unaffected.
+  const rmMatch = command.match(/(?:^|[;&|]\s*)rm\s+(?:-\w+\s+)*(.+?)(?:[;&|]|$)/);
+  if (rmMatch) {
+    const targets = rmMatch[1].split(/\s+/).filter((t) => t.length > 0 && !t.startsWith('-'));
+    for (const target of targets) {
+      const status = spawnSync('git', ['status', '--porcelain', '--', target], {
+        cwd: root,
+        encoding: 'utf-8',
+      });
+      if (status.status === 0 && /^\?\?/.test(String(status.stdout).trim())) {
+        block(
+          'Rule 2 (no gate-appeasement deletions)',
+          `"${target}" is untracked — deleting it to make a gate pass is forbidden`,
+        );
+      }
+    }
+  }
+} catch (err) {
+  process.stderr.write(
+    `[arbiter] CLOSER MODE: guard error while evaluating \`${command}\` — blocking to fail ` +
+      `closed: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

package/dist/templates/claude/hooks/debug-state-on-failure.mjs.ejs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// Arbiter hook: persist debug state when test/gate commands fail
+// Hook type: PostToolUseFailure (Bash)
+// Creates/updates DEBUG_STATE.md in .evidence/ so debug context survives context resets
+// Only triggers for test/gate commands — skips unrelated bash failures
+// Always exits 0 (non-blocking)
+<%
+// EJS render-time: escape the project's testCommand for use as a RegExp literal
+const escapedTestCmd = testCommand.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+%>
+import { readTaskState, getRepoRoot, logWarn } from './lib.mjs'
+import { readFileSync, openSync, closeSync, appendFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+// Read failure info from stdin (PostToolUseFailure JSON payload)
+let command = ''
+let errorOutput = ''
+try {
+  const raw = readFileSync(0, 'utf-8')
+  const payload = JSON.parse(raw)
+  command = payload?.tool_input?.command ?? payload?.command ?? ''
+  errorOutput = (payload?.error ?? payload?.stderr ?? '').slice(0, 2000)
+} catch {
+  process.exit(0)
+}
+
+// Only trigger for test/gate commands matching this project's stack
+const TEST_PATTERNS = [
+  /\bnpm\s+(run\s+)?test\b/,
+  /\bnpx\s+vitest\b/,
+  /\bcargo\s+test\b/,
+  /\bgo\s+test\b/,
+  /\bpytest\b/,
+  /\b\.\/gradlew\s+test\b/,
+  /\bmvn\s+(test|verify)\b/,
+  /\bnode\s+scripts\/check-all\.mjs\b/,
+  new RegExp(<%- JSON.stringify(escapedTestCmd) %>),
+]
+if (!TEST_PATTERNS.some((p) => p.test(command))) process.exit(0)
+
+const root = getRepoRoot()
+const { taskId } = readTaskState(root)
+
+// Determine evidence directory
+const evidenceDir =
+  taskId && taskId !== 'unknown'
+    ? join(root, '.evidence', `task-${taskId.replace(/^#/, '')}`)
+    : join(root, '.evidence', `debug-${new Date().toISOString().slice(0, 10)}`)
+
+mkdirSync(evidenceDir, { recursive: true })
+
+const debugFile = join(evidenceDir, 'DEBUG_STATE.md')
+const timestamp = new Date().toISOString()
+const branch =
+  spawnSync('git', ['branch', '--show-current'], {
+    encoding: 'utf-8',
+    cwd: root,
+  }).stdout?.trim() ?? 'unknown'
+
+// Atomically create header on first invocation (O_CREAT|O_EXCL — concurrent racers skip)
+try {
+  const fd = openSync(debugFile, 'wx')
+  closeSync(fd)
+  appendFileSync(
+    debugFile,
+    `# Debug State — Task ${taskId}\n\n` +
+      `**Created:** ${timestamp}\n` +
+      `**Branch:** ${branch}\n\n` +
+      `---\n\n` +
+      `## Current Hypothesis\n\n` +
+      `_To be filled by the agent after analyzing the failure._\n\n` +
+      `## Command Run\n\n` +
+      `\`\`\`bash\n${command}\n\`\`\`\n\n` +
+      `## Output (truncated)\n\n` +
+      `\`\`\`\n${errorOutput.slice(0, 1000)}\n\`\`\`\n\n` +
+      `## Next Action\n\n` +
+      `_To be determined after root-cause analysis._\n\n` +
+      `---\n\n` +
+      `## History\n\n`,
+    'utf-8',
+  )
+} catch {
+  // EEXIST — file already exists, skip header
+}
+
+// Atomic append for this attempt entry (POSIX atomic for writes < PIPE_BUF ~4KB)
+appendFileSync(
+  debugFile,
+  `### Attempt — ${timestamp}\n\n` +
+    `- **Command:** \`${command}\`\n` +
+    `- **Result:** FAIL\n` +
+    `- **Output (truncated):** ${errorOutput.slice(0, 500)}\n`,
+  'utf-8',
+)
+
+process.stderr.write(`[DEBUG-STATE] Failure recorded in ${debugFile}\n`)
+logWarn(`debug-state: failure captured for command: ${command.slice(0, 80)}`)

package/dist/templates/claude/hooks/enforce-gate-before-pr.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Arbiter hook: block gh pr create unless gate marker is fresh (R1.S5)
+// FAIL-OPEN-INTENT: hook exits 0 for non-PR commands; gate-fail exits 2 explicitly
+// Fires on: PreToolUse → Bash
+// Exit 2: block — stderr returned to Claude as error context
+// Delegated Agent-tool sessions do not run the `.claude/settings.json` hook chain.
+// This hook is defence-in-depth/advisory there; CI plus branch protection enforce.
+// See `docs/internal/SYSTEM/HOOK-CONTRACTS.md#scope-and-threat-model` (#2022).
+//
+// #1990: worktree-aware. A session cwd on repo root must not gate a `gh pr
+// create` that actually targets a different worktree (`cd <dir> && gh pr
+// create ...`, or `--head <branch>` naming a branch checked out elsewhere).
+// resolveTargetRoot() finds that worktree and the marker is validated
+// against ITS HEAD, not the session cwd's. `gh issue create` is exempt
+// (opening an issue is not a completion claim) — the segment-anchored match
+// below also refuses to treat `gh pr create` mentioned inside a
+// `gh issue create --body "..."` string as a real invocation.
+import { readFileSync, existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { resolveToolInputCommand } from './lib.mjs'
+
+// Resolve the command from stdin-JSON (real Claude Code) or the env var (Codex).
+// Reading only the env var made this guard silently inert under Claude Code (#1565).
+const command = resolveToolInputCommand()
+
+// Split on shell chain operators and match each segment anchored at its start.
+// This is what makes `gh issue create --body "run gh pr create after"` safe:
+// that segment starts with `gh issue create`, not `gh pr create`, so it never
+// matches — no separate exemption list needed for gh issue create.
+const segments = command.split(/&&|\|\||;|\|/).map((s) => s.trim())
+const prCreateIndex = segments.findIndex((s) => /^gh\s+pr\s+create\b/.test(s))
+if (prCreateIndex === -1) process.exit(0)
+
+if (process.env.ARBITER_SKIP_GATE_MARKER === '1') {
+  process.stderr.write('[arbiter] Gate marker check bypassed (ARBITER_SKIP_GATE_MARKER=1)\n')
+  process.exit(0)
+}
+
+/**
+ * Finds the worktree the `gh pr create` invocation actually targets, if any.
+ * Checked in order:
+ *   1. A `cd <dir> &&` segment earlier in the same command chain.
+ *   2. A `--head <branch>` flag naming a branch checked out in another worktree.
+ * Returns the worktree's toplevel path, or null when neither is present (the
+ * caller then falls back to the previous cwd-based resolution unchanged).
+ */
+function resolveTargetRoot(cmdSegments, prIndex) {
+  for (let i = prIndex - 1; i >= 0; i--) {
+    const cdMatch = cmdSegments[i].match(/^cd\s+(.+)$/)
+    if (!cdMatch) continue
+    const dir = cdMatch[1].trim().replace(/^["']|["']$/g, '')
+    const top = spawnSync(
+      'git',
+      ['-C', resolve(process.cwd(), dir), 'rev-parse', '--show-toplevel'],
+      { encoding: 'utf-8' },
+    )
+    if (top.status === 0 && top.stdout.trim()) return top.stdout.trim()
+    break
+  }
+
+  const headMatch = cmdSegments[prIndex].match(/--head[= ]("?)([^"\s]+)\1/)
+  if (headMatch) {
+    const branch = headMatch[2]
+    const listResult = spawnSync('git', ['worktree', 'list', '--porcelain'], { encoding: 'utf-8' })
+    if (listResult.status === 0) {
+      for (const entry of listResult.stdout.split('\n\n')) {
+        const wtPath = entry.match(/^worktree (.+)$/m)?.[1]
+        const wtBranch = entry.match(/^branch refs\/heads\/(.+)$/m)?.[1]
+        if (wtPath && wtBranch === branch) return wtPath
+      }
+    }
+  }
+
+  return null
+}
+
+const resolvedRoot = resolveTargetRoot(segments, prCreateIndex)
+
+let repoRoot
+if (resolvedRoot) {
+  repoRoot = resolvedRoot
+} else {
+  const gitResult = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' })
+  repoRoot = gitResult.stdout.trim() || process.cwd()
+}
+
+const markerPath = resolve(repoRoot, '.arbiter/gate-pass.json')
+const rootNote = resolvedRoot ? ` (worktree: ${repoRoot})` : ''
+
+if (!existsSync(markerPath)) {
+  process.stderr.write(
+    `[arbiter] GATE GUARD: No gate-pass.json found${rootNote}.\n` +
+      'Run `node scripts/check-all.mjs L2` before creating a PR.\n',
+  )
+  process.exit(2)
+}
+
+let marker
+try {
+  marker = JSON.parse(readFileSync(markerPath, 'utf-8'))
+} catch (err) {
+  process.stderr.write(
+    `[arbiter] GATE GUARD: gate-pass.json is invalid${rootNote}: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(2)
+}
+
+// The shared verifier is loaded lazily and fail-CLOSED: a static import that
+// cannot resolve would abort the hook with exit 1, which Claude Code treats as
+// non-blocking — a missing verifier would silently open the gate.
+let gateEvidence
+try {
+  gateEvidence = await import('../../scripts/lib/gate-evidence.mjs')
+} catch (err) {
+  process.stderr.write(
+    `[arbiter] GATE GUARD: the gate-pass verifier could not be loaded${rootNote}: ` +
+      `${err instanceof Error ? err.message : String(err)}\n` +
+      'Restore scripts/lib/gate-evidence.mjs (arbiter emits it) and re-run the gate.\n',
+  )
+  process.exit(2)
+}
+
+// head_sha alone lets a marker from a sibling worktree, a changed lockfile or an
+// hours-old run open a PR. Every identity axis is checked here, against the
+// worktree the PR actually targets, and every one fails closed.
+const verdict = gateEvidence.verifyGateEvidence(marker, {
+  root: repoRoot,
+  minLevel: 'L2',
+  maxAgeMin:
+    Number(process.env.ARBITER_EVIDENCE_MAX_AGE_MIN) || gateEvidence.GATE_EVIDENCE_DEFAULT_TTL_MIN,
+})
+
+if (!verdict.ok) {
+  process.stderr.write(
+    `[arbiter] GATE GUARD: gate-pass.json is stale or does not bind this checkout${rootNote}.\n` +
+      `${verdict.reason}\n` +
+      'Run `node scripts/check-all.mjs L2` again after your last commit.\n',
+  )
+  process.exit(2)
+}

package/dist/templates/claude/hooks/enforce-read-only.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Arbiter hook: guard designated read-only files
+// Fires on: PreToolUse → Edit|Write
+import { resolveToolInputPath } from './lib.mjs'
+
+const file = resolveToolInputPath()
+
+// Fail closed (INV-96): an unresolvable edit path must BLOCK, not fall through to
+// allow. A guard that protects read-only files must not disarm on uncertainty.
+if (!file) {
+  process.stderr.write(
+    '[arbiter] Read-only guard: unresolvable edit path — blocking (fail-closed, INV-96).\n',
+  )
+  process.exit(2)
+}
+
+const READ_ONLY_PATTERNS = ['AGENTS.md', 'LICENSE', 'package-lock.json', 'Cargo.lock']
+
+for (const pattern of READ_ONLY_PATTERNS) {
+  if (file.includes(pattern)) {
+    process.stderr.write(
+      `[arbiter] Read-only file — edit requires explicit justification: ${file}\n`,
+    )
+    // Exit 2 BLOCKS the edit (#1631). Exit 1 was non-blocking — the protected-file
+    // edit proceeded, and the guard was inverted vs the fail-closed path above (exit 2).
+    process.exit(2)
+  }
+}

package/dist/templates/claude/hooks/exitplanmode-banner.mjs.ejs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// exitplanmode-banner.mjs — prints a next-step banner when ExitPlanMode fires (#1210)
+// Hook type: PostToolUse:ExitPlanMode — fires after the agent leaves plan mode
+// stdout is shown to the model as a banner; always exits 0 (non-blocking)
+// FAIL-OPEN-INTENT: advisory banner — any error must not block the agent workflow
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const BANNER_PHASES = new Set(['plan', 'red-team-review'])
+
+function git(args) {
+  return (spawnSync('git', args, { encoding: 'utf-8' }).stdout ?? '').trim()
+}
+
+try {
+  const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'])
+  if (/^(?:backup|preserve|wip)\//.test(branch)) process.exit(0)
+
+  const root = git(['rev-parse', '--show-toplevel'])
+  const statusPath = join(root, '.claude', '.task', 'status.json')
+
+  if (!existsSync(statusPath)) process.exit(0)
+
+  let state
+  try {
+    state = JSON.parse(readFileSync(statusPath, 'utf-8'))
+  } catch {
+    // FAIL-OPEN-INTENT: corrupted status file — silently skip banner
+    process.exit(0)
+  }
+
+  if (!BANNER_PHASES.has(state.phase)) process.exit(0)
+
+  const taskId = (state.taskId ?? '').replace(/^#/, '')
+  process.stdout.write(`[arbiter] Plan mode ended — run: arbiter ship #${taskId} --advance\n`)
+  process.exit(0)
+} catch (err) {
+  process.stderr.write(
+    `[exitplanmode-banner] unexpected error: ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  process.exit(1)
+}

package/dist/templates/claude/hooks/guard-done-evidence.mjs.ejs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Arbiter hook: validate SHA-pinned evidence before accepting done claims
+// Hook type: UserPromptSubmit — fires before every user prompt
+// Hard block (exit 2) — returns stderr to Claude as error context
+// Checks the current task v2 done receipt on completion claims
+// Generated by arbiter for project: <%= projectName %>
+import { readTaskState, getRepoRoot } from './lib.mjs';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = getRepoRoot();
+
+// --- Flag gate (#1872): inert unless the project opts in ---------------------
+// This hook is materialized for dogfood regardless of the flag, but stays
+// no-op (exit 0) until the owner flips features.evidenceHarness: true in
+// arbiter.json. The flag is the owner-flippable one-line activation switch;
+// the artifacts (hook + script + wiring) travel with it so the flip alone
+// turns enforcement on. Env ARBITER_EVIDENCE_HARNESS overrides for testing/CI:
+//   '1'/'true' → on, '0'/'false' → off, unset → read arbiter.json.
+// An absent config leaves the optional harness inert; malformed config blocks.
+function evidenceHarnessEnabled(repoRoot) {
+  const env = process.env.ARBITER_EVIDENCE_HARNESS;
+  if (env === '1' || env === 'true') return true;
+  if (env === '0' || env === 'false') return false;
+  try {
+    const cfg = JSON.parse(readFileSync(join(repoRoot, 'arbiter.json'), 'utf-8'))
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) fail('harness config must be an object')
+    return cfg.features?.evidenceHarness === true
+  } catch (err) {
+    if (err.code === 'ENOENT') return false
+    fail(`harness config unreadable or malformed: ${err.message}`)
+  }
+}
+if (!evidenceHarnessEnabled(root)) process.exit(0);
+
+const { phase, taskId } = readTaskState(root);
+
+// Only guard during verification phase (evidence required before claiming done)
+if (phase !== 'verification') process.exit(0);
+
+// Only guard when a completion claim is made (mirrors guard-task-completion pattern)
+let promptText = '';
+let raw;
+try {
+  raw = readFileSync(0, 'utf-8');
+} catch (e) {
+  process.stderr.write(`[guard-done-evidence] WARN: could not read stdin (${e.code ?? e.message}) — blocking as fail-safe\n`);
+  process.exit(2);
+}
+try {
+  promptText = JSON.parse(raw)?.prompt ?? '';
+  // FAIL-OPEN-INTENT: non-JSON stdin is not a hook error — treat as empty prompt (exit 0).
+} catch {
+  process.exit(0);
+}
+
+const COMPLETION_PATTERNS = /\b(task complete|task completed|all phases complete|pr merged|merged to main|wrapping up|ready to (merge|close))\b/i;
+if (!COMPLETION_PATTERNS.test(promptText)) process.exit(0);
+
+// Completion claimed — validate evidence integrity
+
+function fail(reason) {
+  process.stderr.write(
+    `━━━ DONE EVIDENCE GUARD ━━━\n` +
+    `Completion claim blocked — evidence check failed:\n` +
+    `  ${reason}\n\n` +
+    `Run: node scripts/done-evidence.mjs\n` +
+    `This captures the current gate state + SHA-256 of pinned files.\n` +
+    `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`,
+  );
+  process.exit(2);
+}
+
+let verifyDoneEvidenceReceipt
+try {
+  ;({ verifyDoneEvidenceReceipt } = await import('../../scripts/lib/gate-evidence.mjs'))
+  if (typeof verifyDoneEvidenceReceipt !== 'function') fail('done receipt verifier unavailable')
+} catch (err) {
+  fail(`done receipt verifier unavailable: ${err.message}`)
+}
+const receiptVerdict = verifyDoneEvidenceReceipt({ root, taskId, archetype: '<%= archetype %>' });
+if (!receiptVerdict.ok) fail(receiptVerdict.reason);
+
+// All checks passed — allow completion claim through.
+process.exit(0)