@getarbiter/cli 0.5.0

package/dist/templates/claude/hooks/stop-dangerous.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Arbiter hook: block dangerous bash commands
+// Fires on: PreToolUse → Bash
+// 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).
+import { resolveToolInputCommand, stripQuotedAndHeredocs } 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()
+
+const DANGEROUS_PATTERNS = [
+  'rm -rf /',
+  'rm -rf ~',
+  'git push --force',
+  'git push -f ',
+  'git reset --hard',
+  'DROP TABLE',
+  'DROP DATABASE',
+  'sudo rm',
+  '> /dev/sda',
+]
+
+for (const pattern of DANGEROUS_PATTERNS) {
+  if (command.includes(pattern)) {
+    process.stderr.write(`[arbiter] Blocked dangerous command: ${command}\n`)
+    // Exit 2 is the ONLY blocking code for a PreToolUse hook (#1631): it aborts the
+    // Bash call and feeds stderr to the agent. Any other non-zero exit (incl. 1) is
+    // non-blocking — the dangerous command would run anyway.
+    process.exit(2)
+  }
+}
+
+// #2403: protected-Arbiter-state-write guard. The previous form scanned free TEXT for
+// an evidence path plus a write-ish word anywhere in a `;`/`&&`/`|`-split segment —
+// including inside a quoted string — so `gh issue create --body "rm ...evidence..."`
+// (free text) and the ship playbook's own `node -e` evidence writers both false-blocked.
+// This scans only the COMMAND HEAD of each segment, after (a) stripping quoted spans and
+// heredoc bodies (stripQuotedAndHeredocs — a mentioned path never counts) and (b)
+// stripping a leading `sudo`/env-var assignment: a destructive verb (rm, unlink,
+// truncate, mv, cp, `sed -i`) whose arguments reference the protected path, OR a
+// `>`/`>>` redirect whose target is the protected path. `node scripts/*.mjs`,
+// `arbiter …`, `node -e`, `gh …`, `git …`, `cat`, `printf`, `echo` (without a redirect
+// onto the path) are never destructive heads, so they pass regardless of what their
+// (redacted) arguments contain.
+const protectedPathPattern =
+  /(?:^|[\s"'`])((?:\.\/|\/[^\s"'`]*)?\.arbiter\/(?:gate-pass\.json|status\.json|evidence(?:\/[^\s"'`]*)?))(?=$|[\s"'`,;)&|])/
+const DESTRUCTIVE_HEADS = new Set(['rm', 'unlink', 'truncate', 'mv', 'cp', 'tee'])
+
+/** Drops a leading `sudo` and any leading `FOO=bar` env assignments before head detection. */
+function stripLeading(seg) {
+  let s = seg.trim().replace(/^sudo\s+/, '')
+  while (/^[A-Za-z_][A-Za-z0-9_]*=\S*\s+/.test(s)) {
+    s = s.replace(/^[A-Za-z_][A-Za-z0-9_]*=\S*\s+/, '')
+  }
+  return s
+}
+
+/** True when a `>`/`>>` redirect target (any fd) in `seg` is the protected path. */
+function redirectsIntoProtectedPath(seg) {
+  const redirectPattern = /(?:^|\s)\d*(>>|>)\s*(\S+)/g
+  let m
+  while ((m = redirectPattern.exec(seg))) {
+    if (protectedPathPattern.test(` ${m[2]} `)) return true
+  }
+  return false
+}
+
+/** True when `seg`'s head is a destructive verb AND its arguments name the protected path. */
+function destructiveHeadOnProtectedPath(seg) {
+  const tokens = seg.split(/\s+/).filter(Boolean)
+  const head = tokens[0] ?? ''
+  const isSedInPlace = head === 'sed' && tokens.some((t) => t === '--in-place' || /^-i/.test(t))
+  if (!DESTRUCTIVE_HEADS.has(head) && !isSedInPlace) return false
+  return protectedPathPattern.test(seg)
+}
+
+const redactedCommand = stripQuotedAndHeredocs(command)
+const commandParts = redactedCommand.split(/\|\||&&|;|\|/).map(stripLeading)
+for (const commandPart of commandParts) {
+  if (redirectsIntoProtectedPath(commandPart) || destructiveHeadOnProtectedPath(commandPart)) {
+    process.stderr.write(`[arbiter] Blocked protected Arbiter state write: ${command}\n`)
+    process.exit(2)
+  }
+}

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

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Arbiter hook: fail-closed completion backstop (#1212, INV-114)
+// Hook type: Stop — fires when the agent finishes responding
+// Hard block (exit 2) — prevents the stop and returns stderr to the model
+// On every working branch with phase != complete, a completion claim in the
+// final assistant message requires THREE correlated evidence artifacts, all
+// bound to the current branch + HEAD sha. Missing or stale → block.
+// Generated by arbiter for project: <%= projectName %>
+import { readTaskState, getRepoRoot, sanitizeTaskId } from './lib.mjs';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// 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 — the completion backstop would go silent instead of blocking.
+let gateEvidence = null;
+try {
+  gateEvidence = await import('../../scripts/lib/gate-evidence.mjs');
+} catch {
+  gateEvidence = null;
+}
+
+// #2399 — the review-evidence binding (ancestor + source-unchanged). Loaded the same
+// lazy, fail-CLOSED way, and kept a SEPARATE binding so one missing module cannot null
+// both verifiers.
+let evidenceBinding = null;
+try {
+  evidenceBinding = await import('../../scripts/lib/evidence-binding.mjs');
+} catch {
+  evidenceBinding = null;
+}
+
+function main() {
+  // --- stdin (Stop event payload) -------------------------------------------
+  let input = {};
+  try {
+    input = JSON.parse(readFileSync(0, 'utf-8')) ?? {};
+  } catch {
+    // Unreadable/non-JSON stdin is not something we can correlate against — the
+    // guard only ever blocks on a *detected* completion claim, so stand down.
+    process.exit(0);
+  }
+
+  // Re-entry guard: exit 2 re-prompts the model with this hook still active. If we
+  // fired again we would loop forever, so always allow the stop on re-entry.
+  if (input.stop_hook_active === true) process.exit(0);
+
+  const root = getRepoRoot();
+
+  const git = (args) => spawnSync('git', args, { cwd: root, encoding: 'utf-8' });
+  const gitLine = (args) => {
+    const r = git(args);
+    return r.status === 0 ? String(r.stdout).trim() : '';
+  };
+
+  // Explicit save refs carry incomplete snapshots and are the only branches where
+  // completion enforcement stands down. Main/trunk-solo and ordinary work branches
+  // remain governed.
+  const branch = gitLine(['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (/^(?:backup|preserve|wip)\//.test(branch)) process.exit(0);
+
+  // Only guard for an active, not-yet-complete task.
+  const { phase, taskId } = readTaskState(root);
+  if (phase === 'complete' || phase === 'unknown') process.exit(0);
+
+  // Only guard when the final assistant message claims completion.
+  const claimText = latestAssistantText(input.transcript_path);
+  if (claimText === null) process.exit(0); // missing/unreadable transcript → stand down
+  const COMPLETION_PATTERNS = /\b(task (is )?(complete|completed|done|finished)|task complete|task completed|all phases complete|work is (done|complete)|implementation (is )?(complete|done|finished)|pr merged|merged to main|wrapping up|ready to (merge|close)|shipped)\b/i;
+  if (!COMPLETION_PATTERNS.test(claimText)) {
+    // #1402 — end-of-task reflection sweep: a non-blocking nudge to drain seen-but-unrecorded
+    // findings. Only fires when undrained findings exist; never changes the exit code.
+    reflectionSweep(root);
+    process.exit(0);
+  }
+
+  // --- completion claimed: require correlated evidence ----------------------
+
+  const fail = (reason) => {
+    process.stderr.write(
+      `━━━ STOP EVIDENCE GUARD ━━━\n` +
+      `Completion claim blocked on ${branch} (phase: ${phase}):\n` +
+      `  ${reason}\n\n` +
+      `A completion claim requires plan-review + dispatch + gate-pass<% if (enableEvidenceHarness) { %> + journey<% } %> evidence,\n` +
+      `each recorded on this branch at a commit reachable from HEAD.\n` +
+      `Re-run the missing step, then claim completion again.\n` +
+      `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`,
+    );
+    process.exit(2);
+  };
+
+  const readJson = (path) => {
+    try {
+      return JSON.parse(readFileSync(path, 'utf-8'));
+    } catch {
+      return null;
+    }
+  };
+
+  // exit 0 = ancestor-or-equal; anything else (incl. bad sha error) = uncorrelated.
+  const isAncestor = (sha) => {
+    if (typeof sha !== 'string' || sha.length === 0) return false;
+    return git(['merge-base', '--is-ancestor', sha, 'HEAD']).status === 0;
+  };
+
+  let config = {}
+  try {
+    config = JSON.parse(readFileSync(join(root, 'arbiter.json'), 'utf8'))
+    if (!config || typeof config !== 'object' || Array.isArray(config)) fail('harness config must be an object')
+  } catch (err) {
+    if (err.code !== 'ENOENT') fail(`harness config unreadable or malformed: ${err.message}`)
+  }
+  const harnessOverride = process.env.ARBITER_EVIDENCE_HARNESS
+  const harnessEnabled = harnessOverride === '1' || harnessOverride === 'true' ||
+    (!['0', 'false'].includes(harnessOverride) && config.features?.evidenceHarness === true)
+  if (harnessEnabled) {
+    if (typeof gateEvidence?.verifyDoneEvidenceReceipt !== 'function') fail('done receipt verifier unavailable')
+    const doneVerdict = gateEvidence.verifyDoneEvidenceReceipt({ root, taskId, archetype: '<%= archetype %>' })
+    if (!doneVerdict.ok) fail(doneVerdict.reason)
+  }
+
+  // 1. plan-review — verdict PASS, on this branch, sha is an ancestor of HEAD.
+  // Deliberately ancestor-only: a plan is reviewed BEFORE the implementation commits, so
+  // source necessarily changes afterwards. The #2399 source-unchanged binding applies to
+  // evidence that describes reviewed CODE (the dispatch sidecar), never to the plan.
+  const planPath = join(root, '.arbiter', 'evidence', 'plan-review', sanitizeTaskId(taskId), 'latest.json');
+  const plan = readJson(planPath);
+  if (plan === null) fail('plan-review evidence missing or unreadable (latest.json)');
+  if (plan.verdict !== 'PASS') fail(`plan-review verdict is ${JSON.stringify(plan.verdict)} — must be PASS`);
+  if (plan.branch !== branch) fail(`plan-review evidence is for branch ${JSON.stringify(plan.branch)}, not ${branch}`);
+  if (!isAncestor(plan.sha)) fail('plan-review evidence sha is not an ancestor of HEAD (stale)');
+
+  // 2. dispatch sidecar — review agents dispatched on this branch, and the source they
+  // reviewed is still the source at HEAD (#2399). The sidecar is a TRACKED, branch-shared
+  // file, so one recorded for a different task counts as ABSENT for this one.
+  if (evidenceBinding === null) fail('evidence binding verifier unavailable (scripts/lib/evidence-binding.mjs) — dispatch evidence cannot be bound to this tree');
+  const dispatch = readJson(join(root, '.arbiter', 'agents-dispatched.json'));
+  if (dispatch === null) fail('dispatch evidence missing (.arbiter/agents-dispatched.json)');
+  if (evidenceBinding.isForeignSidecar(dispatch, taskId)) fail(`dispatch evidence on disk was recorded for task ${JSON.stringify(dispatch.taskId ?? dispatch.task)}, not ${taskId} — dispatch this task's reviewers`);
+  const dispatchStaleness = evidenceBinding.evidenceStaleness(root, dispatch.sha, {
+    branch: dispatch.branch,
+  });
+  if (dispatchStaleness !== null) fail(`dispatch evidence ${dispatchStaleness}`);
+
+  // 3. gate-pass — strict: THIS tree, in THIS checkout, under THIS toolchain, was
+  // verified recently enough. The full identity binding replaces the old
+  // branch+head_sha pair; #1441 anti-replay rides along as the task-id axis.
+  const gatePath = join(root, '.arbiter', 'gate-pass.json');
+  if (!existsSync(gatePath)) fail('gate-pass evidence missing (.arbiter/gate-pass.json)');
+  if (gateEvidence === null)
+    fail(
+      'gate-pass verifier unavailable (scripts/lib/gate-evidence.mjs) — evidence cannot be bound to this tree',
+    );
+  const gateVerdict = gateEvidence.verifyGateEvidenceFile(gatePath, {
+    root,
+    minLevel: 'L2',
+    maxAgeMin: Number(process.env.ARBITER_EVIDENCE_MAX_AGE_MIN) ||
+      gateEvidence.GATE_EVIDENCE_DEFAULT_TTL_MIN,
+    taskId,
+  });
+  if (!gateVerdict.ok) fail(gateVerdict.reason);
+<% if (enableEvidenceHarness) { -%>
+
+  // 4. journey evidence (#A2, extends INV-114) — a completion claim must reference a run of the
+  // task's declared acceptance E2E spec AGAINST THE BUILT ARTIFACT (compose image / dist), not the
+  // dev server. One downstream project shipped green-tested images whose prod UI ran in fixture mode (buttons
+  // dead) because the acceptance journey was only ever exercised against the dev server.
+  const journey = readJson(join(root, '.arbiter', 'evidence', 'journey', sanitizeTaskId(taskId) + '.json'));
+  if (journey === null) fail('journey evidence missing or unreadable (.arbiter/evidence/journey/<taskId>.json) — declare the acceptance E2E spec up front and run it before claiming completion');
+  if (journey.branch !== branch) fail(`journey evidence is for branch ${JSON.stringify(journey.branch)}, not ${branch}`);
+  if (!isAncestor(journey.sha)) fail('journey evidence sha is not an ancestor of HEAD (stale) — re-run the acceptance spec on the current tree');
+  if (typeof journey.spec !== 'string' || journey.spec.length === 0) fail('journey evidence does not name the acceptance spec it ran (missing "spec")');
+  // Artifact parity: the run must have exercised the built artifact, never dev-server-only.
+  if (journey.target !== 'artifact') fail(`journey evidence ran against ${JSON.stringify(journey.target)}, not the built artifact — a dev-server run does not prove the packaged image works (set target:"artifact" after running the spec against the compose image / dist)`);
+<% } -%>
+
+  // All correlated evidence present — allow the stop, after a final reflection-sweep nudge (#1402).
+  reflectionSweep(root);
+  process.exit(0);
+}
+
+/**
+ * #1402 — count undrained findings across `.arbiter/findings/*.jsonl` and, when any exist, emit a
+ * non-blocking nudge to drain them with `arbiter note`/review. Never throws (best-effort), never
+ * changes the exit code — it only writes advisory text to stderr (visible to the model).
+ */
+function reflectionSweep(root) {
+  try {
+    const fd = join(root, '.arbiter', 'findings');
+    if (!existsSync(fd)) return;
+    let count = 0;
+    for (const f of readdirSync(fd)) {
+      if (!f.endsWith('.jsonl')) continue;
+      const raw = readFileSync(join(fd, f), 'utf-8');
+      count += raw.split('\n').filter((l) => l.trim().length > 0).length;
+    }
+    if (count === 0) return;
+    process.stderr.write(
+      `[arbiter] REFLECTION SWEEP: ${count} undrained finding${count === 1 ? '' : 's'} in .arbiter/findings/.\n` +
+      `Capture anything seen-but-unrecorded with \`arbiter note\`, then review/drain the spool before wrapping up.\n`,
+    );
+  } catch {
+    // Best-effort nudge — never block the stop on a sweep failure.
+  }
+}
+
+/** Concatenated text of the last assistant message, or null if unreadable. */
+function latestAssistantText(transcriptPath) {
+  if (typeof transcriptPath !== 'string' || transcriptPath.length === 0) return null;
+  let raw;
+  try {
+    raw = readFileSync(transcriptPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  let last = null;
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let obj;
+    try {
+      obj = JSON.parse(trimmed);
+    } catch {
+      continue; // skip a partially-written trailing line
+    }
+    if (obj && obj.type === 'assistant') last = obj;
+  }
+  if (last === null) return null;
+  const content = last.message && Array.isArray(last.message.content) ? last.message.content : [];
+  return content
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n');
+}
+
+// Fail-visible backstop: an *unexpected* crash exits 1 (a non-blocking Stop-hook
+// notice — the agent can still stop, but the failure is surfaced, never swallowed).
+// Deliberate exit(0)/exit(2) decisions inside main() are unaffected.
+try {
+  main();
+} catch (err) {
+  process.stderr.write(`[stop-evidence-guard] unexpected error: ${err?.message ?? err} — allowing stop\n`);
+  process.exit(1);
+}

package/dist/templates/claude/hooks/stop-finding-loss.mjs.ejs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Arbiter hook: finding-loss detector (E6b, #1948, design doc §E6b).
+// Fires on: Stop
+// Exit 2 (hard grading only): re-prompts the model to persist findings before stopping.
+// Exit 0: advisory (soft grading) or nothing to flag.
+//
+// WIRED (OD-14, 2026-07-17): registered in .claude/settings.json's Stop chain
+// (after stop-evidence-guard.mjs), advisory by default (exit 0 nudge, never
+// blocks). Hard grading — exit 2 re-prompt — is opt-in via
+// ARBITER_FINDING_LOSS_HARD=1; see the CLAUDE.md hooks table row for
+// stop-finding-loss.mjs and docs/design/anti-context-rot-enforcers.md §E6b for
+// the hardness-classification rationale.
+//
+// Detects the R1 signature at session scale: a session that dispatched >= 2
+// research sub-agents (Task/Agent tool_use blocks) but persisted NOTHING — no
+// .arbiter/findings/*.jsonl lines, no .arbiter/evidence/agent-returns/ files —
+// since session start. Distinct from stop-evidence-guard.mjs's reflectionSweep,
+// which nudges to drain findings already in the spool; this detects that ZERO
+// were ever captured.
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { getRepoRoot } from './lib.mjs'
+
+/** Parses the Stop transcript JSONL, returning { dispatchCount, sessionStartMs } or null. */
+function parseTranscript(transcriptPath) {
+  if (typeof transcriptPath !== 'string' || transcriptPath.length === 0) return null
+  let raw
+  try {
+    raw = readFileSync(transcriptPath, 'utf-8')
+    // FAIL-OPEN-INTENT: transcript path missing/unreadable — treat as "no signal" so the caller stands down instead of crashing the Stop hook.
+  } catch {
+    return null
+  }
+  let dispatchCount = 0
+  let sessionStartMs = null
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) continue
+    let obj
+    try {
+      obj = JSON.parse(trimmed)
+      // FAIL-OPEN-INTENT: a partially-written trailing transcript line is expected during a live session; skip it rather than aborting the whole parse.
+    } catch {
+      continue
+    }
+    if (sessionStartMs === null && typeof obj.timestamp === 'string') {
+      const ms = Date.parse(obj.timestamp)
+      if (!Number.isNaN(ms)) sessionStartMs = ms
+    }
+    const blocks =
+      obj?.message && Array.isArray(obj.message.content) ? obj.message.content : []
+    for (const b of blocks) {
+      if (b && b.type === 'tool_use' && (b.name === 'Task' || b.name === 'Agent')) dispatchCount++
+    }
+  }
+  if (sessionStartMs === null) return null
+  return { dispatchCount, sessionStartMs }
+}
+
+/** Counts JSONL lines with ts >= sinceMs across .arbiter/findings/*.jsonl. */
+function countFindingsSince(root, sinceMs) {
+  const dir = join(root, '.arbiter', 'findings')
+  if (!existsSync(dir)) return 0
+  let count = 0
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.jsonl')) continue
+    let raw
+    try {
+      raw = readFileSync(join(dir, f), 'utf-8')
+      // FAIL-OPEN-INTENT: a findings file can be deleted/rotated between readdir and read; skip it, one missing spool file must not abort the count.
+    } catch {
+      continue
+    }
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim()
+      if (trimmed.length === 0) continue
+      try {
+        const entry = JSON.parse(trimmed)
+        const ms = Date.parse(entry.ts)
+        if (!Number.isNaN(ms) && ms >= sinceMs) count++
+        // FAIL-OPEN-INTENT: a malformed JSONL finding line must not abort the count — skip and keep scanning.
+      } catch {
+        void 0
+      }
+    }
+  }
+  return count
+}
+
+/** Counts files under .arbiter/evidence/agent-returns/ with mtime >= sinceMs. */
+function countAgentReturnsSince(root, sinceMs) {
+  const dir = join(root, '.arbiter', 'evidence', 'agent-returns')
+  if (!existsSync(dir)) return 0
+  let count = 0
+  const walk = (d) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, entry.name)
+      if (entry.isDirectory()) {
+        walk(p)
+      } else if (entry.isFile()) {
+        try {
+          if (statSync(p).mtimeMs >= sinceMs) count++
+          // FAIL-OPEN-INTENT: the file can be removed between readdir and stat (concurrent writer); skip it rather than aborting the walk.
+        } catch {
+          void 0
+        }
+      }
+    }
+  }
+  try {
+    walk(dir)
+    // FAIL-OPEN-INTENT: a directory scan error (permissions/race) must not crash the Stop hook — return the partial count so far.
+  } catch {
+    void 0
+  }
+  return count
+}
+
+function main() {
+  let input = {}
+  try {
+    input = JSON.parse(readFileSync(0, 'utf-8')) ?? {}
+    // FAIL-OPEN-INTENT: unreadable/non-JSON stdin — same stand-down posture as stop-evidence-guard.mjs; a guard that cannot read the Stop payload must not block the stop.
+  } catch {
+    process.exit(0)
+  }
+
+  // Re-entry guard: exit 2 re-prompts the model with this hook still active. If it
+  // fired again we would loop forever, so always allow the stop on re-entry.
+  if (input.stop_hook_active === true) process.exit(0)
+
+  const parsed = parseTranscript(input.transcript_path)
+  if (parsed === null) process.exit(0) // unreadable transcript — stand down (FAIL-OPEN-INTENT)
+
+  const { dispatchCount, sessionStartMs } = parsed
+  if (dispatchCount < 2) process.exit(0) // nothing to flag — fewer than 2 research dispatches
+
+  const root = getRepoRoot()
+  const persisted =
+    countFindingsSince(root, sessionStartMs) + countAgentReturnsSince(root, sessionStartMs)
+  if (persisted > 0) process.exit(0) // at least one artifact was captured — not a total loss
+
+  const HARD_GRADING = process.env.ARBITER_FINDING_LOSS_HARD === '1'
+  const message =
+    `[arbiter] FINDING LOSS: ${dispatchCount} research agent${dispatchCount === 1 ? '' : 's'} ` +
+    `returned; nothing was persisted — write \`arbiter note\` / record envelopes before stopping.\n`
+
+  if (HARD_GRADING) {
+    process.stderr.write(message)
+    process.exit(2)
+  }
+  process.stderr.write(message) // advisory: soft grading always exits 0
+  process.exit(0)
+}
+
+// Top-level guard: an unexpected crash in main() must not silently fall through to the
+// shell's default success code with no explanation, nor hard-block a stop this advisory
+// hook was never meant to gate — surface the error to stderr and exit 0 (fail-open).
+try {
+  main()
+} catch (err) {
+  process.stderr.write(
+    `[arbiter] FINDING LOSS: unexpected error — ${err instanceof Error ? err.message : String(err)}\n`,
+  )
+  // FAIL-OPEN-INTENT: a crash in this advisory hook must not hard-block the Stop it does not own; surface and stand down.
+  process.exit(0)
+}

