@boyingliu01/xp-gate 0.14.9 → 0.14.11

package/lib/__tests__/install-skill.test.js

@@ -178,7 +178,8 @@ describe('install-skill', () => {
     expect(fs.existsSync(configFile)).toBe(true);
     const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
     expect(config.installedSkills).toHaveProperty('delphi-review');
-    expect(config.installedSkills['delphi-review'].version).toBe('1.0.0');
+    // Version should be actual CLI version (0.14.10.0), not hardcoded '1.0.0'
+    expect(config.installedSkills['delphi-review'].version).toBe('0.14.10.0');
     expect(config.installedSkills['delphi-review'].installedAt).toMatch(/^\d{4}-/);
   });
 

package/lib/__tests__/sprint-discovery.test.ts

@@ -322,10 +322,12 @@ describe('sprint-discovery: discoverActiveSprints', () => {
       // no id, no status, no started_at
       task_description: 'Partial fields only',
     });
-    // Should not throw, result should be skipped (no valid id)
+    // After migration, missing id gets auto-generated, so result is found
     const results = sprintDiscovery.discoverActiveSprints(TMP_ROOT);
     const partials = results.filter(r => r.state.task_description === 'Partial fields only');
-    expect(partials.length).toBe(0);
+    expect(partials.length).toBe(1);
+    // Migrated state should have auto-generated id
+    expect(partials[0].state.id).toMatch(/^sprint-\d+$/);
   });
 
   test('handles EACCES on .sprint-state/ directory gracefully', () => {
@@ -359,7 +361,7 @@ describe('sprint-discovery: discoverActiveSprints', () => {
     const results = sprintDiscovery.discoverActiveSprints(TMP_ROOT);
     const desc = results.filter(r => r.state.id === 'sprint-2026-06-23-nodesc');
     expect(desc.length).toBe(1);
-    // task_description will be null/undefined, but entry should still be returned
-    expect(desc[0].state.task_description).toBeUndefined();
+    // After migration, missing task_description gets default '-'
+    expect(desc[0].state.task_description).toBe('-');
   });
 });

package/lib/__tests__/sprint-state-manager.test.js

