@boyingliu01/xp-gate 0.35.1 → 0.35.3

package/adapters/gate-4.sh

@@ -165,13 +165,42 @@ else
         rm -f "$PRINCIPLES_STDERR"
 
         if [ "$PRINCIPLES_EXIT" -ge 2 ]; then
-          echo "⚠️  Warning: Principles checker execution failed"
-          echo "⏭️  SKIPPED - Principles check (execution issue)"
-          GATE_4_STATUS="SKIP"
-          # Consumed by the sourcing parent, not here (see #548).
+          # Fail-closed (#661), same rule as Gate 8 (#499): a gate that cannot run
+          # must not report success.
+          #
+          # This branch used to settle on SKIP, which the caller reads as
+          # non-blocking -- so a checker that crashed on startup
+          # (`Cannot find module 'C:\c\Users\...'`, the POSIX-path-to-native-node
+          # bug) still printed "PASSED - Principles checker (no errors found)".
+          # The path conversion fixed that one cause; any other way of breaking
+          # the launch (missing tsx, corrupt module, OOM) lands here too, and all
+          # of them would have been absorbed into a green light.
+          #
+          # SKIP stays reserved for "language not applicable / tool not
+          # installed", which is not what this is: the checker exists and failed.
+          echo ""
+          echo "❌ BLOCKED - Principles checker failed to execute (exit $PRINCIPLES_EXIT)"
+          echo "This is a tool fault, NOT a clean result. A gate that cannot run must not pass."
+          echo "  Fix the checker, or set PRINCIPLES_SKIP_TOOL_FAULT=1 to downgrade to a warning."
+          echo "  (downgrade is audit-logged and never allowed on main/master)"
+          GATE_4_STATUS="FAIL"
           # shellcheck disable=SC2034
           GATE_4_REASON="checker_execution_error"
           rm -f "$PRINCIPLES_JSON"
+          if [ "${PRINCIPLES_SKIP_TOOL_FAULT:-0}" = "1" ]; then
+            echo "⚠️  ESCAPE VALVE: PRINCIPLES_SKIP_TOOL_FAULT=1 — downgrading to SKIP"
+            # Same asymmetry as Gate 5a: a downgrade is tolerable on a feature
+            # branch, never on main/master, where it would green-light the trunk.
+            _g4_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+            if [ "$_g4_branch" = "main" ] || [ "$_g4_branch" = "master" ]; then
+              echo "❌ ESCAPE VALVE BLOCKED: PRINCIPLES_SKIP_TOOL_FAULT not allowed on $_g4_branch"
+              GATE_4_STATUS="FAIL"
+              exit 1
+            fi
+            GATE_4_STATUS="SKIP"
+          else
+            exit 1
+          fi
         else
           # Check severity levels. The reporter emits JSON.stringify(out, null, 2),
           # i.e. `"severity": "warning"` WITH a space; tolerate any whitespace so a

package/bin/xp-gate.js

@@ -350,6 +350,21 @@ 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 => {

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__/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 });
+    }
+  });
+});

package/lib/doctor.js

@@ -885,7 +885,14 @@ function diagnoseModuleDrift(ctx = {}) {
       continue;
     }
     const hint = TIER_HINTS[tierFor(executed, dirs).tier] || '';
-    checks.push({ name: label, status: 'FAIL', detail: `${moduleDriftDetail(repoOnly, installedOnly)}${hint}` });
+    const driftDetail = moduleDriftDetail(texts.repoText, texts.installedText);
+    // A re-wrap is not drift: both copies say the same thing, so FAILing (and
+    // refusing to sync) over it teaches the reader to distrust the check.
+    if (/differ only in formatting/.test(driftDetail)) {
+      checks.push({ name: label, status: 'PASS', detail: driftDetail });
+      continue;
+    }
+    checks.push({ name: label, status: 'FAIL', detail: `${driftDetail}${hint}` });
     issues++;
   }
 
@@ -935,22 +942,87 @@ function nonExecutedCopies(dirs, executedFor) {
   return found;
 }
 
