@boyingliu01/xp-gate 0.14.22 → 0.14.24

package/scripts/sync-package-content.js

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const REPO_ROOT = path.resolve(PKG_ROOT, '..', '..');
+
+const CORE_SKILLS = [
+  'admin-template-guidelines',
+  'delphi-review',
+  'improve-codebase-architecture',
+  'ralph-loop',
+  'sprint-flow',
+  'test-driven-development',
+  'test-specification-alignment',
+  'to-issues',
+];
+
+const PLUGINS = ['claude-code', 'opencode', 'qoder'];
+
+// Plugins whose `skills/` subtree is gitignored (build artifact). For these,
+// the source-of-truth skill content lives in repo-root `skills/` and must be
+// injected during sync so the npm-package mirror is complete even on a clean
+// checkout (e.g. CI Mirror Parity job). Plugins not listed here are expected
+// to ship their own committed `skills/` subtree (e.g. `plugins/qoder/skills/`).
+const PLUGINS_WITH_GITIGNORED_SKILLS = new Set(['claude-code', 'opencode']);
+
+function rmrf(target) {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.opencode']);
+const SKIP_FILES = new Set(['package-lock.json']);
+const SKIP_FILE_SUFFIXES = ['.lock', '.js.map'];
+
+function shouldSkipFile(name) {
+  if (SKIP_FILES.has(name)) return true;
+  return SKIP_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.error(`[sync] SKIP (missing): ${src}`);
+    return false;
+  }
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else if (entry.isFile()) {
+      if (shouldSkipFile(entry.name)) continue;
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+  return true;
+}
+
+function syncSkills() {
+  const destRoot = path.join(PKG_ROOT, 'skills');
+  rmrf(destRoot);
+  fs.mkdirSync(destRoot, { recursive: true });
+  let copied = 0;
+  for (const name of CORE_SKILLS) {
+    const src = path.join(REPO_ROOT, 'skills', name);
+    const dest = path.join(destRoot, name);
+    if (copyDir(src, dest)) {
+      copied += 1;
+      console.error(`[sync] skills/${name}`);
+    }
+  }
+  return copied;
+}
+
+function injectCanonicalSkills(pluginDest) {
+  const skillsDest = path.join(pluginDest, 'skills');
+  rmrf(skillsDest);
+  fs.mkdirSync(skillsDest, { recursive: true });
+  for (const name of CORE_SKILLS) {
+    const src = path.join(REPO_ROOT, 'skills', name);
+    const dest = path.join(skillsDest, name);
+    if (!copyDir(src, dest)) {
+      console.error(`[sync] ERROR: missing canonical skill ${name}`);
+      process.exit(1);
+    }
+  }
+}
+
+// tui-plugin.ts was removed in v0.13.0 (slimming). The TUI panel approach
+// was abandoned after multiple unsuccessful integration attempts.
+
+function syncPlugins() {
+  const destRoot = path.join(PKG_ROOT, 'plugins');
+  rmrf(destRoot);
+  fs.mkdirSync(destRoot, { recursive: true });
+  let copied = 0;
+  for (const name of PLUGINS) {
+    const src = path.join(REPO_ROOT, 'plugins', name);
+    const dest = path.join(destRoot, name);
+    if (copyDir(src, dest)) {
+      if (PLUGINS_WITH_GITIGNORED_SKILLS.has(name)) {
+        injectCanonicalSkills(dest);
+      }
+      // tui-plugin.ts was removed in v0.13.0 — no import rewriting needed.
+      copied += 1;
+      console.error(`[sync] plugins/${name}`);
+    }
+  }
+  return copied;
+}
+
+function syncScripts() {
+  const srcRoot = path.join(REPO_ROOT, 'scripts');
+  const destRoot = path.join(PKG_ROOT, 'scripts');
+  const scriptsToSync = ['delphi-external-review.cjs'];
+  let copied = 0;
+  for (const name of scriptsToSync) {
+    const src = path.join(srcRoot, name);
+    if (fs.existsSync(src)) {
+      fs.mkdirSync(destRoot, { recursive: true });
+      fs.copyFileSync(src, path.join(destRoot, name));
+      copied += 1;
+      console.error(`[sync] scripts/${name}`);
+    }
+  }
+  return copied;
+}
+
+function syncAdapters() {
+  const srcRoot = path.join(REPO_ROOT, 'githooks', 'adapters');
+  const destRoot = path.join(PKG_ROOT, 'adapters');
+  if (!fs.existsSync(srcRoot)) {
+    console.error(`[sync] SKIP adapters (missing): ${srcRoot}`);
+    return 0;
+  }
+  rmrf(destRoot);
+  fs.mkdirSync(destRoot, { recursive: true });
+  const entries = fs.readdirSync(srcRoot, { withFileTypes: true });
+  let copied = 0;
+  for (const entry of entries) {
+    const srcPath = path.join(srcRoot, entry.name);
+    const destPath = path.join(destRoot, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+      copied += 1;
+    } else if (entry.isFile() && entry.name.endsWith('.sh')) {
+      fs.copyFileSync(srcPath, destPath);
+      copied += 1;
+    }
+  }
+  console.error(`[sync] adapters/ (${copied} entries)`);
+
+  // Sync gate scripts (gate-*.sh) from githooks/ to package root so they ship
+  // with the npm package and can be installed to the global adapter dir.
+  const githooksDir = path.join(REPO_ROOT, 'githooks');
+  const gateFiles = fs.readdirSync(githooksDir).filter(f =>
+    (f.startsWith('gate-') || f === 'sprint-gate.sh') && f.endsWith('.sh')
+  );
+  for (const f of gateFiles) {
+    fs.copyFileSync(path.join(githooksDir, f), path.join(PKG_ROOT, f));
+  }
+  if (gateFiles.length > 0) {
+    console.error(`[sync] gate scripts: ${gateFiles.join(', ')}`);
+  }
+  return copied + gateFiles.length;
+}
+
+function syncModules(moduleName) {
+  const src = path.join(REPO_ROOT, 'src', moduleName);
+  const dest = path.join(PKG_ROOT, moduleName);
+  if (!copyDir(src, dest)) {
+    console.error(`[sync] ERROR: missing module ${moduleName}`);
+    process.exit(1);
+  }
+  console.error(`[sync] ${moduleName}/`);
+  return 1;
+}
+
+function extractPreCommitGateNumbers(preCommitContent) {
+  const SCRIPT_META_GATES = new Set([]);
+  const gates = new Set();
+  for (const m of preCommitContent.matchAll(/Gate (\d+):/g)) {
+    if (!SCRIPT_META_GATES.has(m[1])) {
+      gates.add(m[1]);
+    }
+  }
+  return gates;
+}
+
+function extractReadmeGateNumbers(readmeContent, section) {
+  const gates = new Set();
+  for (const m of readmeContent.matchAll(section)) {
+    gates.add(m[1]);
+  }
+  return gates;
+}
+
+function compareGateSets(scriptGates, readmeGates, label, sortFn) {
+  const scriptOnly = [...scriptGates].filter((g) => !readmeGates.has(g));
+  const readmeOnly = [...readmeGates].filter((g) => !scriptGates.has(g));
+
+  if (scriptOnly.length > 0 || readmeOnly.length > 0) {
+    const hookFile = label.toLowerCase();
+    console.error(`[drift-check] ERROR: ${label} Gate table drift detected!`);
+    const sortedScript = [...scriptGates].sort(sortFn);
+    const sortedReadme = [...readmeGates].sort(sortFn);
+    console.error(`  Script githooks/${hookFile} has ${scriptGates.size} gates: [${sortedScript.join(', ')}]`);
+    console.error(`  README.md documents ${readmeGates.size} gates: [${sortedReadme.join(', ')}]`);
+    if (scriptOnly.length > 0) {
+      const sorted = sortFn ? scriptOnly.sort(sortFn) : scriptOnly;
+      console.error(`  In script but NOT in README: Gate ${sorted.join(', Gate ')}`);
+    }
+    if (readmeOnly.length > 0) {
+      const sorted = sortFn ? readmeOnly.sort(sortFn) : readmeOnly;
+      console.error(`  In README but NOT in script: Gate ${sorted.join(', Gate ')}`);
+    }
+    console.error(`  Fix: Update README.md Gate table to match githooks/${hookFile}`);
+  }
+  return { scriptOnly, readmeOnly };
+}
+
+function checkPreCommitDrift(preCommitPath, readmePath) {
+  let scriptContent = '';
+  if (fs.existsSync(preCommitPath)) {
+    scriptContent = fs.readFileSync(preCommitPath, 'utf8');
+  } else {
+    console.error('[drift-check] WARN: githooks/pre-commit not found, skipping pre-commit check');
+    return null;
+  }
+
+  const scriptGates = extractPreCommitGateNumbers(scriptContent);
+
+  let readmeContent = '';
+  if (fs.existsSync(readmePath)) {
+    readmeContent = fs.readFileSync(readmePath, 'utf8');
+  } else {
+    console.error('[drift-check] WARN: README.md not found, skipping drift check');
+    return true;
+  }
+
+  const readmeGates = extractReadmeGateNumbers(readmeContent, /\| Gate (\d+) \|/g);
+
+  if (scriptGates.size > 0 && readmeGates.size > 0) {
+    const numericSort = (a, b) => +a - +b;
+    const { scriptOnly, readmeOnly } = compareGateSets(scriptGates, readmeGates, 'Pre-commit', numericSort);
+    if (scriptOnly.length > 0 || readmeOnly.length > 0) {
+      return false;
+    }
+    console.error(`[drift-check] OK: pre-commit ${scriptGates.size} gates match README`);
+  }
+  return true;
+}
+
+function checkPrePushDrift(prePushPath, readmePath) {
+  let scriptContent = '';
+  if (fs.existsSync(prePushPath)) {
+    scriptContent = fs.readFileSync(prePushPath, 'utf8');
+  } else {
+    console.error('[drift-check] WARN: githooks/pre-push not found, skipping pre-push check');
+    return null;
+  }
+
+  const scriptGates = extractReadmeGateNumbers(scriptContent, /[Gg][Aa][Tt][Ee] (M\d*)/g);
+
+  let readmeContent = '';
+  if (fs.existsSync(readmePath)) {
+    readmeContent = fs.readFileSync(readmePath, 'utf8');
+  } else {
+    return true;
+  }
+
+  const readmeGates = extractReadmeGateNumbers(readmeContent, /\| Gate (M\d*) \|/g);
+
+  if (scriptGates.size > 0 && readmeGates.size > 0) {
+    const { scriptOnly, readmeOnly } = compareGateSets(scriptGates, readmeGates, 'Pre-push');
+    if (scriptOnly.length > 0 || readmeOnly.length > 0) {
+      return false;
+    }
+    console.error(`[drift-check] OK: pre-push ${scriptGates.size} gates match README`);
+  }
+  return true;
+}
+
+/**
+ * Docs-drift check (REQ-TDD-005): compare Gate table in README.md against
+ * actual gate definitions in githooks/pre-commit and githooks/pre-push.
+ * Blocks publish if counts diverge.
+ */
+/**
+ * Adapter mirror drift check (REQ-329): compares githooks/adapters/ (source of truth)
+ * against src/npm-package/adapters/ (npm mirror). Content must be byte-identical;
+ * any mismatch blocks publish because syncAdapters() would overwrite the mirror.
+ */
+function checkAdapterDrift(srcRootPath, mirrorRootPath) {
+  const srcRoot = srcRootPath || path.join(REPO_ROOT, 'githooks', 'adapters');
+  const mirrorRoot = mirrorRootPath || path.join(PKG_ROOT, 'adapters');
+
+  if (!fs.existsSync(srcRoot)) {
+    console.error('[drift-check] WARN: githooks/adapters not found, skipping adapter drift check');
+    return true;
+  }
+  if (!fs.existsSync(mirrorRoot)) {
+    console.error('[drift-check] WARN: src/npm-package/adapters not found, skipping adapter drift check');
+    return true;
+  }
+
+  const crypto = require('crypto');
+
+  /**
+   * Recursively compute a sorted, deterministic hash table for a directory.
+   * Keys are relative paths (POSIX separators); values are SHA-256 hex digests.
+   */
+  function hashDirectory(root) {
+    const table = {};
+    function walk(dir, base) {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      // Sort for determinism
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        const rel = path.posix.join(base, entry.name);
+        if (entry.isDirectory()) {
+          walk(full, rel);
+        } else if (entry.isFile()) {
+          if (shouldSkipFile(entry.name)) continue;
+          const buf = fs.readFileSync(full);
+          table[rel] = crypto.createHash('sha256').update(buf).digest('hex');
+        }
+      }
+    }
+    walk(root, '');
+    return table;
+  }
+
+  const srcHashes = hashDirectory(srcRoot);
+  const mirrorHashes = hashDirectory(mirrorRoot);
+
+  // Check for files only in one side
+  const srcOnly = Object.keys(srcHashes).filter((f) => !(f in mirrorHashes));
+  const mirrorOnly = Object.keys(mirrorHashes).filter((f) => !(f in srcHashes));
+
+  // Check for content mismatches
+  const mismatched = [];
+  for (const f of Object.keys(srcHashes)) {
+    if (mirrorHashes[f] && srcHashes[f] !== mirrorHashes[f]) {
+      mismatched.push(f);
+    }
+  }
+
+  if (srcOnly.length > 0) {
+    console.error(`[drift-check] ERROR: ${srcOnly.length} file(s) in githooks/adapters/ missing from npm-package mirror:`);
+    for (const f of srcOnly) console.error(`  - ${f}`);
+  }
+  if (mirrorOnly.length > 0) {
+    console.error(`[drift-check] ERROR: ${mirrorOnly.length} file(s) in npm-package mirror NOT in githooks/adapters/:`);
+    for (const f of mirrorOnly) console.error(`  - ${f}`);
+  }
+  if (mismatched.length > 0) {
+    console.error(`[drift-check] ERROR: ${mismatched.length} adapter file(s) have drifted (SHA-256 mismatch):`);
+    for (const f of mismatched) console.error(`  - ${f}`);
+    console.error('[drift-check] Fix: Run `node src/npm-package/scripts/sync-package-content.js` (or `npm pack`) to resync.');
+  }
+
+  if (srcOnly.length > 0 || mirrorOnly.length > 0 || mismatched.length > 0) {
+    return false;
+  }
+
+  const totalSrc = Object.keys(srcHashes).length;
+  const totalMirror = Object.keys(mirrorHashes).length;
+  console.error(`[drift-check] OK: ${totalSrc} adapter files match between githooks/adapters/ and npm-package mirror (${totalMirror} files)`);
+  return true;
+}
+
+function checkDocsDrift(preCommitPath, prePushPath, readmePath, agentsPath) {
+  const preCommitScript = preCommitPath || path.join(REPO_ROOT, 'githooks', 'pre-commit');
+  const prePushScript = prePushPath || path.join(REPO_ROOT, 'githooks', 'pre-push');
+  const readme = readmePath || path.join(REPO_ROOT, 'README.md');
+
+  const preCommitResult = checkPreCommitDrift(preCommitScript, readme);
+  if (preCommitResult === false) return false;
+
+  const prePushResult = checkPrePushDrift(prePushScript, readme);
+  if (prePushResult === false) return false;
+
+  return true;
+}
+
+function main() {
+  console.error(`[sync] repo root: ${REPO_ROOT}`);
+  console.error(`[sync] package root: ${PKG_ROOT}`);
+  if (checkDocsDrift() === false) {
+    process.exit(1);
+  }
+  if (checkAdapterDrift() === false) {
+    process.exit(1);
+  }
+  const skills = syncSkills();
+  const plugins = syncPlugins();
+  const scripts = syncScripts();
+  const adapters = syncAdapters();
+const principles = syncModules('principles');
+const mutation = syncModules('mutation');
+const mockPolicy = syncModules('mock-policy');
+const buildIntegrity = syncModules('build-integrity');
+console.error(`[sync] done: ${skills} skill(s), ${plugins} plugin(s), ${scripts} script(s), ${adapters} adapter entries, ${principles + mutation + mockPolicy + buildIntegrity} module(s)`);
+  if (skills !== CORE_SKILLS.length) {
+    console.error(`[sync] ERROR: expected ${CORE_SKILLS.length} skills, copied ${skills}`);
+    process.exit(1);
+  }
+  if (plugins !== PLUGINS.length) {
+    console.error(`[sync] ERROR: expected ${PLUGINS.length} plugins, copied ${plugins}`);
+    process.exit(1);
+  }
+
+  // tui-plugin removed in v0.13.0 — validation skipped.
+}
+
+if (require.main !== module) {
+  module.exports = { checkDocsDrift, checkAdapterDrift };
+}
+
+main();

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-07-21
-**Commit:** 03d6f26
+**Generated:** 2026-07-22
+**Commit:** e331f2c
 **Branch:** main
