@boyingliu01/xp-gate 0.35.0 → 0.35.2

package/bin/xp-gate.js

@@ -350,6 +350,29 @@ const COMMANDS = {
     },
     usage: 'xp-gate retro [--days N] [--all] [--json] [--sprint <id>]'
   },
+  'gate-coverage': {
+    description: 'One view of compliance against every gate: PASS / DEBT / SKIP / FAIL, with debt and evidence (#636)',
+    run: subargs => {
+      const { main } = require('../lib/gate-coverage.js');
+      const { execFileSync } = require('node:child_process');
+      let headCommit;
+      try {
+        headCommit = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+      } catch {
+        headCommit = undefined;
+      }
+      process.exit(main(subargs, { headCommit }));
+    },
+    usage: 'xp-gate gate-coverage [--json] [--debt] [--strict] [--branch <name>]'
+  },
+  'rework': {
+    description: 'Report rework: first-pass rate, rounds before landing, top blocking reasons (#651)',
+    run: subargs => {
+      const { main } = require('../lib/rework.js');
+      process.exit(main(subargs));
+    },
+    usage: 'xp-gate rework [--top N] [--dir <path>] [--json]'
+  },
   'crap': {
     description: 'Rank functions by CRAP score (complexity x weak coverage) — advisory, never blocks (#404)',
     run: subargs => {

package/hooks/pre-commit

@@ -627,6 +627,98 @@ record_gate_audit() {
   disown 2>/dev/null || true
 }
 
+# ── #651: journal a blocking exit ──────────────────────────────────────────
+#
+# Failure was invisible in this repo's own history: audit.jsonl had 8,258 records
+# and essentially zero gate FAILs, because pre-commit has ~76 `exit 1` blocking
+# paths and record_gate_audit() is only reached AFTER a gate settles. The moment a
+# gate FAILs and exits, the record that would have said so is never written — so
+# `xp-gate retro` and `sprint-status --rework-check` computed rework over a
+# denominator with no failures in it, and rework trended to zero by construction.
+#
+# The trap catches the failure on its way OUT rather than adding a record call to
+# all 76 branches, which would rot the first time someone adds branch 77.
+_BLOCKING_RECORDED=""
+_record_blocking_exit() {
+  local rc=$?
+  # 0 = success, nothing to journal.
+  [ "$rc" -eq 0 ] && return 0
+  # One record per run. Without the latch, a gate that already recorded and then
+  # exited non-zero would be counted twice, halving the reported first-pass rate.
+  [ -n "$_BLOCKING_RECORDED" ] && return 0
+  _BLOCKING_RECORDED="1"
+
+  # Identify the gate that was running. Status vars are NO*-gradeable: any of
+  # FAIL/BLOCK means this gate is the reason. Latest failing gate wins, which is
+  # the one that actually called exit.
+  local _bg_id="" _bg_name="" _bg_status="" _bg_detail=""
+  local _i _st_var _st
+  for _i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13; do
+    _st_var="GATE_${_i}_STATUS"
+    _st="${!_st_var:-}"
+    case "$_st" in
+      FAIL|BLOCK)
+        # Latest failing gate wins: it is the one that actually called exit.
+        _bg_id="$_i"
+        _bg_status="$_st"
+        ;;
+    esac
+  done
+  local _bg_detail_var="GATE_${_bg_id}_DETAIL"
+  _bg_detail="${!_bg_detail_var:-}"
+
+  # Gate names for the journal. Deliberately short: this runs during shutdown.
+  case "$_bg_id" in
+    0)  _bg_name="Version Consistency" ;;
+    1)  _bg_name="Code Quality" ;;
+    2)  _bg_name="Duplicate Code" ;;
+    3)  _bg_name="Cyclomatic Complexity" ;;
+    4)  _bg_name="Principles" ;;
+    5)  _bg_name="Tests + Coverage" ;;
+    6)  _bg_name="Architecture + Boy Scout" ;;
+    7)  _bg_name="IaC Security" ;;
+    8)  _bg_name="Secret Scanning" ;;
+    9)  _bg_name="Build Integrity" ;;
+    10) _bg_name="SAST Security" ;;
+    11) _bg_name="Sprint Flow" ;;
+    12) _bg_name="File Hygiene" ;;
+    13) _bg_name="Compiler Strictness" ;;
+    *)  _bg_name="unknown" ;;
+  esac
+  [ -n "$_bg_id" ] || _bg_id="unknown"
+
+  # The reason must reach the journal or "top-N failing rules" cannot exist.
+  # Prefer the gate's own detail (it carries the rule/threshold), else the status.
+  local _bg_reason="${_bg_detail:-gate_exit_${rc}}"
+
+  local _bg_start_var="GATE_${_bg_id}_START"
+  local _bg_start="${!_bg_start_var:-}"
+  local _bg_dur="null"
+  if [ -n "$_bg_start" ]; then
+    local _bg_end
+    _bg_end=$(now_ms 2>/dev/null || echo "")
+    if [ -n "$_bg_end" ]; then
+      _bg_dur=$((_bg_end - _bg_start))
+      [ "$_bg_dur" -ge 0 ] 2>/dev/null || _bg_dur="null"
+    fi
+  fi
+
+  # Fire-and-forget, and never let journaling change the exit code.
+  {
+    run_tsx "${PROJECT_ROOT_FOR_AUDIT}/src/npm-package/lib/gate-audit.ts" record \
+      --gate-id "$_bg_id" \
+      --gate-name "$_bg_name" \
+      --passed false \
+      --issues-found 1 \
+      --duration-ms "$_bg_dur" \
+      --trigger commit \
+      --failure-reason "$_bg_reason" \
+      2>/dev/null
+  } >/dev/null 2>&1 || true
+  return 0
+}
+trap _record_blocking_exit EXIT
+
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "   QUALITY GATES - PRE-COMMIT CHECK"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/lib/__tests__/doctor-drift-direction.test.js

