@getarbiter/cli 0.5.0

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

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// <%= projectName %> — evidence harness collector (INV-33)
+// Collects test/coverage/mutation/security metrics and writes:
+//   .evidence/SUMMARY.json  — machine-readable gate result
+//   .evidence/SUMMARY.md    — human-readable report
+// L3 gate: check-all.mjs L3 block fails when obs_gate !== "PASS"
+// Usage: node scripts/evidence-collect.mjs
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, writeFileSync, readFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Mirrors src/risk/sha-check.ts — inline so this script runs without a build step.
+function canonicalise(v) {
+  if (Array.isArray(v)) return v.map(canonicalise);
+  if (v !== null && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = canonicalise(v[k]);
+    return out;
+  }
+  return v;
+}
+function computeSummarySha(body) {
+  const { sha: _ignored, ...rest } = body;
+  return createHash('sha256').update(JSON.stringify(canonicalise(rest))).digest('hex');
+}
+
+const EVIDENCE_DIR = '.evidence';
+const MUTATION_THRESHOLD = <%= mutationThreshold || 80 %>;
+const COVERAGE_THRESHOLD = <%= coverageThreshold || 80 %>;
+
+mkdirSync(EVIDENCE_DIR, { recursive: true });
+
+const start = Date.now();
+
+/** @returns {{ total: number, passed: number, failed: number, skipped: number }} */
+function collectTestResults() {
+  const result = { total: 0, passed: 0, failed: 0, skipped: 0 };
+<% if (language === 'typescript') { %>
+  const r = spawnSync('npx', ['vitest', 'run', '--reporter=json'], { encoding: 'utf-8', shell: false });
+  try {
+    const json = JSON.parse(r.stdout || '{}');
+    result.total = json.numTotalTests ?? 0;
+    result.passed = json.numPassedTests ?? 0;
+    result.failed = json.numFailedTests ?? 0;
+    result.skipped = json.numPendingTests ?? 0;
+  } catch { /* test output not JSON-parseable, leave defaults */ }
+<% } %><% if (language === 'java' && buildTool === 'gradle') { %>
+  const r = spawnSync('./gradlew', ['test', '-q'], { encoding: 'utf-8', shell: false });
+  result.failed = r.status !== 0 ? 1 : 0;
+  result.passed = r.status === 0 ? 1 : 0;
+  result.total = 1;
+<% } %><% if (language === 'java' && buildTool === 'maven') { %>
+  const r = spawnSync('mvn', ['test', '-q'], { encoding: 'utf-8', shell: false });
+  result.failed = r.status !== 0 ? 1 : 0;
+  result.passed = r.status === 0 ? 1 : 0;
+  result.total = 1;
+<% } %><% if (language === 'rust') { %>
+  const r = spawnSync('cargo', ['test', '--', '--format', 'json'], { encoding: 'utf-8', shell: false });
+  result.failed = r.status !== 0 ? 1 : 0;
+  result.passed = r.status === 0 ? 1 : 0;
+  result.total = 1;
+<% } %><% if (language === 'python') { %>
+  const r = spawnSync('pytest', ['--tb=no', '-q'], { encoding: 'utf-8', shell: false });
+  const match = (r.stdout || '').match(/(\d+) passed(?:, (\d+) failed)?(?:, (\d+) error)?/);
+  if (match) {
+    result.passed = parseInt(match[1] ?? '0', 10);
+    result.failed = parseInt(match[2] ?? '0', 10);
+    result.total = result.passed + result.failed;
+  }
+<% } %><% if (language === 'go') { %>
+  const r = spawnSync('go', ['test', '-json', './...'], { encoding: 'utf-8', shell: false });
+  for (const line of (r.stdout || '').split('\n').filter(Boolean)) {
+    try {
+      const ev = JSON.parse(line);
+      if (ev.Action === 'pass' && ev.Test) result.passed++;
+      if (ev.Action === 'fail' && ev.Test) result.failed++;
+    } catch { /* skip */ }
+  }
+  result.total = result.passed + result.failed;
+<% } %>
+  return result;
+}
+
+/** @returns {{ line: number, branch: number }} */
+function collectCoverage() {
+<% if (language === 'typescript') { %>
+  const r = spawnSync('npx', ['vitest', 'run', '--coverage', '--coverage.reporter=json', '--reporter=silent'], {
+    encoding: 'utf-8', shell: false,
+  });
+  try {
+    const coverageJson = JSON.parse(readFileSync('coverage/coverage-summary.json', 'utf-8'));
+    const total = coverageJson.total;
+    return {
+      line: (total?.lines?.pct ?? 0) / 100,
+      branch: (total?.branches?.pct ?? 0) / 100,
+    };
+  } catch { return { line: 0, branch: 0 }; }
+<% } %><% if (language === 'java' && buildTool === 'gradle') { %>
+  spawnSync('./gradlew', ['jacocoTestReport', '-q'], { encoding: 'utf-8', shell: false });
+  return { line: 0, branch: 0 };
+<% } %><% if (language === 'java' && buildTool === 'maven') { %>
+  spawnSync('mvn', ['verify', '-Pjacoco', '-q'], { encoding: 'utf-8', shell: false });
+  return { line: 0, branch: 0 };
+<% } %><% if (language === 'rust') { %>
+  const r = spawnSync('cargo', ['tarpaulin', '--out', 'Json', '--output-dir', '.evidence'], {
+    encoding: 'utf-8', shell: false,
+  });
+  return { line: 0, branch: 0 };
+<% } %><% if (language === 'python') { %>
+  const r = spawnSync('pytest', ['--cov', '--cov-report=json:.evidence/coverage.json'], {
+    encoding: 'utf-8', shell: false,
+  });
+  try {
+    const cov = JSON.parse(readFileSync('.evidence/coverage.json', 'utf-8'));
+    return { line: (cov.totals?.percent_covered ?? 0) / 100, branch: 0 };
+  } catch { return { line: 0, branch: 0 }; }
+<% } %><% if (language === 'go') { %>
+  // Default covermode (set), NOT atomic (#2106, same class as #2104): covermode is
+  // part of Go's test-cache key, so a run pinning `atomic` shares nothing with the
+  // default-covermode coverage run in check-all.mjs over the same packages and
+  // re-executes the whole suite. This script is operator-run — no generated
+  // workflow invokes it — so it runs in the same working tree as the gate, with a
+  // warm cache, which is exactly where the pin is expensive. Statement coverage is
+  // identical between the modes; `atomic` is only required under `-race`, which
+  // collects no coverage here.
+  const r = spawnSync('go', ['test', '-coverprofile=.evidence/coverage.out', './...'], {
+    encoding: 'utf-8', shell: false,
+  });
+  const coverResult = spawnSync('go', ['tool', 'cover', '-func=.evidence/coverage.out'], {
+    encoding: 'utf-8', shell: false,
+  });
+  const match = (coverResult.stdout || '').match(/total:\s+\(statements\)\s+([\d.]+)%/);
+  return { line: match ? parseFloat(match[1]) / 100 : 0, branch: 0 };
+<% } %>
+}
+
+/** @returns {{ score: number }} */
+function collectMutationScore() {
+<% if (language === 'typescript') { %>
+  if (!existsSync('stryker.conf.json')) return { score: 0 };
+  const r = spawnSync('npx', ['stryker', 'run', '--reporters', 'json'], { encoding: 'utf-8', shell: false });
+  try {
+    const report = JSON.parse(readFileSync('reports/mutation/mutation.json', 'utf-8'));
+    const score = report.metrics?.mutationScore ?? 0;
+    return { score: score / 100 };
+  } catch { return { score: 0 }; }
+<% } %><% if (language === 'java' && buildTool === 'gradle') { %>
+  if (!existsSync('gradle/pitest.gradle')) return { score: 0 };
+  spawnSync('./gradlew', ['pitest', '-q'], { encoding: 'utf-8', shell: false });
+  return { score: 0 };
+<% } %><% if (language === 'java' && buildTool === 'maven') { %>
+  spawnSync('mvn', ['org.pitest:pitest-maven:mutationCoverage', '-q'], { encoding: 'utf-8', shell: false });
+  return { score: 0 };
+<% } %><% if (language === 'rust') { %>
+  if (!existsSync('cargo-mutants.toml')) return { score: 0 };
+  spawnSync('cargo', ['mutants', '--config', 'cargo-mutants.toml'], { encoding: 'utf-8', shell: false });
+  return { score: 0 };
+<% } %><% if (language === 'python') { %>
+  if (!existsSync('mutmut-config.toml')) return { score: 0 };
+  spawnSync('mutmut', ['run'], { encoding: 'utf-8', shell: false });
+  return { score: 0 };
+<% } %><% if (language === 'go') { %>
+  return { score: 0 };
+<% } %>
+}
+
+/** @returns {{ critical: number, high: number }} */
+function collectSecurityFindings() {
+  const r = spawnSync('trivy', ['fs', '--format', 'json', '--severity', 'CRITICAL,HIGH', '.'], {
+    encoding: 'utf-8', shell: false,
+  });
+  try {
+    const report = JSON.parse(r.stdout || '{}');
+    let critical = 0;
+    let high = 0;
+    for (const result of (report.Results ?? [])) {
+      for (const vuln of (result.Vulnerabilities ?? [])) {
+        if (vuln.Severity === 'CRITICAL') critical++;
+        if (vuln.Severity === 'HIGH') high++;
+      }
+    }
+    return { critical, high };
+  } catch {
+    return { critical: 0, high: 0 };
+  }
+}
+
+const tests = collectTestResults();
+const coverage = collectCoverage();
+const mutation = collectMutationScore();
+const security = collectSecurityFindings();
+const duration = Math.round((Date.now() - start) / 1000);
+
+const commitResult = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf-8', shell: false });
+const commit = (commitResult.stdout || '').trim();
+const headShaResult = spawnSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf-8', shell: false });
+const head_sha = (headShaResult.stdout || '').trim();
+const head_sha_short = commit;
+
+const coverageOk = coverage.line >= COVERAGE_THRESHOLD / 100;
+const mutationOk = mutation.score >= MUTATION_THRESHOLD / 100;
+const testsOk = tests.failed === 0;
+const securityOk = security.critical === 0;
+
+const obs_gate = (coverageOk && mutationOk && testsOk && securityOk) ? 'PASS' : 'FAIL';
+
+const summaryBody = {
+  // #1316: persist the resolved stack so `arbiter verify` classifies against the
+  // signed language instead of re-detecting on disk (which can yield 'unknown'
+  // and silently skip the risk matrix). Part of the SHA-signed body.
+  stack: '<%= language %>',
+  head_sha,
+  head_sha_short,
+  obs_gate,
+  timestamp: new Date().toISOString(),
+  commit,
+  duration_seconds: duration,
+  tests,
+  coverage: {
+    line: Math.round(coverage.line * 10000) / 100,
+    branch: Math.round(coverage.branch * 10000) / 100,
+  },
+  mutation: {
+    score: Math.round(mutation.score * 10000) / 100,
+    threshold: MUTATION_THRESHOLD,
+  },
+  security,
+};
+const sha = computeSummarySha(summaryBody);
+const summary = { ...summaryBody, sha };
+
+writeFileSync(join(EVIDENCE_DIR, 'SUMMARY.json'), JSON.stringify(summary, null, 2));
+
+const md = `# Evidence Summary — <%= projectName %>
+
+**Gate:** \`${obs_gate}\`
+**Commit:** \`${commit}\`
+**Timestamp:** ${summary.timestamp}
+**Duration:** ${duration}s
+
+## Tests
+- Total: ${tests.total} | Passed: ${tests.passed} | Failed: ${tests.failed} | Skipped: ${tests.skipped}
+
+## Coverage
+- Line: ${summary.coverage.line}% (threshold: ${COVERAGE_THRESHOLD}%) — ${coverageOk ? 'PASS' : 'FAIL'}
+- Branch: ${summary.coverage.branch}%
+
+## Mutation
+- Score: ${summary.mutation.score}% (threshold: ${MUTATION_THRESHOLD}%) — ${mutationOk ? 'PASS' : 'FAIL'}
+
+## Security
+- Critical: ${security.critical} | High: ${security.high} — ${securityOk ? 'PASS' : 'FAIL'}
+`;
+
+writeFileSync(join(EVIDENCE_DIR, 'SUMMARY.md'), md);
+
+process.stdout.write(`[evidence-collect] obs_gate=${obs_gate}\n`);
+process.stdout.write(`[evidence-collect] wrote ${EVIDENCE_DIR}/SUMMARY.json\n`);
+
+if (obs_gate !== 'PASS') {
+  process.stderr.write(`[evidence-collect] GATE FAIL — see ${EVIDENCE_DIR}/SUMMARY.json for details\n`);
+  process.exit(1);
+}

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Arbiter — evidence-prune.mjs
+// Manual maintenance script for .evidence/ runs.
+// Unlike evidence-rotate.mjs (automated, count-only), this supports:
+//   --keep-last=N   keep the N most recent runs (default: 5)
+//   --keep-days=D   keep runs newer than D days
+//   --dry-run       list what would be removed without deleting
+//   --yes           skip the confirmation prompt
+//
+// Usage: node scripts/evidence-prune.mjs [--dry-run] [--yes] [--keep-last=N] [--keep-days=D]
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+
+const args = process.argv.slice(2)
+function flag(name) {
+  return args.includes(name)
+}
+function opt(name) {
+  const entry = args.find((a) => a.startsWith(`${name}=`))
+  return entry ? entry.split('=')[1] : undefined
+}
+
+const DRY_RUN = flag('--dry-run')
+const YES = flag('--yes')
+const keepLast = opt('--keep-last') ? parseInt(opt('--keep-last'), 10) : 5
+const keepDays = opt('--keep-days') ? parseFloat(opt('--keep-days')) : undefined
+
+const EVIDENCE_DIR = join(process.cwd(), '.evidence')
+
+if (!existsSync(EVIDENCE_DIR)) {
+  console.log('No .evidence/ directory found — nothing to prune.')
+  process.exit(0)
+}
+
+const allRuns = readdirSync(EVIDENCE_DIR)
+  .filter((n) => n.startsWith('run-'))
+  .sort()
+
+const now = Date.now()
+const keepDaysMs = keepDays != null ? keepDays * 24 * 60 * 60 * 1000 : undefined
+
+function shouldKeep(name, index) {
+  const rank = allRuns.length - index
+  if (rank <= keepLast) return true
+  if (keepDaysMs != null) {
+    try {
+      const mtime = statSync(join(EVIDENCE_DIR, name)).mtimeMs
+      if (now - mtime < keepDaysMs) return true
+    } catch {
+      return false
+    }
+  }
+  return false
+}
+
+const toDelete = allRuns.filter((name, idx) => !shouldKeep(name, idx))
+
+if (toDelete.length === 0) {
+  console.log(`No runs to prune (keeping last ${keepLast}${keepDaysMs != null ? ` or < ${keepDays}d` : ''}).`)
+  process.exit(0)
+}
+
+console.log(`Runs to delete (${toDelete.length}):`)
+for (const name of toDelete) {
+  console.log(`  .evidence/${name}`)
+}
+
+if (DRY_RUN) {
+  console.log('\n--dry-run: nothing deleted.')
+  process.exit(0)
+}
+
+async function confirm() {
+  if (YES) return true
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise((resolve) => {
+    rl.question(`\nDelete ${toDelete.length} run(s)? Type YES to confirm: `, (answer) => {
+      rl.close()
+      resolve(answer.trim() === 'YES')
+    })
+  })
+}
+
+const ok = await confirm()
+if (!ok) {
+  console.log('Aborted.')
+  process.exit(0)
+}
+
+for (const name of toDelete) {
+  rmSync(join(EVIDENCE_DIR, name), { recursive: true, force: true })
+  console.log(`  deleted: ${name}`)
+}
+console.log(`Done. Removed ${toDelete.length} run(s), kept ${allRuns.length - toDelete.length}.`)

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// <%= projectName %> — evidence harness rotation (#91)
+// Keeps the last N evidence runs in .evidence/, removes older ones.
+// Usage: node scripts/evidence-rotate.mjs
+<% if (evidenceRetention && evidenceRetention.mode === 'external-bucket') { %>
+// WARNING: external-bucket mode is a stub.
+// Configure credentials before enabling upload:
+//   export EVIDENCE_BUCKET_SECRET=<your-secret>
+// Target bucket: <%= evidenceRetention.bucketUrl %>
+// This script currently only rotates local copies.
+// Uncomment and implement the upload block below once credentials are in place.
+<% } %>
+import { readdirSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const EVIDENCE_DIR = '.evidence';
+const KEEP_LAST = <%= (evidenceRetention && evidenceRetention.count != null) ? evidenceRetention.count : 5 %>;
+
+if (!existsSync(EVIDENCE_DIR)) {
+  process.stdout.write(`[evidence-rotate] ${EVIDENCE_DIR}/ not found — nothing to rotate\n`);
+  process.exit(0);
+}
+
+// Collect run directories (direct children only, sorted by name ascending)
+const entries = readdirSync(EVIDENCE_DIR, { withFileTypes: true })
+  .filter(e => e.isDirectory())
+  .map(e => e.name)
+  .sort();
+
+if (entries.length <= KEEP_LAST) {
+  process.stdout.write(`[evidence-rotate] ${entries.length} run(s) — within limit of ${KEEP_LAST}, nothing removed\n`);
+  process.exit(0);
+}
+
+const toRemove = entries.slice(0, entries.length - KEEP_LAST);
+for (const name of toRemove) {
+  const fullPath = join(EVIDENCE_DIR, name);
+  rmSync(fullPath, { recursive: true, force: true });
+  process.stdout.write(`[evidence-rotate] removed ${fullPath}\n`);
+}
+
+process.stdout.write(`[evidence-rotate] kept ${KEEP_LAST} most recent run(s)\n`);
+<% if (evidenceRetention && evidenceRetention.mode === 'external-bucket') { %>
+
+// ─── External bucket upload stub ─────────────────────────────────────────────
+// TODO(#91): implement upload to <%= evidenceRetention.bucketUrl %>
+// Requires: EVIDENCE_BUCKET_SECRET env var
+// if (!process.env.EVIDENCE_BUCKET_SECRET) {
+//   process.stderr.write('[evidence-rotate] WARN: EVIDENCE_BUCKET_SECRET not set — skipping upload\n');
+// } else {
+//   // upload remaining runs to bucket
+// }
+<% } %>

package/dist/templates/scripts/evidence-writer.sh.ejs

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# <%- projectName %> — TDD evidence writer (POSIX shell)
+#
+# Generated by arbiter (#973) — Port #11: bash evidence-writer for non-Node runners.
+#
+# Emits a TDD red-phase evidence bundle conforming to the same schema as
+# scripts/evidence-collect.mjs (see src/evidence/tdd.ts TddEvidenceV1).
+# Intended for minimal CI runner images that lack Node (e.g. some Java/Rust/Go
+# images) so they can still produce conformant evidence under L3 governance.
+#
+# Output: <out-dir>/tdd/<task-id>.json  (single file, idempotent overwrite)
+#
+# Schema fields (all required by TddEvidenceV1):
+#   $schemaVersion    — literal 1
+#   task_id           — "#<digits>"
+#   test_path         — path to the failing test
+#   test_commit_sha   — 40 hex chars (defaults to `git rev-parse HEAD`)
+#   test_run_log      — captured test output (from --test-run-log-file or empty)
+#   observed_failure  — non-empty failure signature (REQUIRED)
+#   recorded_at       — ISO-8601 UTC timestamp (auto-generated)
+#
+# Exit codes:
+#   0 — evidence written successfully
+#   1 — runtime error (cannot write, git failed)
+#   2 — usage error (missing/invalid arguments)
+#
+# POSIX-shell only — no bashisms, no zshisms. Tested under dash + bash.
+
+set -eu
+# POSIX `set` has no `pipefail`; guard so the script still runs under dash.
+# bash/ksh will pick it up; dash silently no-ops the failed set.
+( set -o pipefail 2>/dev/null ) && set -o pipefail || true
+
+# ─── Defaults ─────────────────────────────────────────────────────────────────
+
+TASK_ID=""
+PHASE="red"
+TEST_PATH=""
+OUT_DIR=".arbiter/evidence"
+TEST_COMMIT_SHA=""
+OBSERVED_FAILURE=""
+TEST_RUN_LOG_FILE=""
+
+# ─── Usage ────────────────────────────────────────────────────────────────────
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: evidence-writer.sh --task-id <id> --test-path <path> --observed-failure <text>
+                          [--phase <red|green|refactor>] [--out-dir <dir>]
+                          [--test-commit-sha <sha>] [--test-run-log-file <path>]
+
+Required:
+  --task-id <id>            Task id; "#" prefix added if absent (e.g. 973 or #973)
+  --test-path <path>        Path to the failing test
+  --observed-failure <text> Non-empty failure signature
+
+Optional:
+  --phase <p>               red | green | refactor (default: red)
+  --out-dir <dir>           Evidence root dir (default: .arbiter/evidence)
+  --test-commit-sha <sha>   40-hex commit sha (default: git rev-parse HEAD)
+  --test-run-log-file <p>   File whose contents become test_run_log (default: empty)
+USAGE
+}
+
+# ─── Argument parsing ─────────────────────────────────────────────────────────
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --task-id)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --task-id" >&2; exit 2; }
+      TASK_ID="$2"; shift 2 ;;
+    --phase)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --phase" >&2; exit 2; }
+      PHASE="$2"; shift 2 ;;
+    --test-path)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --test-path" >&2; exit 2; }
+      TEST_PATH="$2"; shift 2 ;;
+    --out-dir)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --out-dir" >&2; exit 2; }
+      OUT_DIR="$2"; shift 2 ;;
+    --test-commit-sha)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --test-commit-sha" >&2; exit 2; }
+      TEST_COMMIT_SHA="$2"; shift 2 ;;
+    --observed-failure)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --observed-failure" >&2; exit 2; }
+      OBSERVED_FAILURE="$2"; shift 2 ;;
+    --test-run-log-file)
+      [ $# -ge 2 ] || { echo "[evidence-writer] missing value for --test-run-log-file" >&2; exit 2; }
+      TEST_RUN_LOG_FILE="$2"; shift 2 ;;
+    -h|--help)
+      usage; exit 0 ;;
+    *)
+      echo "[evidence-writer] unknown argument: $1" >&2
+      usage
+      exit 2 ;;
+  esac
+done
+
+# ─── Validation ───────────────────────────────────────────────────────────────
+
+if [ -z "$TASK_ID" ]; then
+  echo "[evidence-writer] --task-id is required" >&2
+  usage; exit 2
+fi
+if [ -z "$TEST_PATH" ]; then
+  echo "[evidence-writer] --test-path is required" >&2
+  usage; exit 2
+fi
+if [ -z "$OBSERVED_FAILURE" ]; then
+  echo "[evidence-writer] --observed-failure is required (schema: non-empty)" >&2
+  usage; exit 2
+fi
+
+case "$PHASE" in
+  red|green|refactor) ;;
+  *)
+    echo "[evidence-writer] --phase must be one of: red, green, refactor (got: $PHASE)" >&2
+    exit 2 ;;
+esac
+
+# Normalize task_id: prepend "#" if absent. Schema regex: ^#\d+$
+case "$TASK_ID" in
+  '#'*) ;;
+  *) TASK_ID="#$TASK_ID" ;;
+esac
+# Validate the digits portion (POSIX expr returns 0 when pattern matches)
+DIGITS=$(printf '%s' "$TASK_ID" | sed 's/^#//')
+case "$DIGITS" in
+  ''|*[!0-9]*)
+    echo "[evidence-writer] --task-id must match ^#?[0-9]+\$ (got: $TASK_ID)" >&2
+    exit 2 ;;
+esac
+
+# Default test_commit_sha to git HEAD (40 hex). Fail-closed if git missing.
+if [ -z "$TEST_COMMIT_SHA" ]; then
+  if ! command -v git >/dev/null 2>&1; then
+    echo "[evidence-writer] git not on PATH and --test-commit-sha not provided" >&2
+    exit 1
+  fi
+  TEST_COMMIT_SHA=$(git rev-parse HEAD 2>/dev/null || true)
+  if [ -z "$TEST_COMMIT_SHA" ]; then
+    echo "[evidence-writer] git rev-parse HEAD failed (not a repo?)" >&2
+    exit 1
+  fi
+fi
+
+# Schema requires exactly 40 hex chars.
+case "$TEST_COMMIT_SHA" in
+  *[!0-9a-fA-F]*|"")
+    echo "[evidence-writer] test_commit_sha must be 40 hex chars (got: $TEST_COMMIT_SHA)" >&2
+    exit 2 ;;
+esac
+SHA_LEN=$(printf '%s' "$TEST_COMMIT_SHA" | wc -c | tr -d ' ')
+if [ "$SHA_LEN" -ne 40 ]; then
+  echo "[evidence-writer] test_commit_sha must be exactly 40 chars (got $SHA_LEN)" >&2
+  exit 2
+fi
+
+# Read test_run_log from file if provided; default to empty string.
+TEST_RUN_LOG=""
+if [ -n "$TEST_RUN_LOG_FILE" ]; then
+  if [ ! -f "$TEST_RUN_LOG_FILE" ]; then
+    echo "[evidence-writer] --test-run-log-file not found: $TEST_RUN_LOG_FILE" >&2
+    exit 1
+  fi
+  TEST_RUN_LOG=$(cat "$TEST_RUN_LOG_FILE")
+fi
+
+# ─── ISO-8601 UTC timestamp ───────────────────────────────────────────────────
+
+# GNU/BSD `date` both support `-u` and these specifiers.
+RECORDED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# ─── JSON-string escaping (pure shell, no jq) ─────────────────────────────────
+#
+# Escape backslash, double-quote, and control chars to satisfy RFC 8259.
+# Order matters: backslash must be escaped first so its replacement does not
+# get re-escaped by later substitutions.
+json_escape() {
+  # Pure-bash parameter expansion — deterministic across mawk/gawk/busybox-awk.
+  # Order matters: backslash must be escaped first so its replacement does not
+  # get re-escaped by later substitutions.
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\t'/\\t}"
+  s="${s//$'\f'/\\f}"
+  s="${s//$'\b'/\\b}"
+  s="${s//$'\n'/\\n}"
+  printf '%s' "$s"
+}
+
+ESC_TASK_ID=$(json_escape "$TASK_ID")
+ESC_TEST_PATH=$(json_escape "$TEST_PATH")
+ESC_TEST_COMMIT_SHA=$(json_escape "$TEST_COMMIT_SHA")
+ESC_TEST_RUN_LOG=$(json_escape "$TEST_RUN_LOG")
+ESC_OBSERVED_FAILURE=$(json_escape "$OBSERVED_FAILURE")
+ESC_RECORDED_AT=$(json_escape "$RECORDED_AT")
+
+# ─── Write evidence ───────────────────────────────────────────────────────────
+
+TDD_DIR="$OUT_DIR/tdd"
+mkdir -p "$TDD_DIR"
+OUT_FILE="$TDD_DIR/$TASK_ID.json"
+
+# Compose JSON via heredoc — single source of truth, no jq required.
+cat > "$OUT_FILE" <<JSON
+{
+  "\$schemaVersion": 1,
+  "task_id": "$ESC_TASK_ID",
+  "test_path": "$ESC_TEST_PATH",
+  "test_commit_sha": "$ESC_TEST_COMMIT_SHA",
+  "test_run_log": "$ESC_TEST_RUN_LOG",
+  "observed_failure": "$ESC_OBSERVED_FAILURE",
+  "recorded_at": "$ESC_RECORDED_AT"
+}
+JSON
+
+echo "[evidence-writer] wrote $OUT_FILE (phase=$PHASE)"