@getarbiter/cli 0.5.0

package/dist/templates/scripts/debt-report.mjs.ejs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// debt-report.mjs — generated by arbiter
+// Compares current debt metrics against scripts/debt-baseline.json.
+// Run from project root: node scripts/debt-report.mjs [--gate] [--require-improvement]
+// --gate: exit non-zero if any metric regressed vs baseline
+// --require-improvement: exit non-zero if no metric improved (L3 mode)
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { collectMetrics, countTodos } from './debt-lib.mjs'
+
+function optionValue(name) {
+  const index = process.argv.indexOf(name)
+  if (index === -1) return undefined
+  const value = process.argv[index + 1]
+  if (!value || value.startsWith('-')) {
+    process.stderr.write(`[arbiter] ${name} requires a value\n`)
+    process.exit(2)
+  }
+  return value
+}
+
+const gateMode = process.argv.includes('--gate')
+const requireImprovement = process.argv.includes('--require-improvement')
+const coverageSummaryPath = optionValue('--coverage-summary')
+const coverageStartedAtRaw = optionValue('--coverage-started-at')
+const coverageStartedAt = coverageStartedAtRaw === undefined ? undefined : Number(coverageStartedAtRaw)
+if (coverageStartedAtRaw !== undefined && !Number.isFinite(coverageStartedAt)) {
+  process.stderr.write('[arbiter] --coverage-started-at must be a finite epoch timestamp\n')
+  process.exit(2)
+}
+if (coverageSummaryPath !== undefined && coverageStartedAt === undefined) {
+  process.stderr.write('[arbiter] --coverage-summary requires --coverage-started-at for stale-report protection\n')
+  process.exit(2)
+}
+const cwd = process.cwd()
+const BASELINE_FILE = resolve(cwd, 'scripts/debt-baseline.json')
+
+// ─── Load baseline ────────────────────────────────────────────────────────────
+if (!existsSync(BASELINE_FILE)) {
+<% if (isL3Plus) { %>
+  process.stderr.write('[arbiter] GATE FAIL: debt-baseline.json not found. Run: node scripts/capture-debt-baseline.mjs\n')
+  process.exit(1);
+<% } else { %>
+  console.warn(
+    '[arbiter] WARN: debt-baseline.json not found.\n  Run: node scripts/capture-debt-baseline.mjs\n  Until baseline is captured, debt ratchet is INACTIVE.',
+  )
+  process.exit(0)
+<% } %>
+}
+
+const rawBaseline = JSON.parse(readFileSync(BASELINE_FILE, 'utf-8'))
+
+// ─── Schema version check ─────────────────────────────────────────────────────
+if (rawBaseline.version !== 2) {
+  const ver = rawBaseline.version ?? 'unknown'
+  process.stdout.write(
+    `[arbiter] Baseline is schema v${ver}; run: node scripts/capture-debt-baseline.mjs to migrate to v2.\n`,
+  )
+  process.exit(0)
+}
+
+const baseline = rawBaseline
+
+// ─── Collect current metrics ──────────────────────────────────────────────────
+// collectionErrors receives tool-RAN-but-collection-failed events (distinct
+// from tool-not-installed soft-skips). In --gate mode these are hard failures:
+// treating them as "missing tool" would let fileset/config drift silently
+// disable a ratchet metric (#1286, fail-closed CANON-22).
+const collectionErrors = []
+const current = collectMetrics(cwd, collectionErrors, {
+  ...(coverageSummaryPath !== undefined ? { coverageSummaryPath } : {}),
+  ...(coverageStartedAt !== undefined ? { coverageStartedAt } : {}),
+})
+current.todoCount = { value: countTodos(cwd), unit: 'count', direction: 'lower-is-better' }
+
+if (collectionErrors.length > 0) {
+  for (const e of collectionErrors) {
+    process.stdout.write(`[arbiter] collection FAILURE for ${e.metric}: ${e.reason}\n`)
+  }
+  if (gateMode) {
+    process.stdout.write('[arbiter] ❌ debt gate FAILED: metric collection error (fail-closed)\n')
+    process.exit(1)
+  }
+}
+
+// Measurement-noise tolerance for v8-coverage metrics (#2253): CI's v8
+// collector measures ~0.2pp lower than a locally-captured baseline on the
+// same code (platform/timing variance in which lines v8 marks covered), so a
+// strict any-decrease-is-a-regression comparison is structurally prone to a
+// first-CI false regression the moment the baseline is captured on a
+// different machine than CI (observed: coverageLine -0.16pp, coverageBranch
+// -0.22pp — both well under a real change). check-coverage-ratchet.mjs
+// (#1483) carries this exact TOLERANCE=0.4 pp noise floor for the
+// same v8-jitter reason; mirroring its value here is parity, not invention.
+const COVERAGE_NOISE_TOLERANCE_PP = 0.4
+const NOISE_TOLERANT_METRICS = new Set(['coverageLine', 'coverageBranch'])
+
+// ─── Compare ──────────────────────────────────────────────────────────────────
+const rows = []
+let regressions = 0
+let improvements = 0
+
+for (const [key, base] of Object.entries(baseline.metrics)) {
+  const curr = current[key]
+  if (!curr) {
+    // Tool missing on this machine — soft warn, never fail gate
+    rows.push({
+      key,
+      base: base.value,
+      curr: 'N/A',
+      delta: '?',
+      status: '⚠️  missing tool',
+      unit: base.unit,
+      items: base.items ?? [],
+    })
+    continue
+  }
+  const delta = curr.value - base.value
+  const tolerance = NOISE_TOLERANT_METRICS.has(key) ? COVERAGE_NOISE_TOLERANCE_PP : 0
+  let status
+  if (base.direction === 'higher-is-better') {
+    if (curr.value > base.value) {
+      status = '✅ improved'
+      improvements++
+    } else if (curr.value < base.value - tolerance) {
+      status = '❌ regressed'
+      regressions++
+    } else if (curr.value < base.value) {
+      status = '➡️  unchanged (within noise tolerance)'
+    } else {
+      status = '➡️  unchanged'
+    }
+  } else {
+    if (curr.value < base.value) {
+      status = '✅ improved'
+      improvements++
+    } else if (curr.value > base.value) {
+      status = '❌ regressed'
+      regressions++
+    } else {
+      status = '➡️  unchanged'
+    }
+  }
+  rows.push({
+    key,
+    base: base.value,
+    curr: curr.value,
+    delta: delta > 0 ? `+${delta.toFixed(1)}` : delta.toFixed(1),
+    status,
+    unit: base.unit,
+    items: base.items ?? [],
+  })
+}
+
+// New metrics not yet in baseline — informational only
+for (const [key, curr] of Object.entries(current)) {
+  if (!baseline.metrics[key]) {
+    rows.push({
+      key,
+      base: 'new',
+      curr: curr.value,
+      delta: 'new',
+      status: '✨ new metric',
+      unit: curr.unit,
+      items: [],
+    })
+  }
+}
+
+// ─── Render report ────────────────────────────────────────────────────────────
+process.stdout.write('\n## Debt Ratchet Report\n\n')
+process.stdout.write(
+  `Baseline: v${baseline.version} — captured ${baseline.capturedAt} @ ${baseline.commit} | archetype: ${baseline.archetype}\n\n`,
+)
+process.stdout.write('| Metric | Baseline | Current | Delta | Status |\n')
+process.stdout.write('|--------|----------|---------|-------|--------|\n')
+for (const r of rows) {
+  const suffix = r.unit === 'percent' ? '%' : ''
+  const baseStr = typeof r.base === 'number' ? `${r.base}${suffix}` : r.base
+  const currStr = typeof r.curr === 'number' ? `${r.curr}${suffix}` : r.curr
+  process.stdout.write(`| ${r.key} | ${baseStr} | ${currStr} | ${r.delta} | ${r.status} |
+`)
+  if (r.items && r.items.length > 0) {
+    process.stdout.write(`|   ↳ items | \`${r.items.join('`, `')}\` | | | |
+`)
+  }
+}
+process.stdout.write('\n')
+
+// ─── Gate enforcement ─────────────────────────────────────────────────────────
+if (gateMode && regressions > 0) {
+  console.error(`[arbiter] GATE FAIL: ${regressions} metric(s) regressed vs baseline.`)
+  process.exit(1)
+}
+if (requireImprovement && improvements === 0) {
+  console.error('[arbiter] GATE FAIL: No metrics improved (--require-improvement mode).')
+  process.exit(1)
+}
+process.exit(0)