@@ -0,0 +1,104 @@
+/**
+ * @test REQ-670 doctor: classify module drift by DIRECTION, not by line counts
+ * @intent `xp-gate doctor` used to report five gate modules as
+ *
+ *           diverged both ways — githooks/ has 70 line(s) the install lacks,
+ *           the install has 2 line(s) githooks/ lacks; sync refuses without an
+ *           explicit decision
+ *
+ *         I checked every "<" line (installed-only) by hand: all of them were
+ *         OLDER versions of code the repository had already rewritten. The
+ *         "install has 2 lines githooks lacks" was purely the shape a re-wrapped
+ *         line leaves in a line-level diff — the same logic, with a `&&` or a
+ *         pipe moved onto a new line, produces a line present on neither side.
+ *
+ *         The wording matters more than it looks. "diverged both ways" plus
+ *         "sync refuses without an explicit decision" tells the reader that both
+ *         sides hold something worth keeping and a human must choose. The
+ *         consequence is not extra keystrokes: it makes people AVOID syncing,
+ *         because syncing appears to discard the installed copy's work. And not
+ *         syncing is exactly #451 — editing githooks/ and having nothing happen.
+ *
+ *         So the classifier must ask "does the installed copy hold anything the
+ *         repo genuinely lacks?" instead of "are both line counts non-zero?".
+ *         Token-level comparison answers the real question: whitespace and line
+ *         breaks are formatting, and formatting is not work.
+ * @covers AC-670-64, AC-670-65, AC-670-66
+ */
+'use strict';
+
+const { moduleDriftDetail } = require('../doctor');
+
+/** Join lines the way a formatter re-wraps them: same tokens, different breaks. */
+const wrap = (...lines) => lines.join('\n');
+
+describe('moduleDriftDetail direction classification (#667)', () => {
+  it('AC-670-64: a pure re-wrap is "behind", not "diverged both ways"', () => {
+    // Same logic; the `&&` moved to the next line. A line-level diff calls this
+    // two-sided drift. Nothing was authored on the installed side.
+    // Real shape measured on gate-3.sh: an older install re-wrapped the same
+    // statements, so a line-level diff reports lines unique to BOTH sides while
+    // the token content is identical (measured: repoOnly=0, installedOnly=0).
+    const repo = wrap(
+      'RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"',
+      'if [ -f "$RATCHET_LIB" ]; then . "$RATCHET_LIB"; fi',
+      'known.set(norm(f.file) + "::" + f.name, Number(f.ccn) || 0);',
+    );
+    const installed = wrap(
+      '        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"',
+      '        if [ -f "$RATCHET_LIB" ]; then',
+      '          . "$RATCHET_LIB"',
+      '        fi',
+      'known.set(norm(f.file) + "::" + f.name,',
+      '          Number(f.ccn) || 0);',
+    );
+    const detail = moduleDriftDetail(repo, installed);
+    expect(detail).not.toMatch(/diverged both ways/i);
+    expect(detail).toMatch(/formatting|stale|behind/i);
+  });
+
+  it('AC-670-65: a genuine two-sided edit still refuses to sync silently', () => {
+    // The installed copy carries a real, machine-only hardening: a fail-closed
+    // branch that exists nowhere in the repo. Overwriting it would destroy work.
+    const repo = wrap(
+      'if [ -z "$COV" ]; then',
+      '  echo "no coverage tool";',
+      '  return 0;',
+      'fi',
+    );
+    const installed = wrap(
+      'if [ -z "$COV" ]; then',
+      '  # FAIL CLOSED: cannot determine coverage means the check failed.',
+      '  echo "❌ BLOCKED - could not determine coverage";',
+      '  return 1;',
+      'fi',
+    );
+    const detail = moduleDriftDetail(repo, installed);
+    expect(detail).toMatch(/diverged both ways/i);
+    expect(detail).toMatch(/refuses|explicit decision/i);
+  });
+
+  it('AC-670-66: an unreadable pair is reported honestly, never as identical', () => {
+    // readPair() returns null when either side cannot be read. Reporting that as
+    // "matches" would be a fail-open: the drift could be real and unseen.
+    const detail = moduleDriftDetail(null, null);
+    expect(detail).toMatch(/could not be read|cannot be compared/i);
+    expect(detail).not.toMatch(/matches|identical/i);
+  });
+});
+
+describe('re-wrap is not drift (#667)', () => {
+  it('AC-670-64: a pure re-wrap yields no unique tokens on either side', () => {
+    // The end-to-end property: formatting-only differences must not count as an
+    // issue, because failing on them teaches the reader to distrust `doctor`
+    // and to skip the sync that #451 exists to encourage.
+    const { tokenDelta } = require('../doctor.js');
+    const NL = String.fromCharCode(10);
+    const repo = 'a &&' + NL + '  b' + NL;
+    const installed = 'a' + NL + '  && b' + NL;
+    const delta = tokenDelta(repo, installed);
+    expect(delta.repoOnly).toBe(0);
+    expect(delta.installedOnly).toBe(0);
+    expect(moduleDriftDetail(repo, installed)).toMatch(/formatting/i);
+  });
+});