-**Version:** 0.14.22.0
+**Version:** 0.14.24.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/delphi-review/SKILL.md

@@ -294,14 +294,34 @@ Each round MUST output a structured round marker:
 | 2 专家（默认） | A(架构) + B(实现) | 代码变更、小型设计 |
 | 3 专家 | A(架构) + B(实现) + C(可行性) | 架构决策、需求文档 |
 
-### 模型选择策略（强制 — 从 opencode.json 读取）
-
-**MUST 从 `opencode.json` 的 agent 配置中读取模型**，**严禁** hardcode 模型名称。
+### 模型选择策略（强制 — 平台适配）
 
 **关键原则**：
 - ✅ 三个专家必须来自 **至少 2 家不同 provider**
-- ❌ 禁止 hardcode 模型名称（模型列表以 `opencode.json` 为准）
+- ❌ 禁止 hardcode 模型名称
 - ❌ 禁止三个专家全部使用同一 provider 的模型
+- ❌ 禁止使用 Anthropic/OpenAI/Google 等国外模型
+
+#### Qoder 平台（推荐 — Custom Agent 模式）
+
+Qoder 环境下使用 **Custom Agent** 机制，每个专家是一个独立的 custom agent，配置不同的 Qoder 内置模型：
+
+| 专家 | Agent 文件 | 模型 | Credits 费率 |
+|------|-----------|------|-------------|
+| Architecture (A) | `.qoder/agents/delphi-architecture.md` | Qwen3.7-Max | 0.5× |
+| Technical (B) | `.qoder/agents/delphi-technical.md` | GLM-5.2 | 0.6× |
+| Feasibility (C) | `.qoder/agents/delphi-feasibility.md` | DeepSeek-V4-Pro | 0.5× |
+
+**执行方式**：通过 Agent tool 并行启动 3 个 subagent（type=GeneralPurpose），每个 agent 使用自己配置的模型独立评审，主 orchestrator 收集结果后计算共识。
+
+**优势**：无需外部 API key，直接使用 Qoder Credits，模型由平台统一管理。
+
+#### OpenCode 平台（External API 模式）
+
+OpenCode 环境下通过 `opencode.json` 的 agent 配置 + `.delphi-config.json` 调用外部 API：
+- **MUST 从 `opencode.json` 的 agent 配置中读取模型**
+- 通过 `scripts/delphi-external-review.cjs` 调用各 provider 的 OpenAI 兼容 API
+- 需要用户自行配置 API key（环境变量注入）
 
 ### 共识阈值
 

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-07-21
-**Commit:** 03d6f26
+**Generated:** 2026-07-22
+**Commit:** e331f2c
 **Branch:** main
