@boyingliu01/xp-gate 0.9.3 → 0.9.5

package/lib/shared-utils.js

@@ -3,6 +3,7 @@
  * No module-level state — safe for tests that mock fs/path/os.
  */
 const fs = require('fs');
+const path = require('path');
 
 /**
  * Recursively copy a directory.
@@ -12,8 +13,8 @@ function copyDirRecursive(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = require('path').join(src, entry.name);
-    const destPath = require('path').join(dest, entry.name);
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
@@ -22,4 +23,14 @@ function copyDirRecursive(src, dest) {
   }
 }
 
-module.exports = { copyDirRecursive };
+function readXpGateConfig() {
+  const cfgPath = path.join(require('os').homedir(), '.xp-gate', 'config.json');
+  try {
+    if (!fs.existsSync(cfgPath)) return null;
+    return JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { copyDirRecursive, readXpGateConfig };

package/lib/sprint-status.js

@@ -9,22 +9,7 @@
 
 const fs = require('fs');
 const path = require('path');
-
-const PHASE_NAMES = {
-  '-1': 'ISOLATE',
-  '-0.5': 'AUTO-ESTIMATE',
-  '0': 'THINK',
-  '1': 'PLAN',
-  '2': 'BUILD',
-  '3': 'REVIEW',
-  '4': 'USER ACCEPT',
-  '5': 'FEEDBACK',
-  '6': 'SHIP',
-  '7': 'LAND',
-  '8': 'CLEANUP',
-};
-
-const PHASE_ORDER = ['-1', '-0.5', '0', '1', '2', '3', '4', '5', '6', '7', '8'];
+const { PHASE_NAMES, PHASE_ORDER, getLatestTimestamp, isStale } = require('./shared-phase-constants');
 
 /**
  * Read and parse sprint-state.json from a project directory.
@@ -70,29 +55,78 @@ function formatDuration(seconds) {
 }
 
 /**
- * Check if the state is stale (>1h since last activity).
+ * Format the sprint header lines (task description, ID, branch).
+ * @param {object} state - Sprint state object
+ * @param {string} branch - Branch name
+ * @returns {string[]} Header lines
+ */
+function buildHeader(state, branch) {
+  return [
+    `Sprint: ${state.task_description}`,
+    `ID: ${state.id || 'unknown'}  |  Branch: ${branch}`,
+  ];
+}
+
+/**
+ * Format the metrics line (tests, coverage).
+ * @param {object} metrics - Sprint metrics object
+ * @returns {string|null} Metrics line or null if no metrics
+ */
+function buildMetricsLine(metrics) {
+  const parts = [];
+  if (metrics.tests_passed != null) {
+    parts.push(`Tests: ${metrics.tests_passed} passed${metrics.tests_failed ? `, ${metrics.tests_failed} failed` : ''}`);
+  }
+  if (metrics.coverage_pct != null) {
+    parts.push(`Coverage: ${metrics.coverage_pct}%`);
+  }
+  return parts.length > 0 ? `Metrics: ${parts.join('  |  ')}` : null;
+}
+
+/**
+ * Build a phase lookup map from phase_history array.
  * @param {object} state - Sprint state object
- * @returns {boolean}
+ * @returns {object} Map of phase key → phase history entry
  */
