@boyingliu01/xp-gate 0.15.4 → 0.18.0

package/lib/phase-transition.js

@@ -24,6 +24,8 @@
 
 const path = require('path');
 const fs = require('fs');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
 const { SprintStateManager } = require('./sprint-state-manager');
 
 /**
@@ -35,6 +37,214 @@ const PHASE_NAMES = {
   4: 'VERIFY', 5: 'SHIP', 6: 'CLOSE',
 };
 
+/**
+ * Phase-specific evidence file requirements.
+ * Each entry defines the evidence file path, required fields, and a blocking check.
+ * Phases NOT in this map require no evidence validation in v0.17.1.
+ */
+const EVIDENCE_FILES = {
+  2: {
+    path: '.sprint-state/phase-outputs/requirements-reviewed.json',
+    requiredFields: ['verdict', 'requirements_hash'],
+    blockingCheck: (data) => data.verdict === 'APPROVED',
+    blockingMessage: 'Requirements review verdict is not APPROVED',
+  },
+  4: {
+    path: '.sprint-state/phase-outputs/test-alignment-report.json',
+    requiredFields: ['alignment_status', 'head_commit', 'spec_hash'],
+    blockingCheck: (data) => data.alignment_status === 'PASS',
+    blockingMessage: 'Test alignment status is not PASS',
+  },
+};
+
+/**
+ * Get current HEAD commit hash from a project directory.
+ * Returns 'unknown' if not in a git repo.
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function getCurrentHeadCommit(projectDir) {
+  try {
+    return execSync('git rev-parse HEAD', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Compute SHA-256 hash of a file's contents.
+ * @param {string} filePath
+ * @returns {string} hex digest
+ */
+function computeFileHash(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Validate phase evidence files for a given phase transition.
+ *
+ * Returns { ok: boolean, errors: string[], warnings: string[] }.
+ * - For phases not in EVIDENCE_FILES: ok=true, no errors.
+ * - For phases with evidence requirements:
+ *   - If evidence_schema_version >= 2 (new sprint): missing/invalid evidence → ok=false (BLOCK)
+ *   - If evidence_schema_version missing or < 2 (legacy sprint): missing/invalid → ok=true with WARNING
+ *
+ * @param {number} phase - Phase number (1-6)
+ * @param {string} projectDir - Project root directory
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+function validateEvidence(phase, projectDir) {
+  const evidenceConfig = EVIDENCE_FILES[phase];
+  if (!evidenceConfig) {
+    return { ok: true, errors: [], warnings: [] };
+  }
+
+  // Read sprint state to determine evidence_schema_version
+  let evidenceSchemaVersion = 0;
+  try {
+    const manager = new SprintStateManager(projectDir);
+    const state = manager.read();
+    if (state && typeof state.evidence_schema_version === 'number') {
+      evidenceSchemaVersion = state.evidence_schema_version;
+    }
+  } catch {
+    // If state can't be read, treat as legacy (version 0)
+  }
+
+  const isLegacySprint = evidenceSchemaVersion < 2;
+  const errors = [];
+  const warnings = [];
+
+  const evidenceFilePath = path.join(projectDir, evidenceConfig.path);
+  const fileName = path.basename(evidenceConfig.path);
+
+  // Check file existence
+  if (!fs.existsSync(evidenceFilePath)) {
+    const msg = `Evidence file missing: ${evidenceConfig.path}`;
+    if (isLegacySprint) {
+      warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      return { ok: true, errors: [], warnings };
+    }
+    errors.push(msg);
+    return { ok: false, errors, warnings };
+  }
+
+  // Parse JSON
+  let data;
+  try {
+    const raw = fs.readFileSync(evidenceFilePath, 'utf8');
+    data = JSON.parse(raw);
+  } catch {
+    const msg = `${fileName} is malformed JSON`;
+    if (isLegacySprint) {
+      warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      return { ok: true, errors: [], warnings };
+    }
+    errors.push(msg);
+    return { ok: false, errors, warnings };
+  }
+
+  // Check required fields
+  for (const field of evidenceConfig.requiredFields) {
+    if (!(field in data)) {
+      const msg = `${fileName} is missing required field: ${field}`;
+      if (isLegacySprint) {
+        warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      } else {
+        errors.push(msg);
+      }
+    }
+  }
+
+  // If any required fields missing for new sprint, block early
+  if (errors.length > 0) {
+    return { ok: false, errors, warnings };
+  }
+
+  // Run blocking check
+  if (!evidenceConfig.blockingCheck(data)) {
+    const msg = `${fileName}: ${evidenceConfig.blockingMessage} (got: ${JSON.stringify(data[evidenceConfig.requiredFields[0]])})`;
+    if (isLegacySprint) {
+      warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      return { ok: true, errors: [], warnings };
+    }
+    errors.push(msg);
+    return { ok: false, errors, warnings };
+  }
+
+  // Phase-specific anti-staleness checks
+  if (phase === 4) {
+    // head_commit check
+    const currentHead = getCurrentHeadCommit(projectDir);
+    if (data.head_commit !== currentHead) {
+      const msg = `${fileName}: head_commit mismatch — report has "${data.head_commit}", current HEAD is "${currentHead}"`;
+      if (isLegacySprint) {
+        warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      } else {
+        errors.push(msg);
+      }
+    }
+
+    // spec_hash check (only if specification.yaml exists)
+    const specPath = path.join(projectDir, 'specification.yaml');
+    if (fs.existsSync(specPath)) {
+      const expectedHash = computeFileHash(specPath);
+      if (data.spec_hash !== expectedHash) {
+        const msg = `${fileName}: spec_hash mismatch — specification.yaml has changed since report was generated`;
+        if (isLegacySprint) {
+          warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+        } else {
+          errors.push(msg);
+        }
+      }
+    }
+  }
+
+  // Phase 2: requirements_hash existence check (full verification in v0.18.0)
+  if (phase === 2) {
+    if (typeof data.requirements_hash !== 'string' || data.requirements_hash.length === 0) {
+      const msg = `${fileName}: requirements_hash must be a non-empty string`;
+      if (isLegacySprint) {
+        warnings.push(`WARNING: ${msg}. Upgrade sprint with evidence_schema_version >= 2 to enforce.`);
+      } else {
+        errors.push(msg);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors, warnings };
+  }
+
+  return { ok: true, errors: [], warnings };
+}
+
+/**
+ * Append an evidence-skipped audit entry to .xp-gate/audit.jsonl.
+ * @param {string} projectDir
+ * @param {number} phase
+ * @param {string} reason
+ */
+function logEvidenceSkip(projectDir, phase, reason) {
+  const auditDir = path.join(projectDir, '.xp-gate');
+  if (!fs.existsSync(auditDir)) {
+    fs.mkdirSync(auditDir, { recursive: true });
+  }
+  const entry = {
+    timestamp: new Date().toISOString(),
+    event: 'evidence_skipped',
+    phase,
+    reason,
+    commit_hash: getCurrentHeadCommit(projectDir),
+  };
+  fs.appendFileSync(path.join(auditDir, 'audit.jsonl'), JSON.stringify(entry) + '\n', 'utf8');
+}
+
 /**
  * Render ASCII dashboard from sprint state.
  * Reuses the formatSprintTable logic from sprint-status.
@@ -152,11 +362,13 @@ async function handlePhaseTransition(args = []) {
     console.log('  --outputs <json>   JSON object of outputs to record');
     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('');
     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"');
     return 0;
   }
 
@@ -182,6 +394,19 @@ async function handlePhaseTransition(args = []) {
     }
   }
 
+  // Parse --skip-evidence flag
+  const skipEvidenceIdx = args.indexOf('--skip-evidence');
+  let skipEvidence = false;
+  let skipEvidenceReason = '';
+  if (skipEvidenceIdx >= 0) {
+    skipEvidence = true;
+    const nextArg = args[skipEvidenceIdx + 1];
+    // Reason is the next arg if it exists and doesn't start with '--'
+    if (nextArg && !nextArg.startsWith('--')) {
+      skipEvidenceReason = nextArg;
+    }
+  }
+
   // Validate inputs
   if (phase < 1 || phase > 6) {
     console.error(`Error: Phase must be 1-6, got ${phase}`);
@@ -221,6 +446,31 @@ async function handlePhaseTransition(args = []) {
       // If no sprint-state.json exists yet, skip check (no previous phase to validate)
     }
 
+    // ── Layer 2: Evidence validation (blocks on status === 'completed') ──
+    if (status === 'completed' && EVIDENCE_FILES[phase]) {
+      if (skipEvidence) {
+        if (!skipEvidenceReason) {
+          console.error('Error: --skip-evidence requires --reason "<text>" to be provided');
+          return 1;
+        }
+        logEvidenceSkip(projectDir, phase, skipEvidenceReason);
+        console.warn('⚠️  Evidence skipped. This will appear in retro reports. Single-sprint limit: >2 skips per sprint will trigger an alert.');
+      } else {
+        const evidence = validateEvidence(phase, projectDir);
+        for (const w of evidence.warnings) {
+          console.warn(`⚠️  [sprint-audit] ${w}`);
+        }
+        if (!evidence.ok) {
+          for (const e of evidence.errors) {
+            console.error(`❌ [sprint-audit] ${e}`);
+          }
+          console.error(`   Phase ${phase} (${PHASE_NAMES[phase]}) cannot transition to 'completed' without valid evidence.`);
+          console.error(`   Use --skip-evidence "<reason>" to bypass (audited).`);
+          return 1;
+        }
+      }
+    }
+
     const newState = manager.transitionPhase(phase, status, { outputs });
 
     console.log(`✅ Phase ${phase} transitioned to '${status}'`);
@@ -246,4 +496,4 @@ async function handlePhaseTransition(args = []) {
   }
 }
 
-module.exports = { handlePhaseTransition, renderDashboard, PHASE_NAMES };
+module.exports = { handlePhaseTransition, renderDashboard, PHASE_NAMES, validateEvidence };

package/lib/retro.js

@@ -0,0 +1,222 @@
+/**
+ * xp-gate retro — Sprint engineering retrospective CLI (#369, design §8.1)
+ *
+ * Reads git log + .xp-gate/audit.jsonl + .quality-history.jsonl + .sprint-history/
+ * and generates a Markdown retrospective report with rework rate trend (#369)
+ * and --skip-evidence exposure (§8.4) sections.
+ *
+ * Zero npm dependencies (Node built-ins only).
+ * @module retro
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Get git commit subjects within a date window.
+ * @param {string} dir - Repository root
+ * @param {number} days - Lookback window in days
+ * @returns {Array<{hash: string, date: string, subject: string}>}
+ */
+function getGitCommits(dir, days) {
+  try {
+    const out = execSync(
+      `git log --since="${days} days ago" --pretty=format:"%H|%ai|%s"`,
+      { cwd: dir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    return out.split('\n').filter(Boolean).map(l => {
+      const [hash, date, ...rest] = l.split('|');
+      return { hash, date, subject: rest.join('|') };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Parse .xp-gate/audit.jsonl entries.
+ * @param {string} dir - Repository root
+ * @returns {object[]} Parsed audit entries
+ */
+function readAuditEntries(dir) {
+  const p = path.join(dir, '.xp-gate', 'audit.jsonl');
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf8').split('\n')
+    .filter(l => l.trim())
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+}
+
+/**
+ * Read last 10 entries from .quality-history.jsonl.
+ * @param {string} dir - Repository root
+ * @returns {object[]} Recent quality entries
+ */
+function readQualityHistory(dir) {
+  const p = path.join(dir, '.quality-history.jsonl');
+  if (!fs.existsSync(p)) return [];
+  const entries = fs.readFileSync(p, 'utf8').split('\n')
+    .filter(l => l.trim())
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+  return entries.slice(-10);
+}
+
+/**
+ * Read sprint history JSON files from .sprint-state/sprint-history/.
+ * @param {string} dir - Repository root
+ * @param {string|null} sprintFilter - Optional sprint ID filter
+ * @returns {object[]} Sprint state objects
+ */
+function readSprintHistory(dir, sprintFilter) {
+  const histDir = path.join(dir, '.sprint-state', 'sprint-history');
+  const results = [];
+  if (fs.existsSync(histDir)) {
+    for (const f of fs.readdirSync(histDir).filter(f => f.endsWith('.json'))) {
+      try {
+        const s = JSON.parse(fs.readFileSync(path.join(histDir, f), 'utf8'));
+        if (!sprintFilter || s.id === sprintFilter) results.push(s);
+      } catch { /* skip */ }
+    }
+  }
+  return results;
+}
+
+/**
+ * Build the Markdown retrospective report.
+ * @param {object} opts - Report data
+ * @returns {string} Markdown report
+ */
+function buildReport(opts) {
+  const { days, commits, audit, quality, sprints } = opts;
+  const now = new Date();
+  const start = new Date(now.getTime() - days * 86400000);
+  const L = [];
+
+  L.push('# Sprint Engineering Retrospective');
+  L.push('');
+  L.push(`Period: ${start.toISOString().slice(0, 10)} to ${now.toISOString().slice(0, 10)}`);
+  L.push('');
+
+  // Activity Summary
+  L.push('## Activity Summary');
+  const gateEntries = audit.filter(e => e.gate_id);
+  const passed = gateEntries.filter(e => e.passed).length;
+  const normal = gateEntries.filter(e => !e.duration_anomaly);
+  const anomalous = gateEntries.length - normal.length;
+  const avgMs = normal.length > 0
+    ? Math.round(normal.reduce((s, e) => s + (e.duration_ms || 0), 0) / normal.length)
+    : 0;
+  L.push(`- Total commits in window: ${commits.length}`);
+  L.push(`- Sprint transitions recorded: ${sprints.length}`);
+  L.push(`- Gate pass rate: ${gateEntries.length > 0 ? ((passed / gateEntries.length) * 100).toFixed(1) : '0.0'}% (${gateEntries.length} gates total, ${gateEntries.length - passed} failed)`);
+  if (gateEntries.length > 0) {
+    L.push(`- Avg gate duration: ${avgMs}ms (${anomalous} anomal${anomalous === 1 ? 'y' : 'ies'} excluded)`);
+  }
+  L.push('');
+
+  // Rework Rate Trend (#369)
+  L.push('## Rework Rate Trend (#369)');
+  const withRate = sprints.filter(s => s.metrics && s.metrics.rework_rate != null);
+  if (withRate.length === 0) {
+    L.push('No data');
+  } else {
+    L.push('| Sprint | Rework Rate | Fix Commits | Total Commits |');
+    L.push('|--------|-------------|-------------|---------------|');
+    for (const s of withRate) {
+      const pct = (s.metrics.rework_rate * 100).toFixed(1);
+      const fix = s.metrics.total_sprint_commits != null
+        ? Math.round(s.metrics.rework_rate * s.metrics.total_sprint_commits)
+        : '?';
+      L.push(`| ${s.id || 'unknown'} | ${pct}% | ${fix} | ${s.metrics.total_sprint_commits ?? '?'} |`);
+      if (s.metrics.rework_rate > 0.30) {
+        L.push(`⚠️ Sprint ${s.id || 'unknown'}: ${pct}% rework — exceeds 30% threshold`);
+      }
+    }
+  }
+  L.push('');
+
+  // Evidence Skip Exposure (§8.4)
+  L.push('## Evidence Skip Exposure (§8.4)');
+  const skipped = audit.filter(e => e.event === 'evidence_skipped');
+  if (skipped.length === 0) {
+    L.push('No data');
+  } else {
+    L.push('| Phase | Reason | Timestamp |');
+    L.push('|-------|--------|-----------|');
+    for (const e of skipped) {
+      L.push(`| ${e.phase || '?'} | ${e.reason || '?'} | ${(e.timestamp || '').slice(0, 19)} |`);
+    }
+    const bySprint = {};
+    for (const e of skipped) {
+      const k = e.sprint_id || 'unknown';
+      bySprint[k] = (bySprint[k] || 0) + 1;
+    }
+    for (const [sid, count] of Object.entries(bySprint)) {
+      if (count > 2) {
+        L.push(`⚠️ Sprint ${sid} used skip ${count} times`);
+      }
+    }
+  }
+  L.push('');
+
+  // Quality Trend
+  L.push('## Quality Trend');
+  if (quality.length === 0) {
+    L.push('No data');
+  } else {
+    for (const q of quality) {
+      L.push(`- ${(q.timestamp || '').slice(0, 10)}: score ${q.score ?? '?'}`);
+    }
+  }
+
+  return L.join('\n');
+}
+
+/**
+ * CLI entry point for xp-gate retro.
+ * @param {string[]} args - CLI subargs (without 'retro')
+ * @returns {Promise<number>} Exit code
+ */
+async function handleRetro(args = []) {
+  const allFlag = args.includes('--all');
+  const jsonFlag = args.includes('--json');
+  const daysIdx = args.indexOf('--days');
+  const sprintIdx = args.indexOf('--sprint');
+
+  let days = allFlag ? 30 : 7;
+  if (daysIdx >= 0 && args[daysIdx + 1]) {
+    days = parseInt(args[daysIdx + 1], 10);
+    if (isNaN(days) || days < 1) days = 7;
+  }
+
+  const sprintFilter = (sprintIdx >= 0 && args[sprintIdx + 1]) ? args[sprintIdx + 1] : null;
+  const dir = process.cwd();
+
+  const commits = getGitCommits(dir, days);
+  const audit = readAuditEntries(dir);
+  const quality = readQualityHistory(dir);
+  const sprints = readSprintHistory(dir, sprintFilter);
+
+  if (jsonFlag) {
+    const gateEntries = audit.filter(e => e.gate_id);
+    const passed = gateEntries.filter(e => e.passed).length;
+    console.log(JSON.stringify({
+      period: { days, from: new Date(Date.now() - days * 86400000).toISOString(), to: new Date().toISOString() },
+      total_commits: commits.length,
+      gate_pass_rate: gateEntries.length > 0 ? passed / gateEntries.length : null,
+      rework_rates: sprints.filter(s => s.metrics?.rework_rate != null).map(s => ({ id: s.id, rate: s.metrics.rework_rate })),
+      evidence_skipped: audit.filter(e => e.event === 'evidence_skipped'),
+      quality: quality.map(q => ({ timestamp: q.timestamp, score: q.score })),
+    }, null, 2));
+    return 0;
+  }
+
+  console.log(buildReport({ days, commits, audit, quality, sprints }));
+  return 0;
+}
+
+module.exports = { handleRetro };

package/lib/shared-utils.js

@@ -42,6 +42,13 @@ function copyHooks(srcDir, destDir) {
       fs.chmodSync(dest, 0o755);
     }
   });
+
+  // Copy lib/ directory (e.g. now-ms.sh) — sourced by pre-commit at runtime
+  const libSrc = path.join(srcDir, 'hooks', 'lib');
+  const libDest = path.join(destDir, 'lib');
+  if (fs.existsSync(libSrc)) {
+    copyDirRecursive(libSrc, libDest);
+  }
 }
 
 function copyAdapters(srcDir, destDir) {