package/lib/__tests__/gate-coverage.test.js

@@ -0,0 +1,137 @@
+/**
+ * @test REQ-636 One command that shows compliance against EVERY gate
+ * @intent Today the answer to "how healthy is this project against xp-gate's
+ *        gates" takes six commands and mental arithmetic:
+ *
+ *          xp-gate gate-list && xp-gate check . --all && xp-gate doctor
+ *          node scripts/ccn-report.cjs --check
+ *          node -e "...sum .warnings-baseline.json..."
+ *          gh run list
+ *
+ *        Every existing command answers "did THIS gate pass". None answers
+ *        "where is the debt and what should I fix first".
+ *
+ *        The single most important property is that the view has FOUR states,
+ *        not three. `passed / skipped / failed` merges "did not run" into
+ *        "ran and was fine", and that is exactly where technical debt hides.
+ *        A gate that never executed renders identically to a gate that passed
+ *        clean -- a false green, which is the most dangerous output this
+ *        tooling can produce.
+ *
+ *        Two data hazards drive the rest of the design:
+ *
+ *        - The producer artifact numbers its gates `gate9_build_integrity` and
+ *          `gate10_sast`, but the CLI calls Build Integrity Gate 10 and SAST
+ *          Gate 9 -- the two are SWAPPED. Rendering the artifact naively shows
+ *          the user the wrong gate name, which is worse than showing nothing.
+ *          The mapping is therefore keyed on the artifact's own taxonomy and
+ *          pinned by a test.
+ *
+ *        - `quality-status/<branch>.json` records the commit it was generated
+ *          from. Rendering it for a different HEAD silently presents stale
+ *          results as current. This repo has had that artifact sit at an old
+ *          commit for days, so staleness must be explicit, not inferred away.
+ * @covers AC-636-01, AC-636-02, AC-636-03, AC-636-04, AC-636-05, AC-636-06
+ */
+'use strict';
+
+const { renderGateCoverage, buildCoverageRows, STATUS } = require('../gate-coverage');
+
+/** A `quality-status` artifact shaped like the real producer's output. */
+function artifact(overrides) {
+  return {
+    reportVersion: '2.0',
+    generatedAt: '2026-10-27T03:06:05Z',
+    commit: 'a0bceb9c0000000000000000000000000000000',
+    branch: 'main',
+    language: 'typescript iac',
+    overall: {
+      gatesPassed: 6,
+      gatesTotal: 12,
+      gatesSkipped: 6,
+      gatesWarned: 0,
+      gatesFailed: 0,
+      gatesEffective: 6,
+      effectivePassRate: 100,
+      scoreAllGates: 5,
+      score: 10,
+      verdict: 'PARTIAL',
+      ...(overrides && overrides.overall ? overrides.overall : {}),
+    },
+    gates: {
+      gate1_static_analysis: { name: 'Static Analysis', status: 'PASS', tool: 'eslint' },
+      gate9_build_integrity: { name: 'Build Integrity', status: 'PASS', tool: 'tsc' },
+      gate10_sast: { name: 'SAST Security', status: 'PASS', tool: 'semgrep' },
+      ...(overrides && overrides.gates ? overrides.gates : {}),
+    },
+  };
+}
+
+describe('gate coverage — four states, never a false green (#636)', () => {
+  it('AC-636-01: a gate that never ran is SKIP with a reason, never folded into PASS', () => {
+    const rows = buildCoverageRows(artifact(), { headCommit: 'a0bceb9c0000000000000000000000000000000' });
+    // Gates 0/1/5/11 are hook-only: they exist but the CLI cannot run them.
+    const version = rows.find((r) => r.gate === 0);
+    expect(version, 'Gate 0 must appear even though it never ran').toBeDefined();
+    expect(version.status).toBe(STATUS.SKIP);
+    // A bare SKIP is the false green. The reason is mandatory.
+    expect(version.reason).toBeTruthy();
+    // The reason must say WHY it did not run -- "hook only" and "not run here"
+    // are both honest; a bare SKIP is not.
+    expect(version.reason).toMatch(/hook|git commit|not run/i);
+  });
+
+  it('AC-636-02: the artifact gate-number swap does not mislabel the gates', () => {
+    // The producer says gate9_* = Build Integrity; the CLI says Gate 10 is Build
+    // Integrity. Rendering the artifact's own key would show SAST as Gate 10.
+    const rows = buildCoverageRows(artifact(), { headCommit: 'a0bceb9c0000000000000000000000000000000' });
+    const build = rows.find((r) => r.name === 'Build Integrity');
+    const sast = rows.find((r) => r.name === 'SAST Security');
+    expect(build, 'Build Integrity row must exist').toBeDefined();
+    expect(sast, 'SAST row must exist').toBeDefined();
+    // Both rows exist and carry the CLI's numbering, not the artifact's.
+    expect(build.gate).toBe(10);
+    expect(sast.gate).toBe(9);
+  });
+
+  it('AC-636-03: a stale artifact is marked STALE instead of presented as current', () => {
+    const rows = buildCoverageRows(artifact(), { headCommit: 'ffffffffffffffffffffffffffffffffffffffff' });
+    const rendered = renderGateCoverage(rows, { stale: true, headCommit: 'ffffffffffffffffffffffffffffffffffffffff' });
+    expect(rendered).toMatch(/STALE/i);
+  });
+
+  it('AC-636-04: DEBT is observable and quantified, not rendered as a clean PASS', () => {
+    // Gate 6 holds no warnings of its own; the debt lives in the Boy Scout
+    // baseline. A view that only reads gate statuses reports "PASS" and hides it.
+    const rows = buildCoverageRows(artifact(), {
+      headCommit: 'a0bceb9c0000000000000000000000000000000',
+      boyScout: { files: 14, warnings: 129 },
+    });
+    const boyScout = rows.find((r) => /boy scout/i.test(r.name));
+    expect(boyScout).toBeDefined();
+    expect(boyScout.status).toBe(STATUS.DEBT);
+    expect(String(boyScout.debt)).toMatch(/129/);
+    expect(boyScout.evidence).toMatch(/warnings-baseline/);
+  });
+
+  it('AC-636-05: default exit does not fail on DEBT, but --strict does', () => {
+    const debtRows = [{ gate: 6, name: 'Boy Scout', status: STATUS.DEBT, debt: '1 warning' }];
+    expect(buildCoverageRows).toBeDefined();
+    const { exitCodeFor } = require('../gate-coverage');
+    // Debt is budgeted and known: failing on it by default makes the command
+    // unusable as a CI dashboard.
+    expect(exitCodeFor(debtRows, {})).toBe(0);
+    expect(exitCodeFor(debtRows, { strict: true })).toBe(1);
+    // A real failure always fails.
+    expect(exitCodeFor([{ gate: 7, name: 'x', status: STATUS.FAIL }], {})).toBe(1);
+  });
+
+  it('AC-636-06: every row carries evidence pointing at the artifact that decided it', () => {
+    const rows = buildCoverageRows(artifact(), { headCommit: 'a0bceb9c0000000000000000000000000000000' });
+    // Without Evidence the user can only trust a one-line claim; with it they
+    // can go check. Same reason `doctor` prints paths.
+    for (const row of rows) {
+      expect(row.evidence, `Gate ${row.gate} (${row.name}) has no evidence pointer`).toBeTruthy();
+    }
+  });
+});

