@boyingliu01/xp-gate 0.24.0 → 0.25.0

package/lib/__tests__/issue-519-phase-transition-guard.test.js

@@ -0,0 +1,233 @@
+/**
+ * @intent #519: A real pointer-drift incident (#507) showed that a MISSED
+ *         phase transition is invisible — the state file cannot distinguish
+ *         "never ran" from "not yet advanced". Guards under test:
+ *           (1) sequence guard: `completed` on phase n is refused unless phase
+ *               n-1 is completed/skipped, with `--force` as the explicit escape;
+ *           (2) before/after echo so "command didn't run" and "ran without
+ *               effect" are distinguishable in the output;
+ *           (3) an append-only transition audit log;
+ *           (4) phase_history field normalization (`name` → `phase_name`).
+ * @covers handlePhaseTransition guard/echo, appendTransitionAudit, migrateState
+ */
+
+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 } from '../phase-transition.js';
+import { SprintStateManager } from '../sprint-state-manager.js';
+import { migrateState } from '../sprint-state-migrator.js';
+
+function writeState(dir, state) {
+  try {
+    fs.mkdirSync(path.join(dir, '.sprint-state'), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, '.sprint-state', 'sprint-state.json'),
+      JSON.stringify(state, null, 2),
+    );
+  } catch (err) {
+    throw new Error(`writeState failed for ${dir}: ${err.message}`);
+  }
+}
+
+function baseState(overrides = {}) {
+  return {
+    _schema_version: 1,
+    id: 'sprint-519',
+    task_description: 'test',
+    phase: 2,
+    status: 'in_progress',
+    started_at: '2026-10-14T00:00:00Z',
+    phase_history: [],
+    isolation: { worktree_path: null, branch: null },
+    ...overrides,
+  };
+}
+
+describe('#519 phase-transition sequence guard', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('refuses `completed` on phase 3 when phase 2 is not completed/skipped', async () => {
+    writeState(dir, baseState({
+      phase: 3,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'in_progress' }],
+    }));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const stderr = errSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    errSpy.mockRestore();
+    expect(code).toBe(1);
+    expect(stderr).toContain('Cannot complete phase 3');
+    expect(stderr).toContain('phase 2');
+    expect(stderr).toContain('phase history');
+  });
+
+  it('refuses the jump and names --force as the override', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await handlePhaseTransition(['5', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const stderr = errSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    errSpy.mockRestore();
+    expect(stderr).toContain('--force');
+  });
+
+  it('allows `completed` when the previous phase is completed', async () => {
+    writeState(dir, baseState({
+      phase: 2,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'completed' }],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('treats a skipped previous phase as valid', async () => {
+    writeState(dir, baseState({
+      phase: 2,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'skipped' }],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('--force overrides the guard and warns', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x', '--force']);
+    const warned = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    outSpy.mockRestore();
+    warnSpy.mockRestore();
+    expect(code).toBe(0);
+    expect(warned).toContain('overridden');
+  });
+
+  it('does not guard phase 1 (no predecessor)', async () => {
+    writeState(dir, baseState({ phase: 1, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['1', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('does not guard non-completed statuses', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'in_progress', '--dir', dir]);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+});
+
+describe('#519 before/after echo', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519echo-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('prints before→after for the top-level phase/status and the entry', async () => {
+    // Phase 1 must be completed for the phase-2 completion to pass the
+    // sequence guard (#519) — otherwise the echo is never reached.
+    writeState(dir, baseState({
+      phase: 2,
+      status: 'in_progress',
+      phase_history: [
+        { phase: 1, name: 'PREP', status: 'completed' },
+        { phase: 2, phase_name: 'DESIGN', status: 'in_progress' },
+      ],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['2', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const output = outSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+    expect(output).toContain('before→after');
+    expect(output).toContain('in_progress → completed');
+  });
+});
+
+describe('#519 transition audit log + field normalization', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519audit-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('appends one JSON line per transition with from/to', () => {
+    writeState(dir, baseState({ phase: 2, phase_history: [] }));
+    const manager = new SprintStateManager(dir);
+    manager.transitionPhase(2, 'in_progress');
+    manager.transitionPhase(2, 'completed');
+    const auditFile = path.join(dir, '.sprint-state', 'transition-audit.jsonl');
+    expect(fs.existsSync(auditFile)).toBe(true);
+    const lines = fs.readFileSync(auditFile, 'utf8').trim().split('\n');
+    expect(lines.length).toBe(2);
+    const first = JSON.parse(lines[0]);
+    expect(first.phase).toBe(2);
+    expect(first.phase_name).toBe('DESIGN');
+    expect(first.to_status).toBe('in_progress');
+    expect(first.timestamp).toBeTruthy();
+    const second = JSON.parse(lines[1]);
+    expect(second.to_status).toBe('completed');
+  });
+
+  it('audit is best-effort: a write failure does not break the transition', () => {
+    writeState(dir, baseState({ phase: 2, phase_history: [] }));
+    const manager = new SprintStateManager(dir);
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // Break the real appendFileSync so appendTransitionAudit's OWN try/catch is
+    // exercised (mocking the method itself would bypass the production guard).
+    const appendSpy = vi.spyOn(fs, 'appendFileSync').mockImplementation(() => {
+      throw new Error('disk full');
+    });
+    expect(() => manager.transitionPhase(2, 'in_progress')).not.toThrow();
+    const warned = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    appendSpy.mockRestore();
+    warnSpy.mockRestore();
+    expect(warned).toContain('transition audit write failed');
+  });
+
+  it('migrateState normalizes legacy `name` into `phase_name`', () => {
+    // A legacy file (no _schema_version) whose phase 1 entry carries `name`
+    // rather than `phase_name` — the exact shape #507 left behind.
+    const legacy = baseState({
+      _schema_version: undefined,
+      phase_history: [{ phase: 1, name: 'PREP', status: 'completed' }],
+    });
+    const migrated = migrateState(legacy, dir);
+    const entry = migrated.phase_history[0];
+    // The canonical field is populated (via the legacy remap and/or the
+    // name→phase_name normalization) and the legacy field is preserved.
+    expect(entry.phase_name).toBeTruthy();
+    expect(entry.name).toBe('PREP');
+  });
+
+  it('migrateState backfills `name` from `phase_name` (both directions)', () => {
+    const legacy = baseState({
+      _schema_version: undefined,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'in_progress' }],
+    });
+    const migrated = migrateState(legacy, dir);
+    const entry = migrated.phase_history[0];
+    expect(entry.phase_name).toBeTruthy();
+    // `name` is backfilled so a reader consulting either field agrees.
+    expect(entry.name).toBe(entry.phase_name);
+  });
+});

package/lib/init.js

@@ -271,6 +271,46 @@ function printCliToolStatus() {
   }
 }
 
+/**
+ * Probe for gitleaks and warn when it is missing (#511).
+ *
+ * Gate 8 became fail-closed in #499: a missing gitleaks BLOCKs the commit
+ * outright (it does NOT skip, unlike the tools reported by
+ * printCliToolStatus). The user-facing installers never provisioned it, so an
+ * existing user upgrading into #499 hits a hard BLOCK on their next commit with
+ * no prior signal — this is the missing migration notice.
+ *
+ * Probe-and-prompt only: nothing is installed here (installing is the user's
+ * explicit choice, via the printed command). The fail-closed semantics of
+ * #499 are untouched.
+ *
+ * @param {(name: string) => {available: boolean, version?: string}} checkTool
+ * @param {(line: string) => void} [log]
+ * @returns {{available: boolean}} the probe result, for callers that branch on it
+ */
+function probeGitleaksNotice(checkTool, log = console.log) {
+  const result = checkTool('gitleaks');
+  if (result.available) {
+    log(`✓ gitleaks present${result.version ? `: ${result.version}` : ''}`);
+    return { available: true };
+  }
+
+  log('');
+  log('⚠  gitleaks is NOT installed.');
+  log('   Gate 8 (secret scanning) is FAIL-CLOSED since #499: your next commit');
+  log('   will be BLOCKED until gitleaks is available.');
+  log('');
+  log('   Install it now:');
+  log('     bash scripts/install-gitleaks.sh');
+  log('');
+  log('   Per-OS alternatives:');
+  log('     macOS:    brew install gitleaks');
+  log('     Linux:    https://github.com/gitleaks/gitleaks/releases');
+  log('     Windows:  winget install gitleaks  (or: scoop install gitleaks)');
+  log('');
+  return { available: false };
+}
+
 /**
  * Ask the user for confirmation via stdin.
  * @param {string} question - The yes/no question to display
@@ -352,6 +392,11 @@ async function init(args) {
   console.log('Checking CLI tools...');
   printCliToolStatus();
 
+  // #511: gitleaks is the one tool whose absence BLOCKS rather than SKIPs
+  // (Gate 8 fail-closed, #499) — surface it separately so an upgrading user
+  // has a migration path before the first blocked commit.
+  probeGitleaksNotice(checkCliTool);
+
   console.log('Checking platform dependencies...');
   // Detect platform and check/auto-install dependencies
   const platform = detectPlatform();
@@ -925,4 +970,4 @@ function injectKarpathyPrinciples(projectRoot) {
 // setupGlobal is exported so the global-install wiring (agents deployed to the
 // real HOME) can be audited under a sandboxed HOME, not just asserted to exist
 // — the historical miss was "local deployed, global did not" (#417, #429).
-module.exports = { init, promptBootstrap, installModuleRuntimeDeps, deployQoderDelphiAgents, configureQoderDelphiAgents, readQoderModelId, setupGlobal };
+module.exports = { init, promptBootstrap, installModuleRuntimeDeps, deployQoderDelphiAgents, configureQoderDelphiAgents, readQoderModelId, setupGlobal, probeGitleaksNotice };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-14T09:00:41.434Z",
+  "checked_at": "2026-10-15T07:13:54.700Z",
   "source": "network"
 }

package/lib/phase-transition.js

@@ -532,12 +532,14 @@ async function handlePhaseTransition(args = []) {
     console.log('  --render           Render ASCII dashboard after transition');
     console.log('  --dir <path>       Project directory (default: cwd)');
     console.log('  --skip-evidence <reason>  Skip evidence validation (requires reason)');
+    console.log('  --force            Override the phase sequence guard (#519)');
     console.log('');
     console.log('Examples:');
     console.log('  xp-gate phase-transition 1 completed');
     console.log('  xp-gate phase-transition 3 completed --render');
     console.log('  xp-gate phase-transition 2 in_progress --outputs \'{"spec":"path.yaml"}\'');
     console.log('  xp-gate phase-transition 4 completed --skip-evidence "Emergency hotfix"');
+    console.log('  xp-gate phase-transition 3 completed --force   # skip-order override');
     return 0;
   }
 
@@ -576,6 +578,9 @@ async function handlePhaseTransition(args = []) {
     }
   }
 
+  // #519: explicit override for the sequence guard below.
+  const forceTransition = args.includes('--force');
+
   // Validate inputs
   if (phase < 1 || phase > 6) {
     console.error(`Error: Phase must be 1-6, got ${phase}`);
@@ -592,6 +597,37 @@ async function handlePhaseTransition(args = []) {
   try {
     const manager = new SprintStateManager(projectDir);
 
+    // ── #519 Layer 0: Sequence guard ──
+    // `completed` on phase n requires phase n-1 to be completed/skipped first.
+    // #507 proved that a missed transition is invisible in the state file (the
+    // pointer just looks "not yet advanced"), so out-of-order completion —
+    // skipping a phase, or completing from a stale pointer — must be refused
+    // loudly rather than written silently. `--force` overrides for the rare
+    // legitimate case (e.g. retroactively recording a skipped phase).
+    if (status === 'completed' && phase >= 2) {
+      const seqState = manager.read();
+      if (seqState && Array.isArray(seqState.phase_history)) {
+        const prevPhase = phase - 1;
+        const prevEntry = seqState.phase_history.find(e => e.phase === prevPhase);
+        const prevOk = prevEntry && (prevEntry.status === 'completed' || prevEntry.status === 'skipped');
+        if (!prevOk && !forceTransition) {
+          const summary = seqState.phase_history
+            .map(e => `  ${e.phase}:${e.phase_name || PHASE_NAMES[e.phase] || '?'} = ${e.status}`)
+            .join('\n');
+          console.error(`❌ [sprint-audit] Cannot complete phase ${phase} (${PHASE_NAMES[phase]}):`);
+          console.error(`   phase ${prevPhase} (${PHASE_NAMES[prevPhase]}) is not completed/skipped.`);
+          console.error('   Current phase history:');
+          console.error(summary || '  (empty)');
+          console.error(`   Advance it first: xp-gate phase-transition ${prevPhase} completed`);
+          console.error('   Or override explicitly: --force');
+          return 1;
+        }
+        if (!prevOk && forceTransition) {
+          console.warn(`⚠️  [sprint-audit] Sequence guard overridden (--force): phase ${prevPhase} is not completed/skipped.`);
+        }
+      }
+    }
+
     // ── Layer 1: Pre-transition gate check ──
     // Check BEFORE transitionPhase() to validate previous phase completion.
     // Runs when status === 'in_progress' and phase >= 2.
@@ -640,9 +676,34 @@ async function handlePhaseTransition(args = []) {
       }
     }
 
+    // Capture the before-image for the echo below (#519). Read once here so a
+    // concurrent writer cannot make before/after disagree about their baseline.
+    const beforeSnapshot = (() => {
+      try {
+        const s = manager.read();
+        if (!s) return { phase: undefined, status: undefined, entryStatus: undefined };
+        const e = Array.isArray(s.phase_history) ? s.phase_history.find(x => x.phase === phase) : undefined;
+        return { phase: s.phase, status: s.status, entryStatus: e ? e.status : undefined };
+      } catch {
+        return { phase: undefined, status: undefined, entryStatus: undefined };
+      }
+    })();
+
     const newState = manager.transitionPhase(phase, status, { outputs });
 
+    // #519: before/after echo. The #507 failure mode was "the command either
+    // never ran or ran without effect" — both look identical in a terminal that
+    // prints only a success line. Printing the observed state on both sides
+    // makes those two cases distinguishable in the output itself.
+    const afterEntry = Array.isArray(newState.phase_history)
+      ? newState.phase_history.find(e => e.phase === phase)
+      : undefined;
+    const oldTop = `${beforeSnapshot.phase ?? '-'}/${beforeSnapshot.status ?? '-'}`;
+    const newTop = `${newState.phase ?? '-'}/${newState.status ?? '-'}`;
+    const oldEntry = beforeSnapshot.entryStatus ?? '(none)';
+    const newEntryStatus = afterEntry ? afterEntry.status : '(none)';
     console.log(`✅ Phase ${phase} transitioned to '${status}'`);
+    console.log(`   before→after  phase/status: ${oldTop} → ${newTop}  |  phase ${phase} entry: ${oldEntry} → ${newEntryStatus}`);
 
     // ── Layer 1.5: Auto-trigger Layer 2 reminder on Phase 6 completed ──
     if (phase === 6 && status === 'completed') {

package/lib/sprint-state-manager.js

@@ -12,6 +12,38 @@ const fs = require('fs');
 const path = require('path');
 const { migrateState, createInitialState, rollbackState, LEGACY_PHASE_MAP } = require('./sprint-state-migrator');
 
+/** Canonical phase order; index = phase - 1. */
+const PHASE_NAMES = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+
+/**
+ * Apply a status change to the phase_history entry for `phase`, creating it on
+ * first sight, and stamp started_at/completed_at/duration_seconds.
+ *
+ * Module-level and pure (it only mutates the passed-in state), extracted from
+ * transitionPhase (#519) so that method stays within the long-function budget.
+ */
+function applyHistoryEntry(state, phase, phaseName, status) {
+  let entry = state.phase_history.find(e => e.phase === phase);
+  if (!entry) {
+    entry = { phase, phase_name: phaseName, status };
+    state.phase_history.push(entry);
+  }
+
+  entry.status = status;
+  if (status === 'in_progress' && !entry.started_at) {
+    entry.started_at = new Date().toISOString();
+  }
+  if (status === 'completed' || status === 'skipped') {
+    entry.completed_at = new Date().toISOString();
+    if (entry.started_at) {
+      const startMs = new Date(entry.started_at).getTime();
+      const endMs = new Date(entry.completed_at).getTime();
+      entry.duration_seconds = Math.round((endMs - startMs) / 1000);
+    }
+  }
+  return entry;
+}
+
 class SprintStateManager {
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
@@ -48,59 +80,57 @@ class SprintStateManager {
   }
 
   write(state) {
-    // Ensure state directory exists
-    if (!fs.existsSync(this.stateDir)) {
-      fs.mkdirSync(this.stateDir, { recursive: true });
+    try {
+      if (!fs.existsSync(this.stateDir)) {
+        fs.mkdirSync(this.stateDir, { recursive: true });
+      }
+      // Atomic write: write to tmp, then rename
+      const tmpFile = this.stateFile + '.tmp';
+      fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
+      fs.renameSync(tmpFile, this.stateFile);
+    } catch (err) {
+      throw new Error(`Failed to write sprint state: ${err.message}`);
     }
-
-    // Atomic write: write to tmp, then rename
-    const tmpFile = this.stateFile + '.tmp';
-    fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
-    fs.renameSync(tmpFile, this.stateFile);
   }
 
   transitionPhase(phase, status, options = {}) {
     const state = this.read() || createInitialState(this.projectRoot);
 
-    // Update current phase
-    state.phase = phase;
-
-    // Find or create phase_history entry
-    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
-    const phaseName = phaseNames[phase - 1];
-
-    let entry = state.phase_history.find(e => e.phase === phase);
-    if (!entry) {
-      entry = {
-        phase,
-        phase_name: phaseName,
-        status,
-      };
-      state.phase_history.push(entry);
-    }
+    // Capture the before-image so the caller can echo a before/after
+    // comparison. #519: the same values feed the append-only audit log.
+    const beforePhase = state.phase;
+    const beforeEntry = Array.isArray(state.phase_history)
+      ? state.phase_history.find(e => e.phase === phase)
+      : undefined;
+    const beforeStatus = beforeEntry ? beforeEntry.status : undefined;
 
-    // Update entry
-    entry.status = status;
-    if (status === 'in_progress' && !entry.started_at) {
-      entry.started_at = new Date().toISOString();
-    }
-    if (status === 'completed' || status === 'skipped') {
-      entry.completed_at = new Date().toISOString();
-      if (entry.started_at) {
-        const startMs = new Date(entry.started_at).getTime();
-        const endMs = new Date(entry.completed_at).getTime();
-        entry.duration_seconds = Math.round((endMs - startMs) / 1000);
-      }
-    }
+    state.phase = phase;
+    const phaseName = PHASE_NAMES[phase - 1];
+    applyHistoryEntry(state, phase, phaseName, status);
 
-    // Update outputs if provided
     if (options.outputs) {
       state.outputs = { ...state.outputs, ...options.outputs };
     }
 
-    // Write state atomically
     this.write(state);
 
+    // #519: append-only transition audit. The #507 incident proved that a
+    // MISSED transition is invisible in the state file — the pointer drift
+    // looked identical to a legitimately-not-yet-run phase. A per-transition
+    // record — from/to plus statuses — lets post-mortems distinguish "never
+    // ran" from "ran and was overwritten". Best-effort: a logging failure must
+    // never break the transition, same contract as the onTransition callback.
+    this.appendTransitionAudit({
+      phase,
+      phase_name: phaseName,
+      from_phase: beforePhase,
+      // from_status === undefined together with a defined to_status is exactly
+      // what proves the phase was reached from nothing — i.e. never ran.
+      from_status: beforeStatus,
+      to_status: status,
+      timestamp: new Date().toISOString(),
+    });
+
     // Trigger onTransition callback (for auto-render)
     if (typeof options.onTransition === 'function') {
       try {
@@ -114,6 +144,23 @@ class SprintStateManager {
     return state;
   }
 
+  /**
+   * Append one JSON line to .sprint-state/transition-audit.jsonl (#519).
+   * Never throws — audit is evidence, not a gate.
+   * @param {object} record
+   */
+  appendTransitionAudit(record) {
+    try {
+      if (!fs.existsSync(this.stateDir)) {
+        fs.mkdirSync(this.stateDir, { recursive: true });
+      }
+      const auditFile = path.join(this.stateDir, 'transition-audit.jsonl');
+      fs.appendFileSync(auditFile, JSON.stringify(record) + '\n', 'utf8');
+    } catch (err) {
+      console.warn(`[WARN] transition audit write failed: ${err.message}`);
+    }
+  }
+
   rollback() {
     return rollbackState(this.stateFile, this.backupFile);
   }

package/lib/sprint-state-migrator.js

@@ -57,18 +57,9 @@ function migrateState(state, stateDir) {
   if (!state.phase_history) { state.phase_history = []; }
   if (!state.isolation) { state.isolation = { worktree_path: null, branch: null }; }
 
-  state.phase_history = state.phase_history.map(entry => {
-    const phaseNum = String(entry.phase);
-    const mapped = LEGACY_PHASE_MAP[phaseNum];
-    if (mapped) {
-      warnings.push(`Migrated legacy phase ${entry.phase} → ${mapped.phase} (${mapped.phase_name})`);
-      return { ...entry, phase: mapped.phase, phase_name: mapped.phase_name };
-    }
-    if (!entry.phase_name && entry.phase >= 1 && entry.phase <= 6) {
-      entry.phase_name = PHASE_NAMES[entry.phase - 1];
-    }
-    return entry;
-  });
+  state.phase_history = state.phase_history.map(entry =>
+    normalizePhaseEntry(entry, warnings),
+  );
 
   const currentPhaseNum = String(state.phase);
   const currentMapped = LEGACY_PHASE_MAP[currentPhaseNum];
@@ -91,6 +82,47 @@ function migrateState(state, stateDir) {
   return state;
 }
 
+/**
+ * Migrate and normalize a single phase_history entry.
+ *
+ * Two passes, in this order:
+ *   1. legacy numbering → current numbering via LEGACY_PHASE_MAP;
+ *   2. field normalization: phase 1 historically carried `name` while phase 2+
+ *      carried `phase_name` (transitionPhase always writes `phase_name`).
+ *      Normalize to `phase_name` as the single canonical field, in BOTH
+ *      directions so a half-migrated file converges. The legacy `name` is kept
+ *      (not deleted) so any reader still consulting it keeps working.
+ *
+ * Ordering matters: the normalization must run for every entry, including those
+ * the legacy remap just rewrote — LEGACY_PHASE_MAP covers every phase 1-6, so
+ * gating normalization on "not remapped" would skip exactly the legacy files it
+ * exists for. (#507 left such a file: phase 1 with `name: 'PREP'`, phase 2+
+ * with `phase_name`.)
+ *
+ * @param {Object} entry - One phase_history entry (possibly legacy-shaped)
+ * @param {string[]} warnings - Accumulator for human-readable migration notes
+ * @returns {Object} The normalized entry
+ */
+function normalizePhaseEntry(entry, warnings) {
+  const phaseNum = String(entry.phase);
+  const mapped = LEGACY_PHASE_MAP[phaseNum];
+  if (mapped) {
+    warnings.push(`Migrated legacy phase ${entry.phase} → ${mapped.phase} (${mapped.phase_name})`);
+    entry = { ...entry, phase: mapped.phase, phase_name: mapped.phase_name };
+  }
+
+  if (!entry.phase_name && entry.name) {
+    entry.phase_name = entry.name;
+  }
+  if (!entry.phase_name && entry.phase >= 1 && entry.phase <= 6) {
+    entry.phase_name = PHASE_NAMES[entry.phase - 1];
+  }
+  if (!entry.name && entry.phase_name) {
+    entry.name = entry.phase_name;
+  }
+  return entry;
+}
+
 /**
  * Create initial sprint state for new sprints.
  *
@@ -120,17 +152,23 @@ function createInitialState(projectRoot) {
  * @param {string} stateDir - Path to .sprint-state directory
  */
 function logMigrationWarnings(warnings, stateDir) {
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
-  }
-
-  const warningsFile = path.join(stateDir, 'migration-warnings.json');
-  const existing = fs.existsSync(warningsFile)
-    ? JSON.parse(fs.readFileSync(warningsFile, 'utf8'))
-    : [];
+  try {
+    if (!fs.existsSync(stateDir)) {
+      fs.mkdirSync(stateDir, { recursive: true });
+    }
 
-  existing.push({ timestamp: new Date().toISOString(), warnings });
-  fs.writeFileSync(warningsFile, JSON.stringify(existing, null, 2), 'utf8');
+    const warningsFile = path.join(stateDir, 'migration-warnings.json');
+    const existing = fs.existsSync(warningsFile)
+      ? JSON.parse(fs.readFileSync(warningsFile, 'utf8'))
+      : [];
+
+    existing.push({ timestamp: new Date().toISOString(), warnings });
+    fs.writeFileSync(warningsFile, JSON.stringify(existing, null, 2), 'utf8');
+  } catch (err) {
+    // Migration must still return the migrated state; a failure to persist the
+    // warning log is reported to stderr and never thrown.
+    console.warn(`[WARN] could not write migration warnings: ${err.message}`);
+  }
 }
 
 /**

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-10-14
-**Commit:** e466ce16
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.24.0.0
+**Version:** 0.25.0.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.