package/dist/templates/claude/hooks/wiki-on-commit.mjs.ejs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Arbiter hook: incremental wiki regeneration after commits that touch docs/ (INV-116)
+// Fires on: PostToolUse → Bash (git commit)
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } 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();
+
+// Only act on git commit commands
+if (!/^git commit/.test(command)) process.exit(0);
+
+// Check if any docs/ files changed in the last commit
+const diff = spawnSync('git', ['diff', '--name-only', 'HEAD~1', 'HEAD', '--', 'docs/'], {
+  encoding: 'utf-8',
+});
+const changedDocs = (diff.stdout ?? '').trim().split('\n').filter((f) => f.endsWith('.md'));
+
+// No docs/ changes — skip wiki regen
+if (changedDocs.length === 0) process.exit(0);
+
+// wiki/ must exist (skip if not yet bootstrapped)
+const wikiDir = join(process.cwd(), 'wiki');
+if (!existsSync(wikiDir)) process.exit(0);
+
+// Incremental regeneration for changed source docs
+const result = spawnSync('node', ['scripts/gen-wiki.mjs', '--changed'], {
+  encoding: 'utf-8',
+  stdio: 'inherit',
+});
+
+if (result.status !== 0) {
+  process.stderr.write('[arbiter] wiki-on-commit: gen-wiki.mjs --changed failed\n');
+  process.exit(1);
+}