-function isStale(state) {
-  if (!state || !state.started_at) return false;
-  const started = new Date(state.started_at).getTime();
-  if (isNaN(started)) return false;
-  // Check latest phase_history timestamp (started_at or completed_at)
-  let latest = started;
-  if (Array.isArray(state.phase_history) && state.phase_history.length > 0) {
+function buildPhaseLookup(state) {
+  const map = {};
+  if (Array.isArray(state.phase_history)) {
     for (const ph of state.phase_history) {
-      if (ph.completed_at) {
-        const t = new Date(ph.completed_at).getTime();
-        if (!isNaN(t) && t > latest) latest = t;
-      }
-      if (ph.started_at) {
-        const t = new Date(ph.started_at).getTime();
-        if (!isNaN(t) && t > latest) latest = t;
-      }
+      map[String(ph.phase)] = ph;
     }
   }
-  return Date.now() - latest > 3600000; // 1h
+  return map;
+}
+
+/**
+ * Format a single phase row line.
+ * @param {string} key - Phase key (e.g. '0', '1')
+ * @param {object|undefined} history - Phase history entry
+ * @param {number} maxNameLen - Max phase name length for padding
+ * @returns {string} Formatted phase line
+ */
+function formatPhaseLine(key, history, maxNameLen) {
+  const name = history?.phase_name || PHASE_NAMES[key] || key;
+  const status = history?.status || 'pending';
+  const icon = statusIcon(status);
+  const dur = formatDuration(history?.duration_seconds);
+  const statusLabel = status === 'completed' ? 'Completed' :
+    status === 'in_progress' ? 'In Progress' : 'Pending';
+  return `  Phase ${key.padStart(4)}  ${name.padEnd(maxNameLen + 1)} ${icon} ${dur.padEnd(5)} ${statusLabel}`;
+}
+
+/**
+ * Format REQ-level progress sub-lines for a phase (typically BUILD).
+ * @param {object|undefined} history - Phase history entry with optional reqs
+ * @returns {string[]} Array of REQ progress lines (may be empty)
+ */
+function formatReqLines(history) {
+  if (!history?.reqs) return [];
+  const lines = [];
+  for (const [reqId, req] of Object.entries(history.reqs)) {
+    lines.push(`    ${statusIcon(req.status)} ${reqId}  ${req.name}`);
+  }
+  return lines;
 }
 
 /**
@@ -105,77 +139,35 @@ function formatSprintTable(state) {
     return 'No active sprint in this directory';
   }
 
-  const lines = [];
   const branch = state.isolation?.branch || 'unknown';
   const metrics = state.metrics || {};
+  const lines = buildHeader(state, branch);
 
-  // Header
-  lines.push(`Sprint: ${state.task_description}`);
-  lines.push(`ID: ${state.id || 'unknown'}  |  Branch: ${branch}`);
-
-  // Metrics line (if available)
-  const metricParts = [];
-  if (metrics.tests_passed != null) {
-    metricParts.push(`Tests: ${metrics.tests_passed} passed${metrics.tests_failed ? `, ${metrics.tests_failed} failed` : ''}`);
-  }
-  if (metrics.coverage_pct != null) {
-    metricParts.push(`Coverage: ${metrics.coverage_pct}%`);
-  }
-  if (metricParts.length > 0) {
-    lines.push(`Metrics: ${metricParts.join('  |  ')}`);
-  }
+  const metricsLine = buildMetricsLine(metrics);
+  if (metricsLine) lines.push(metricsLine);
 
-  // Stale warning
   if (isStale(state)) {
     lines.push('⚠️  State may be stale (last updated >1h ago)');
   }
-
   lines.push('');
 
-  // Build phase lookup from phase_history
-  const historyByPhase = {};
-  if (Array.isArray(state.phase_history)) {
-    for (const ph of state.phase_history) {
-      historyByPhase[String(ph.phase)] = ph;
-    }
-  }
+  const historyByPhase = buildPhaseLookup(state);
 
-  // Calculate column widths dynamically
   let maxNameLen = 'Phase'.length;
   for (const key of PHASE_ORDER) {
-    const history = historyByPhase[key];
-    const name = history?.phase_name || PHASE_NAMES[key] || key;
+    const name = historyByPhase[key]?.phase_name || PHASE_NAMES[key] || key;
     if (name.length > maxNameLen) maxNameLen = name.length;
   }
 
-  // Separator line
   const sep = '─'.repeat(maxNameLen + 40);
-
   lines.push(sep);
 
   for (const key of PHASE_ORDER) {
-    const history = historyByPhase[key];
-    const name = history?.phase_name || PHASE_NAMES[key] || key;
-    const status = history?.status || 'pending';
-    const icon = statusIcon(status);
-    const dur = formatDuration(history?.duration_seconds);
-    const statusLabel = status === 'completed' ? 'Completed' :
-      status === 'in_progress' ? 'In Progress' : 'Pending';
-
-    const line = `  Phase ${key.padStart(4)}  ${name.padEnd(maxNameLen + 1)} ${icon} ${dur.padEnd(5)} ${statusLabel}`;
-    lines.push(line);
-
-    // REQ-level progress for BUILD phase
-    if (history?.reqs) {
-      for (const [reqId, req] of Object.entries(history.reqs)) {
-        const reqIcon = statusIcon(req.status);
-        lines.push(`    ${reqIcon} ${reqId}  ${req.name}`);
-      }
-    }
+    lines.push(formatPhaseLine(key, historyByPhase[key], maxNameLen));
+    lines.push(...formatReqLines(historyByPhase[key]));
   }
 
   lines.push(sep);
-
   return lines.join('\n');
 }
 

package/lib/upgrade.js

@@ -1,105 +1,116 @@
-const { execSync } = require('child_process');
+const { execSync, spawn } = require('child_process');
 const { checkUpgrade, formatUpgradeMsg, clearCache, getLocalVersion, getPackageName } = require('./check-version.js');
 
 /**
- * xp-gate upgrade command handler.
- *
- * Modes:
- *   xp-gate upgrade           — human-readable output
- *   xp-gate upgrade --preview — single-line JSON for plugin consumption
- *   xp-gate upgrade --apply   — auto-upgrade via npm install -g
- *
- * @param {string[]} args
- * @returns {Promise<number>} exit code
+ * Handle checkUpgrade() failure.
+ * @param {Error} err
+ * @param {boolean} isPreview
+ * @returns {number} exit code (always 1)
  */
-async function upgrade(args) {
-  const isPreview = args.includes('--preview');
-  const isApply = args.includes('--apply');
-  const pkgName = getPackageName();
-
-  // --- check for upgrade ---
-  let result;
-  try {
-    result = await checkUpgrade(pkgName);
-  } catch (err) {
-    if (isPreview) {
-      console.log(JSON.stringify({ error: 'check failed', detail: err.message }));
-    } else {
-      console.error('Unable to check for updates (check error).');
-    }
-    return 1;
-  }
-
-  // Guard: if checkUpgrade returned null remote (network issue)
-  if (!result.remote) {
-    if (isPreview) {
-      console.log(JSON.stringify({
-        local: result.local || 'unknown',
-        remote: null,
-        outdated: false,
-        lagDays: 0,
-        error: 'Unable to check for updates (network issue)',
-      }));
-    } else {
-      console.error('Unable to check for updates (network issue).');
-    }
-    return 0;
+function handleCheckError(err, isPreview) {
+  if (isPreview) {
+    console.log(JSON.stringify({ error: 'check failed', detail: err.message }));
+  } else {
+    console.error('Unable to check for updates (check error).');
   }
+  return 1;
+}
 
-  // --- --preview: JSON output ---
+/**
+ * Handle null remote (network issue) after checkUpgrade().
+ * @param {{ local: string|null }} result
+ * @param {boolean} isPreview
+ * @returns {number} exit code (always 0)
+ */
+function handleNullRemote(result, isPreview) {
   if (isPreview) {
-    const releaseUrl = result.outdated
-      ? `https://github.com/boyingliu01/xp-gate/releases/tag/v${result.remote}`
-      : null;
     console.log(JSON.stringify({
-      local: result.local,
-      remote: result.remote,
-      outdated: result.outdated,
-      lagDays: result.lagDays,
-      releaseUrl,
-      publishedAt: result.publishedAt || null,
+      local: result.local || 'unknown',
+      remote: null,
+      outdated: false,
+      lagDays: 0,
+      error: 'Unable to check for updates (network issue)',
     }));
-    return 0;
+  } else {
+    console.error('Unable to check for updates (network issue).');
   }
+  return 0;
+}
+
+/**
+ * Handle --preview mode: emit single-line JSON.
+ * @param {{ local: string, remote: string, outdated: boolean, lagDays: number, publishedAt?: string }} result
+ * @returns {number} exit code (always 0)
+ */
+function handlePreviewMode(result) {
+  const releaseUrl = result.outdated
+    ? `https://github.com/boyingliu01/xp-gate/releases/tag/v${result.remote}`
+    : null;
+  console.log(JSON.stringify({
+    local: result.local,
+    remote: result.remote,
+    outdated: result.outdated,
+    lagDays: result.lagDays,
+    releaseUrl,
+    publishedAt: result.publishedAt || null,
+  }));
+  return 0;
+}
 
-  // --- --apply: auto-upgrade ---
-  if (isApply) {
-    if (!result.outdated) {
-      if (result.local) {
-        console.log(`\u2713 xp-gate v${result.local} is up to date`);
-      } else {
-        console.log('xp-gate is up to date.');
-      }
-      return 0;
+/**
+ * Handle --apply mode: auto-upgrade via npm install -g.
+ * @param {{ local: string, remote: string, outdated: boolean }} result
+ * @param {string} pkgName
+ * @returns {Promise<number>} exit code
+ */
+async function handleApplyMode(result, pkgName) {
+  if (!result.outdated) {
+    if (result.local) {
+      console.log(`\u2713 xp-gate v${result.local} is up to date`);
+    } else {
+      console.log('xp-gate is up to date.');
     }
+    return 0;
+  }
 
-    console.log(`Upgrading xp-gate from v${result.local} to v${result.remote}...`);
-    try {
-      execSync(`npm install -g ${pkgName}@${result.remote}`, {
-        stdio: 'inherit',
-        timeout: 120000, // 2 minute timeout
+  console.log(`Upgrading xp-gate from v${result.local} to v${result.remote}...`);
+  try {
+    const child = spawn('npm', ['install', '-g', `${pkgName}@${result.remote}`], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+    await new Promise((resolve, reject) => {
+      child.on('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`npm install exited with code ${code}`));
       });
-      // clear cache so next check picks up the new version
-      clearCache();
-      console.log(`\u2713 Upgraded to v${result.remote}`);
-      return 0;
-    } catch (err) {
-      const stderr = (err.stderr || '').toString();
-      if (stderr.includes('EACCES') || stderr.includes('permission') || stderr.includes('EPERM')) {
-        console.error(`Permission denied. Try: sudo npm install -g ${pkgName}`);
-      } else if (err.code === 'ETIMEDOUT' || stderr.includes('ETIMEDOUT')) {
-        console.error('npm install timed out. Check your network and try again.');
-        console.error(`  Retry: npm install -g ${pkgName}@latest`);
-      } else {
-        console.error('Upgrade failed:');
-        console.error(`  ${err.message}`);
-        console.error(`  Retry manually: npm install -g ${pkgName}@latest`);
-      }
-      return 1;
+      child.on('error', reject);
+    });
+    clearCache();
+    console.log(`\u2713 Upgraded to v${result.remote}`);
+    return 0;
+  } catch (err) {
+    const msg = err.message || '';
+    if (msg.includes('EACCES') || msg.includes('permission') || msg.includes('EPERM')) {
+      console.error(`Permission denied. Try: sudo npm install -g ${pkgName}`);
+    } else if (msg.includes('ETIMEDOUT')) {
+      console.error('npm install timed out. Check your network and try again.');
+      console.error(`  Retry: npm install -g ${pkgName}@latest`);
+    } else {
+      console.error('Upgrade failed:');
+      console.error(`  ${msg}`);
+      console.error(`  Retry manually: npm install -g ${pkgName}@latest`);
     }
+    return 1;
   }
+}
 
-  // --- default mode: human-readable ---
+/**
+ * Handle default mode: human-readable output.
+ * @param {{ local: string, remote: string, outdated: boolean, lagDays: number, publishedAt?: string }} result
+ * @returns {number} exit code (always 0)
+ */
+function handleDefaultMode(result) {
   if (!result.outdated) {
     if (result.local) {
       console.log(`\u2713 xp-gate v${result.local} is up to date`);
@@ -113,4 +124,36 @@ async function upgrade(args) {
   return 0;
 }
 
+/**
+ * xp-gate upgrade command handler.
+ *
+ * Modes:
+ *   xp-gate upgrade           — human-readable output
+ *   xp-gate upgrade --preview — single-line JSON for plugin consumption
+ *   xp-gate upgrade --apply   — auto-upgrade via npm install -g
+ *
+ * @param {string[]} args
+ * @returns {Promise<number>} exit code
+ */
+async function upgrade(args) {
+  const isPreview = args.includes('--preview');
+  const isApply = args.includes('--apply');
+  const pkgName = getPackageName();
+
+  let result;
+  try {
+    result = await checkUpgrade(pkgName);
+  } catch (err) {
+    return handleCheckError(err, isPreview);
+  }
+
+  if (!result.remote) {
+    return handleNullRemote(result, isPreview);
+  }
+
+  if (isPreview) return handlePreviewMode(result);
+  if (isApply) return handleApplyMode(result, pkgName);
+  return handleDefaultMode(result);
+}
+
 module.exports = { upgrade };

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-06-18
-**Commit:** b67fc85
+**Generated:** 2026-06-21
+**Commit:** 1050a30
 **Branch:** main
-**Version:** 0.9.3.0
+**Version:** 0.9.5.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-06-18
-**Commit:** b67fc85
+**Generated:** 2026-06-21
+**Commit:** 1050a30
 **Branch:** main
-**Version:** 0.9.3.0
+**Version:** 0.9.5.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.9.3",
+  "version": "0.9.5",
   "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.9.3",
+  "version": "0.9.5",
   "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-06-18
-**Commit:** b67fc85
+**Generated:** 2026-06-21
+**Commit:** 1050a30
 **Branch:** main
-**Version:** 0.9.3.0
+**Version:** 0.9.5.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/delphi-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: delphi-review
 description: "Use when asked to review a design, plan, or architecture; before implementation starts; or when multi-expert consensus is needed. Triggers: 'review this design', '评审这个需求', 'design review', '多专家评审', 'consensus review', 'code walkthrough', 'push review', 'architecture review', 'PR review', or any request for multi-expert evaluation of requirements, design docs, or PRs."
+auto_continue: true
 ---
 
 # Delphi Consensus Review
@@ -109,6 +110,39 @@ Phase 0: 准备 → Round 1: 匿名独立评审 → 共识检查
 
 **Automatic re-review**: 对于常见可控问题（措辞模糊、AC 缺失、格式问题），subagent 应自行修复后自动重评审，无需等待用户。
 
+### ⭐ 自动延续规则（MANDATORY — 防止流程卡住）
+
+当 Delphi Review 启动多轮评审（Round 2+）时，**orchestrator 必须自动延续流程，不得等待用户输入**。
+
+**触发条件**：
+- Round N 完成，但未达到终止条件（100% approved + ≥90% consensus + 所有 Critical/Major 已处理）
+- 存在待处理的背景任务（subagent  dispatched tasks）
+
+**自动延续动作**：
+1. **收集背景任务结果**：等待 `<system-reminder>` 通知后，立即调用 `background_output(task_id="bg_...")` 获取所有 subagent 输出
+2. **合成 Round N 总结**：汇总专家意见、共识度、待处理问题
+3. **自动启动 Round N+1**：立即 dispatch 新一轮 subagent 任务，携带上一轮总结作为上下文
+4. **循环直至终止**：重复步骤 1-3，直到达到终止条件
+
+**终止条件**（满足全部）：
+- ✅ 所有专家状态 = APPROVED
+- ✅ 共识度 ≥ 90%
+- ✅ 所有 Critical 级别问题已解决
+- ✅ 所有 Major 级别问题已处理（或已记录为已知问题）
+
+**例外情况**（直接输出，不进入下一轮）：
+- Round 1 即达到 100% approved + 100% consensus → 直接输出最终报告
+- 已达最大轮数（5 轮）→ 输出"未达成共识"报告，标记为 PROCESS_BLOCK
+
+**禁止行为**：
+- ❌ 询问用户"要继续吗？"
+- ❌ 等待用户手动触发 Round N+1
+- ❌ 在未达到终止条件时停止流程
+
+**错误处理**：
+- 背景任务超时（>10min）→ 标记为 TIMEOUT，输出部分结果并终止
+- 背景任务失败（subagent 错误）→ 重试 1 次，仍失败则输出错误报告并终止
+
 ---
 
 ## 修复与重新评审

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

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-06-18
-**Commit:** b67fc85
+**Generated:** 2026-06-21
+**Commit:** 1050a30
 **Branch:** main
-**Version:** 0.9.3.0
+**Version:** 0.9.5.0
 
 ## OVERVIEW
 **11-phase** development pipeline: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW → USER ACCEPTANCE → FEEDBACK → SHIP → LAND → CLEANUP. Phase 2 default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE in Phase 1: design must pass Delphi review (≥90% consensus) before any coding.

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

@@ -408,6 +408,58 @@ Sprint Flow: ISOLATE → AUTO-ESTIMATE → THINK → PLAN → BUILD → REVIEW
 
 ---
 
+### ⭐ Phase State Persistence（阶段状态持久化 — MANDATORY）
+
+**编排器必须在每个 Phase 完成后更新 `.sprint-state/sprint-state.json`**：
+
+1. **Phase 完成后立即更新**（每个 Phase 结束前）：
+   - `phase`: 更新为当前 Phase 编号（如 `0`, `1`, `2`...）
+   - `status`: 更新为 `"completed"`（已完成 Phase）
+   - `phase_history`: 追加新条目
+
+2. **`phase_history` 数组条目 schema**：
+   ```json
+   {
+     "phase": 0,
+     "phase_name": "THINK",
+     "status": "completed",
+     "timestamp": "2026-06-20T10:30:00Z"
+   }
+   ```
+
+3. **检查点**：
+   - `--status` 参数读取 `sprint-state.json` 并渲染进度看板
+   - TUI panel 显示当前 Phase 和历史
+   - `--resume-from` 校验 `phase_history` 中的最后完成 Phase
+
+4. **完整 sprint-state.json 示例**：
+   ```json
+   {
+     "id": "sprint-2026-06-20-01",
+     "phase": 2,
+     "status": "in_progress",
+     "phase_history": [
+       {"phase": -1, "phase_name": "ISOLATE", "status": "completed", "timestamp": "2026-06-20T10:00:00Z"},
+       {"phase": -0.5, "phase_name": "AUTO-ESTIMATE", "status": "completed", "timestamp": "2026-06-20T10:05:00Z"},
+       {"phase": 0, "phase_name": "THINK", "status": "completed", "timestamp": "2026-06-20T10:15:00Z"},
+       {"phase": 1, "phase_name": "PLAN", "status": "completed", "timestamp": "2026-06-20T10:30:00Z"}
+     ],
+     "isolation": {
+       "worktree_path": "/home/boyingliu01/projects/xp-gate/.worktrees/sprint/sprint-2026-06-20-01",
+       "branch": "sprint/2026-06-20-01"
+     },
+     "outputs": {
+       "pain_document": "phase-outputs/phase-0-summary.md",
+       "specification": "phase-outputs/specification.yaml"
+     },
+     "metrics": {
+       "coverage_pct": 85.5
+     }
+   }
+   ```
+
+---
+
 ## 使用示例
 
 | 场景 | 命令 | 说明 |
@@ -447,7 +499,7 @@ See [Output Contract](#output-contract) below for the canonical machine-readable
 
 **Phase Summary** (每个 Phase 必须输出 YAML frontmatter): `phase/N`, `phase_name`, `status`, `outputs[]`, `decisions[]`, `next_phase_context` + markdown body (≤50 lines)
 
-**Sprint State JSON**: `{id, phase, status, isolation {worktree_path, branch}, outputs, metrics}` — 存储于 `.sprint-state/sprint-state.json`
+**Sprint State JSON**: `{id, phase, status, phase_history[], isolation {worktree_path, branch}, outputs, metrics}` — 存储于 `.sprint-state/sprint-state.json`
 
 **Final User-Facing Output**: Phase/status, file paths, validation results, next user decision, PR URL or cleanup report