kld-sdd 2.4.17 → 2.4.19

package/templates/hooks/claude/hooks/sdd-apply-test-gate.cjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * SDD Apply Test Gate Hook
+ *
+ * 当 proposal 选择单元测试策略（test-strategy: tdd | impl-first）时，
+ * 在 apply 收尾前校验是否已有真实测试执行证据；缺失则阻断并提示模型执行测试。
+ *
+ * 触发点：
+ *   - PreToolUse(Bash): apply-worktree-finish（非 --record-base）、log.cjs end（apply 阶段）
+ *   - Stop: 存在活跃 apply 阶段且即将结束会话
+ *
+ * 退出码：0 放行 | 2 阻断（stdout JSON decision:block）
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function hasTelemetryCli(dir) {
+  return fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.cjs')) ||
+    fs.existsSync(path.join(dir, 'skywalk-sdd', 'log.js'));
+}
+
+function findProjectRoot(startDir) {
+  if (!startDir) return '';
+  let current = path.resolve(startDir);
+  for (let i = 0; i < 25; i++) {
+    if (hasTelemetryCli(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return '';
+    current = parent;
+  }
+  return '';
+}
+
+function getProjectRoot(input) {
+  const toolInput = input.tool_input || input.toolInput || {};
+  const candidates = [
+    toolInput.cwd,
+    input.cwd,
+    input.project_root,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.PWD,
+    process.cwd(),
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    const root = findProjectRoot(dir);
+    if (root) return root;
+  }
+  return process.cwd();
+}
+
+function safeChangeName(name) {
+  if (!name) return '';
+  return String(name)
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9一-鿿\-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function findActiveApplyStage(projectRoot) {
+  const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return null;
+
+  let latest = null;
+  for (const file of fs.readdirSync(stateDir).filter((f) => f.endsWith('.json'))) {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(stateDir, file), 'utf8'));
+      const event = data.event || null;
+      if (event && event.command === 'apply') {
+        if (!latest || new Date(event.timestamp) > new Date(latest.timestamp)) {
+          latest = event;
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+  return latest;
+}
+
+function findProposalPath(projectRoot, changeName) {
+  const candidates = [
+    path.join(projectRoot, 'openspec', 'changes', changeName, 'proposal.md'),
+    path.join(projectRoot, 'changes', changeName, 'proposal.md'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  const safe = safeChangeName(changeName);
+  if (safe && safe !== changeName) {
+    return findProposalPath(projectRoot, safe);
+  }
+  return null;
+}
+
+function readTestStrategy(projectRoot, changeName) {
+  const proposalPath = findProposalPath(projectRoot, changeName);
+  if (!proposalPath) return null;
+  try {
+    const content = fs.readFileSync(proposalPath, 'utf8');
+    const fm = content.match(/^---\s*[\r\n]+([\s\S]*?)[\r\n]+---/);
+    if (!fm) return null;
+    const m = fm[1].match(/^\s*test-strategy:\s*["']?([a-z-]+)["']?\s*$/im);
+    return m ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function requiresUnitTests(strategy) {
+  return strategy === 'tdd' || strategy === 'impl-first';
+}
+
+function isRealTestDetails(testResults) {
+  if (!testResults || typeof testResults !== 'object') return false;
+  const command = String(testResults.command || '').trim();
+  if (!command) return false;
+  const passed = Number(testResults.passed);
+  const failed = Number(testResults.failed);
+  const duration = Number(testResults.duration_ms);
+  if (Number.isFinite(passed) && passed > 0) return true;
+  if (Number.isFinite(failed) && failed > 0) return true;
+  if (Number.isFinite(duration) && duration > 0) return true;
+  return false;
+}
+
+function loadChangeEvents(projectRoot, changeName) {
+  const safe = safeChangeName(changeName);
+  const dir = path.join(projectRoot, 'skywalk-sdd', 'events', safe);
+  if (!fs.existsSync(dir)) return [];
+
+  const events = [];
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'))) {
+    try {
+      const lines = fs.readFileSync(path.join(dir, file), 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try {
+          events.push(JSON.parse(line));
+        } catch {
+          // skip
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+  return events;
+}
+
+function hasRealTestExecution(projectRoot, changeName, capability, sinceTimestamp) {
+  const since = sinceTimestamp ? new Date(sinceTimestamp).getTime() : 0;
+  const events = loadChangeEvents(projectRoot, changeName);
+
+  for (const event of events) {
+    const ts = new Date(event.timestamp || 0).getTime();
+    if (since && ts < since) continue;
+
+    if (event.type === 'stage_end' && event.command === 'test' &&
+        (event.result === 'success' || event.result === 'failure')) {
+      return { kind: 'opsx-test', event };
+    }
+
+    if (event.type === 'test_result') {
+      const tr = event.details && event.details.test_results;
+      if (isRealTestDetails(tr)) {
+        return { kind: 'test_result', event };
+      }
+    }
+
+    if (event.type === 'task_update' && (event.command === 'apply' || !event.command)) {
+      const tr = event.details && event.details.test_results;
+      if (isRealTestDetails(tr)) {
+        if (!capability || !event.capability || event.capability === capability) {
+          return { kind: 'task_update', event };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function isApplyCompletionBash(command) {
+  const cmd = String(command || '');
+  if (/apply-worktree-finish\.cjs/.test(cmd) && !/--record-base/.test(cmd)) {
+    return true;
+  }
+  if (/(?:skywalk-sdd\/)?log\.cjs\s+end\b/.test(cmd)) {
+    return true;
+  }
+  return false;
+}
+
+function block(decision, reason, extra) {
+  console.log(JSON.stringify({ decision, reason, ...extra }));
+  process.exit(2);
+}
+
+function recordWarning(projectRoot, applyEvent, code, message) {
+  const logPath = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+  if (!fs.existsSync(logPath)) return;
+  try {
+    const args = [
+      logPath,
+      'record',
+      '--type=telemetry_warning',
+      '--command=apply',
+      `--project=${projectRoot}`,
+      `--change=${applyEvent.change || 'general'}`,
+      '--agent=claude-code',
+      '--source=claude-hook',
+      '--result=partial',
+      `--summary=${message}`,
+      `--details-json=${JSON.stringify({ warning: code, test_strategy: applyEvent.test_strategy })}`,
+    ];
+    if (applyEvent.capability) args.push(`--capability=${applyEvent.capability}`);
+    if (applyEvent.session_id) args.push(`--session-id=${applyEvent.session_id}`);
+    execFileSync('node', args, { cwd: projectRoot, stdio: 'ignore' });
+  } catch {
+    // ignore
+  }
+}
+
+function buildReason(strategy, changeName, capability) {
+  const cap = capability ? ` / ${capability}` : '';
+  const strict = strategy === 'tdd';
+  const lines = [
+    `[SDD Apply Test Gate] 变更 ${changeName}${cap} 的 test-strategy=${strategy}，但尚未检测到真实单元测试执行记录。`,
+    '',
+    '请先在本项目根目录（或 apply worktree）执行单元测试，例如：',
+    '  npm test / pnpm test / pytest / go test ./... / cargo test',
+    '',
+    '执行后应产生以下任一 telemetry 证据：',
+    '  - skywalk-sdd 事件 test_result（含实际 command 与 passed/failed/duration）',
+    '  - task_update 中 test_results 非空占位',
+    '  - 或运行 /opsx-test 完成 test 阶段',
+    '',
+    strict
+      ? 'tdd 策略：测试未执行前不得结束 apply 或执行 apply-worktree-finish。'
+      : 'impl-first 策略：实现后须补跑测试并确认通过，再结束 apply。',
+    '',
+    '完成后可重试当前操作。',
+  ];
+  return lines.join('\n');
+}
+
+function shouldGate(projectRoot, applyEvent) {
+  const strategy = readTestStrategy(projectRoot, applyEvent.change);
+  if (!requiresUnitTests(strategy)) {
+    return null;
+  }
+  const evidence = hasRealTestExecution(
+    projectRoot,
+    applyEvent.change,
+    applyEvent.capability,
+    applyEvent.timestamp
+  );
+  if (evidence) {
+    return null;
+  }
+  return { strategy, changeName: applyEvent.change, capability: applyEvent.capability };
+}
+
+// ── 主逻辑 ─────────────────────────────────────────────
+
+const input = parseInput(readStdin());
+const projectRoot = getProjectRoot(input);
+const toolName = String(input.tool_name || input.toolName || '');
+const toolInput = input.tool_input || input.toolInput || {};
+const command = String(toolInput.command || '');
+
+const activeApply = findActiveApplyStage(projectRoot);
+if (!activeApply) {
+  process.exit(0);
+}
+
+const bashGate = toolName === 'Bash' && isApplyCompletionBash(command);
+const stopGate = !toolName || toolName === 'Stop';
+
+if (!bashGate && !stopGate) {
+  process.exit(0);
+}
+
+const gate = shouldGate(projectRoot, activeApply);
+if (!gate) {
+  process.exit(0);
+}
+
+const reason = buildReason(gate.strategy, gate.changeName, gate.capability);
+recordWarning(projectRoot, { ...activeApply, test_strategy: gate.strategy }, 'apply_test_missing', 'Apply test gate blocked: no unit test evidence');
+
+block('block', reason, {
+  test_strategy: gate.strategy,
+  change: gate.changeName,
+  capability: gate.capability,
+});

package/templates/hooks/claude/hooks/sdd-skill-apply-gate.cjs

@@ -3,10 +3,11 @@
  *
  * PreToolUse(Skill) 门禁 —— 在 opsx-apply Skill 被调用的瞬间阻断，不再等到 Write/Edit 阶段。
  *
- * 三层门禁体系中的第一层：
- *   L1: sdd-skill-apply-gate  (PreToolUse/Skill) ← 本文件
+ * 门禁体系：
+ *   L1: sdd-skill-apply-gate  (PreToolUse/Skill) ← 本文件 — check 前置
  *   L2: sdd-apply-gate        (PreToolUse/Write|Edit)
  *   L3: SKILL.md Step 1.2     (Skill 自检)
+ *   L4: sdd-apply-test-gate   (PreToolUse/Bash + Stop) — apply 后单元测试真实执行
  *
  * 判定逻辑：
  *   - 非 opsx-apply 调用 → 放行

package/templates/hooks/claude/settings.json

@@ -26,6 +26,10 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-pre-tool.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-apply-test-gate.cjs\""
           }
         ]
       },
@@ -53,6 +57,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-apply-test-gate.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/sdd-stop.cjs\""

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -146,25 +146,170 @@ openspec list --json
    >
    > 是否要现在执行 check？"
 
-> **🔗 双重保障**：此技能自检与 `sdd-apply-gate.cjs` Hook 形成双重门禁。即使 Hook 因环境问题未触发，技能自检仍会拦截未 check 的 apply。
+> **🔗 门禁体系**：
+> - Check：`sdd-skill-apply-gate` + `sdd-apply-gate` + 本技能 §1.2
+> - 单元测试（`test-strategy: tdd | impl-first`）：`sdd-apply-test-gate` 在 `log.cjs end` / `apply-worktree-finish` / Stop 时校验是否**真实执行**过测试
 
-### 1.5 【隔离工作区】设置 Git Worktree
+### 1.5 【本地并行】Worktree 与工作区（建议性策略）
 
-> **🤖 使用 Git Worktree 创建隔离工作区，保护主分支不受变更影响。**
-> 与子代理并行派发配合使用——同一 Worktree 中多个子代理并行工作，零冲突。
+> **目标（本质）**：在**本地仓库**加快 SDD Apply——让**解耦**的 spec/capability 可以各自实现、互不踩目录，做完再按依赖顺序合并回你**当时所在的分支**（集成分支，如 `hotfix-1`）。
+>
+> **不是**：保护 `master`、不是「主分支只放文档」、不是远程流水线分支策略。一切基于**本地 Git + 本地 worktree**。
+
+#### 两层并行（不要混为一谈）
+
+| 层级 | 手段 | 适用 |
+|------|------|------|
+| **Capability 级**（跨 spec） | 每个解耦的 capability **单独**跑一次 `/opsx-apply` + **独立** worktree/apply 分支 | proposal 中能力**可并行**、无文件/接口/数据强依赖 |
+| **Task 级**（cap 内） | **同一** worktree 内，DAG 同层子代理并行 | tasks.md 同层任务不改相同文件 |
+
+- 本技能单次仍只实施**一个** capability；「多 spec 并行」= 多个 apply 会话 + 多个 worktree，不是一次加载多个 capability 文档。
+- §5 子代理并行 **不** 再建 worktree；Capability 级并行在 §1.5 决定「本次是否建 worktree」。
+
+#### 何时建议建 worktree / 按 capability 切分支？（模型判断，非强制）
+
+**倾向创建**（full 模式常见：`.worktrees/apply-<change>-<capability>` + `kld-sdd/<change>/<capability>`）：
+
+- `proposal.md` §3 中该 capability 与并行中的其他能力**无**「修改同一模块 / 共享表 / 必须先合入」等描述
+- `design.md` 显示文件路径、包、表与并行中的其他 cap **基本不重叠**
+- 用户需要在**同一集成分支**上并行推进多个 cap，且机器资源允许（多份 `node_modules`）
+
+**倾向不建 / 串行 apply**（仍在集成分支上改，或只开一个 worktree）：
+
+- proposal 写明 capability **依赖**（B 依赖 A 已合入）
+- 多 cap 改**同一文件/模块/配置**（merge 冲突几乎必然）
+- 数据库迁移、公共类型、单例注册等**顺序敏感**
+- 已有另一个 capability 的 worktree **尚未 finish merge** 到集成分支，且当前 cap 需要基于**最新**集成结果开发
+- 沙箱禁止 `git worktree add` → 回退当前目录 + 功能分支，并告知用户
+
+**full 模式「一 capability 一分支」**：是**命名与目录约定 + 建议**，须先通过下方 **§1.5 Step 0.1 校验** 再命名/建 worktree。simple 模式通常**一 change 一 worktree**。
+
+#### Step 0.1 【必做】分支/隔离校验（早于 record-base 与 `git worktree add`）
+
+> 在建议分支名 `kld-sdd/<change>/<capability>` 或创建 worktree **之前**，用 `proposal.md` + 各 capability **spec 依赖信息** 做交叉校验。未通过则**不**按 full 并行策略拆分支，改为串行或本次不建 worktree。
+
+**Step A — 读变更级能力清单（允许读 proposal，不读其它 cap 的 design/tasks）**
+
+从 `changes/<change-name>/proposal.md` 提取：
+
+| 字段 | 用途 |
+|------|------|
+| frontmatter `mode` | `full` → 倾向 `apply-<change>-<cap>`；`simple` → 倾向 `apply-<change>` |
+| §3.1 / §3.2 能力列表 | 本 change 下全部 capability 名 |
+| §4.2 依赖关系图 | 能力间先后 / 上下游 |
+| §5.3 前置依赖 checkbox | 未满足则当前 cap 不宜并行 |
+
+**Step B — 读当前 capability 的 spec 依赖（§2 正式加载前仅此文件）**
+
+读取**当前** capability 的 `spec.md`（路径按 mode）：
+
+- **full**：`changes/<change>/specs/<capability>/spec.md` 或 `openspec/changes/.../specs/<capability>/spec.md`（以项目实际为准）
+- **simple**：`changes/<change>/spec.md`
+
+只重点读 spec 中：**能力边界 / 涉及模块 / §4 内部与外部依赖**（是否写明依赖其它 capability、共享表、必须先发布的接口）。
+
+**Step C — 跨 capability 轻量交叉（隔离例外，仅本节）**
+
+对 §3 中**其它** capability，**只**读取其 `spec.md` 的：
+
+- 标题与能力简述
+- **§4 依赖**（是否依赖 `<当前 capability>` 或其它 cap）
+- **涉及模块 / 数据表 / 公共配置**（若有）
+
+⛔ 禁止为校验而加载其它 cap 的 `design.md`、`tasks.md`（完整实施上下文仍遵守 §2 隔离红线）。
+
+**Step D — 判定矩阵（输出给用户）**
+
+| 校验项 | 不通过时的处理 |
+|--------|----------------|
+| proposal §4.2 / §5.3 写明当前 cap **依赖** 未完成的其它 cap | **串行**：先 finish 上游，再 apply 当前；不并行拆分支 |
+| 其它 cap 的 spec 写明 **依赖当前 cap** 且当前 cap 未 finish | 当前可并行实施，但提醒下游须等本次 finish |
+| 多 cap spec 出现**相同模块路径 / 同表 / 同配置文件** | **不并行** worktree；串行或合并为一个 apply 范围 |
+| 当前 cap spec §4 要求接口/表已由其它 cap 提供 | 若其它 cap 未 merge 到集成分支 → **不建** worktree，先完成上游 |
+| `git branch --list 'kld-sdd/<change>/*'` 已存在同名分支 | 复用既有 worktree/分支，或询问用户是否清理后重建 |
+| 沙箱 / 环境无法 `worktree add` | 不建 worktree；集成分支上直接开发 |
+
+**Step E — 分支与目录命名（校验通过后）**
+
+| mode | worktree 目录（建议） | apply 分支（建议） |
+|------|----------------------|-------------------|
+| full + 可隔离 | `.worktrees/apply-<change>-<capability>` | `kld-sdd/<change>/<capability>` |
+| simple 或 change 内单实现体 | `.worktrees/apply-<change>` | `kld-sdd/<change>/<capability>`（cap 可与 change 同名） |
+| 校验不通过但仍需隔离 | `.worktrees/apply-<change>-<capability>` 或单 worktree | 仍用 `kld-sdd/<change>/<capability>`，但**不得**与其它 cap 并行 |
+
+**报告模板**（创建 worktree 前必须输出）：
+
+```
+📋 Apply 隔离校验 — <change>/<capability>
+- mode: full | simple
+- 本 change 能力域: [cap-a, cap-b, …]
+- 与当前 cap 冲突/依赖: [无 | cap-a 必须先合入 | 与 cap-b 共享模块 X]
+- 并行建议: [可独立 worktree | 串行等待 cap-a | 不建 worktree，原地 apply]
+- 分支（建议）: kld-sdd/<change>/<capability>
+- 集成分支（将 record-base）: <当前 git 分支>
+```
+
+#### 多 Capability 并行时的合并顺序（本地）
+
+1. 各 capability 在各自 worktree 内完成 + `§6.1 finish` 前，先根据 `proposal.md` 排出 **capability 依赖 DAG**。
+2. **按 DAG 顺序**依次 `finish` merge 到**同一** `integration_base`（先 A 合入，再 B；B 的 worktree 若基于旧尖端，merge 前应在 B 的 worktree 内 `merge/rebase integration_base` 或由用户选择重建 worktree）。
+3. 有依赖的 cap **不要**与上游 cap 同时 finish；无依赖的可并行实施，但 **merge 仍建议逐个** 以降低冲突。
+
+向用户简要说明判断结果：
+> "📌 并行建议：cap-A、cap-C 可并行 worktree；cap-B 依赖 A，待 A finish 后再 apply。"
+
+#### 分支 / Worktree 创建时机（勿与子代理混淆）
+
+| 时机 | 做什么 | 谁执行 |
+|------|--------|--------|
+| **§1.5 Step 0.25～1（仅一次）** | 记录集成分支 → 创建 worktree + 新建 `kld-sdd/<change>/<capability>` | **主会话** |
+| §2～§4 | 读文档、解析 DAG | 主会话 |
+| **§5 子代理** | 在**已有** worktree 内实现任务 | **子代理**（不建 worktree、不建分支） |
+| **§6.1** | merge 回集成分支 → remove worktree → 删 apply 分支 | **主会话** + `apply-worktree-finish.cjs` |
+
+- 集成分支 = Apply **开始时**主仓库 `git branch --show-current`（例：用户在 `hotfix-1` 上开始，则 merge 回 `hotfix-1`）。
+- `git worktree add -b` 在主仓库处于集成分支时执行，apply 分支从该分支尖端分出。
+- **子代理禁止** `EnterWorktree` / `git worktree add` / `checkout -b`；同层并行共享**同一** worktree 与 apply 分支。
 
 **设置流程**（详见 `./worktree-setup.md`）：
 
 **Step 0: 检测当前状态**
-- 若已是 Git Worktree → 跳过创建
+- 若已是 Git Worktree → 跳过创建（集成分支应已在 state 文件中）
 - 若非 Git 项目（`vcs_mode=no-git`）→ 跳过
 
+**Step 0.1: 分支/隔离校验** — 见上文「Step 0.1 【必做】」，**通过后再执行** 0.25 / 0.5 / Step 1
+
+**Step 0.25: 记录集成分支（Git 项目必做，创建 worktree 之前）**
+
+在主仓库根目录、**尚未** `cd` 进 `.worktrees/` 时执行：
+
+```bash
+node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+  --change=<变更名称> \
+  --capability=<capability-name>
+```
+
+- 将当前具名分支写入 `skywalk-sdd/state/apply-<change>-<capability>.json` 的 `integration_base`
+- 若为 detached HEAD，先 `git checkout` 到具名分支再记录
+- simple 模式可省略 `--capability`（默认与 change 相同）
+
+**Step 0.5: 主仓库冲突预检（Git 项目必做）**
+- 在主仓库根目录执行 `git status`，确认**无**与本次 Apply 将修改路径冲突的**未跟踪**实现文件（如 `src/`、`package.json` 等）
+- 若存在，先移走、提交或删除；否则收尾 `merge` 会报 `untracked working tree files would be overwritten`
+- 收尾脚本默认启用 `--check-untracked` 预检并给出明确报错
+
 **Step 1: 创建隔离工作区**
+
+> 确认主仓库仍检出在 **Step 0.25 记录的集成分支**（或与其一致的尖端），再创建 worktree。
+
 - **首选**：使用 `EnterWorktree` 工具（Claude Code 原生）
   ```
   EnterWorktree(name="apply-<change-name>-<capability-name>")
   ```
 - **回退**：仅当原生工具不可用时，使用 `git worktree add`
+  - **full 模式**目录：`.worktrees/apply-<change-name>-<capability-name>`
+  - **simple 模式**目录：`.worktrees/apply-<change-name>`（无 capability 后缀）
+  - **分支命名**：仅当 Step 0.1 校验通过后，使用报告中的 `kld-sdd/<change-name>/<capability-name>`（勿对强依赖 cap 强行并行拆分支）
   ```bash
   git worktree add .worktrees/apply-<change-name>-<capability-name> \
     -b kld-sdd/<change-name>/<capability-name>
@@ -178,6 +323,7 @@ openspec list --json
 
 **报告**：
 > "✅ Worktree 就绪：`<path>`
+> 集成分支：`<integration_base>`（收尾将 merge 回此分支）
 > 基线测试通过（N 个测试，0 失败）
 > 准备实施 `<change-name>/<capability-name>`"
 
@@ -243,6 +389,7 @@ b. **显示当前层级任务**
 c. **🤖 派发子代理实现代码**
 
       > **使用 Agent 工具并行派发同层任务，每个子代理负责一个任务，上下文隔离、专注高效。**
+      > **⛔ 子代理阶段不创建 worktree/分支**——隔离环境已在 §1.5 就绪；子代理仅在 worktree 目录内实现 TASK。
 
       **派发准备（每个子代理）：**
       1. 从 tasks.md 中提取该任务的完整描述
@@ -333,11 +480,66 @@ node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --proj
 > 建议执行 `/kld-review --local` 对本次变更的代码进行评审。
 > 该技能可在公司内部 SkillHub 下载安装。
 >
-> **🧹 Worktree 清理**：
-> 全部完成后，清理隔离工作区：
-> - 使用 `EnterWorktree` 时：`ExitWorktree(action="remove", discard_changes=false)`
-> - 使用 `git worktree add` 时：`git worktree remove .worktrees/<dir> && git branch -D <branch>`
-> - 需保留变更时：`ExitWorktree(action="keep")`
+> **🧹 Worktree 收尾**：若本次使用了 worktree，见 **§6.1**；若判定未建 worktree，跳过 §6.1。
+> **其他 capability**：若并行 apply 中仍有未 finish 的 worktree，提示按 proposal 依赖顺序继续 `finish`。
+
+### 6.0 【条件必做】单元测试真实执行（`test-strategy` 非 `none`）
+
+当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时：
+
+1. **在结束 apply 或执行 §6.1 收尾之前**，必须在项目根或 worktree 内**真实运行**单元测试命令（`npm test` / `pytest` / `go test` 等）。
+2. 须留下可核验的 telemetry 证据（任选其一）：
+   - `node skywalk-sdd/log.cjs record --type=test_result ...`（`test_results.command` 非空，且 `passed`/`failed`/`duration_ms` 有实际值）
+   - `task_update` 的 `details-json` 中 `test_results` 含真实执行数据
+   - 或单独运行 `/opsx-test` 并完成 `command=test` 的 `stage_end`
+3. **Claude Code**：`sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验；无证据则**阻断**并提示补跑测试。
+
+| test-strategy | 行为 |
+|---------------|------|
+| `tdd` | 无测试证据不得结束 apply / 不得 finish worktree |
+| `impl-first` | 同上，实现后必须补跑并记录 |
+| `none` | 跳过本节与 test gate |
+
+### 6.1 【条件必做】Worktree 收尾（仅当 §1.5 已创建 worktree）
+
+> **⛔ 本次 Apply 若创建了 worktree**：DAG 全部完成且 **§6.0 测试门禁（若适用）** 通过后，必须在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）。
+> 若 §1.5 判定未建 worktree（串行、强依赖、沙箱回退），跳过本节。
+
+**前置条件**：
+- worktree 内 `git status` 干净（实现代码已全部 commit）
+- 主仓库无与 merge 冲突的未跟踪文件（见 §1.5 Step 0.5）
+- `test-strategy` 为 `tdd`/`impl-first` 时，§6.0 测试证据已存在
+
+**执行**（主仓库根目录）：
+```bash
+node skywalk-sdd/apply-worktree-finish.cjs \
+  --change=<变更名称> \
+  --capability=<capability-name>
+```
+
+- **默认 merge 目标**：§1.5 `--record-base` 写入的 `integration_base`（**不是**默认 master）
+- 仅当 state 缺失或需覆盖时传 `--target=<集成分支>`
+- **simple 模式**：`--capability` 可省略；目录为 `.worktrees/apply-<change>`
+- **full 模式**：目录为 `.worktrees/apply-<change>-<capability>`
+
+**脚本行为**：`checkout 集成分支` → `merge --no-ff` apply 分支 → `worktree remove` → 删临时目录 → `branch -d` apply 分支
+
+**常用 flags**：`--dry-run` 预演；`--skip-merge` 已手动 merge；`--keep-branch` 保留 apply 分支；`--no-check-untracked` 跳过未跟踪预检
+
+**收尾 Telemetry（推荐）**：
+```bash
+node skywalk-sdd/log.cjs record --type=worktree_finish \
+  --command=apply --project=. --change=<变更名称> --capability=<capability-name> \
+  --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> \
+  --result=success --summary="merge+remove completed" \
+  --details-json='{"integration_base":"<branch>","merge_commit":"<sha>","worktree_removed":true}'
+```
+
+**回退**（仅当脚本不可用时，详见 `./worktree-setup.md`）：
+- `EnterWorktree`：`ExitWorktree(action="remove", discard_changes=false)`
+- `git worktree add`：`git worktree remove` + `git branch -D`
+
+> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。
 
 ---
 
@@ -348,9 +550,15 @@ node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --proj
 - **⛔ 隔离红线**：绝对禁止加载同级其他 Capability 的文档
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - **⛔ 编译检查门禁**：每完成一个任务后，**必须运行编译检查**，编译失败禁止标记已完成
-- **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=警告, none=跳过）
+- **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 会校验非占位数据
 - **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 中的 `- [ ]` 为 `- [x]`，**同时修改** `**状态**: [ ] 未完成` 为 `**状态**: [x] 已完成`，两种格式不可遗漏
 - **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目使用 `vcs_mode=no-git` 继续执行
+- **⛔ Step 0.1 隔离校验必做**：建 worktree / 建议分支名前，必须完成 proposal + 跨 cap spec 依赖校验并输出报告；未通过不得按 full 并行策略拆 `kld-sdd/<change>/<cap>`
+- **Worktree 为加速手段，非必选项**：校验通过且解耦方可多 worktree；有依赖或共享修改面则串行
+- **本地集成分支**：使用 worktree 时，`--record-base` 记录用户**当前本地分支**为 merge 目标，禁止默认写死 `master`
+- **⛔ 已建 worktree 则收尾必做**：`apply-worktree-finish.cjs` merge 回 `integration_base`；多 cap 并行时按依赖顺序逐个 finish
+- **⛔ 子代理不建分支**：worktree/apply 分支仅在 §1.5（主会话）创建一次，§5 子代理不得再建
+- **Capability 级并行**：多个 `/opsx-apply` 会话 = 多个 worktree；禁止为未解耦的 cap 仅因 full 模式而拆分支
 - **显示进度反馈**：每完成一个任务，显示「✅ [TASK-ID] 已完成 [N/M]」
 - **保持任务聚焦**：每次只处理一个任务
 - **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问