@@ -0,0 +1,279 @@
+/**
+ * Tests for Sprint State Manager
+ * @test REQ-001 Sprint State Manager
+ * @intent Verify read/write/migration/transitionPhase/rollback
+ * @covers AC-001-01, AC-001-02, AC-001-03
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { SprintStateManager, LEGACY_PHASE_MAP } from '../sprint-state-manager.js';
+import { migrateState, createInitialState } from '../sprint-state-migrator.js';
+
+describe('SprintStateManager', () => {
+  let tmpDir;
+  let manager;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-state-test-'));
+    manager = new SprintStateManager(tmpDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('read()', () => {
+    it('returns null when file does not exist', () => {
+      const state = manager.read();
+      expect(state).toBeNull();
+    });
+
+    it('reads valid state file', () => {
+      const state = {
+        _schema_version: 1,
+        id: 'sprint-123',
+        task_description: 'Test sprint',
+        phase: 2,
+        status: 'in_progress',
+        started_at: '2026-07-14T10:00:00Z',
+        phase_history: [],
+        isolation: { worktree_path: tmpDir, branch: 'test' },
+      };
+      fs.mkdirSync(path.join(tmpDir, '.sprint-state'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, '.sprint-state', 'sprint-state.json'),
+        JSON.stringify(state, null, 2)
+      );
+
+      const result = manager.read();
+      expect(result.id).toBe('sprint-123');
+      expect(result._schema_version).toBe(1);
+    });
+
+    it('auto-migrates legacy state and creates backup', () => {
+      const legacyState = {
+        id: 'sprint-legacy',
+        task_description: 'Legacy sprint',
+        phase: -1, // Legacy ISOLATE → 1 (PREP)
+        status: 'completed',
+        phase_history: [
+          { phase: -1, phase_name: 'ISOLATE', status: 'completed', timestamp: '2026-07-14T10:00:00Z' },
+        ],
+        isolation: { worktree_path: tmpDir, branch: 'test' },
+      };
+      fs.mkdirSync(path.join(tmpDir, '.sprint-state'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, '.sprint-state', 'sprint-state.json'),
+        JSON.stringify(legacyState, null, 2)
+      );
+
+      const result = manager.read();
+
+      // Should be migrated
+      expect(result._schema_version).toBe(1);
+      expect(result.phase).toBe(1); // -1 → 1
+      expect(result.phase_history[0].phase).toBe(1);
+      expect(result.phase_history[0].phase_name).toBe('PREP');
+      expect(result.phase_history[0].started_at).toBe('2026-07-14T10:00:00Z'); // timestamp → started_at
+
+      // Backup should exist
+      const backupExists = fs.existsSync(path.join(tmpDir, '.sprint-state', 'sprint-state.json.backup'));
+      expect(backupExists).toBe(true);
+    });
+  });
+
+  describe('write()', () => {
+    it('writes state atomically', () => {
+      const state = {
+        _schema_version: 1,
+        id: 'sprint-test',
+        task_description: 'Test',
+        phase: 1,
+        status: 'in_progress',
+        started_at: new Date().toISOString(),
+        phase_history: [],
+        isolation: { worktree_path: tmpDir, branch: 'test' },
+      };
+
+      manager.write(state);
+
+      const written = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, '.sprint-state', 'sprint-state.json'), 'utf8')
+      );
+      expect(written.id).toBe('sprint-test');
+
+      // Tmp file should not exist (atomic write completed)
+      const tmpExists = fs.existsSync(path.join(tmpDir, '.sprint-state', 'sprint-state.json.tmp'));
+      expect(tmpExists).toBe(false);
+    });
+  });
+
+  describe('transitionPhase()', () => {
+    it('creates new phase_history entry', () => {
+      // Create initial state
+      const initialState = createInitialState(tmpDir);
+      manager.write(initialState);
+
+      // Transition to phase 2
+      const result = manager.transitionPhase(2, 'in_progress');
+
+      expect(result.phase).toBe(2);
+      expect(result.phase_history.length).toBe(1);
+      expect(result.phase_history[0].phase).toBe(2);
+      expect(result.phase_history[0].phase_name).toBe('DESIGN');
+      expect(result.phase_history[0].status).toBe('in_progress');
+      expect(result.phase_history[0].started_at).toBeDefined();
+    });
+
+    it('updates existing phase_history entry', () => {
+      const initialState = createInitialState(tmpDir);
+      manager.write(initialState);
+
+      // Start phase 2
+      manager.transitionPhase(2, 'in_progress');
+
+      // Complete phase 2
+      const result = manager.transitionPhase(2, 'completed');
+
+      expect(result.phase_history[0].status).toBe('completed');
+      expect(result.phase_history[0].completed_at).toBeDefined();
+      expect(result.phase_history[0].duration_seconds).toBeGreaterThanOrEqual(0);
+    });
+
+    it('calls onTransition callback', () => {
+      const initialState = createInitialState(tmpDir);
+      manager.write(initialState);
+
+      let callbackCalled = false;
+      let callbackState = null;
+
+      manager.transitionPhase(2, 'in_progress', {
+        onTransition: (state) => {
+          callbackCalled = true;
+          callbackState = state;
+        },
+      });
+
+      expect(callbackCalled).toBe(true);
+      expect(callbackState.phase).toBe(2);
+    });
+
+    it('handles onTransition callback errors gracefully', () => {
+      const initialState = createInitialState(tmpDir);
+      manager.write(initialState);
+
+      // Should not throw
+      expect(() => {
+        manager.transitionPhase(2, 'in_progress', {
+          onTransition: () => {
+            throw new Error('Render failed');
+          },
+        });
+      }).not.toThrow();
+
+      // State should still be updated
+      const state = manager.read();
+      expect(state.phase).toBe(2);
+    });
+
+    it('updates outputs when provided', () => {
+      const initialState = createInitialState(tmpDir);
+      manager.write(initialState);
+
+      const result = manager.transitionPhase(2, 'completed', {
+        outputs: { specification: 'spec.yaml' },
+      });
+
+      expect(result.outputs.specification).toBe('spec.yaml');
+    });
+  });
+
+  describe('migrate()', () => {
+    it('adds _schema_version', () => {
+      const state = { id: 'test', phase: 1, phase_history: [] };
+      const migrated = migrateState(state, manager.stateDir);
+      expect(migrated._schema_version).toBe(1);
+    });
+
+    it('sets default task_description if missing', () => {
+      const state = { id: 'test', phase: 1, phase_history: [] };
+      const migrated = migrateState(state, manager.stateDir);
+      expect(migrated.task_description).toBe('-');
+    });
+
+    it('migrates all legacy phase numbers', () => {
+      for (const [legacy, expected] of Object.entries(LEGACY_PHASE_MAP)) {
+        const state = {
+          id: 'test',
+          phase: Number(legacy),
+          phase_history: [{ phase: Number(legacy), status: 'completed' }],
+        };
+        const migrated = migrateState(state, manager.stateDir);
+        expect(migrated.phase).toBe(expected.phase);
+        expect(migrated.phase_history[0].phase).toBe(expected.phase);
+        expect(migrated.phase_history[0].phase_name).toBe(expected.phase_name);
+      }
+    });
+
+    it('preserves unknown fields', () => {
+      const state = {
+        id: 'test',
+        phase: 1,
+        phase_history: [],
+        custom_field: 'preserved',
+      };
+      const migrated = migrateState(state, manager.stateDir);
+      expect(migrated.custom_field).toBe('preserved');
+    });
+  });
+
+  describe('rollback()', () => {
+    it('returns false when no backup exists', () => {
+      const result = manager.rollback();
+      expect(result).toBe(false);
+    });
+
+    it('restores from backup', () => {
+      // Create initial state and backup
+      const originalState = {
+        _schema_version: 1,
+        id: 'original',
+        task_description: 'Original',
+        phase: 1,
+        status: 'in_progress',
+        started_at: '2026-07-14T10:00:00Z',
+        phase_history: [],
+        isolation: { worktree_path: tmpDir, branch: 'test' },
+      };
+      fs.mkdirSync(path.join(tmpDir, '.sprint-state'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, '.sprint-state', 'sprint-state.json'),
+        JSON.stringify(originalState, null, 2)
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, '.sprint-state', 'sprint-state.json.backup'),
+        JSON.stringify(originalState, null, 2)
+      );
+
+      // Modify current state
+      const modifiedState = { ...originalState, id: 'modified' };
+      fs.writeFileSync(
+        path.join(tmpDir, '.sprint-state', 'sprint-state.json'),
+        JSON.stringify(modifiedState, null, 2)
+      );
+
+      // Rollback
+      const result = manager.rollback();
+      expect(result).toBe(true);
+
+      // Verify restored
+      const restored = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, '.sprint-state', 'sprint-state.json'), 'utf8')
+      );
+      expect(restored.id).toBe('original');
+    });
+  });
+});

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

@@ -14,12 +14,13 @@ const TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-status-test-'));
 const STATE_DIR = path.join(TMP_DIR, '.sprint-state');
 const STATE_FILE = path.join(STATE_DIR, 'sprint-state.json');
 
-// Active sprint state (canonical format per SKILL.md L893-942)
+// Active sprint state (v1 schema per sprint-state-manager.js)
 const ACTIVE_STATE = {
+  _schema_version: 1,
   id: 'sprint-2026-06-16-01',
   task_description: 'Test sprint',
-  phase: 2,
-  status: 'running',
+  phase: 3,
+  status: 'in_progress',
   started_at: '2026-06-16T10:00:00Z',
   isolation: {
     worktree_path: '.worktrees/sprint/sprint-2026-06-16-01',
@@ -33,15 +34,11 @@ const ACTIVE_STATE = {
     user_decision: 'accepted'
   },
   phase_history: [
-    { phase: -1, phase_name: 'ISOLATE', status: 'completed',
+    { phase: 1, phase_name: 'PREP', status: 'completed',
       started_at: '2026-06-16T10:00:00Z', completed_at: '2026-06-16T10:03:00Z', duration_seconds: 180 },
-    { phase: -0.5, phase_name: 'AUTO-ESTIMATE', status: 'completed',
-      started_at: '2026-06-16T10:03:00Z', completed_at: '2026-06-16T10:05:00Z', duration_seconds: 120 },
-    { phase: 0, phase_name: 'THINK', status: 'completed',
+    { phase: 2, phase_name: 'DESIGN', status: 'completed',
       started_at: '2026-06-16T10:05:00Z', completed_at: '2026-06-16T10:15:00Z', duration_seconds: 600 },
-    { phase: 1, phase_name: 'PLAN', status: 'completed',
-      started_at: '2026-06-16T10:15:00Z', completed_at: '2026-06-16T10:25:00Z', duration_seconds: 600 },
-    { phase: 2, phase_name: 'BUILD', status: 'in_progress',
+    { phase: 3, phase_name: 'BUILD', status: 'in_progress',
       started_at: '2026-06-16T10:25:00Z', completed_at: null, duration_seconds: null,
       reqs: {
         'REQ-001': { name: 'Feature A', status: 'completed' },
@@ -87,8 +84,8 @@ describe('sprint-status: readSprintState', () => {
     const state = sprintStatus.readSprintState(TMP_DIR);
     expect(state).not.toBeNull();
     expect(state.task_description).toBe('Test sprint');
-    expect(state.phase).toBe(2);
-    expect(state.status).toBe('running');
+    expect(state.phase).toBe(3);
+    expect(state.status).toBe('in_progress');
     expect(Array.isArray(state.phase_history)).toBe(true);
     expect(state.phase_history.length).toBeGreaterThan(0);
   });
@@ -166,7 +163,7 @@ describe('sprint-status: formatSprintTable', () => {
     const json = sprintStatus.jsonMode(ACTIVE_STATE);
     const parsed = JSON.parse(json);
     expect(parsed.task_description).toBe('Test sprint');
-    expect(parsed.phase).toBe(2);
+    expect(parsed.phase).toBe(3);
   });
 
   // AC-SPRINTSTATUS-001-09: Stale state detection

package/lib/__tests__/sprint-status.test.ts

@@ -16,12 +16,13 @@ const TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-status-test-'));
 const STATE_DIR = path.join(TMP_DIR, '.sprint-state');
 const STATE_FILE = path.join(STATE_DIR, 'sprint-state.json');
 
-// Active sprint state (canonical format per SKILL.md L893-942, 6-phase schema)
+// Active sprint state (v1 schema per sprint-state-manager.js, 6-phase schema)
 const ACTIVE_STATE = {
+  _schema_version: 1,
   id: 'sprint-2026-06-16-01',
   task_description: 'Test sprint',
   phase: 3,
-  status: 'running',
+  status: 'in_progress',
   started_at: '2026-06-16T10:00:00Z',
   isolation: {
     worktree_path: '.worktrees/sprint/sprint-2026-06-16-01',
@@ -95,7 +96,7 @@ describe('sprint-status: readSprintState', () => {
     const stateObj = state as Record<string, unknown>;
     expect(stateObj.task_description).toBe('Test sprint');
     expect(stateObj.phase).toBe(3);
-    expect(stateObj.status).toBe('running');
+    expect(stateObj.status).toBe('in_progress');
     expect(Array.isArray(stateObj.phase_history)).toBe(true);
   });
 

package/lib/install-skill.js

@@ -20,6 +20,15 @@ function getSkillsDir() {
   return path.join(HOME_DIR, '.config', 'opencode', 'skills');
 }
 
+function getCliVersion() {
+  try {
+    const versionFile = path.join(__dirname, '..', '..', '..', 'VERSION');
+    return fs.readFileSync(versionFile, 'utf8').trim();
+  } catch {
+    return '0.0.0';
+  }
+}
+
 const SKILLS_REGISTRY = {
   'sprint-flow': { repo: 'boyingliu01/xp-gate', path: 'skills/sprint-flow' },
   'delphi-review': { repo: 'boyingliu01/xp-gate', path: 'skills/delphi-review' },
@@ -123,10 +132,14 @@ async function performInstall(skillInfo, name, targetDir, offline, verbose) {
   }
 
   ensureConfigDir();
+  
+  // Read actual CLI version from VERSION file
+  const version = getCliVersion();
+  
   updateConfig({
     installedSkills: {
       ...(getConfig().installedSkills || {}),
-      [name]: { version: '1.0.0', installedAt: new Date().toISOString() }
+      [name]: { version, installedAt: new Date().toISOString() }
     }
   });
 

package/lib/next-sprint.js

@@ -1,12 +1,11 @@
 const childProcess = require('child_process');
-const fs = require('fs');
 const path = require('path');
+const { SprintStateManager } = require('./sprint-state-manager');
 
 function readSprintState(dir) {
   try {
-    const stateFile = path.join(dir, '.sprint-state', 'sprint-state.json');
-    if (!fs.existsSync(stateFile)) return null;
-    return JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    const manager = new SprintStateManager(dir);
+    return manager.read();
   } catch {
     return null;
   }

package/lib/sprint-discovery.js

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { SprintStateManager } = require('./sprint-state-manager');
 
 /**
  * Maximum number of active sprints to return.
@@ -62,16 +63,15 @@ function findGitRoot(startDir) {
 
 /**
  * Read and parse a sprint-state.json from a given project directory.
+ * Uses SprintStateManager for schema validation + auto-migration.
  *
  * @param {string} dir - Directory containing .sprint-state/
  * @returns {object|null} Parsed sprint state, or null if not found or malformed
  */
 function readSprintState(dir) {
   try {
-    const stateFile = path.join(dir, '.sprint-state', 'sprint-state.json');
-    if (!fs.existsSync(stateFile)) return null;
-    const raw = fs.readFileSync(stateFile, 'utf8');
-    return JSON.parse(raw);
+    const manager = new SprintStateManager(dir);
+    return manager.read();
   } catch {
     return null;
   }

package/lib/sprint-state-manager.js

@@ -0,0 +1,122 @@
+/**
+ * Sprint State Manager — centralized read/write/transition for sprint state.
+ *
+ * Resolves #343 (schema drift) and #338 (auto-render enforcement).
+ *
+ * @module sprint-state-manager
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { migrateState, createInitialState, rollbackState, LEGACY_PHASE_MAP } = require('./sprint-state-migrator');
+
+class SprintStateManager {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.stateDir = path.join(projectRoot, '.sprint-state');
+    this.stateFile = path.join(this.stateDir, 'sprint-state.json');
+    this.backupFile = path.join(this.stateDir, 'sprint-state.json.backup');
+  }
+
+  read() {
+    if (!fs.existsSync(this.stateFile)) {
+      return null;
+    }
+
+    const raw = fs.readFileSync(this.stateFile, 'utf8');
+    let state;
+    try {
+      state = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Failed to parse sprint-state.json: ${err.message}`);
+    }
+
+    // Check if migration needed
+    if (!state._schema_version) {
+      // Create backup before first migration
+      if (!fs.existsSync(this.backupFile)) {
+        fs.copyFileSync(this.stateFile, this.backupFile);
+      }
+      state = migrateState(state, this.stateDir);
+      // Write migrated state atomically
+      this.write(state);
+    }
+
+    return state;
+  }
+
+  write(state) {
+    // Ensure state directory exists
+    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);
+  }
+
+  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);
+    }
+
+    // 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);
+      }
+    }
+
+    // Update outputs if provided
+    if (options.outputs) {
+      state.outputs = { ...state.outputs, ...options.outputs };
+    }
+
+    // Write state atomically
+    this.write(state);
+
+    // Trigger onTransition callback (for auto-render)
+    if (typeof options.onTransition === 'function') {
+      try {
+        options.onTransition(state);
+      } catch (err) {
+        // Render failure is WARNING, not BLOCK
+        console.warn(`[WARN] onTransition callback failed: ${err.message}`);
+      }
+    }
+
+    return state;
+  }
+
+  rollback() {
+    return rollbackState(this.stateFile, this.backupFile);
+  }
+}
+
+module.exports = { SprintStateManager, LEGACY_PHASE_MAP };

package/lib/sprint-state-migrator.js

@@ -0,0 +1,153 @@
+/**
+ * Sprint State Migrator — legacy phase migration + rollback helpers.
+ *
+ * Extracted from SprintStateManager to satisfy god-class rule (≤15 methods).
+ *
+ * @module sprint-state-migrator
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Legacy phase number → v1 phase mapping
+ */
+const LEGACY_PHASE_MAP = {
+  '-1': { phase: 1, phase_name: 'PREP' },
+  '-0.5': { phase: 1, phase_name: 'PREP' },
+  '0': { phase: 2, phase_name: 'DESIGN' },
+  '1': { phase: 2, phase_name: 'DESIGN' },
+  '2': { phase: 3, phase_name: 'BUILD' },
+  '3': { phase: 4, phase_name: 'VERIFY' },
+  '4': { phase: 4, phase_name: 'VERIFY' },
+  '5': { phase: 5, phase_name: 'SHIP' },
+  '6': { phase: 5, phase_name: 'SHIP' },
+  '7': { phase: 6, phase_name: 'CLOSE' },
+  '8': { phase: 6, phase_name: 'CLOSE' },
+};
+
+const PHASE_NAMES = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+
+/**
+ * Migrate legacy sprint-state.json to v1 schema.
+ *
+ * @param {Object} state - Raw state from file
+ * @param {string} stateDir - Path to .sprint-state directory
+ * @returns {Object} Migrated state with _schema_version: 1
+ */
+function migrateState(state, stateDir) {
+  const warnings = [];
+
+  state._schema_version = 1;
+
+  if (!state.task_description) {
+    state.task_description = '-';
+    warnings.push('task_description was missing, set to "-"');
+  }
+
+  if (!state.id) {
+    state.id = `sprint-${Date.now()}`;
+    warnings.push('id was missing, generated from timestamp');
+  }
+
+  if (!state.status) { state.status = 'in_progress'; }
+  if (!state.started_at) { state.started_at = new Date().toISOString(); }
+  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;
+  });
+
+  const currentPhaseNum = String(state.phase);
+  const currentMapped = LEGACY_PHASE_MAP[currentPhaseNum];
+  if (currentMapped) {
+    state.phase = currentMapped.phase;
+    warnings.push(`Migrated current phase ${currentPhaseNum} → ${currentMapped.phase}`);
+  }
+
+  state.phase_history = state.phase_history.map(entry => {
+    if (entry.timestamp && !entry.started_at) {
+      entry.started_at = entry.timestamp;
+    }
+    return entry;
+  });
+
+  if (warnings.length > 0) {
+    logMigrationWarnings(warnings, stateDir);
+  }
+
+  return state;
+}
+
+/**
+ * Create initial sprint state for new sprints.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Initial state
+ */
+function createInitialState(projectRoot) {
+  return {
+    _schema_version: 1,
+    id: `sprint-${Date.now()}`,
+    task_description: '-',
+    phase: 1,
+    status: 'in_progress',
+    started_at: new Date().toISOString(),
+    phase_history: [],
+    isolation: { worktree_path: projectRoot, branch: null },
+    outputs: {},
+    metrics: {},
+  };
+}
+
+/**
+ * Log migration warnings to file.
+ *
+ * @param {string[]} warnings - Array of warning messages
+ * @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'))
+    : [];
+
+  existing.push({ timestamp: new Date().toISOString(), warnings });
+  fs.writeFileSync(warningsFile, JSON.stringify(existing, null, 2), 'utf8');
+}
+
+/**
+ * Rollback to backup state.
+ *
+ * @param {string} stateFile - Path to sprint-state.json
+ * @param {string} backupFile - Path to sprint-state.json.backup
+ * @returns {boolean} True if rollback succeeded
+ */
+function rollbackState(stateFile, backupFile) {
+  if (!fs.existsSync(backupFile)) { return false; }
+  fs.copyFileSync(backupFile, stateFile);
+  return true;
+}
+
+module.exports = {
+  LEGACY_PHASE_MAP,
+  migrateState,
+  createInitialState,
+  rollbackState,
+};