package/lib/__tests__/rework.test.js

@@ -0,0 +1,127 @@
+/**
+ * @test REQ-651 rework
+ * @intent #651 asks for a command that turns the gate journal into the three
+ *        numbers rework management actually needs:
+ *
+ *          1. first-pass rate     -- how often a round clears the gates on try 1
+ *          2. rework round stats  -- median / mean / worst rounds per landing
+ *          3. top-N failing rules -- which rule_id blocks most often
+ *
+ *        Without (3) the only thing you can do is "try harder". With it, the
+ *        answer to "why is development slow" becomes a ranked list.
+ *
+ *        Two data hazards decide the design:
+ *
+ *        - Before #651 the journal contained NO failures, so every derived rate
+ *          was 100% by construction. A command that reports "first-pass rate: 100%"
+ *          from an empty failure set is worse than no command: it manufactures
+ *          confidence. So an input with zero FAIL records must report that the
+ *          figure is NOT MEASURABLE, not that it is perfect.
+ *
+ *        - ~401 historical records carry epoch-sized `duration_ms` (flagged
+ *          `duration_anomaly`). Any duration aggregate must exclude them rather
+ *          than average them in -- one of them once produced "average 430 million
+ *          seconds".
+ *
+ *        These tests exercise the pure aggregation function, so the numbers are
+ *        pinned independently of file layout.
+ * @covers AC-670-59, AC-670-60, AC-670-61, AC-670-62
+ */
+'use strict';
+
+const { computeReworkStats } = require('../rework');
+
+/** One journal record, defaulting to a pass. */
+function rec(overrides) {
+  return {
+    timestamp: '2026-10-30T10:00:00.000Z',
+    gate_id: '1',
+    gate_name: 'Code Quality',
+    passed: true,
+    issues_found: 0,
+    duration_ms: 1000,
+    trigger: 'commit',
+    ...overrides,
+  };
+}
+
+describe('computeReworkStats (#651)', () => {
+  it('AC-670-59: reports an unmeasurable first-pass rate when the journal has no failures', () => {
+    // This is exactly the pre-#651 journal: thousands of passes, zero fails.
+    const entries = Array.from({ length: 50 }, () => rec());
+    const stats = computeReworkStats(entries);
+    // A rate derived from an empty failure set is not 100% -- it is unknown.
+    expect(stats.firstPassRate).toBeNull();
+    expect(stats.measurable).toBe(false);
+    expect(stats.reason).toMatch(/no failure/i);
+  });
+
+  it('AC-670-60: counts failing rules and ranks them, so the worst rule is actionable', () => {
+    const entries = [
+      rec({ passed: false, failure_reason: 'long-function' }),
+      rec({ passed: false, failure_reason: 'long-function' }),
+      rec({ passed: false, failure_reason: 'long-function' }),
+      rec({ passed: false, failure_reason: 'tests_failed' }),
+      rec(),
+      rec(),
+    ];
+    const stats = computeReworkStats(entries);
+    expect(stats.measurable).toBe(true);
+    expect(stats.topFailures[0]).toEqual({ reason: 'long-function', count: 3 });
+    expect(stats.topFailures[1]).toEqual({ reason: 'tests_failed', count: 1 });
+    // 4 failures out of 6 attempts -> 33% first-pass.
+    expect(stats.firstPassRate).toBeCloseTo(33.3, 1);
+  });
+
+  it('AC-670-61: excludes anomaly-flagged durations instead of averaging them in', () => {
+    // A real epoch-sized value from the corpus; averaging it in produced
+    // "average 430 million seconds" on gate-1.
+    const entries = [
+      rec({ duration_ms: 1000 }),
+      rec({ duration_ms: 3000 }),
+      rec({ duration_ms: 1784536915891, duration_anomaly: true }),
+    ];
+    const stats = computeReworkStats(entries);
+    expect(stats.duration).not.toBeNull();
+    // Median over the two sane values (1000, 3000) is 2000, not ~5.9e11.
+    expect(stats.duration.medianMs).toBe(2000);
+    expect(stats.duration.samples).toBe(2);
+    expect(stats.duration.excludedAnomalies).toBe(1);
+  });
+
+  it('AC-670-62: a failure with no reason is bucketed, never silently dropped', () => {
+    const entries = [
+      rec({ passed: false }),                              // no failure_reason
+      rec({ passed: false, failure_reason: '' }),          // empty
+      rec({ passed: false, failure_reason: 'short-circuit' }),
+    ];
+    const stats = computeReworkStats(entries);
+    // Dropping unlabelled failures would understate the failure count and push
+    // the first-pass rate UP -- the optimistic direction is the dangerous one.
+    expect(stats.failures).toBe(3);
+    const unattributed = stats.topFailures.find((f) => /unattributed|unknown/i.test(f.reason));
+    expect(unattributed, 'unlabelled failures must appear in the ranking').toBeDefined();
+    expect(unattributed.count).toBe(2);
+  });
+});
+
+describe('rework duration sampling (#651)', () => {
+  it('AC-670-61: an UNFLAGGED epoch-sized duration is still excluded', () => {
+    // Measured on the real journal: 391 records carry duration_anomaly, but 6
+    // more epoch-sized values do not. Trusting the flag alone left the mean at
+    // 1.3e9 ms -- the "average 430 million seconds" artifact returning through
+    // the back door. Plausibility must be checked independently of the flag.
+    const entries = [
+      rec({ duration_ms: 2000 }),
+      rec({ duration_ms: 4000 }),
+      rec({ duration_ms: 1785001784992 }), // no duration_anomaly flag
+    ];
+    const stats = computeReworkStats(entries);
+    expect(stats.duration).not.toBeNull();
+    expect(stats.duration.medianMs).toBe(3000);
+    expect(stats.duration.samples).toBe(2);
+    // Excluded count covers BOTH flagged and implausible, or the sample size
+    // looks closer to the record count than it really is.
+    expect(stats.duration.excludedAnomalies).toBe(1);
+  });
+});