+/**
+ * Split source into comparable tokens, discarding formatting.
+ *
+ * Whitespace, line breaks and blank lines are dropped so a re-wrapped statement
+ * and its one-line original compare equal. Crucially this keeps `x &&` + `y` on
+ * two lines equal to `x && y` on one: a line-level set difference reports BOTH
+ * of those lines as unique to their side, which is what made every re-wrap look
+ * like two-sided drift (#667).
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenizeForDrift(text) {
+  return String(text).split(/\s+/).filter((t) => t.length > 0);
+}
+
+/**
+ * Token-level delta between two copies: how many tokens each side holds that
+ * the other does not.
+ *
+ * @param {string} repoText
+ * @param {string} installedText
+ * @returns {{repoOnly: number, installedOnly: number}}
+ */
+function tokenDelta(repoText, installedText) {
+  const repo = tokenizeForDrift(repoText);
+  const installed = tokenizeForDrift(installedText);
+  const repoSet = new Set(repo);
+  const installedSet = new Set(installed);
+  let repoOnly = 0;
+  let installedOnly = 0;
+  for (const t of repoSet) if (!installedSet.has(t)) repoOnly++;
+  for (const t of installedSet) if (!repoSet.has(t)) installedOnly++;
+  return { repoOnly, installedOnly };
+}
+
+/**
+ * NO tolerance: any installed-only token blocks the silent sync.
+ *
+ * A threshold looked tempting (a re-wrap can leave a stray token), but it gets
+ * the risk backwards. The case the refusal exists for is precisely a ONE-token
+ * hardening -- `return 0` -> `return 1`, the difference between a gate that
+ * fails open and one that fails closed. Measured on the real gate modules, a
+ * pure re-wrap produces ZERO unique tokens on either side, so the tolerance
+ * would have bought nothing and could have destroyed the exact fix it is meant
+ * to protect.
+ */
+const FORMATTING_NOISE_TOKENS = 0;
+
 /**
  * Describe one drifted module by the direction of its drift.
  *
  * Only a module the *repo* is ahead of is safe to overwrite; anything where the
- * installed copy holds its own lines needs an explicit decision, because syncing
+ * installed copy holds its own work needs an explicit decision, because syncing
  * would delete work that exists nowhere else.
+ *
+ * The question is NOT "are both line counts non-zero" -- every re-wrapped
+ * statement satisfies that. It is "does the installed copy hold anything the
+ * repo genuinely lacks", which is a token question (#667).
+ *
+ * @param {string|null} repoText
+ * @param {string|null} installedText
+ * @returns {string}
  */
-function moduleDriftDetail(repoOnly, installedOnly) {
-  if (repoOnly > 0 && installedOnly > 0) {
-    return `diverged both ways — githooks/ has ${repoOnly} line(s) the install lacks, `
-      + `the install has ${installedOnly} line(s) githooks/ lacks; sync refuses without an explicit decision`;
+function moduleDriftDetail(repoText, installedText) {
+  if (typeof repoText !== 'string' || typeof installedText !== 'string') {
+    return 'executed copy could not be read for comparison';
+  }
+  const { repoOnly, installedOnly } = tokenDelta(repoText, installedText);
+  if (repoOnly > 0 && installedOnly > FORMATTING_NOISE_TOKENS) {
+    return `diverged both ways — githooks/ has ${repoOnly} token(s) the install lacks, `
+      + `the install has ${installedOnly} token(s) githooks/ lacks; sync refuses without an explicit decision`;
   }
   if (repoOnly > 0) {
-    return `installed copy is stale (${repoOnly} line(s) in githooks/ absent from the install)`;
+    return `installed copy is stale (${repoOnly} token(s) in githooks/ absent from the install); `
+      + 'sync will fast-forward it from githooks/';
+  }
+  if (installedOnly > 0) {
+    return `installed copy is newer than githooks/ (${installedOnly} token(s) absent from the repo)`;
   }
-  return `installed copy is newer than githooks/ (${installedOnly} line(s) absent from the repo)`;
+  return 'copies differ only in formatting; content is equivalent';
 }
 
 /**
@@ -3409,6 +3481,8 @@ module.exports = {
   classifyHooksDir,
   syncGlobalHooksFromRepo,
   diagnoseModuleDrift,
+  moduleDriftDetail,
+  tokenDelta,
   diagnoseAuditLedger,
   syncModulesFromRepo,
   resolveExecutedModuleDirs,