package/lib/sprint-status.js

@@ -10,6 +10,7 @@
 const fs = require('fs');
 const path = require('path');
 const { discoverActiveSprints } = require('./sprint-discovery');
+const { SprintStateManager } = require('./sprint-state-manager');
 
 // Phase constants (inlined; was shared-phase-constants.js, removed in v0.13.0 slimming)
 const PHASE_NAMES = {
@@ -47,15 +48,14 @@ function isStale(state) {
 
 /**
  * Read and parse sprint-state.json from a project directory.
+ * Uses SprintStateManager for schema validation + auto-migration.
  * @param {string} dir - Project root directory
  * @returns {object|null} Parsed sprint state, or null if not found or malformed
  */
 function readSprintState(dir) {
   try {
-    const stateFile = path.join(dir, '.sprint-state', 'sprint-state.json');
-    if (!fs.existsSync(stateFile)) return null;
-    const raw = fs.readFileSync(stateFile, 'utf8');
-    return JSON.parse(raw);
+    const manager = new SprintStateManager(dir);
+    return manager.read();
   } catch {
     return null;
   }

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-07-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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.9",
+  "version": "0.14.11",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

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

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.14.9",
+  "version": "0.14.11",
   "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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-07-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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.9",
+  "version": "0.14.11",
   "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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-07-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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.9",
+  "version": "0.14.11",
   "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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.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/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-07-13
-**Commit:** cb954fe
-**Branch:** sprint/2026-07-13-01
-**Version:** 0.14.9.0
+**Generated:** 2026-07-16
+**Commit:** 2f70dd5
+**Branch:** main
+**Version:** 0.14.11.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.