@boyingliu01/xp-gate 0.35.16 → 0.35.18

package/mutation/runners/mutmut-runner.ts

@@ -1,5 +1,5 @@
 // @no-test-required: mutmut wrapper — tested via gate-m integration + pre-push Gate M
-import { spawn, execSync } from 'child_process';
+import { spawn, execSync, type ChildProcess } from 'child_process';
 import { writeFileSync, unlinkSync, readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import type {
@@ -24,6 +24,87 @@ type MutmutRoute = 'native' | 'wsl' | 'unavailable' | 'unresolved';
  * - Results stored in SQLite; `mutmut results` outputs per-mutant status lines
  * - `mutmut run` stdout shows emoji progress: 🎉 N 🫥 N ⏰ N 🤔 N 🙁 N
  */
+/**
+ * Wire a child process's stdout/stderr into one accumulating callback.
+ *
+ * Extracted from `runMutmut`: the two listeners were six lines of pure
+ * accumulation inside an already-long Promise body, and their nesting was part
+ * of what made that method exceed both the length and the nesting budget.
+ */
+function collectOutput(
+  child: ChildProcess,
+  onChunk: (chunk: string, isStderr: boolean) => void,
+): void {
+  child.stdout?.on('data', (data: Buffer) => onChunk(data.toString(), false));
+  child.stderr?.on('data', (data: Buffer) => onChunk(data.toString(), true));
+}
+
+/** How long a SIGTERMed mutmut gets before it is killed outright. */
+const ESCALATION_DELAY_MS = 5000;
+
+/** Where the pre-run copy of pyproject.toml lives. */
+function pyprojectBackupPath(pyprojectPath: string): string {
+  return `${pyprojectPath}.xp-gate-backup`;
+}
+
+/**
+ * Put pyproject.toml back the way it was, or remove the one we generated.
+ *
+ * Cleanup is best-effort by design: the mutation run's own result is what the
+ * caller acts on, and failing here would replace a usable outcome with an
+ * exception raised from a `finally`. Extracted from `run` because the nested
+ * try/if/if/else was what pushed that method to 5 nesting levels.
+ */
+function restorePyproject(pyprojectPath: string, hadExisting: boolean): void {
+  const backupPath = pyprojectBackupPath(pyprojectPath);
+  try {
+    if (hadExisting && existsSync(backupPath)) {
+      writeFileSync(pyprojectPath, readFileSync(backupPath, 'utf-8'), { encoding: 'utf-8' });
+      unlinkSync(backupPath);
+    } else if (!hadExisting && existsSync(pyprojectPath)) {
+      unlinkSync(pyprojectPath);
+    }
+  } catch {
+    // Best effort cleanup
+  }
+}
+
+/** The tracker shape `settleTracker` returns; only the timeout path uses these. */
+interface SettleTracker {
+  didTimeOut: () => boolean;
+  markTimedOut: () => void;
+  settle: (outcome: MutationRunOutcome) => void;
+  isSettled: () => boolean;
+}
+
+/**
+ * Arm the run timeout, escalating SIGTERM to SIGKILL once.
+ *
+ * Extracted from `runMutmut` for the same reason as `collectOutput`: the
+ * two-step kill sequence is twelve lines of policy that pushed the method past
+ * both budgets. The escalation timer id is handed back through `setEscalation`
+ * so the caller's `cancelTimers` closure can still reach it.
+ *
+ * @returns the primary timer id, to be cleared by the caller.
+ */
+function armTimeout(
+  child: ChildProcess,
+  timeoutMs: number,
+  tracker: SettleTracker,
+  setEscalation: (id: NodeJS.Timeout) => void,
+): NodeJS.Timeout {
+  const escalationMs = ESCALATION_DELAY_MS;
+  return setTimeout(() => {
+    tracker.markTimedOut();
+    child.kill('SIGTERM');
+    if (tracker.isSettled()) return;
+    // SIGTERM may be ignored; escalate once.
+    setEscalation(setTimeout(() => {
+      if (!tracker.isSettled()) child.kill('SIGKILL');
+    }, escalationMs));
+  }, timeoutMs);
+}
+
 export class MutmutRunner implements MutationRunner {
   readonly name = 'mutmut';
   readonly extensions = ['py'];
@@ -72,33 +153,35 @@ export class MutmutRunner implements MutationRunner {
     const sourceDirs = this.extractUniqueDirs(options.files);
 
     const pyprojectPath = join(options.cwd, 'pyproject.toml');
-    const backupPath = join(options.cwd, 'pyproject.toml.xp-gate-backup');
-    let hadExisting = false;
+    const hadExisting = this.backupPyproject(pyprojectPath);
 
     try {
-      if (existsSync(pyprojectPath)) {
-        hadExisting = true;
-        const existing = readFileSync(pyprojectPath, 'utf-8');
-        writeFileSync(backupPath, existing, { encoding: 'utf-8' });
-      }
       this.writeMutmutConfig(pyprojectPath, sourceDirs);
-
       return await this.runMutmut(options);
     } finally {
-      try {
-        if (hadExisting && existsSync(backupPath)) {
-          const backup = readFileSync(backupPath, 'utf-8');
-          writeFileSync(pyprojectPath, backup, { encoding: 'utf-8' });
-          unlinkSync(backupPath);
-        } else if (!hadExisting && existsSync(pyprojectPath)) {
-          unlinkSync(pyprojectPath);
-        }
-      } catch {
-        // Best effort cleanup
-      }
+      restorePyproject(pyprojectPath, hadExisting);
     }
   }
 
+  /**
+   * Copy an existing pyproject.toml aside so `run` can put it back.
+   * @returns whether a file was there to back up.
+   */
+  private backupPyproject(pyprojectPath: string): boolean {
+    if (!existsSync(pyprojectPath)) return false;
+    const backupPath = pyprojectBackupPath(pyprojectPath);
+    try {
+      writeFileSync(backupPath, readFileSync(pyprojectPath, 'utf-8'), { encoding: 'utf-8' });
+    } catch (err) {
+      // Failing here must be loud: without a backup, `restorePyproject` would
+      // silently leave this repo's pyproject.toml overwritten by a generated one.
+      throw new Error(
+        `Could not back up ${pyprojectPath} before writing a mutmut config: ${(err as Error).message}`,
+      );
+    }
+    return true;
+  }
+
   /**
    * Build the terminal-outcome handler for one `mutmut run`.
    *
@@ -173,39 +256,17 @@ export class MutmutRunner implements MutationRunner {
 
       const tracker = this.settleTracker(resolve, cancelTimers);
 
-      const timeoutId = setTimeout(() => {
-        tracker.markTimedOut();
-        child.kill('SIGTERM');
-        if (tracker.isSettled()) return;
-        // SIGTERM may be ignored; escalate once, and let the retry live in a
-        // variable so `cancelTimers` can reach it.
-        escalationId = setTimeout(() => {
-          if (!tracker.isSettled()) child.kill('SIGKILL');
-        }, 5000);
-      }, options.timeoutMs);
-
-      child.stdout?.on('data', (data: Buffer) => {
-        stdout += data.toString();
+      const timeoutId = armTimeout(child, options.timeoutMs, tracker, (id) => {
+        escalationId = id;
       });
 
-      child.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString();
+      collectOutput(child, (chunk, isErr) => {
+        if (isErr) stderr += chunk;
+        else stdout += chunk;
       });
 
       child.on('close', (code) => {
-        // A null exit code means the process was killed ("timed out" when we did
-        // it, "unknown" otherwise); there is no report to parse either way.
-        if (code === null) {
-          tracker.settle({ report: null, timedOut: tracker.didTimeOut() });
-          return;
-        }
-
-        tracker.settle({
-          // Parse results from mutmut run stdout (v3.x emoji progress)
-          report: this.parseEmojiProgress(stdout),
-          timedOut: tracker.didTimeOut(),
-          error: code !== 0 ? stderr || stdout : undefined,
-        });
+        tracker.settle(this.outcomeFor(code, stdout, stderr, tracker));
       });
 
       child.on('error', (err) => {
@@ -214,6 +275,29 @@ export class MutmutRunner implements MutationRunner {
     });
   }
 
+  /**
+   * Turn one `mutmut run` exit into the outcome the caller expects.
+   *
+   * Extracted from `runMutmut`'s close handler to bring that method back under
+   * the length and nesting budgets. A null exit code means the process was
+   * killed -- "timed out" when we did it, "unknown" otherwise -- and there is no
+   * report to parse either way.
+   */
+  private outcomeFor(
+    code: number | null,
+    stdout: string,
+    stderr: string,
+    tracker: SettleTracker,
+  ): MutationRunOutcome {
+    if (code === null) return { report: null, timedOut: tracker.didTimeOut() };
+    return {
+      // Parse results from mutmut run stdout (v3.x emoji progress)
+      report: this.parseEmojiProgress(stdout),
+      timedOut: tracker.didTimeOut(),
+      error: code !== 0 ? stderr || stdout : undefined,
+    };
+  }
+
   private toWslPath(path: string): string | null {
     const match = path.match(/^([A-Za-z]):[\\/](.*)$/);
     if (!match) return null;
@@ -300,28 +384,39 @@ export class MutmutRunner implements MutationRunner {
   }
 
   private writeMutmutConfig(pyprojectPath: string, sourceDirs: string[]): void {
-    const sourcePaths = sourceDirs.map((d) => `"${d}"`).join(', ');
-    const sourcePathsLine = `source_paths = [${sourcePaths}]`;
-
-    let content = '';
-    if (existsSync(pyprojectPath)) {
-      content = readFileSync(pyprojectPath, 'utf-8');
-      if (content.includes('[tool.mutmut]')) {
-        const sourcePathsRegex = /source_paths\s*=\s*\[.*?\]/;
-        if (sourcePathsRegex.test(content)) {
-          content = content.replace(sourcePathsRegex, sourcePathsLine);
-        } else {
-          content = content.replace(
-            '[tool.mutmut]',
-            `[tool.mutmut]\n${sourcePathsLine}`,
-          );
-        }
-      } else {
-        content = content.trimEnd() + `\n\n[tool.mutmut]\n${sourcePathsLine}\n`;
-      }
-    } else {
-      content = `[tool.mutmut]\n${sourcePathsLine}\n`;
+    const sourcePathsLine = `source_paths = [${sourceDirs.map((d) => `"${d}"`).join(', ')}]`;
+    try {
+      // Read here so the content builder stays pure: it then has no I/O to
+      // fail on, and the one place that can fail is the one that explains why.
+      const existing = existsSync(pyprojectPath) ? readFileSync(pyprojectPath, 'utf-8') : null;
+      writeFileSync(pyprojectPath, mutmutConfigContent(existing, sourcePathsLine), {
+        encoding: 'utf-8',
+      });
+    } catch (err) {
+      // A missing or half-written pyproject.toml would make mutmut scan the wrong
+      // tree, so surface the path instead of letting a bare fs error escape.
+      throw new Error(`Could not write mutmut config to ${pyprojectPath}: ${(err as Error).message}`);
     }
-    writeFileSync(pyprojectPath, content, { encoding: 'utf-8' });
   }
 }
+
+/**
+ * pyproject.toml content with `[tool.mutmut] source_paths` set as requested.
+ *
+ * Pure by design: the caller reads the existing file and passes it in, so this
+ * function has no I/O that could fail partway through. Three shapes have to be
+ * preserved -- an existing `source_paths` is rewritten in place, a bare
+ * `[tool.mutmut]` table gets the key added, and a file without the table gets
+ * one appended (a fresh file passes `null`).
+ *
+ * @param existing current file content, or null when the file does not exist.
+ */
+function mutmutConfigContent(existing: string | null, sourcePathsLine: string): string {
+  if (existing === null) return `[tool.mutmut]\n${sourcePathsLine}\n`;
+  if (!existing.includes('[tool.mutmut]')) {
+    return existing.trimEnd() + `\n\n[tool.mutmut]\n${sourcePathsLine}\n`;
+  }
+  const sourcePathsRegex = /source_paths\s*=\s*\[.*?\]/;
+  if (sourcePathsRegex.test(existing)) return existing.replace(sourcePathsRegex, sourcePathsLine);
+  return existing.replace('[tool.mutmut]', `[tool.mutmut]\n${sourcePathsLine}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.35.16",
+  "version": "0.35.18",
   "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.35.16",
+  "version": "0.35.18",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 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-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

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

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.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/sprint-flow/__tests__/verify-sprint-state.test.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+# @test REQ-688
+# @intent 验证 sprint-flow 的校验脚本能接受 `xp-gate sprint-init` 自己写出的状态文件
+#         ——脚本曾要求 sprint_id/current_phase/phases 这套从未被写入过的键，
+#         对 CLI 刚创建的 sprint 恒判失败（#679）
+# @covers AC-688-01, AC-688-02
+#
+# 为什么用真 sprint-init 而不是手写一个 fixture：缺陷的本质是「校验方与生产方对
+# schema 的认知不一致」。手写 fixture 会把「我认为 CLI 写什么」固化下来，双方一起
+# 错就一起绿。只有让生产方真的产出、校验方真的读，才能发现这类偏差。
+
+setup() {
+  REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../.." && pwd)"
+  VERIFY="$REPO_ROOT/skills/sprint-flow/scripts/verify-sprint-state.sh"
+  CLI="$REPO_ROOT/src/npm-package/bin/xp-gate.js"
+  WORK="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$WORK"
+}
+
+@test "AC-688-01: accepts state written by xp-gate sprint-init" {
+  cd "$WORK"
+  git init -q .
+  echo '{}' > package.json
+  git add -A
+  git -c user.email=t@t -c user.name=t commit -q -m init
+
+  run node "$CLI" sprint-init "probe task"
+  [ -f ".sprint-state/sprint-state.json" ]
+
+  run bash "$VERIFY"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"OK:"* ]]
+}
+
+@test "AC-688-02: still rejects a state file missing real keys" {
+  # The fix must not become "accept anything": a file that lost its task or its
+  # phase is genuinely broken and the verifier should say so.
+  mkdir -p "$WORK/.sprint-state"
+  printf '{"id":"s-1","phase":"BUILD"}\n' > "$WORK/.sprint-state/sprint-state.json"
+
+  cd "$WORK"
+  run bash "$VERIFY"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"task_description"* ]]
+}

package/plugins/claude-code/skills/sprint-flow/references/definition-of-done.md

@@ -0,0 +1,47 @@
+# Definition of Done（统一完成定义）
+
+一个 REQ 只有在**全部 10 项**都可指向证据时才算完成。这份清单是 #607 的落地，
+对应指南 §12；它存在的理由是本仓库历史上反复出现「以为完成了，其实没有」：
+
+- **#561** 覆盖率阈值形状写错（`Path` 而非 `Partial<Record>`），声明 80% 但整个门禁是空转
+- **#570** 覆盖率检查 fail-open，跑不起来时报告通过
+- **#585** Gate 5c 静默通过
+- **.xp-gate/modules 陈旧副本**（2026-10-19）劫持 Gate 6 数周，hook 报的警告数和独立扫描永远对不上
+
+共同点全部是：**某一步从未真正执行，而没有任何东西把这件事说出来。**
+所以这份清单里每一项的判据都是「证据在哪儿」，不是「做没做」。
+
+---
+
+## 10 项完成定义
+
+| # | 条目 | 判据（必须能指出位置） |
+|---|------|------------------------|
+| 1 | **需求可追溯** | `specification.yaml` 有 REQ + AC；测试文件带 `@covers AC-xxx`；`scripts/__tests__/ac-reference-guard.test.cjs` 通过 |
+| 2 | **测试先行** | 实现前存在失败的测试；或说明为何不适用（纯文档/配置） |
+| 3 | **测试真的能失败** | 至少一个变异体/破坏被测试抓住。「测试通过」在从未运行时和「功能正确」无法区分 |
+| 4 | **验证命令已运行** | 记录实际命令与输出，不是「应该是绿的」。CI 命令与本地命令一致 |
+| 5 | **门禁未降级** | 无 `--no-verify`；无新增基线额度来吸收本次改动自身的告警 |
+| 6 | **镜像已同步** | 改了 `githooks/`/`skills/`/`plugins/` → `bash scripts/check-hook-mirror.sh` 输出 PASS |
+| 7 | **不做未经要求的相邻改动** | 每行改动可追溯到本 REQ；顺手发现的无关死代码只提及不删除 |
+| 8 | **已知限制已写明** | 没做的部分、以及为什么没做，写进 issue/提交，而不是留空 |
+| 9 | **文档与实现一致** | 门禁数量、CLI 表、阈值等出现在多处的事实同步更新（见 `AGENTS.md` "Known Drift"） |
+| 10 | **可回滚** | 提交粒度单一；出问题时能单独 revert 而不牵连其他改动 |
+
+---
+
+## 相位落点
+
+- **Phase 4 VERIFY**：逐项过 1/2/3/4/5/6，任何一项拿不出证据 → 不得进入 SHIP。
+- **Phase 5 SHIP**：逐项过 7/8/9/10，然后才推送。
+- **Phase 6 CLOSE**：把第 8 项「已知限制」回填到 issue 并关闭。
+
+## 常见误判
+
+| 看起来完成了 | 实际没有 |
+|---|---|
+| 「测试通过」 | 没跑过会失败的版本，不知道它能不能失败 |
+| 「门禁有配置」 | 配置形状错/键名不对时被静默丢弃，等于没有（#561） |
+| 「工具缺失时跳过」 | 跳过被当成通过；只有 Gate 8 是 fail-closed |
+| 「CI 绿了」 | CI 可能没跑到那一步（`if:` 条件不满足），或跑的是旧副本（#451） |
+| 「注释写了这么做」 | 注释与代码漂移；只有测试能固定行为 |

package/plugins/claude-code/skills/sprint-flow/references/phase-4-verify.md

@@ -142,6 +142,22 @@ ELSE:
 - Web 前端附加: ui-review report + OPTIONAL QA/design-review/benchmark reports
 - 验证通过的 MVP
 
+### 完成定义（DoD 第 1–6 项）
+
+离开 VERIFY 前逐项过一遍 [`definition-of-done.md`](./definition-of-done.md)。**任何一项拿不出证据 → 不得进入 SHIP。**
+
+| # | 条目 | 在 VERIFY 的检查方式 |
+|---|------|----------------------|
+| 1 | 需求可追溯 | `npx vitest run scripts/__tests__/ac-reference-guard.test.cjs` 通过（测试引用的 AC 都在 spec 里） |
+| 2 | 测试先行 | 有 RED 证据（提交历史或记录），或说明为何不适用 |
+| 3 | **测试真的能失败** | 至少证明过一个变异体会被抓住——「测试通过」在从未运行时与「功能正确」无法区分 |
+| 4 | 验证命令已运行 | 记录实际命令 + 输出，不是「应该是绿的」 |
+| 5 | 门禁未降级 | 无 `--no-verify`；无为了本次改动新增的基线额度 |
+| 6 | 镜像已同步 | `bash scripts/check-hook-mirror.sh` → PASS |
+
+第 5 项值得单独说明：**加基线额度来吸收自己刚产生的告警，等于把门禁关掉一次。**
+`.warnings-baseline.json` 只应记录「改动之前就存在」的告警。
+
 ---
 
 ## Part B: FEEDBACK CAPTURE（反馈获取）

package/plugins/claude-code/skills/sprint-flow/references/phase-5-ship.md

@@ -99,6 +99,20 @@ Sprint 分支已准备就绪。请选择操作：
 
 ### Step 2: 原生 Ship 步骤序列（选择 Option 2 时执行）
 
+#### Step 2.0: 完成定义后半段（DoD 第 7–10 项，MANDATORY）
+
+推送前逐项过 [`definition-of-done.md`](./definition-of-done.md)：
+
+| # | 条目 | 在这里怎么查 |
+|---|------|--------------|
+| 7 | 不做未经要求的相邻改动 | `git diff` 逐行对照 REQ；顺手发现的无关问题只提及，不删改 |
+| 8 | **已知限制已写明** | 没做的部分与原因写进提交说明或 issue，而不是留空 |
+| 9 | 文档与实现一致 | 门禁数量/CLI 表/阈值等出现在多处的事实同步更新（`AGENTS.md` "Known Drift"） |
+| 10 | 可回滚 | 提交粒度单一，能单独 revert 而不牵连其他改动 |
+
+第 8 项最容易被跳过，也最容易造成误导：**一个没写下来的限制，下一个人会按"已完成"来依赖它。**
+
+
 ```
 1. 运行测试:
    npm test  # 或项目特定测试命令

package/plugins/claude-code/skills/sprint-flow/scripts/verify-sprint-state.sh

@@ -3,6 +3,12 @@
 # Checks that sprint-state.json is valid JSON and all expected keys exist.
 #
 # Usage: bash verify-sprint-state.sh [sprint-state-dir]
+#
+# The expected keys are the ones `xp-gate sprint-init` actually writes (#679).
+# They were previously ['sprint_id','status','current_phase','phases'] -- a schema
+# this project has never written, so the check failed on every sprint the CLI
+# itself had just created. A verifier that rejects its own producer's output is
+# worse than no verifier: it trains people to ignore it.
 
 set -euo pipefail
 
@@ -24,12 +30,19 @@ node -e "
 const fs = require('fs');
 try {
     const data = JSON.parse(fs.readFileSync('$STATE_FILE', 'utf8'));
-    const requiredKeys = ['sprint_id', 'status', 'current_phase', 'phases'];
+    // These are the keys src/npm-package/lib/sprint-init.js writes.
+    const requiredKeys = ['id', 'task_description', 'phase', 'status'];
     const missing = requiredKeys.filter(k => !(k in data));
     if (missing.length > 0) {
         console.error('ERROR: Missing required keys in sprint-state.json:', missing.join(', '));
         process.exit(1);
     }
+    // phase_history is an array by construction; a non-array here means the file
+    // was hand-edited or written by a different tool, which is worth failing on.
+    if (!Array.isArray(data.phase_history)) {
+        console.error('ERROR: phase_history must be an array in sprint-state.json');
+        process.exit(1);
+    }
     console.log('OK: sprint-state.json is valid with all required keys');
 } catch (e) {
     console.error('ERROR: sprint-state.json is not valid JSON:', e.message);

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.35.16",
+  "version": "0.35.18",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/dsh/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.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/dsh/skills/sprint-flow/__tests__/verify-sprint-state.test.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+# @test REQ-688
+# @intent 验证 sprint-flow 的校验脚本能接受 `xp-gate sprint-init` 自己写出的状态文件
+#         ——脚本曾要求 sprint_id/current_phase/phases 这套从未被写入过的键，
+#         对 CLI 刚创建的 sprint 恒判失败（#679）
+# @covers AC-688-01, AC-688-02
+#
+# 为什么用真 sprint-init 而不是手写一个 fixture：缺陷的本质是「校验方与生产方对
+# schema 的认知不一致」。手写 fixture 会把「我认为 CLI 写什么」固化下来，双方一起
+# 错就一起绿。只有让生产方真的产出、校验方真的读，才能发现这类偏差。
+
+setup() {
+  REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../.." && pwd)"
+  VERIFY="$REPO_ROOT/skills/sprint-flow/scripts/verify-sprint-state.sh"
+  CLI="$REPO_ROOT/src/npm-package/bin/xp-gate.js"
+  WORK="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$WORK"
+}
+
+@test "AC-688-01: accepts state written by xp-gate sprint-init" {
+  cd "$WORK"
+  git init -q .
+  echo '{}' > package.json
+  git add -A
+  git -c user.email=t@t -c user.name=t commit -q -m init
+
+  run node "$CLI" sprint-init "probe task"
+  [ -f ".sprint-state/sprint-state.json" ]
+
+  run bash "$VERIFY"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"OK:"* ]]
+}
+
+@test "AC-688-02: still rejects a state file missing real keys" {
+  # The fix must not become "accept anything": a file that lost its task or its
+  # phase is genuinely broken and the verifier should say so.
+  mkdir -p "$WORK/.sprint-state"
+  printf '{"id":"s-1","phase":"BUILD"}\n' > "$WORK/.sprint-state/sprint-state.json"
+
+  cd "$WORK"
+  run bash "$VERIFY"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"task_description"* ]]
+}

package/plugins/dsh/skills/sprint-flow/references/definition-of-done.md

@@ -0,0 +1,47 @@
+# Definition of Done（统一完成定义）
+
+一个 REQ 只有在**全部 10 项**都可指向证据时才算完成。这份清单是 #607 的落地，
+对应指南 §12；它存在的理由是本仓库历史上反复出现「以为完成了，其实没有」：
+
+- **#561** 覆盖率阈值形状写错（`Path` 而非 `Partial<Record>`），声明 80% 但整个门禁是空转
+- **#570** 覆盖率检查 fail-open，跑不起来时报告通过
+- **#585** Gate 5c 静默通过
+- **.xp-gate/modules 陈旧副本**（2026-10-19）劫持 Gate 6 数周，hook 报的警告数和独立扫描永远对不上
+
+共同点全部是：**某一步从未真正执行，而没有任何东西把这件事说出来。**
+所以这份清单里每一项的判据都是「证据在哪儿」，不是「做没做」。
+
+---
+
+## 10 项完成定义
+
+| # | 条目 | 判据（必须能指出位置） |
+|---|------|------------------------|
+| 1 | **需求可追溯** | `specification.yaml` 有 REQ + AC；测试文件带 `@covers AC-xxx`；`scripts/__tests__/ac-reference-guard.test.cjs` 通过 |
+| 2 | **测试先行** | 实现前存在失败的测试；或说明为何不适用（纯文档/配置） |
+| 3 | **测试真的能失败** | 至少一个变异体/破坏被测试抓住。「测试通过」在从未运行时和「功能正确」无法区分 |
+| 4 | **验证命令已运行** | 记录实际命令与输出，不是「应该是绿的」。CI 命令与本地命令一致 |
+| 5 | **门禁未降级** | 无 `--no-verify`；无新增基线额度来吸收本次改动自身的告警 |
+| 6 | **镜像已同步** | 改了 `githooks/`/`skills/`/`plugins/` → `bash scripts/check-hook-mirror.sh` 输出 PASS |
+| 7 | **不做未经要求的相邻改动** | 每行改动可追溯到本 REQ；顺手发现的无关死代码只提及不删除 |
+| 8 | **已知限制已写明** | 没做的部分、以及为什么没做，写进 issue/提交，而不是留空 |
+| 9 | **文档与实现一致** | 门禁数量、CLI 表、阈值等出现在多处的事实同步更新（见 `AGENTS.md` "Known Drift"） |
+| 10 | **可回滚** | 提交粒度单一；出问题时能单独 revert 而不牵连其他改动 |
+
+---
+
+## 相位落点
+
+- **Phase 4 VERIFY**：逐项过 1/2/3/4/5/6，任何一项拿不出证据 → 不得进入 SHIP。
+- **Phase 5 SHIP**：逐项过 7/8/9/10，然后才推送。
+- **Phase 6 CLOSE**：把第 8 项「已知限制」回填到 issue 并关闭。
+
+## 常见误判
+
+| 看起来完成了 | 实际没有 |
+|---|---|
+| 「测试通过」 | 没跑过会失败的版本，不知道它能不能失败 |
+| 「门禁有配置」 | 配置形状错/键名不对时被静默丢弃，等于没有（#561） |
+| 「工具缺失时跳过」 | 跳过被当成通过；只有 Gate 8 是 fail-closed |
+| 「CI 绿了」 | CI 可能没跑到那一步（`if:` 条件不满足），或跑的是旧副本（#451） |
+| 「注释写了这么做」 | 注释与代码漂移；只有测试能固定行为 |