package/lib/__tests__/test-alignment.test.ts

@@ -263,7 +263,7 @@ test.each([['hello', 5], ['world', 5]])('%s has length %i', (str, len) => {
  * @covers AC-SKIP-001-01
  */
 it.skip('should parse skipped tests', () => {
-  expect(true).toBe(true);
+  expect(subject).toBe('fixture');
 });
 
 /**
@@ -292,7 +292,7 @@ test.todo('should parse todo tests');
  */
 const featureName = 'Login';
 it(\`should authenticate \${featureName} user\`, () => {
-  expect(true).toBe(true);
+  expect(subject).toBe('fixture');
 });
 `;
 
@@ -665,7 +665,7 @@ specification:
  * @covers AC-PUNCT-001-01
  */
 test('punctuation handling', () => {
-  expect(true).toBe(true);
+  expect(subject).toBe('fixture');
 });
 
 /**
@@ -674,7 +674,7 @@ test('punctuation handling', () => {
  * @covers AC-PUNCT-002-01
  */
 test('comma handling', () => {
-  expect(true).toBe(true);
+  expect(subject).toBe('fixture');
 });
 `;
 
@@ -796,3 +796,44 @@ specification:
     expect(report.alignment_status).toBe('FAIL');
   });
 });
+
+describe('writeReport error handling (Boy Scout debt, #641)', () => {
+  it('AC-670-63: surfaces a write failure instead of throwing out of the run', () => {
+    // writeReport() runs as the LAST step of runFullAlignment — after the spec is
+    // parsed and every test file is scanned. An unguarded throw here discards all
+    // of that work and turns a reportable condition (disk full, read-only mount,
+    // permission denied) into a crashed command with no report at all. The report
+    // schema already carries an `errors` array for exactly this.
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const os = require('node:os');
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-wr-'));
+    // A path whose PARENT is a regular file cannot be created as a directory.
+    const blocker = path.join(tmp, 'blocker');
+    fs.writeFileSync(blocker, 'not a directory');
+    const outputPath = path.join(blocker, 'nested', 'report.json');
+
+    const report = {
+      alignment_status: 'FAIL' as const,
+      phase: 1,
+      score: 0,
+      head_commit: 'abc123',
+      spec_hash: sha256('x'),
+      timestamp: new Date().toISOString(),
+      misaligned_tests: [],
+      anti_pattern_detected: false,
+      errors: [] as string[],
+    };
+
+    try {
+      // Assert the OBSERVABLE outcome, not merely "did not throw": the contract is
+      // that the failure is reported through the report object the caller holds.
+      const written = writeReport(report, outputPath);
+      expect(written).toBe(false);
+      expect(report.errors.length).toBe(1);
+      expect(report.errors[0]).toContain('Failed to write report');
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});