@boyingliu01/xp-gate 0.14.28 → 0.14.30

package/bin/xp-gate.js

@@ -203,6 +203,14 @@ const COMMANDS = {
       handlePhaseTransition(subargs).then(code => process.exit(code));
     },
     usage: 'xp-gate phase-transition <phase> <status> [--render] [--outputs <json>]'
+  },
+  'sprint-audit': {
+    description: 'Final sprint completeness audit (Phase 6 CLOSE)',
+    run: subargs => {
+      const { handleSprintAudit } = require('../lib/sprint-audit.js');
+      handleSprintAudit(subargs).then(code => process.exit(code));
+    },
+    usage: 'xp-gate sprint-audit [--dir <path>] [--json]'
   }
 };
 

package/lib/__tests__/phase-transition.test.js

@@ -8,11 +8,11 @@
  * @covers AC-338-04 (--outputs flag records outputs in state)
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { handlePhaseTransition, renderDashboard } from '../phase-transition.js';
+import { handlePhaseTransition, renderDashboard, PHASE_NAMES } from '../phase-transition.js';
 
 describe('phase-transition', () => {
   let tmpDir;
@@ -171,4 +171,102 @@ describe('phase-transition', () => {
       expect(result).toContain('sprint-min');
     });
   });
+  describe('Layer 1: Pre-transition gate check', () => {
+    it('warns when previous phase not completed', async () => {
+      // Set up: Phase 1 completed, then try Phase 3 in_progress (skipping Phase 2)
+      await handlePhaseTransition(['1', 'completed', '--dir', tmpDir]);
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['3', 'in_progress', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Phase 2 (DESIGN) not recorded')
+      );
+      warnSpy.mockRestore();
+    });
+
+    it('does NOT warn when previous phase is completed', async () => {
+      await handlePhaseTransition(['1', 'completed', '--dir', tmpDir]);
+      await handlePhaseTransition(['2', 'completed', '--dir', tmpDir]);
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['3', 'in_progress', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('does NOT warn when previous phase is skipped', async () => {
+      await handlePhaseTransition(['1', 'completed', '--dir', tmpDir]);
+      await handlePhaseTransition(['2', 'skipped', '--dir', tmpDir]);
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['3', 'in_progress', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('skips check when no sprint-state.json exists', async () => {
+      // No state file — fresh project
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['2', 'in_progress', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('does NOT check for Phase 1 (no predecessor)', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['1', 'in_progress', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('handles phase_history with gaps correctly', async () => {
+      // Set up: Phase 1 completed, Phase 3 completed (gap at Phase 2)
+      await handlePhaseTransition(['1', 'completed', '--dir', tmpDir]);
+      // Manually add Phase 3 without Phase 2
+      const stateFile = path.join(tmpDir, '.sprint-state', 'sprint-state.json');
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      state.phase_history.push({ phase: 3, phase_name: 'BUILD', status: 'completed' });
+      state.phase = 3;
+      fs.writeFileSync(stateFile, JSON.stringify(state));
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['4', 'in_progress', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      // Phase 3 is completed, so no warning for Phase 3→4 transition
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe('Layer 1.5: Phase 6 auto-trigger', () => {
+    it('outputs sprint-audit reminder on Phase 6 completed', async () => {
+      // Set up state through Phase 5
+      await handlePhaseTransition(['1', 'completed', '--dir', tmpDir]);
+      await handlePhaseTransition(['2', 'completed', '--dir', tmpDir]);
+      await handlePhaseTransition(['3', 'completed', '--dir', tmpDir]);
+      await handlePhaseTransition(['4', 'completed', '--dir', tmpDir]);
+      await handlePhaseTransition(['5', 'completed', '--dir', tmpDir]);
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handlePhaseTransition(['6', 'completed', '--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(logSpy).toHaveBeenCalledWith(
+        expect.stringContaining('sprint-audit')
+      );
+      logSpy.mockRestore();
+    });
+  });
+
+  describe('PHASE_NAMES export', () => {
+    it('exports PHASE_NAMES as shared constant', () => {
+      expect(PHASE_NAMES).toBeDefined();
+      expect(PHASE_NAMES[1]).toBe('PREP');
+      expect(PHASE_NAMES[6]).toBe('CLOSE');
+    });
+  });
 });

package/lib/__tests__/sprint-audit.test.js

@@ -0,0 +1,207 @@
+/**
+ * Tests for sprint-audit CLI command (Layer 2)
+ * @test REQ-338 Sprint audit — final completeness check
+ * @intent Verify sprint-audit correctly checks phase coverage, artifacts, consistency
+ * @covers AC-AUDIT-01 (SKIP when no sprint-state.json)
+ * @covers AC-AUDIT-02 (PASS when 6/6 completed)
+ * @covers AC-AUDIT-03 (PASS_WITH_WARNINGS when 4-5/6 completed)
+ * @covers AC-AUDIT-04 (FAIL when <4/6 completed)
+ * @covers AC-AUDIT-05 (FAIL on state inconsistency)
+ * @covers AC-AUDIT-06 (--json flag outputs JSON)
+ * @covers AC-AUDIT-07 (report persisted to audit-report.json)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { handleSprintAudit } from '../sprint-audit.js';
+
+describe('sprint-audit', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-audit-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeState(state) {
+    const stateDir = path.join(tmpDir, '.sprint-state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), JSON.stringify(state));
+  }
+
+  function makeState(overrides = {}) {
+    return {
+      _schema_version: 1,
+      id: 'sprint-test-audit',
+      task_description: 'Test audit feature',
+      phase: 6,
+      status: 'completed',
+      started_at: '2026-07-22T10:00:00Z',
+      phase_history: [],
+      isolation: { branch: 'sprint/test-audit', worktree_path: null },
+      outputs: {},
+      ...overrides,
+    };
+  }
+
+  function makePhaseHistory(completedPhases) {
+    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+    return completedPhases.map((p, i) => ({
+      phase: p,
+      phase_name: phaseNames[p - 1],
+      status: 'completed',
+      started_at: `2026-07-22T10:${String(i).padStart(2, '0')}:00Z`,
+      completed_at: `2026-07-22T10:${String(i).padStart(2, '0')}:30Z`,
+      duration_seconds: 30,
+    }));
+  }
+
+  describe('handleSprintAudit()', () => {
+    it('returns 0 and shows help with --help', async () => {
+      const code = await handleSprintAudit(['--help']);
+      expect(code).toBe(0);
+    });
+
+    it('returns SKIP (exit 0) when no sprint-state.json exists', async () => {
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('No sprint-state.json'));
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS when 6/6 phases completed', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      // Check output contains PASS
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS');
+      expect(output).toContain('6/6');
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS_WITH_WARNINGS when 5/6 completed', async () => {
+      writeState(makeState({ phase: 5, phase_history: makePhaseHistory([1, 2, 3, 4, 5]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS_WITH_WARNINGS');
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS_WITH_WARNINGS when 4/6 completed', async () => {
+      writeState(makeState({ phase: 4, phase_history: makePhaseHistory([1, 2, 3, 4]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS_WITH_WARNINGS');
+      logSpy.mockRestore();
+    });
+
+    it('returns FAIL when <4/6 completed', async () => {
+      writeState(makeState({ phase: 3, phase_history: makePhaseHistory([1, 2, 3]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('FAIL');
+      logSpy.mockRestore();
+    });
+
+    it('returns FAIL on state inconsistency (phase vs phase_history)', async () => {
+      const history = makePhaseHistory([1, 2, 3, 4, 5, 6]);
+      writeState(makeState({ phase: 3, phase_history: history })); // phase=3 but last entry is 6
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('State inconsistency');
+      logSpy.mockRestore();
+    });
+
+    it('outputs JSON when --json flag is set', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.verdict).toBe('PASS');
+      expect(result.coverage.completed).toBe(6);
+      logSpy.mockRestore();
+    });
+
+    it('counts skipped phases as completed in coverage', async () => {
+      const history = makePhaseHistory([1, 2, 3, 4, 5]);
+      history.push({
+        phase: 6, phase_name: 'CLOSE', status: 'skipped',
+        started_at: '2026-07-22T10:05:00Z', completed_at: '2026-07-22T10:05:00Z', duration_seconds: 0,
+      });
+      writeState(makeState({ phase: 6, phase_history: history }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.coverage.completed).toBe(6);
+      expect(result.verdict).toBe('PASS');
+      logSpy.mockRestore();
+    });
+
+    it('warns about missing summary files for completed phases', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+      // No phase-outputs directory → all summaries missing
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.warnings.length).toBeGreaterThan(0);
+      expect(result.warnings.some(w => w.includes('summary missing'))).toBe(true);
+      logSpy.mockRestore();
+    });
+
+    it('persists audit report to audit-report.json', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      await handleSprintAudit(['--dir', tmpDir]);
+      logSpy.mockRestore();
+
+      const reportPath = path.join(tmpDir, '.sprint-state', 'audit-report.json');
+      expect(fs.existsSync(reportPath)).toBe(true);
+      const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+      expect(report.verdict).toBe('PASS');
+      expect(report.sprint_id).toBe('sprint-test-audit');
+    });
+
+    it('handles corrupted sprint-state.json gracefully', async () => {
+      const stateDir = path.join(tmpDir, '.sprint-state');
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), 'not-valid-json');
+
+      const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse'));
+      errSpy.mockRestore();
+    });
+  });
+});

package/lib/phase-transition.js

@@ -23,8 +23,18 @@
 'use strict';
 
 const path = require('path');
+const fs = require('fs');
 const { SprintStateManager } = require('./sprint-state-manager');
 
+/**
+ * Shared phase name lookup — single source of truth.
+ * Used by renderDashboard, sprint-audit, and Layer 1 gate check.
+ */
+const PHASE_NAMES = {
+  1: 'PREP', 2: 'DESIGN', 3: 'BUILD',
+  4: 'VERIFY', 5: 'SHIP', 6: 'CLOSE',
+};
+
 /**
  * Render ASCII dashboard from sprint state.
  * Reuses the formatSprintTable logic from sprint-status.
@@ -34,10 +44,7 @@ const { SprintStateManager } = require('./sprint-state-manager');
 function renderDashboard(state) {
   if (!state) return 'No sprint state found';
 
-  const PHASE_NAMES = {
-    '1': 'PREP', '2': 'DESIGN', '3': 'BUILD',
-    '4': 'VERIFY', '5': 'SHIP', '6': 'CLOSE',
-  };
+  const PHASE_NAMES_LOCAL = PHASE_NAMES;
 
   function statusIcon(status) {
     switch (status) {
@@ -75,7 +82,7 @@ function renderDashboard(state) {
   }
 
   const currentPhase = state.phase || 1;
-  const currentPhaseName = PHASE_NAMES[String(currentPhase)] || `Phase ${currentPhase}`;
+  const currentPhaseName = PHASE_NAMES_LOCAL[String(currentPhase)] || `Phase ${currentPhase}`;
 
   // Progress bar
   const completedCount = Object.values(historyLookup).filter(h => h.status === 'completed').length;
@@ -99,7 +106,7 @@ function renderDashboard(state) {
   for (let i = 1; i <= 6; i++) {
     const entry = historyLookup[String(i)];
     const icon = statusIcon(entry?.status || (i < currentPhase ? 'completed' : i === currentPhase ? 'in_progress' : 'pending'));
-    const name = (PHASE_NAMES[String(i)] || `Phase ${i}`).padEnd(10);
+    const name = (PHASE_NAMES_LOCAL[String(i)] || `Phase ${i}`).padEnd(10);
     const dur = formatDuration(entry?.duration_seconds).padEnd(8);
     lines.push(`|  ${icon} Phase ${i}/6  ${name} ${dur}          |`);
   }
@@ -190,10 +197,41 @@ async function handlePhaseTransition(args = []) {
   // Execute transition
   try {
     const manager = new SprintStateManager(projectDir);
+
+    // ── Layer 1: Pre-transition gate check ──
+    // Check BEFORE transitionPhase() to validate previous phase completion.
+    // Runs when status === 'in_progress' and phase >= 2.
+    // No side effects — only outputs WARNING, does not modify state.
+    if (status === 'in_progress' && phase >= 2) {
+      const preState = manager.read();
+      if (preState && Array.isArray(preState.phase_history)) {
+        const prevPhase = phase - 1;
+        const prevEntry = preState.phase_history.find(e => e.phase === prevPhase);
+        const prevName = PHASE_NAMES[prevPhase] || `Phase ${prevPhase}`;
+        // 'completed' and 'skipped' are both valid predecessor statuses
+        if (!prevEntry || (prevEntry.status !== 'completed' && prevEntry.status !== 'skipped')) {
+          console.warn(
+            `⚠️  [sprint-audit] Phase ${prevPhase} (${prevName}) not recorded as 'completed'`
+          );
+          console.warn(
+            `   Previous phase may have been skipped. Run: xp-gate phase-transition ${prevPhase} completed`
+          );
+        }
+      }
+      // If no sprint-state.json exists yet, skip check (no previous phase to validate)
+    }
+
     const newState = manager.transitionPhase(phase, status, { outputs });
 
     console.log(`✅ Phase ${phase} transitioned to '${status}'`);
 
+    // ── Layer 1.5: Auto-trigger Layer 2 reminder on Phase 6 completed ──
+    if (phase === 6 && status === 'completed') {
+      console.log('');
+      console.log('📋 [sprint-audit] Sprint complete — run final coverage audit:');
+      console.log('   npx xp-gate sprint-audit');
+    }
+
     // Auto-render dashboard if --render flag is set
     if (renderFlag) {
       console.log('');
@@ -208,4 +246,4 @@ async function handlePhaseTransition(args = []) {
   }
 }
 
-module.exports = { handlePhaseTransition, renderDashboard };
+module.exports = { handlePhaseTransition, renderDashboard, PHASE_NAMES };

package/lib/sprint-audit.js

@@ -0,0 +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 };

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.14.28",
+  "version": "0.14.30",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"
@@ -39,7 +39,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "version": "0.14.28",
+    "version": "0.14.30",
     "prepack": "node scripts/sync-package-content.js",
     "test": "echo \"Run tests\" && exit 0"
   },

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.14.28",
+  "version": "0.14.30",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 10 quality gates (Gate 0-9), Sprint Flow (11 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/sprint-flow/references/orchestration-rules.md

@@ -103,6 +103,16 @@
 
 3. **等待用户确认 checkpoint**（如适用）
 
+4. **Phase 6 CLOSE 完成后运行 sprint-audit**（自动提醒，Layer 1.5 触发）：
+   ```
+   npx xp-gate sprint-audit
+   ```
+   - 检查 phase 覆盖度、时间记录、输出物记录、状态一致性
+   - 输出人类可读报告或 JSON（`--json`）
+   - 报告写入 `.sprint-state/audit-report.json`（最新覆盖）
+   - Verdict: PASS / PASS_WITH_WARNINGS / FAIL / SKIP
+   - `phase-transition` CLI 在 Phase 6 completed 时自动输出提醒，无需额外指令
+
 ### Background Task Resume Protocol (MANDATORY — Issue #248)
 
 After dispatching background agents with `run_in_background=true`:

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.14.28",
+  "version": "0.14.30",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/opencode/skills/sprint-flow/references/orchestration-rules.md

@@ -103,6 +103,16 @@
 
 3. **等待用户确认 checkpoint**（如适用）
 
+4. **Phase 6 CLOSE 完成后运行 sprint-audit**（自动提醒，Layer 1.5 触发）：
+   ```
+   npx xp-gate sprint-audit
+   ```
+   - 检查 phase 覆盖度、时间记录、输出物记录、状态一致性
+   - 输出人类可读报告或 JSON（`--json`）
+   - 报告写入 `.sprint-state/audit-report.json`（最新覆盖）
+   - Verdict: PASS / PASS_WITH_WARNINGS / FAIL / SKIP
+   - `phase-transition` CLI 在 Phase 6 completed 时自动输出提醒，无需额外指令
+
 ### Background Task Resume Protocol (MANDATORY — Issue #248)
 
 After dispatching background agents with `run_in_background=true`:

package/plugins/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.14.28",
+  "version": "0.14.30",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 10 quality gates (Gate 0-9), Sprint Flow (11 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, 3 experts from ≥2 providers, domestic models only). Supports design + code-walkthrough modes.

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/skills/sprint-flow/references/orchestration-rules.md

@@ -103,6 +103,16 @@
 
 3. **等待用户确认 checkpoint**（如适用）
 
+4. **Phase 6 CLOSE 完成后运行 sprint-audit**（自动提醒，Layer 1.5 触发）：
+   ```
+   npx xp-gate sprint-audit
+   ```
+   - 检查 phase 覆盖度、时间记录、输出物记录、状态一致性
+   - 输出人类可读报告或 JSON（`--json`）
+   - 报告写入 `.sprint-state/audit-report.json`（最新覆盖）
+   - Verdict: PASS / PASS_WITH_WARNINGS / FAIL / SKIP
+   - `phase-transition` CLI 在 Phase 6 completed 时自动输出提醒，无需额外指令
+
 ### Background Task Resume Protocol (MANDATORY — Issue #248)
 
 After dispatching background agents with `run_in_background=true`:

package/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-07-22
-**Commit:** a39f4e7
+**Commit:** a465b02
 **Branch:** main
-**Version:** 0.14.28.0
+**Version:** 0.14.30.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.