package/dist/templates/claude/knowledge-map.json.ejs

@@ -0,0 +1,26 @@
+{
+  "project": <%- JSON.stringify(projectName) %>,
+  "detected_lanes": <%- JSON.stringify(lanes) %>,
+  "tracks": {
+    "frontend": {
+      "signal_paths": ["src/", "web/", "frontend/", "*.tsx", "*.jsx", "*.vue", "*.svelte", "*.css", "*.scss"],
+      "required_docs": ["docs/INDEX.md"],
+      "optional_docs": ["docs/METHOD/FRONTEND_CONTEXT.md"]
+    },
+    "backend": {
+      "signal_paths": ["src/", "api/", "backend/", "server/", "cmd/", "*.go", "*.py", "*.java", "*.rs", "*.rb"],
+      "required_docs": ["docs/INDEX.md"],
+      "optional_docs": ["docs/METHOD/BACKEND_CONTEXT.md"]
+    },
+    "docs": {
+      "signal_paths": ["docs/", "*.md"],
+      "required_docs": ["docs/INDEX.md"],
+      "optional_docs": []
+    }
+  },
+  "minimum_startup_set": [
+    "AGENTS.md",
+    "docs/INDEX.md",
+    ".claude/knowledge-map.json"
+  ]
+}

package/dist/templates/claude/rules/05-agent-lifecycle.md

