@boyingliu01/xp-gate 0.27.0 → 0.27.2

package/lib/detect-deps.js

@@ -296,10 +296,14 @@ function probeWindowsBash() {
 function resolveWindowsBashCandidates(spawnProbe, whereExecSync) {
   const _execSync = whereExecSync || execSync;
   const candidates = [];
-  try {
-    const found = _execSync('where bash', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-    for (const line of found.split(/\r?\n/)) if (line.trim()) candidates.push(line.trim());
-  } catch { /* where unavailable */ }
+  // Well-known interpreters FIRST. Two reasons, both measured on win32:
+  // 1. A cold WSL launch (System32\bash.exe leads `where bash` when WSL is
+  //    installed) blocks its spawnSync for ~3.4s. checkBash runs inside
+  //    doctor's parallel fan-out, and that synchronous stall starves the
+  //    event loop past EXEC_TIMEOUT_MS — node/git then falsely report
+  //    "Not found" while spawning them standalone takes ~300ms.
+  // 2. The known Git paths ARE the answer we are looking for; probing them
+  //    first also skips pointless launches of stubs we would reject anyway.
   candidates.push(
     'C:\\Program Files\\Git\\bin\\bash.exe',
     'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
@@ -308,6 +312,33 @@ function resolveWindowsBashCandidates(spawnProbe, whereExecSync) {
     'C:\\msys64\\usr\\bin\\bash.exe',
     'C:\\cygwin64\\bin\\bash.exe'
   );
+  try {
+    const found = _execSync('where bash', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    for (const line of found.split(/\r?\n/)) {
+      const p = line.trim();
+      // Skip the WSL launcher outright: uname would reject it, and a cold
+      // launch costs seconds (see above). WindowsApps\bash.exe is the same
+      // WSL stub family (it just errors differently when WSL is absent).
+      if (!p) continue;
+      // Match on normalized separators: forward slashes, mixed case, or a
+      // non-C drive would otherwise slip a WSL stub past the filter and back
+      // into the multi-second cold-launch stall.
+      const norm = p.replace(/\//g, '\\');
+      // The WSL launcher appears as System32/Sysnative/SysWOW64\bash.exe, the
+      // AppX alias <Windows>\SystemApps\Microsoft.WSL_*\bash.exe, and the
+      // per-user AppX execution alias ...\AppData\Local\Microsoft\WindowsApps\
+      // bash.exe. A user's own install merely NAMED ...\WindowsApps\... (not
+      // under Microsoft\) is NOT the stub and stays in the list.
+      if (/\\windowsapps\\bash\.exe$/i.test(norm)
+        && (/\\systemapps\\/i.test(norm) || /\\appdata\\local\\microsoft\\windowsapps\\/i.test(norm))) continue;
+      // The WSL stub lives in the matching-arch System32 view: 64-bit
+      // C:\Windows\System32\bash.exe AND the 32-bit emulation redirect target
+      // C:\Windows\SysWOW64\bash.exe (where reports either depending on the
+      // bitness of the caller).
+      if (/\\windows\\system32\\bash\.exe$/i.test(norm) || /\\windows\\sysnative\\bash\.exe$/i.test(norm) || /\\windows\\syswow64\\bash\.exe$/i.test(norm)) continue;
+      if (!candidates.includes(p)) candidates.push(p);
+    }
+  } catch { /* where unavailable */ }
   for (const candidate of candidates) {
     try {
       const r = spawnProbe(candidate, ['-c', 'echo "[$1]"; uname -s', 'sh', 'XPGATE_ARGV_PROBE'], {
@@ -327,22 +358,46 @@ function resolveWindowsBashCandidates(spawnProbe, whereExecSync) {
 /**
  * Check if bash is available on the system.
  * XP-Gate hooks are bash scripts — Windows users need Git Bash installed.
- * @returns {{ok: boolean, path?: string, message?: string}}
+ * @returns {{ok: boolean, path?: string, version?: string, message?: string}}
  */
+// Split out for behavior tests: checkBashVersion takes the resolved bash path
+// and a spawner so the version-field contract (a bash VERSION tuple, not the
+// uname string) is assertable without a real interpreter on the host.
+function checkBashVersion(spawnProbe, winBash) {
+  let version = 'unknown';
+  try {
+    // --version through the SAME probe-style argv as the candidate loop:
+    // Git Bash's login startup (`bash --version`) costs ~1.7s, and checkBash
+    // sits on hot paths (doctor fan-out, every gate-runner launch) where a
+    // synchronous stall starves concurrent execs past their timeouts. The
+    // -c form is non-login (~300ms). uname proves the MSYS family AND bash
+    // --version inside it still yields the real bash version number — the
+    // `version` field must stay a bash version, not the uname string. No
+    // sed in the command: the parse lives in JS below, so a stripped MSYS
+    // install without sed cannot silently degrade to "unknown".
+    // NOTE the cp. prefix: this module binds only execSync at file scope,
+    // and checkBash sits outside probeWindowsBash's local spawnSync binding
+    // — a bare spawnSync here is a ReferenceError swallowed by the catch,
+    // which used to pin the detail line at "unknown" forever.
+    const result = spawnProbe(winBash, ['-c', 'uname -s; bash --version', 'sh'], { encoding: 'utf8', timeout: 5000 });
+    const out = String((result && result.stdout) || '').trim();
+    // Keep the field in the same shape checkEnv prints for every other tool
+    // ("GNU bash, version X.Y.Z(...)"): doctor prefixes "GNU bash, version ",
+    // so hand back the bare version tuple, not the whole line.
+    const versionLine = out.split('\n').find(line => /version/.test(line));
+    const match = versionLine && versionLine.match(/version\s+(\S+)/);
+    if (match) version = match[1];
+  } catch { /* keep unknown */ }
+  return version;
+}
+
 function checkBash() {
   // On Windows resolve explicitly: PATH may lead with the WSL System32 stub,
   // which cannot execute these hooks (wrong filesystem view, dropped $1).
   if (process.platform === 'win32') {
     const winBash = probeWindowsBash();
     if (winBash) {
-      let version = 'unknown';
-      try {
-        // spawnSync with discrete argv — never interpolate a discovered path
-        // into a shell string (a PATH dir name may carry cmd metacharacters).
-        const result = spawnSync(winBash, ['--version'], { encoding: 'utf8', timeout: 5000 });
-        const versionMatch = String(result.stdout || '').match(/version\s+([^\s]+)/);
-        if (versionMatch) version = versionMatch[1];
-      } catch { /* keep unknown */ }
+      const version = checkBashVersion((...args) => require('child_process').spawnSync(...args), winBash);
       return { ok: true, path: winBash, version };
     }
     return {
@@ -567,6 +622,7 @@ function compareVersions(a, b) {
 module.exports = {
   checkDeps,
   checkBash,
+  checkBashVersion,
   resolveWindowsBashCandidates,
   autoInstallDeps,
   detectPlatform,

package/lib/doctor.js

@@ -104,18 +104,52 @@ function noteSandboxAttribution(err) {
 }
 
 async function execWithTimeout(cmd, opts = {}) {
-  try {
-    const { stdout, stderr } = await execAsync(cmd, {
-      ...opts,
-      timeout: opts.timeout || EXEC_TIMEOUT_MS,
-    });
-    return { stdout: stdout.trim(), stderr: stderr.trim() };
-  } catch (err) {
-    // #525: a bare null here reads as "tool missing" and has already cost a
-    // misdiagnosis round. Name the sandbox once when it is the sandbox.
-    noteSandboxAttribution(err);
-    return null;
+  // Win32 false-negative guard. Under cmd.exe (exec's shell), a spawned probe
+  // can exit 0 while its stdout never reaches us — measured on this machine:
+  // `node --version` returns exit 0 with an EMPTY stream when many spawns are
+  // in flight at once (doctor's parallel fan-out), while the same command
+  // standalone prints fine in ~300ms. The old code read that empty stream as
+  // "Not found" and red-flagged Node/Git/hooksPath. A version/config probe is
+  // idempotent, so quiet retries distinguish the lost stream from a tool that
+  // genuinely fails. Contract: every caller here runs an IDEMPOTENT probe
+  // (`--version`, `config --get`, `rev-parse`) — a future side-effecting call
+  // site must pass { attempts: 1 } to opt out of the retry below. The option
+  // is consumed here and never forwarded to exec.
+  // Scope note: only the exit-0-with-empty-stream shape is retried. A probe
+  // that exits non-zero is a REAL failure verdict (cmd.exe reports a missing
+  // tool as exit 1 + "'x' is not recognized"), and re-running it would only
+  // burn time, so that path still returns null immediately.
+  const { attempts, ...execOpts } = opts;
+  const maxAttempts = process.platform === 'win32' ? (attempts || 3) : 1;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const { stdout, stderr } = await execAsync(cmd, {
+        ...execOpts,
+        timeout: execOpts.timeout || EXEC_TIMEOUT_MS,
+      });
+      if (!stdout.trim() && !stderr.trim()) {
+        // Exit-0-but-empty: nothing usable came back. Retry while attempts
+        // remain; report null once they are exhausted, so every caller's
+        // existing null check ("probe produced nothing") applies — an empty
+        // non-null result would read as a present tool with no version.
+        if (attempt + 1 < maxAttempts) {
+          await new Promise(resolve => setTimeout(resolve, 50));
+          continue;
+        }
+        return null;
+      }
+      return { stdout: stdout.trim(), stderr: stderr.trim() };
+    } catch (err) {
+      // #525: a bare null here reads as "tool missing" and has already cost a
+      // misdiagnosis round. Name the sandbox once when it is the sandbox.
+      noteSandboxAttribution(err);
+      return null;
+    }
   }
+  // Exhausted all attempts with exit-0-but-empty streams: report null so every
+  // caller's existing null check ("probe produced nothing usable") applies —
+  // an empty non-null result would read as a present tool with no version.
+  return null;
 }
 
 /**

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-16T13:39:44.004Z",
+  "checked_at": "2026-10-16T16:21:34.578Z",
   "source": "network"
 }

package/lib/sprint-audit.js

@@ -1,235 +1,235 @@
-/**
- * xp-gate sprint-audit — Layer 2: Final sprint completeness audit.
- *
- * Checks phase_history coverage, time records, artifact records,
- * and state consistency at Phase 6 CLOSE.
- *
- * Usage:
- *   xp-gate sprint-audit [--dir <path>] [--json]
- *
- * Verdict rules:
- *   6/6 completed + 0 errors       → PASS (exit 0)
- *   >= 4/6 completed + 0 errors    → PASS_WITH_WARNINGS (exit 0)
- *   < 4/6 completed or any errors  → FAIL (exit 1)
- *   No sprint-state.json           → SKIP (exit 0)
- *
- * @module sprint-audit
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { PHASE_NAMES } = require('./phase-transition');
-
-/**
- * Run the sprint audit.
- * @param {string[]} args - CLI arguments
- * @returns {Promise<number>} Exit code
- */
-async function handleSprintAudit(args = []) {
-  if (args.includes('--help')) {
-    console.log('Usage: xp-gate sprint-audit [options]');
-    console.log('');
-    console.log('Options:');
-    console.log('  --dir <path>   Project directory (default: cwd)');
-    console.log('  --json         Output as JSON instead of human-readable');
-    console.log('');
-    console.log('Runs final sprint completeness audit at Phase 6 CLOSE.');
-    console.log('Checks phase coverage, time records, artifact records,');
-    console.log('and state consistency.');
-    return 0;
-  }
-
-  const dirIdx = args.indexOf('--dir');
-  const projectDir = dirIdx >= 0 ? args[dirIdx + 1] : process.cwd();
-  const jsonFlag = args.includes('--json');
-
-  const stateFile = path.join(projectDir, '.sprint-state', 'sprint-state.json');
-
-  // No sprint-state.json → SKIP
-  if (!fs.existsSync(stateFile)) {
-    if (jsonFlag) {
-      console.log(JSON.stringify({ verdict: 'SKIP', reason: 'No sprint-state.json found' }));
-    } else {
-      console.log('⏭️  No sprint-state.json found — skipping audit.');
-    }
-    return 0;
-  }
-
-  let state;
-  try {
-    state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-  } catch (err) {
-    const result = {
-      verdict: 'FAIL',
-      errors: [`Failed to parse sprint-state.json: ${err.message}`],
-    };
-    if (jsonFlag) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.error(`❌ ${result.errors[0]}`);
-    }
-    return 1;
-  }
-
-  // ── Run checks ──
-  const warnings = [];
-  const errors = [];
-  const phaseHistory = Array.isArray(state.phase_history) ? state.phase_history : [];
-
-  // Build lookup
-  const historyLookup = {};
-  for (const entry of phaseHistory) {
-    historyLookup[entry.phase] = entry;
-  }
-
-  // Check 1: Phase coverage
-  const completedPhases = [];
-  const missingPhases = [];
-  const incompletePhases = [];
-
-  for (let i = 1; i <= 6; i++) {
-    const entry = historyLookup[i];
-    if (!entry) {
-      missingPhases.push(i);
-    } else if (entry.status === 'completed' || entry.status === 'skipped') {
-      completedPhases.push(i);
-    } else {
-      incompletePhases.push({ phase: i, name: PHASE_NAMES[i] || `Phase ${i}`, status: entry.status });
-    }
-  }
-
-  // Check 2: Time records for completed phases
-  for (const phaseNum of completedPhases) {
-    const entry = historyLookup[phaseNum];
-    if (entry.status === 'completed' && (entry.duration_seconds == null || entry.duration_seconds === 0)) {
-      warnings.push(`Phase ${phaseNum} (${PHASE_NAMES[phaseNum]}) completed but has no duration recorded`);
-    }
-  }
-
-  // Check 3: Artifact records (phase-{N}-summary.md)
-  const outputsDir = path.join(projectDir, '.sprint-state', 'phase-outputs');
-  for (const phaseNum of completedPhases) {
-    if (historyLookup[phaseNum].status === 'completed') {
-      const summaryFile = path.join(outputsDir, `phase-${phaseNum}-summary.md`);
-      if (!fs.existsSync(summaryFile)) {
-        warnings.push(`Phase ${phaseNum} summary missing: .sprint-state/phase-outputs/phase-${phaseNum}-summary.md`);
-      }
-    }
-  }
-
-  // Check 4: State consistency — phase field vs phase_history last entry
-  if (phaseHistory.length > 0) {
-    const lastEntry = phaseHistory[phaseHistory.length - 1];
-    if (state.phase !== undefined && state.phase !== lastEntry.phase) {
-      errors.push(
-        `State inconsistency: sprint-state.phase=${state.phase} but phase_history last entry is phase ${lastEntry.phase}`
-      );
-    }
-  }
-
-  // ── Determine verdict ──
-  const completedCount = completedPhases.length;
-  let verdict;
-  if (errors.length > 0 || completedCount < 4) {
-    verdict = 'FAIL';
-  } else if (completedCount >= 6 && errors.length === 0) {
-    verdict = 'PASS';
-  } else {
-    verdict = 'PASS_WITH_WARNINGS';
-  }
-
-  // ── Build result ──
-  const result = {
-    sprint_id: state.id || 'unknown',
-    branch: state.isolation?.branch || 'unknown',
-    coverage: {
-      completed: completedCount,
-      total: 6,
-      pct: Math.round((completedCount / 6) * 100),
-    },
-    missing_phases: missingPhases.map(p => ({ phase: p, name: PHASE_NAMES[p] || `Phase ${p}` })),
-    incomplete_phases: incompletePhases,
-    warnings,
-    errors,
-    verdict,
-  };
-
-  // ── Persist report (latest overwrites — expected behavior) ──
-  const reportPath = path.join(projectDir, '.sprint-state', 'audit-report.json');
-  try {
-    fs.writeFileSync(reportPath, JSON.stringify(result, null, 2), 'utf8');
-  } catch (err) {
-    // Report write failure is WARNING, not BLOCK
-    warnings.push(`Failed to write audit report: ${err.message}`);
-  }
-
-  // ── Output ──
-  if (jsonFlag) {
-    console.log(JSON.stringify(result, null, 2));
-  } else {
-    printHumanReadable(result, state);
-  }
-
-  // Exit code: FAIL → 1, others → 0
-  return verdict === 'FAIL' ? 1 : 0;
-}
-
-/**
- * Print human-readable audit report.
- * @param {object} result - Audit result object
- * @param {object} state - Sprint state object
- */
-function printHumanReadable(result, state) {
-  const lines = [];
-  lines.push('');
-  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  lines.push(`  Sprint Audit Report — ${result.sprint_id}`);
-  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  lines.push('');
-  lines.push(`  Branch: ${result.branch}`);
-  lines.push(`  Phase Coverage: ${result.coverage.completed}/${result.coverage.total} (${result.coverage.pct}%)`);
-  lines.push('');
-  lines.push('  Phase History:');
-
-  for (let i = 1; i <= 6; i++) {
-    const entry = result.incomplete_phases.find(p => p.phase === i);
-    const missing = result.missing_phases.find(p => p.phase === i);
-    const name = (PHASE_NAMES[i] || `Phase ${i}`).padEnd(10);
-
-    if (missing) {
-      lines.push(`  ❌ Phase ${i}/6  ${name} — not recorded`);
-    } else if (entry) {
-      lines.push(`  ⚠️  Phase ${i}/6  ${name} ${entry.status}  ← not yet completed`);
-    } else {
-      lines.push(`  ✅ Phase ${i}/6  ${name} completed`);
-    }
-  }
-
-  if (result.warnings.length > 0) {
-    lines.push('');
-    lines.push('  Warnings:');
-    for (const w of result.warnings) {
-      lines.push(`  ⚠️  ${w}`);
-    }
-  }
-
-  if (result.errors.length > 0) {
-    lines.push('');
-    lines.push('  Errors:');
-    for (const e of result.errors) {
-      lines.push(`  ❌ ${e}`);
-    }
-  }
-
-  lines.push('');
-  const issueCount = result.warnings.length + result.errors.length;
-  lines.push(`  Overall: ${result.warnings.length} warning(s), ${result.errors.length} error(s)`);
-  lines.push(`  Verdict: ${result.verdict}`);
-  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-
-  console.log(lines.join('\n'));
-}
-
-module.exports = { handleSprintAudit };
+/**
+ * xp-gate sprint-audit — Layer 2: Final sprint completeness audit.
+ *
+ * Checks phase_history coverage, time records, artifact records,
+ * and state consistency at Phase 6 CLOSE.
+ *
+ * Usage:
+ *   xp-gate sprint-audit [--dir <path>] [--json]
+ *
+ * Verdict rules:
+ *   6/6 completed + 0 errors       → PASS (exit 0)
+ *   >= 4/6 completed + 0 errors    → PASS_WITH_WARNINGS (exit 0)
+ *   < 4/6 completed or any errors  → FAIL (exit 1)
+ *   No sprint-state.json           → SKIP (exit 0)
+ *
+ * @module sprint-audit
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { PHASE_NAMES } = require('./phase-transition');
+
+/**
+ * Run the sprint audit.
+ * @param {string[]} args - CLI arguments
+ * @returns {Promise<number>} Exit code
+ */
+async function handleSprintAudit(args = []) {
+  if (args.includes('--help')) {
+    console.log('Usage: xp-gate sprint-audit [options]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --dir <path>   Project directory (default: cwd)');
+    console.log('  --json         Output as JSON instead of human-readable');
+    console.log('');
+    console.log('Runs final sprint completeness audit at Phase 6 CLOSE.');
+    console.log('Checks phase coverage, time records, artifact records,');
+    console.log('and state consistency.');
+    return 0;
+  }
+
+  const dirIdx = args.indexOf('--dir');
+  const projectDir = dirIdx >= 0 ? args[dirIdx + 1] : process.cwd();
+  const jsonFlag = args.includes('--json');
+
+  const stateFile = path.join(projectDir, '.sprint-state', 'sprint-state.json');
+
+  // No sprint-state.json → SKIP
+  if (!fs.existsSync(stateFile)) {
+    if (jsonFlag) {
+      console.log(JSON.stringify({ verdict: 'SKIP', reason: 'No sprint-state.json found' }));
+    } else {
+      console.log('⏭️  No sprint-state.json found — skipping audit.');
+    }
+    return 0;
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  } catch (err) {
+    const result = {
+      verdict: 'FAIL',
+      errors: [`Failed to parse sprint-state.json: ${err.message}`],
+    };
+    if (jsonFlag) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`❌ ${result.errors[0]}`);
+    }
+    return 1;
+  }
+
+  // ── Run checks ──
+  const warnings = [];
+  const errors = [];
+  const phaseHistory = Array.isArray(state.phase_history) ? state.phase_history : [];
+
+  // Build lookup
+  const historyLookup = {};
+  for (const entry of phaseHistory) {
+    historyLookup[entry.phase] = entry;
+  }
+
+  // Check 1: Phase coverage
+  const completedPhases = [];
+  const missingPhases = [];
+  const incompletePhases = [];
+
+  for (let i = 1; i <= 6; i++) {
+    const entry = historyLookup[i];
+    if (!entry) {
+      missingPhases.push(i);
+    } else if (entry.status === 'completed' || entry.status === 'skipped') {
+      completedPhases.push(i);
+    } else {
+      incompletePhases.push({ phase: i, name: PHASE_NAMES[i] || `Phase ${i}`, status: entry.status });
+    }
+  }
+
+  // Check 2: Time records for completed phases
+  for (const phaseNum of completedPhases) {
+    const entry = historyLookup[phaseNum];
+    if (entry.status === 'completed' && (entry.duration_seconds == null || entry.duration_seconds === 0)) {
+      warnings.push(`Phase ${phaseNum} (${PHASE_NAMES[phaseNum]}) completed but has no duration recorded`);
+    }
+  }
+
+  // Check 3: Artifact records (phase-{N}-summary.md)
+  const outputsDir = path.join(projectDir, '.sprint-state', 'phase-outputs');
+  for (const phaseNum of completedPhases) {
+    if (historyLookup[phaseNum].status === 'completed') {
+      const summaryFile = path.join(outputsDir, `phase-${phaseNum}-summary.md`);
+      if (!fs.existsSync(summaryFile)) {
+        warnings.push(`Phase ${phaseNum} summary missing: .sprint-state/phase-outputs/phase-${phaseNum}-summary.md`);
+      }
+    }
+  }
+
+  // Check 4: State consistency — phase field vs phase_history last entry
+  if (phaseHistory.length > 0) {
+    const lastEntry = phaseHistory[phaseHistory.length - 1];
+    if (state.phase !== undefined && state.phase !== lastEntry.phase) {
+      errors.push(
+        `State inconsistency: sprint-state.phase=${state.phase} but phase_history last entry is phase ${lastEntry.phase}`
+      );
+    }
+  }
+
+  // ── Determine verdict ──
+  const completedCount = completedPhases.length;
+  let verdict;
+  if (errors.length > 0 || completedCount < 4) {
+    verdict = 'FAIL';
+  } else if (completedCount >= 6 && errors.length === 0) {
+    verdict = 'PASS';
+  } else {
+    verdict = 'PASS_WITH_WARNINGS';
+  }
+
+  // ── Build result ──
+  const result = {
+    sprint_id: state.id || 'unknown',
+    branch: state.isolation?.branch || 'unknown',
+    coverage: {
+      completed: completedCount,
+      total: 6,
+      pct: Math.round((completedCount / 6) * 100),
+    },
+    missing_phases: missingPhases.map(p => ({ phase: p, name: PHASE_NAMES[p] || `Phase ${p}` })),
+    incomplete_phases: incompletePhases,
+    warnings,
+    errors,
+    verdict,
+  };
+
+  // ── Persist report (latest overwrites — expected behavior) ──
+  const reportPath = path.join(projectDir, '.sprint-state', 'audit-report.json');
+  try {
+    fs.writeFileSync(reportPath, JSON.stringify(result, null, 2), 'utf8');
+  } catch (err) {
+    // Report write failure is WARNING, not BLOCK
+    warnings.push(`Failed to write audit report: ${err.message}`);
+  }
+
+  // ── Output ──
+  if (jsonFlag) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHumanReadable(result, state);
+  }
+
+  // Exit code: FAIL → 1, others → 0
+  return verdict === 'FAIL' ? 1 : 0;
+}
+
+/**
+ * Print human-readable audit report.
+ * @param {object} result - Audit result object
+ * @param {object} state - Sprint state object
+ */
+function printHumanReadable(result, state) {
+  const lines = [];
+  lines.push('');
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push(`  Sprint Audit Report — ${result.sprint_id}`);
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push('');
+  lines.push(`  Branch: ${result.branch}`);
+  lines.push(`  Phase Coverage: ${result.coverage.completed}/${result.coverage.total} (${result.coverage.pct}%)`);
+  lines.push('');
+  lines.push('  Phase History:');
+
+  for (let i = 1; i <= 6; i++) {
+    const entry = result.incomplete_phases.find(p => p.phase === i);
+    const missing = result.missing_phases.find(p => p.phase === i);
+    const name = (PHASE_NAMES[i] || `Phase ${i}`).padEnd(10);
+
+    if (missing) {
+      lines.push(`  ❌ Phase ${i}/6  ${name} — not recorded`);
+    } else if (entry) {
+      lines.push(`  ⚠️  Phase ${i}/6  ${name} ${entry.status}  ← not yet completed`);
+    } else {
+      lines.push(`  ✅ Phase ${i}/6  ${name} completed`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push('');
+    lines.push('  Warnings:');
+    for (const w of result.warnings) {
+      lines.push(`  ⚠️  ${w}`);
+    }
+  }
+
+  if (result.errors.length > 0) {
+    lines.push('');
+    lines.push('  Errors:');
+    for (const e of result.errors) {
+      lines.push(`  ❌ ${e}`);
+    }
+  }
+
+  lines.push('');
+  const issueCount = result.warnings.length + result.errors.length;
+  lines.push(`  Overall: ${result.warnings.length} warning(s), ${result.errors.length} error(s)`);
+  lines.push(`  Verdict: ${result.verdict}`);
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  console.log(lines.join('\n'));
+}
+
+module.exports = { handleSprintAudit };