package/dist/templates/scripts/domain-api-surface.json.ejs

@@ -0,0 +1,23 @@
+{
+  "schema": "arbiter-domain-api-surface-v1",
+  "resources": [
+    {
+      "resource": "Example",
+      "domainFields": [
+        {
+          "name": "id",
+          "persisted": true,
+          "inRequestSchema": false,
+          "inResponseSchema": true,
+          "note": "Server-assigned; never in create/update request body"
+        },
+        {
+          "name": "name",
+          "persisted": true,
+          "inRequestSchema": true,
+          "inResponseSchema": true
+        }
+      ]
+    }
+  ]
+}

package/dist/templates/scripts/done-evidence.mjs.ejs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+// <%= projectName %> — done-evidence CLI (INV-38)
+// Captures SHA-256 of load-bearing source files + gate state into
+//   .arbiter/evidence/done/<sanitized-task>.json
+// Guards against "done" claims when source drifted after gate ran.
+//
+// Usage: node scripts/done-evidence.mjs
+//
+// Workflow:
+//   1. Runs the L3 gate (node scripts/check-all.mjs L3)
+//   2. If green: captures SHA-256 of all files in evidence-files.json
+//      and atomically publishes the v2 receipt
+//   3. If red: prints failures, exits 1
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  readdirSync,
+  statSync,
+  realpathSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, extname, relative, resolve, isAbsolute } from 'node:path';
+import { verifyGateEvidenceFile } from './lib/gate-evidence.mjs';
+
+// Anchor all paths to the repo root so the script is CWD-independent
+const _rootResult = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' });
+if (_rootResult.status !== 0) {
+  process.stderr.write('[done-evidence] ERROR: not inside a git repository\n');
+  process.exit(1);
+}
+process.chdir(_rootResult.stdout.trim());
+
+const EVIDENCE_PATH = '.claude/.last-done-evidence.json';
+const CONFIG_PATH = 'evidence-files.json';
+const STATUS_PATH = '.claude/.task/status.json';
+
+function sanitizeTaskId(raw) {
+  const cleaned = String(raw).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+  return cleaned.length > 0 ? cleaned : 'unknown';
+}
+
+let taskId = 'unknown';
+if (existsSync(STATUS_PATH)) {
+  try {
+    taskId = JSON.parse(readFileSync(STATUS_PATH, 'utf-8')).taskId || 'unknown';
+  } catch (err) {
+    // Unknown task identity: revoke the shared marker so no old receipt can revive.
+    rmSync('.arbiter/gate-pass.json', { force: true });
+    process.stderr.write(`[done-evidence] ERROR: could not read task identity — ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+const DONE_RECEIPT_PATH = join('.arbiter', 'evidence', 'done', `${sanitizeTaskId(taskId)}.json`);
+const LEGACY_PATH = join('.arbiter', 'evidence', 'done', 'legacy', `${sanitizeTaskId(taskId)}.json`);
+
+function writeReceipt(state, details = {}) {
+  const dir = join('.arbiter', 'evidence', 'done');
+  const temp = `${DONE_RECEIPT_PATH}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(temp, JSON.stringify({ version: 2, task_id: taskId, state, recorded_at: new Date().toISOString(), ...details }) + '\n', 'utf-8');
+    renameSync(temp, DONE_RECEIPT_PATH);
+    return true;
+  } catch (e) {
+    process.stderr.write(`[done-evidence] ERROR: could not write ${state} receipt — ${e.code ?? e.message}\n`);
+    return false;
+  }
+}
+
+function fail(message) {
+  writeReceipt('failed');
+  process.stderr.write(message);
+  process.exit(1);
+}
+
+// A new attempt must invalidate an older PASS before any config or gate work.
+if (!writeReceipt('pending')) process.exit(1);
+
+if (existsSync(EVIDENCE_PATH)) {
+  try {
+    mkdirSync(join('.arbiter', 'evidence', 'done', 'legacy'), { recursive: true });
+    renameSync(EVIDENCE_PATH, LEGACY_PATH);
+  } catch (e) {
+    fail(`[done-evidence] ERROR: could not migrate legacy evidence — ${e.code ?? e.message}\n`);
+  }
+}
+
+/** Read evidence-files.json config or exit 1 on corrupt JSON. */
+function loadConfig() {
+  if (existsSync(CONFIG_PATH)) {
+    let raw;
+    try {
+      raw = readFileSync(CONFIG_PATH, 'utf-8');
+    } catch (e) {
+      fail(`[done-evidence] ERROR: could not read evidence-files.json — ${e.code ?? e.message}\n`);
+    }
+    try {
+      return JSON.parse(raw);
+    } catch (e) {
+      fail(
+        `[done-evidence] ERROR: evidence-files.json is invalid JSON — ${e.message}\n` +
+          '[done-evidence] Fix or delete evidence-files.json before running done-evidence.\n',
+      );
+    }
+  }
+  return {
+    pin_dirs: ['src'],
+    pin_extensions: ['.ts', '.tsx', '.mjs', '.js'],
+    exclude_dirs: ['node_modules', 'dist', 'build', 'coverage', '.git'],
+  };
+}
+
+const PHYSICAL_ROOT = realpathSync(process.cwd())
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+function configError(message) { fail(`[done-evidence] ERROR: invalid evidence-files.json — ${message}\n`) }
+function checkedRelativeDir(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') configError(`${field} entries must be non-empty strings`)
+  if (isAbsolute(value)) configError(`${field} entries must be relative to the checkout`)
+  const absolute = resolve(process.cwd(), value)
+  const rel = relative(PHYSICAL_ROOT, absolute)
+  if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(rel)) configError(`${field} escapes the checkout`)
+  return absolute
+}
+function assertPhysicalPath(path) {
+  const relativePath = relative(process.cwd(), path)
+  const expected = resolve(PHYSICAL_ROOT, relativePath)
+  let physical
+  try { physical = realpathSync(path) } catch (e) { fail(`[done-evidence] ERROR: could not resolve ${path} — ${e.code ?? e.message}\n`) }
+  if (physical !== expected) fail(`[done-evidence] ERROR: symbolic link or path escape in pinned tree: ${path}\n`)
+}
+function commandArgv(command) {
+  return Array.isArray(command) ? command : command.trim().split(/\s+/)
+}
+
+function validateConfig(config) {
+  if (!isObject(config)) configError('top level must be an object')
+  if ('version' in config && config.version !== 1) configError('unsupported version')
+  for (const field of ['pin_dirs', 'pin_extensions', 'exclude_dirs']) {
+    if (field in config && !Array.isArray(config[field])) configError(`${field} must be an array`)
+  }
+  const dirs = config.pin_dirs ?? ['src']
+  const exts = config.pin_extensions ?? ['.ts', '.tsx', '.mjs', '.js']
+  const excludes = config.exclude_dirs ?? []
+  if (!dirs.every((v) => typeof v === 'string' && v.trim())) configError('pin_dirs entries must be non-empty strings')
+  dirs.forEach((dir) => checkedRelativeDir(dir, 'pin_dirs'))
+  if (!exts.every((v) => typeof v === 'string' && /^\.[A-Za-z0-9]+$/.test(v))) configError('pin_extensions entries must be extensions such as .ts')
+  if (!excludes.every((v) => typeof v === 'string' && v.trim() && !/[\\/]/.test(v) && v !== '.' && v !== '..')) configError('exclude_dirs entries must be directory names')
+  if ('reality_contact' in config) {
+    const rc = config.reality_contact
+    if (!isObject(rc)) configError('reality_contact must be an object')
+    if (typeof rc.archetype !== 'string' || !rc.archetype.trim()) configError('reality_contact.archetype must be a non-empty string')
+    if (typeof rc.required !== 'boolean') configError('reality_contact.required must be boolean')
+    if (typeof rc.suite !== 'string' || !['live-api-e2e', 'render-smoke', 'visual-regression'].includes(rc.suite)) configError('reality_contact.suite is unsupported')
+    if (!(typeof rc.command === 'string' || (Array.isArray(rc.command) && rc.command.length > 0 && rc.command.every((v) => typeof v === 'string' && v.trim())))) configError('reality_contact.command must be a string or argv array')
+    if (rc.required && ((typeof rc.command === 'string' && !rc.command.trim()) || (Array.isArray(rc.command) && rc.command.length === 0))) configError('reality_contact.command is required when reality_contact.required is true')
+  }
+  return config
+}
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', '.git',
+  'target', 'vendor', '__pycache__', '.venv']);
+
+/** Recursively walk a directory; call fn(absolutePath) for each file. */
+function walk(dir, fn, excludeDirs) {
+  const exclude = new Set([...SKIP_DIRS, ...(excludeDirs ?? [])]);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch (e) {
+    fail(`could not read directory ${dir} (${e.code ?? e.message})`);
+  }
+  for (const entry of entries) {
+    if (exclude.has(entry)) continue;
+    const full = join(dir, entry);
+    let stat;
+    try {
+      assertPhysicalPath(full);
+      stat = statSync(full);
+    } catch (e) {
+      fail(`could not stat ${full} (${e.code ?? e.message})`);
+    }
+    if (stat.isDirectory()) {
+      walk(full, fn, excludeDirs);
+    } else {
+      fn(full);
+    }
+  }
+}
+
+/** SHA-256 of file contents; returns null and logs WARN on read error. */
+function sha256File(absPath) {
+  try {
+    return createHash('sha256').update(readFileSync(absPath)).digest('hex');
+  } catch (e) {
+    fail(`could not hash ${absPath} (${e.code ?? e.message})`);
+  }
+}
+
+// ─── Step 1: Read config, then run L3 gate ────────────────────────────────────
+
+const config = validateConfig(loadConfig());
+
+const markerPath = join('.arbiter', 'gate-pass.json');
+let markerVerdict = verifyGateEvidenceFile(markerPath, { root: process.cwd(), minLevel: 'L3', taskId });
+if (markerVerdict.ok) {
+  process.stdout.write('[done-evidence] Reusing valid L3 gate evidence.\n');
+} else {
+  process.stdout.write('[done-evidence] Running L3 gate...\n');
+  const gate = spawnSync('node', ['scripts/check-all.mjs', 'L3'], {
+    stdio: 'inherit',
+    shell: false,
+  });
+  if (gate.error) {
+    fail(
+      `\n[done-evidence] ERROR: could not launch gate command — ${gate.error.message}\n` +
+      `  Ensure 'node' is in PATH and 'scripts/check-all.mjs' exists.\n`,
+    );
+  }
+  if (gate.status === null) {
+    fail(
+      `\n[done-evidence] Gate process killed by signal (${gate.signal ?? 'unknown'}) — possibly OOM or timeout.\n`,
+    );
+  }
+  if (gate.status !== 0) {
+    fail('\n[done-evidence] Gate FAILED — fix the issues above before capturing done evidence.\n');
+  }
+  markerVerdict = verifyGateEvidenceFile(markerPath, { root: process.cwd(), minLevel: 'L3', taskId });
+  if (!markerVerdict.ok) fail(`[done-evidence] ERROR: L3 marker is invalid after gate: ${markerVerdict.reason}\n`);
+}
+
+// ─── Step 1.5: Reality-contact suite (archetype-aware, #1368/#1703, anti-fake-green) ─
+// For archetypes that ship a running artifact, exercise the live binary and record
+// HONEST reality-contact evidence — never fabricate `passed:true`. Configurable via
+// evidence-files.json `reality_contact`: { archetype, required, suite, command }.
+// Default (backend-web-db): the live api-e2e runner (tests/api/run.sh) the api-e2e
+// generator emits for every service language — boots the real binary in-test.
+// Non-service archetypes: required:false (no live artifact to exercise).
+const DEFAULT_RC = {
+  archetype: '<%= archetype %>',
+  required: <% if (archetype === 'backend-web-db' || archetype === 'frontend-spa') { %>true<% } else { %>false<% } %>,
+  suite: '<% if (archetype === 'frontend-spa') { %>render-smoke<% } else { %>live-api-e2e<% } %>',
+  command: <% if (archetype === 'backend-web-db') { %>'./tests/api/run.sh'<% } else if (archetype === 'frontend-spa') { %>['node', 'scripts/lib/ephemeral-server.mjs', '--start', 'npm run start:test', '--test', 'npx playwright test tests/e2e/render-smoke.spec.ts', '--port', '4173']<% } else { %>''<% } %>,
+};
+const configuredRc = (config && config.reality_contact !== null && typeof config.reality_contact === 'object') ? config.reality_contact : {};
+const rcConfig = { ...DEFAULT_RC, ...configuredRc, required: DEFAULT_RC.required || configuredRc.required === true };
+
+let realityContact;
+let noOverclaim = false;
+if (rcConfig.required !== true) {
+  // Non-service archetype — no live artifact to exercise; reality contact is N/A.
+  realityContact = {
+    archetype: rcConfig.archetype,
+    required: false,
+    suite: rcConfig.suite,
+    recorded_at: new Date().toISOString(),
+    passed: null,
+    detail: 'not required for this archetype',
+  };
+  noOverclaim = true;
+} else {
+  const rcArgs = commandArgv(rcConfig.command);
+  const rcCmd = rcArgs.join(' ');
+  if (rcArgs.length === 0) {
+    fail(
+      '\n[done-evidence] ERROR: reality_contact.command is empty — cannot exercise live artifact.\n' +
+      '  Set evidence-files.json `reality_contact.command` to a suite that boots the real binary.\n',
+    );
+  }
+  process.stdout.write(`[done-evidence] Running reality-contact suite: ${rcCmd}\n`);
+  const rc = spawnSync(rcArgs[0], rcArgs.slice(1), {
+    stdio: 'inherit',
+    shell: false,
+  });
+  const rcPassed = rc.status === 0;
+  realityContact = {
+    archetype: rcConfig.archetype,
+    required: true,
+    suite: rcConfig.suite,
+    command: rcCmd,
+    recorded_at: new Date().toISOString(),
+    passed: rcPassed,
+  };
+  if (!rcPassed) {
+    fail(
+      `\n[done-evidence] Reality-contact suite FAILED (exit ${rc.status ?? 'signal:' + (rc.signal ?? '?')}) — ` +
+      `fix the failing live e2e before capturing done evidence. No fake green.\n`,
+    );
+  }
+  // Gate green + reality contact exercised + SHAs pinned below ⇒ no overclaim.
+  noOverclaim = true;
+}
+
+// ─── Step 2: Gather pinned files ─────────────────────────────────────────────
+
+const pinDirs = Array.isArray(config.pin_dirs) ? config.pin_dirs : ['src'];
+const pinExts = new Set(Array.isArray(config.pin_extensions) ? config.pin_extensions : ['.ts']);
+const excludeDirs = Array.isArray(config.exclude_dirs) ? config.exclude_dirs : [];
+
+const pinnedFiles = [];
+
+for (const dir of pinDirs) {
+  const checkedDir = checkedRelativeDir(dir, 'pin_dirs');
+  if (!existsSync(checkedDir)) continue;
+  assertPhysicalPath(checkedDir);
+  walk(checkedDir, (absPath) => {
+    if (pinExts.has(extname(absPath))) {
+      const relPath = relative(process.cwd(), absPath).replace(/\\/g, '/');
+      const sha = sha256File(absPath);
+      if (sha !== null) {
+        pinnedFiles.push({ path: relPath, sha256: sha });
+      }
+    }
+  }, excludeDirs);
+}
+
+let gateMarkerBytes;
+const finalMarkerVerdict = verifyGateEvidenceFile(markerPath, { root: process.cwd(), minLevel: 'L3', taskId });
+if (!finalMarkerVerdict.ok) fail(`[done-evidence] ERROR: L3 marker drifted after runtime checks: ${finalMarkerVerdict.reason}\n`);
+try {
+  gateMarkerBytes = readFileSync(markerPath);
+} catch (e) {
+  fail(`[done-evidence] ERROR: could not read gate-pass marker — ${e.code ?? e.message}\n`);
+}
+
+let marker;
+try {
+  marker = JSON.parse(gateMarkerBytes);
+} catch (e) {
+  fail(`[done-evidence] ERROR: gate-pass marker is invalid JSON — ${e.message}\n`);
+}
+
+if (!writeReceipt('passed', {
+  all_green: true,
+  gate_level: 'L3',
+  pinned_files: pinnedFiles,
+  reality_contact: realityContact,
+  no_overclaim: noOverclaim,
+  gate_marker_sha256: createHash('sha256').update(gateMarkerBytes).digest('hex'),
+  head_sha: marker.head_sha,
+  tree_hash: marker.tree_hash,
+  checkout_root: marker.checkout_root,
+  toolchain_fingerprint: marker.toolchain_fingerprint,
+  node_version: marker.node_version,
+})) process.exit(1);
+
+process.stdout.write(
+  `[done-evidence] Evidence captured.\n` +
+  `  task_id:           ${taskId}\n` +
+  `  pinned_files:      ${pinnedFiles.length}\n` +
+  `  reality_contact:   ${realityContact.suite} passed=${realityContact.passed}\n` +
+  `  no_overclaim:      ${noOverclaim}\n` +
+  `  written to:        ${DONE_RECEIPT_PATH}\n`,
+);