@@ -0,0 +1,7 @@
+# Agent Lifecycle Rule
+
+When creating, modifying, or removing sub-agents:
+
+1. Update the agent file in `.claude/agents/<name>.md`
+2. Update this rules file if the agent affects always-loaded rules
+3. Document the change in `docs/adr/` if the change is architectural

package/dist/templates/claude/rules/25-todo-folder-policy.md

@@ -0,0 +1,5 @@
+# TODO Policy
+
+- Every TODO comment in source code MUST reference a task ID: `TODO(#NNN): description`
+- Bare `TODO` or `TODO: description` without a task ID is a gate violation (INV-21)
+- Enforced by the `check-no-orphan-todo.mjs` post-edit hook

package/dist/templates/claude/rules/40-context-economy.md

@@ -0,0 +1,32 @@
+# Context Economy
+
+## Principle
+
+Read the minimum context needed for the current task. Every unnecessary file read wastes tokens and slows responses.
+
+## Minimum Startup Set
+
+Every task reads, regardless of track:
+
+- `AGENTS.md` (invariants + governance)
+- `docs/INDEX.md` (generated doc index)
+- `.claude/knowledge-map.json` (machine-readable track routing)
+- The specific file(s) the task touches
+
+## Track Routing
+
+Detect your track from the task's target paths before reading broad context.
+Full routing table is in `.claude/knowledge-map.json`.
+
+| Track    | Signal paths                         | Load additionally                           |
+| -------- | ------------------------------------ | ------------------------------------------- |
+| frontend | `*.tsx`, `*.vue`, `*.svelte`, `web/` | `docs/METHOD/FRONTEND_CONTEXT.md` if exists |
+| backend  | `*.go`, `*.py`, `*.java`, `api/`     | `docs/METHOD/BACKEND_CONTEXT.md` if exists  |
+| docs     | `docs/`, `*.md`                      | `docs/INDEX.md` only                        |
+
+## Rules
+
+- Do not speculatively read all files in a directory.
+- Do not re-read files already in context.
+- Do not load unrelated track docs for a focused single-track task.
+- When track is unknown, load the minimum startup set and ask rather than reading broadly.