-**Version:** 0.14.22.0
+**Version:** 0.14.24.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/sprint-flow/SKILL.md

@@ -199,11 +199,26 @@ Every phase MUST output its header as the first line of that phase's output. For
 3. NEVER merge phase output — each phase gets its own header
 4. On `/sprint-flow` trigger, first line MUST output: `Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
 5. Each phase completion MUST write Phase Summary to `.sprint-state/phase-outputs/phase-{N}-summary.md`
-6. Each phase completion MUST update `.sprint-state/sprint-state.json`
-
-### Required Rendering (MANDATORY per phase)
-
-7. Each phase completion MUST render the ASCII progress dashboard using `templates/sprint-progress-template.md` — the orchestrator reads `sprint-state.json` and outputs the dashboard after every phase's status block, so the user always sees current global progress without needing to ask
+6. Each phase completion MUST call `xp-gate phase-transition <N> <status> --render` — this programmatically updates `sprint-state.json` AND renders the ASCII dashboard in one command (resolves #338, #146)
+
+### Phase Transition CLI (MANDATORY — replaces manual state updates)
+
+7. **NEVER** manually write to `sprint-state.json` or manually render the dashboard from template. ALWAYS use:
+   ```
+   npx xp-gate phase-transition <phase> <status> --render [--outputs '<json>']
+   ```
+   - `<phase>`: 1-6
+   - `<status>`: `in_progress` | `completed` | `skipped` | `failed` | `paused`
+   - `--render`: Auto-renders ASCII progress dashboard after state update
+   - `--outputs '<json>'`: Optional JSON of phase outputs to record
+   
+   Example (end of each phase):
+   ```
+   npx xp-gate phase-transition 1 completed --render --outputs '{"estimate":"3 story points"}'
+   npx xp-gate phase-transition 2 in_progress --render
+   ```
+   
+   This is a **HARD GATE** — the orchestrator MUST invoke this CLI command. Text-level instructions to "update state" or "render dashboard" are DEPRECATED; the CLI is the single source of truth for state transitions and dashboard rendering.
 
 ### Phase Output Status Schema (MANDATORY per phase)
 

package/skills/sprint-flow/references/orchestration-rules.md

@@ -89,25 +89,20 @@
    - 格式：YAML frontmatter + Markdown body（body ≤ 50 行）
    - 大小限制：≤ 40,000 字符（≈ 10,000 tokens）
 
-2. **更新 sprint-state.json**：
-   - `phase`: 当前阶段编号 (1-6)
-   - `outputs`: 新增当前阶段输出文件路径
-   - `phase_history`: 追加或更新当前阶段的记录
-     - Phase 开始时：追加 `{ "phase": N, "phase_name": "NAME", "status": "running", "started_at": "<ISO 8601>", "completed_at": null, "duration_seconds": null }`
-     - Phase 完成时：更新对应条目，填充 `completed_at`（ISO 8601）和 `duration_seconds`
-     - Phase 跳过时：设置 `status: "skipped"`
+2. **调用 phase-transition CLI**（替代手动更新 sprint-state.json + 手动渲染看板）：
+   ```
+   npx xp-gate phase-transition <phase> <status> --render [--outputs '<json>']
+   ```
+   - Phase 开始时：`npx xp-gate phase-transition <N> in_progress --render`
+   - Phase 完成时：`npx xp-gate phase-transition <N> completed --render --outputs '{"key":"value"}'`
+   - Phase 跳过时：`npx xp-gate phase-transition <N> skipped --render`
+   - CLI 自动完成：更新 `sprint-state.json`（phase, phase_history, outputs）+ 渲染 ASCII 看板
+   - 看板规则：已完成 ✅ + 耗时，当前 🔄，待做 ⬜，跳过 ⏭️，失败 ❌
+   - 进度条：`[████▓░░░░░░] {pct}%`
+   - **禁止**手动写入 `sprint-state.json` 或手动调用 `render-sprint-progress.cjs`（已废弃）
 
 3. **等待用户确认 checkpoint**（如适用）
 
-4. **展示进度看板**：执行 `node scripts/render-sprint-progress.cjs` 渲染进度看板
-   - 脚本自动读取 `.sprint-state/sprint-state.json` 并输出 ASCII 进度看板
-   - 渲染规则：已完成阶段显示 ✅ + 耗时，当前阶段 🔄，待做 ⬜，跳过 ⏭️，失败 ❌
-   - 进度条：`[████▓░░░░░░] {pct}%`（已完成数/总阶段数 6）
-   - 下一步行动：根据当前阶段 + 状态，自动查找对应提示
-   - 输出物路径：列出 `outputs` 中已有的文件路径
-   - 时机：每个 Phase 完成后的 transition 阶段自动展示
-   - 向后兼容：旧版 `sprint-state.json` 缺少 `phase_history` 时，从 `phase` 字段推断状态
-
 ### Background Task Resume Protocol (MANDATORY — Issue #248)
 
 After dispatching background agents with `run_in_background=true`:

package/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-07-21
-**Commit:** 03d6f26
+**Generated:** 2026-07-22
+**Commit:** e331f2c
 **Branch:** main
-**Version:** 0.14.22.0
+**Version:** 0.14.24.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.