@boyingliu01/xp-gate 0.35.17 → 0.35.19

package/plugins/opencode/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/opencode/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/opencode/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/opencode/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/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-31
-**Commit:** 26a741de
+**Generated:** 2026-11-01
+**Commit:** effea31d
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.19.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.17",
+  "version": "0.35.19",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. 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/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-10-31
-**Commit:** 26a741de
+**Generated:** 2026-11-01
+**Commit:** effea31d
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.19.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/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
-**Generated:** 2026-10-31
-**Commit:** 26a741de
+**Generated:** 2026-11-01
+**Commit:** effea31d
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.19.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/qoder/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/qoder/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/qoder/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/qoder/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/qoder/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/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-10-31
-**Commit:** 26a741de
+**Generated:** 2026-11-01
+**Commit:** effea31d
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.19.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-10-31
-**Commit:** 26a741de
+**Generated:** 2026-11-01
+**Commit:** effea31d
 **Branch:** main
-**Version:** 0.35.17.0
+**Version:** 0.35.19.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/scripts/__tests__/sync-package-content.test.js

@@ -9,6 +9,16 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+// Budget for every subprocess this file spawns, and for the vitest test that
+// wraps it. It is deliberately far above the measured cost (the sync takes
+// ~1.4 s here) because Stryker's dry run starts four vitest workers at once
+// with perTest coverage: under that contention a 15 s budget made these tests
+// fail intermittently on CI while passing locally, and the failure surfaced as
+// "sync script must exit 0" -- which reads like a sync defect rather than a
+// starved machine. A sync that genuinely fails still fails fast; only a starved
+// one waits.
+const SYNC_BUDGET_MS = 120000;
+
 const { checkDocsDrift, checkAdapterDrift } = require('../sync-package-content');
 
 function createTempDir() {
@@ -19,12 +29,24 @@ function cleanupTempDir(dir) {
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
+// Fixture writers. These run in `beforeAll`; an uncaught write failure there
+// surfaces as "sync script must exit 0" or as a missing-file assertion, neither
+// of which names the file that could not be written. Wrapping the I/O once keeps
+// every fixture helper reporting what actually failed.
+function writeFixture(filePath, content) {
+  try {
+    fs.writeFileSync(filePath, content, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot write test fixture ${filePath}: ${err.message}`);
+  }
+}
+
 function writeScript(filePath, content) {
-  fs.writeFileSync(filePath, content, 'utf8');
+  writeFixture(filePath, content);
 }
 
 function writeDoc(filePath, content) {
-  fs.writeFileSync(filePath, content, 'utf8');
+  writeFixture(filePath, content);
 }
 
 /**
@@ -35,26 +57,58 @@ function writeDoc(filePath, content) {
  * list from rotting: syncModules() gains a module, this helper needs no edit.
  * Only reads from the real checkout -- nothing is ever written back to it.
  */
+/**
+ * Copy every `src/` module except the package itself.
+ *
+ * Does `name` under `srcRoot` need copying into the package's source seed?
+ *
+ * The package itself is the DESTINATION of the sync, not a canonical source;
+ * copying it would let the test compare a mirror against a stale mirror. Only
+ * directories are copied -- a stray file at that level is not a module.
+ *
+ * Answers false rather than throwing on an unreadable entry: an entry that cannot
+ * be stat'd is not a directory this helper can copy, and `seedSrcModules` reports
+ * the resulting gap against the path it was seeding. Swallowing this into a throw
+ * here would leave the caller unable to name which tree was incomplete.
+ */
+function isSeedableModule(srcRoot, name) {
+  if (name === 'npm-package') return false;
+  try {
+    return fs.statSync(path.join(srcRoot, name)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function seedSrcModules(srcRoot, dest) {
+  try {
+    for (const name of fs.readdirSync(srcRoot)) {
+      if (!isSeedableModule(srcRoot, name)) continue;
+      fs.cpSync(path.join(srcRoot, name), path.join(dest, 'src', name), { recursive: true });
+    }
+  } catch (err) {
+    throw new Error(`Cannot copy src modules from ${srcRoot} into ${dest}: ${err.message}`);
+  }
+}
+
 function seedCanonicalSources(realRoot, destRoot) {
   const real = realRoot || path.resolve(__dirname, '..', '..', '..', '..');
   const dest = destRoot;
-  for (const tree of ['githooks', 'skills', 'plugins']) {
-    const from = path.join(real, tree);
-    if (fs.existsSync(from)) fs.cpSync(from, path.join(dest, tree), { recursive: true });
-  }
-  const srcRoot = path.join(real, 'src');
-  for (const name of fs.readdirSync(srcRoot)) {
-    // The package itself is the DESTINATION of the sync, not a canonical source;
-    // copying it would let the test compare a mirror against a stale mirror.
-    if (name === 'npm-package') continue;
-    const from = path.join(srcRoot, name);
-    if (fs.statSync(from).isDirectory()) {
-      fs.cpSync(from, path.join(dest, 'src', name), { recursive: true });
+  try {
+    for (const tree of ['githooks', 'skills', 'plugins']) {
+      const from = path.join(real, tree);
+      if (fs.existsSync(from)) fs.cpSync(from, path.join(dest, tree), { recursive: true });
     }
-  }
-  fs.mkdirSync(path.join(dest, 'src', 'npm-package', 'scripts'), { recursive: true });
-  for (const rel of ['scripts/sync-package-content.js', 'package.json']) {
-    fs.copyFileSync(path.join(srcRoot, 'npm-package', rel), path.join(dest, 'src', 'npm-package', rel));
+    const srcRoot = path.join(real, 'src');
+    seedSrcModules(srcRoot, dest);
+    fs.mkdirSync(path.join(dest, 'src', 'npm-package', 'scripts'), { recursive: true });
+    for (const rel of ['scripts/sync-package-content.js', 'package.json']) {
+      fs.copyFileSync(path.join(srcRoot, 'npm-package', rel), path.join(dest, 'src', 'npm-package', rel));
+    }
+  } catch (err) {
+    // A half-seeded worktree makes the sync mirror a partial tree, which then
+    // reads as a sync defect. Name the seeding direction instead.
+    throw new Error(`Cannot seed canonical sources from ${real} into ${dest}: ${err.message}`);
   }
 }
 
@@ -329,17 +383,21 @@ describe('syncHooks', () => {
    */
   function seedTempWorktree() {
     seedCanonicalSources(REAL_REPO_ROOT, WORKTREE_PATH);
-    fs.mkdirSync(path.join(PKG_ROOT, 'scripts'), { recursive: true });
-    fs.copyFileSync(
-      path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'scripts', 'sync-package-content.js'),
-      syncScript,
-    );
-    // The script resolves its package root relative to its own location, so it
-    // must sit at <temp>/src/npm-package/scripts/ exactly as in the real tree.
-    fs.copyFileSync(
-      path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'package.json'),
-      path.join(PKG_ROOT, 'package.json'),
-    );
+    try {
+      fs.mkdirSync(path.join(PKG_ROOT, 'scripts'), { recursive: true });
+      fs.copyFileSync(
+        path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'scripts', 'sync-package-content.js'),
+        syncScript,
+      );
+      // The script resolves its package root relative to its own location, so it
+      // must sit at <temp>/src/npm-package/scripts/ exactly as in the real tree.
+      fs.copyFileSync(
+        path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'package.json'),
+        path.join(PKG_ROOT, 'package.json'),
+      );
+    } catch (err) {
+      throw new Error(`Cannot stage the sync script into ${PKG_ROOT}: ${err.message}`);
+    }
   }
 
   beforeAll(() => {
@@ -356,14 +414,20 @@ describe('syncHooks', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
     syncOk = result.status === 0;
     if (!syncOk) {
+      // Distinguish "ran and failed" from "never got to run": the latter is an
+      // infrastructure problem and reporting it as a plain non-zero exit hides
+      // that, exactly as it did while this was misdiagnosed as a sync defect.
+      if (result.signal) console.error('sync killed by signal:', result.signal);
+      if (result.error) console.error('sync spawn error:', result.error.message);
+      console.error('sync status:', result.status);
       console.error('sync stderr:', result.stderr?.toString() || '(empty)');
       console.error('sync stdout:', result.stdout?.toString() || '(empty)');
     }
-  }, 15000);
+  }, SYNC_BUDGET_MS);
 
   it('syncHooks copies pre-commit to hooks dir', () => {
     expect(syncOk, 'sync script must exit 0').toBe(true);
@@ -421,7 +485,7 @@ describe('syncHooks', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
 
     expect(result.status, 'sync script must exit 0').toBe(0);
@@ -439,7 +503,7 @@ describe('syncHooks', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
 
     expect(result.status).toBe(0, 'sync script must exit 0');
@@ -565,15 +629,19 @@ describe('sync-package-content subprocess invocation', () => {
 
   function seedTempWorktree() {
     seedCanonicalSources(REAL_REPO_ROOT, WORKTREE_PATH);
-    fs.mkdirSync(path.join(PKG_ROOT, 'scripts'), { recursive: true });
-    fs.copyFileSync(
-      path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'scripts', 'sync-package-content.js'),
-      path.join(PKG_ROOT, 'scripts', 'sync-package-content.js'),
-    );
-    fs.copyFileSync(
-      path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'package.json'),
-      path.join(PKG_ROOT, 'package.json'),
-    );
+    try {
+      fs.mkdirSync(path.join(PKG_ROOT, 'scripts'), { recursive: true });
+      fs.copyFileSync(
+        path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'scripts', 'sync-package-content.js'),
+        path.join(PKG_ROOT, 'scripts', 'sync-package-content.js'),
+      );
+      fs.copyFileSync(
+        path.join(REAL_REPO_ROOT, 'src', 'npm-package', 'package.json'),
+        path.join(PKG_ROOT, 'package.json'),
+      );
+    } catch (err) {
+      throw new Error(`Cannot stage the sync script into ${PKG_ROOT}: ${err.message}`);
+    }
   }
 
   beforeAll(() => {
@@ -615,7 +683,7 @@ describe('sync-package-content subprocess invocation', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
 
     if (result.status !== 0) {
@@ -650,7 +718,7 @@ describe('sync-package-content subprocess invocation', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
 
     if (result.status !== 0) {
@@ -678,7 +746,7 @@ describe('sync-package-content subprocess invocation', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
 
     if (result.status !== 0) {
@@ -710,7 +778,7 @@ describe('sync-package-content subprocess invocation', () => {
     const result = spawnSync(nodeExe, [syncScript], {
       cwd: WORKTREE_PATH,
       stdio: 'pipe',
-      timeout: 15000,
+      timeout: SYNC_BUDGET_MS,
     });
 
     if (result.status !== 0) {