package/dist/templates/claude/rules/45-mcp-fallback.md

@@ -0,0 +1,25 @@
+# MCP Fallback Determinism
+
+When an MCP tool is unavailable (not found, server unreachable, timeout), do NOT halt or prompt the user — switch immediately to the approved fallback and report the deviation.
+
+## Approved Fallback Equivalents
+
+| MCP Tool            | Approved Fallback                                    |
+| ------------------- | ---------------------------------------------------- |
+| GitHub MCP          | `gh` CLI (`gh issue view`, `gh pr list`, `gh api …`) |
+| File-system MCP     | Built-in Read / Edit / Write tools                   |
+| Browser MCP         | `curl` or `wget` for simple HTTP fetches             |
+| Search / vector MCP | `grep`, `find`, or `git log --grep`                  |
+
+## Protocol
+
+1. **Switch** to the approved fallback without asking.
+2. **Report** the deviation inline:
+   ```
+   [mcp-fallback] <tool-name> unavailable — using <fallback>
+   ```
+3. **Never silently downgrade.** If no safe fallback exists, surface an error to the user rather than proceeding without the required capability.
+
+## Rationale
+
+Silent fallback causes non-deterministic session behavior that is hard to reproduce and audit. Explicit fallback + deviation report keeps transcripts auditable and lets the operator decide whether to restore MCP access.