@boyingliu01/xp-gate 0.14.8 → 0.14.10

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;
   }
@@ -70,6 +70,7 @@ function statusIcon(status) {
   switch (status) {
     case 'completed': return '✅';
     case 'in_progress': return '🔄';
+    case 'skipped': return '⏭️';
     default: return '⏳';
   }
 }
@@ -145,7 +146,8 @@ function formatPhaseLine(key, history, maxNameLen) {
   const icon = statusIcon(status);
   const dur = formatDuration(history?.duration_seconds);
   const statusLabel = status === 'completed' ? 'Completed' :
-    status === 'in_progress' ? 'In Progress' : 'Pending';
+    status === 'in_progress' ? 'In Progress' :
+    status === 'skipped' ? 'Skipped' : 'Pending';
   return `  Phase ${key.padStart(4)}  ${name.padEnd(maxNameLen + 1)} ${icon} ${dur.padEnd(5)} ${statusLabel}`;
 }
 

package/lib/update-hooks.js

@@ -190,7 +190,7 @@ function copyAdapters(srcDir, destDir, dryRun, noBackup) {
 function copyGateScripts(srcDir, destDir, dryRun, noBackup) {
   if (!fs.existsSync(srcDir)) return;
   fs.readdirSync(srcDir).forEach(f => {
-    if (f.startsWith('gate-') && f.endsWith('.sh')) {
+    if ((f.startsWith('gate-') || f === 'sprint-gate.sh') && f.endsWith('.sh')) {
       const src = path.join(srcDir, f);
       const dest = path.join(destDir, f);
       atomicCopyFile(src, dest, dryRun, noBackup, f);

package/lib/upgrade.js

@@ -95,6 +95,14 @@ async function handleApplyMode(result, pkgName) {
     // Also check for and update the local OpenCode plugin if installed.
     await upgradeOpenCodePlugin();
 
+    // Update all installed skills to match the newly upgraded package (#332)
+    try {
+      const { updateSkill } = require('./update-skill.js');
+      await updateSkill(null, { all: true, verbose: false });
+    } catch {
+      // Non-blocking: skill update failure should never break the main upgrade flow.
+    }
+
     return 0;
   } catch (err) {
     const msg = err.message || '';

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-07-13
-**Commit:** d83bb96
-**Branch:** main
-**Version:** 0.14.8.0
+**Generated:** 2026-07-16
+**Commit:** 6193b64
+**Branch:** sprint/2026-07-14-01
+**Version:** 0.14.10.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:** d83bb96
-**Branch:** main
-**Version:** 0.14.8.0
+**Generated:** 2026-07-16
+**Commit:** 6193b64
+**Branch:** sprint/2026-07-14-01
+**Version:** 0.14.10.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/mutation/__tests__/init-baseline.test.ts

@@ -0,0 +1,347 @@
+/**
+ * @test init-baseline.ts - Mutation Baseline Initialization
+ * @intent Verify argument parsing, score calculation, baseline construction,
+ *         and source file filtering logic used by the init-baseline CLI script.
+ * @covers REQ-MUT-002 AC-001, AC-002, AC-003, AC-004
+ */
+
+import { describe, it, expect } from 'vitest';
+
+// ─── Inline copies of pure functions from init-baseline.ts ───────────────────
+// The module runs main() on import, so we cannot import it directly.
+// These are faithful copies of the pure logic for unit testing.
+// See gate-m.test.ts for the same pattern used in this project.
+
+interface MutantStatus {
+  id: string;
+  mutatorName: string;
+  replacement: string;
+  location: {
+    start: { line: number; column: number };
+    end: { line: number; column: number };
+  };
+  status: string;
+}
+
+interface StrykerFileReport {
+  source: string;
+  mutants: MutantStatus[];
+}
+
+interface StrykerReport {
+  schemaVersion: string;
+  thresholds: {
+    high: number;
+    low: number;
+    break: number | null;
+  };
+  files: Record<string, StrykerFileReport>;
+}
+
+interface MutationScoreEntry {
+  score: number;
+  mutants: number;
+  killed: number;
+  survived: number;
+}
+
+interface MutationBaseline {
+  version: string;
+  generatedAt: string;
+  source: 'local' | 'ci';
+  scores: Record<string, MutationScoreEntry>;
+}
+
+function parseArgs(args: string[]): { filesPattern: string; source: 'local' | 'ci' } {
+  let filesPattern = 'src/**/*.ts';
+  let source: 'local' | 'ci' = 'local';
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--files' && args[i + 1]) {
+      filesPattern = args[i + 1];
+      i++;
+    }
+    if (args[i] === '--source' && args[i + 1]) {
+      source = args[i + 1] as 'local' | 'ci';
+      i++;
+    }
+  }
+
+  return { filesPattern, source };
+}
+
+function calculateScore(entry: StrykerFileReport): MutationScoreEntry {
+  const total = entry.mutants.length;
+  const killed = entry.mutants.filter(m => m.status === 'Killed').length;
+  const survived = entry.mutants.filter(m => m.status === 'Survived').length;
+
+  return {
+    score: total > 0 ? parseFloat(((killed / total) * 100).toFixed(1)) : 100,
+    mutants: total,
+    killed,
+    survived
+  };
+}
+
+function buildBaseline(
+  report: StrykerReport,
+  sourceFiles: string[],
+  source: 'local' | 'ci'
+): MutationBaseline {
+  const scores: Record<string, MutationScoreEntry> = {};
+
+  for (const [filePath, fileReport] of Object.entries(report.files)) {
+    const relativePath = filePath.replace(/^\//, '');
+    if (sourceFiles.includes(relativePath) || sourceFiles.some(sf => relativePath.endsWith(sf))) {
+      scores[relativePath] = calculateScore(fileReport);
+    }
+  }
+
+  return {
+    version: '1.0',
+    generatedAt: new Date().toISOString(),
+    source,
+    scores
+  };
+}
+
+function isSourceFile(file: string): boolean {
+  return (
+    file.endsWith('.ts') &&
+    !file.endsWith('.d.ts') &&
+    !file.endsWith('.test.ts') &&
+    !file.includes('/__tests__/') &&
+    !file.includes('/adapters/')
+  );
+}
+
+// ─── Helper factories ────────────────────────────────────────────────────────
+
+function makeMutant(status: string, id = '0'): MutantStatus {
+  return {
+    id,
+    mutatorName: 'BlockMutator',
+    replacement: '{}',
+    location: {
+      start: { line: 1, column: 0 },
+      end: { line: 1, column: 10 }
+    },
+    status
+  };
+}
+
+function makeFileReport(mutants: MutantStatus[]): StrykerFileReport {
+  return { source: 'const x = 1;', mutants };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('parseArgs', () => {
+  it('returns defaults when no arguments provided', () => {
+    const result = parseArgs([]);
+    expect(result.filesPattern).toBe('src/**/*.ts');
+    expect(result.source).toBe('local');
+  });
+
+  it('parses --files flag', () => {
+    const result = parseArgs(['--files', 'lib/**/*.ts']);
+    expect(result.filesPattern).toBe('lib/**/*.ts');
+    expect(result.source).toBe('local');
+  });
+
+  it('parses --source flag', () => {
+    const result = parseArgs(['--source', 'ci']);
+    expect(result.filesPattern).toBe('src/**/*.ts');
+    expect(result.source).toBe('ci');
+  });
+
+  it('parses both --files and --source flags', () => {
+    const result = parseArgs(['--files', 'app/**/*.ts', '--source', 'ci']);
+    expect(result.filesPattern).toBe('app/**/*.ts');
+    expect(result.source).toBe('ci');
+  });
+
+  it('ignores --files without a following value', () => {
+    const result = parseArgs(['--files']);
+    expect(result.filesPattern).toBe('src/**/*.ts');
+  });
+
+  it('ignores unknown flags', () => {
+    const result = parseArgs(['--verbose', '--dry-run']);
+    expect(result.filesPattern).toBe('src/**/*.ts');
+    expect(result.source).toBe('local');
+  });
+});
+
+describe('calculateScore', () => {
+  it('returns 100 score when no mutants exist', () => {
+    const entry = makeFileReport([]);
+    const result = calculateScore(entry);
+    expect(result.score).toBe(100);
+    expect(result.mutants).toBe(0);
+    expect(result.killed).toBe(0);
+    expect(result.survived).toBe(0);
+  });
+
+  it('calculates score from killed and total mutants', () => {
+    const entry = makeFileReport([
+      makeMutant('Killed', '0'),
+      makeMutant('Killed', '1'),
+      makeMutant('Survived', '2'),
+      makeMutant('Survived', '3')
+    ]);
+    const result = calculateScore(entry);
+    expect(result.mutants).toBe(4);
+    expect(result.killed).toBe(2);
+    expect(result.survived).toBe(2);
+    expect(result.score).toBe(50);
+  });
+
+  it('returns 100 score when all mutants are killed', () => {
+    const entry = makeFileReport([
+      makeMutant('Killed', '0'),
+      makeMutant('Killed', '1'),
+      makeMutant('Killed', '2')
+    ]);
+    const result = calculateScore(entry);
+    expect(result.score).toBe(100);
+    expect(result.killed).toBe(3);
+    expect(result.survived).toBe(0);
+  });
+
+  it('returns 0 score when all mutants survived', () => {
+    const entry = makeFileReport([
+      makeMutant('Survived', '0'),
+      makeMutant('Survived', '1')
+    ]);
+    const result = calculateScore(entry);
+    expect(result.score).toBe(0);
+    expect(result.killed).toBe(0);
+    expect(result.survived).toBe(2);
+  });
+
+  it('ignores non-Killed/Survived statuses in killed/survived counts', () => {
+    const entry = makeFileReport([
+      makeMutant('Killed', '0'),
+      makeMutant('NoCoverage', '1'),
+      makeMutant('RuntimeError', '2'),
+      makeMutant('Survived', '3')
+    ]);
+    const result = calculateScore(entry);
+    expect(result.mutants).toBe(4);
+    expect(result.killed).toBe(1);
+    expect(result.survived).toBe(1);
+    expect(result.score).toBe(25);
+  });
+
+  it('rounds score to one decimal place', () => {
+    const entry = makeFileReport([
+      makeMutant('Killed', '0'),
+      makeMutant('Killed', '1'),
+      makeMutant('Survived', '2')
+    ]);
+    const result = calculateScore(entry);
+    // 2/3 * 100 = 66.666... → 66.7
+    expect(result.score).toBe(66.7);
+  });
+});
+
+describe('buildBaseline', () => {
+  const emptyReport: StrykerReport = {
+    schemaVersion: '1.0',
+    thresholds: { high: 80, low: 60, break: null },
+    files: {}
+  };
+
+  it('returns empty scores when report has no files', () => {
+    const baseline = buildBaseline(emptyReport, [], 'local');
+    expect(baseline.version).toBe('1.0');
+    expect(baseline.source).toBe('local');
+    expect(baseline.scores).toEqual({});
+    expect(baseline.generatedAt).toBeDefined();
+  });
+
+  it('includes only source files in baseline scores', () => {
+    const report: StrykerReport = {
+      schemaVersion: '1.0',
+      thresholds: { high: 80, low: 60, break: null },
+      files: {
+        'src/auth.ts': makeFileReport([makeMutant('Killed', '0')]),
+        'src/utils.ts': makeFileReport([makeMutant('Survived', '0')]),
+        'dist/bundle.js': makeFileReport([makeMutant('Killed', '0')])
+      }
+    };
+    const sourceFiles = ['src/auth.ts', 'src/utils.ts'];
+    const baseline = buildBaseline(report, sourceFiles, 'ci');
+    expect(Object.keys(baseline.scores)).toHaveLength(2);
+    expect(baseline.scores['src/auth.ts']).toBeDefined();
+    expect(baseline.scores['src/utils.ts']).toBeDefined();
+    expect(baseline.scores['dist/bundle.js']).toBeUndefined();
+    expect(baseline.source).toBe('ci');
+  });
+
+  it('strips leading slash from file paths', () => {
+    const report: StrykerReport = {
+      schemaVersion: '1.0',
+      thresholds: { high: 80, low: 60, break: null },
+      files: {
+        '/src/auth.ts': makeFileReport([makeMutant('Killed', '0')])
+      }
+    };
+    const sourceFiles = ['src/auth.ts'];
+    const baseline = buildBaseline(report, sourceFiles, 'local');
+    expect(baseline.scores['src/auth.ts']).toBeDefined();
+  });
+
+  it('matches files by suffix when exact match fails', () => {
+    const report: StrykerReport = {
+      schemaVersion: '1.0',
+      thresholds: { high: 80, low: 60, break: null },
+      files: {
+        'packages/core/src/auth.ts': makeFileReport([makeMutant('Killed', '0')])
+      }
+    };
+    const sourceFiles = ['src/auth.ts'];
+    const baseline = buildBaseline(report, sourceFiles, 'local');
+    expect(baseline.scores['packages/core/src/auth.ts']).toBeDefined();
+  });
+
+  it('sets generatedAt to a valid ISO date string', () => {
+    const baseline = buildBaseline(emptyReport, [], 'local');
+    const parsed = new Date(baseline.generatedAt);
+    expect(parsed.toISOString()).toBe(baseline.generatedAt);
+  });
+});
+
+describe('isSourceFile (getSourceFiles filter predicate)', () => {
+  it('accepts regular .ts files', () => {
+    expect(isSourceFile('src/auth.ts')).toBe(true);
+    expect(isSourceFile('src/utils/helper.ts')).toBe(true);
+  });
+
+  it('rejects .d.ts declaration files', () => {
+    expect(isSourceFile('src/types.d.ts')).toBe(false);
+    expect(isSourceFile('src/global.d.ts')).toBe(false);
+  });
+
+  it('rejects .test.ts files', () => {
+    expect(isSourceFile('src/auth.test.ts')).toBe(false);
+    expect(isSourceFile('src/utils/helper.test.ts')).toBe(false);
+  });
+
+  it('rejects files in __tests__ directories', () => {
+    expect(isSourceFile('src/__tests__/auth.test.ts')).toBe(false);
+    expect(isSourceFile('src/__tests__/helpers.ts')).toBe(false);
+  });
+
+  it('rejects files in adapters directories', () => {
+    expect(isSourceFile('githooks/adapters/typescript.sh')).toBe(false);
+    expect(isSourceFile('src/adapters/go.ts')).toBe(false);
+  });
+
+  it('rejects non-.ts files', () => {
+    expect(isSourceFile('src/index.js')).toBe(false);
+    expect(isSourceFile('src/style.css')).toBe(false);
+    expect(isSourceFile('README.md')).toBe(false);
+  });
+});