kld-sdd 2.6.14 → 2.6.16

package/templates/hooks/codebuddy/hooks/sdd-mid-checkpoint.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * SDD Mid-Apply Checkpoint Hook
+ *
+ * 每完成 10 个 TDD 任务后强制检查点，验证 telemetry 证据链完整性。
+ * 不阻断，仅输出警告提醒。
+ *
+ * 触发点：PostToolUse(Bash) - 当检测到测试命令执行后
+ * 退出码：0（不阻断）
+ */
+
+const fs = require('fs');
+const path = require('path');
+const core = require('./hook-gate-core.cjs');
+
+const CHECKPOINT_INTERVAL = 10;
+
+function loadChangeEvents(projectRoot, changeName) {
+  const skywalk = core.resolveSkywalkDir(projectRoot);
+  const safe = core.safeChangeName(changeName);
+  const dir = skywalk
+    ? path.join(skywalk, 'events', safe)
+    : 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 {} }
+    } catch {}
+  }
+  return events;
+}
+
+function latestActiveStage(projectRoot) {
+  const skywalk = core.resolveSkywalkDir(projectRoot);
+  const stateDir = skywalk
+    ? path.join(skywalk, 'state')
+    : path.join(projectRoot, 'skywalk-sdd', 'state');
+  if (!fs.existsSync(stateDir)) return null;
+  return fs.readdirSync(stateDir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => { try { return JSON.parse(fs.readFileSync(path.join(stateDir, f), 'utf8')).event; } catch { return null; } })
+    .filter(Boolean)
+    .filter(e => e.command === 'apply')
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0] || null;
+}
+
+if (require.main === module) {
+  const parsed = core.parseHookInput(core.readStdin(), { strict: false });
+  const input = core.normalizeHookInput(parsed.input || {});
+  const toolInput = input.tool_input || input.toolInput || {};
+  const command = String(toolInput.command || '');
+
+  if (!/\b(npm|pnpm|yarn)\s+(test|run\s+test)\b|\bpytest\b|\bmvn\b.*\btest\b|\bgo\s+test\b|\bcargo\s+test\b/i.test(command)) {
+    process.exit(0);
+  }
+
+  const projectRoot = core.getProjectRoot(input, 'codebuddy');
+  const activeStage = latestActiveStage(projectRoot);
+  if (!activeStage) process.exit(0);
+
+  const events = loadChangeEvents(projectRoot, activeStage.change);
+  const since = new Date(activeStage.timestamp).getTime();
+
+  const taskUpdates = events.filter(e =>
+    e.type === 'task_update' && e.status === 'completed' &&
+    new Date(e.timestamp || 0).getTime() >= since);
+  const completedCount = taskUpdates.length;
+
+  if (completedCount === 0 || completedCount % CHECKPOINT_INTERVAL !== 0) {
+    process.exit(0);
+  }
+
+  const testResults = events.filter(e =>
+    e.type === 'test_result' &&
+    new Date(e.timestamp || 0).getTime() >= since);
+
+  const redCount = testResults.filter(e =>
+    e.result === 'failure' && e.details && e.details.test_results &&
+    e.details.test_results.tdd_phase === 'red').length;
+  const greenCount = testResults.filter(e =>
+    e.result === 'success' && e.details && e.details.test_results &&
+    e.details.test_results.tdd_phase === 'green').length;
+
+  const expectedMin = Math.floor(completedCount * 0.8);
+  const actualEvidence = redCount + greenCount;
+
+  if (actualEvidence < expectedMin) {
+    console.log(JSON.stringify({
+      decision: 'allow',
+      message: '\n⚠️ TDD 中途检查点 [' + completedCount + ' 任务已完成]\n' +
+        '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
+        '  task_update 事件: ' + completedCount + '\n' +
+        '  test_result 事件: ' + actualEvidence + ' (RED: ' + redCount + ', GREEN: ' + greenCount + ')\n' +
+        '  期望最少: ' + expectedMin + '\n\n' +
+        '  ⚠️ 测试证据不足！请确认你仍在遵循严格 RED→GREEN 循环。\n' +
+        '  如果最近的任务跳过了 TDD，请回退并补做。\n' +
+        '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n',
+    }));
+  }
+
+  process.exit(0);
+}
+
+module.exports = { loadChangeEvents, latestActiveStage, CHECKPOINT_INTERVAL };

package/templates/hooks/codebuddy/hooks/sdd-post-tool.cjs

@@ -5,6 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
+const core = require('./hook-gate-core.cjs');
 
 function latestActiveStage(projectRoot) {
   const stateDir = path.join(projectRoot, 'skywalk-sdd', 'state');
@@ -76,6 +77,38 @@ function stableRunId(input, activeStage, command) {
     .slice(0, 20)}`;
 }
 
+function inferTddPhase(projectRoot, activeStage, testResult) {
+  const taskId = activeStage.task_id;
+  if (!taskId) return 'regression';
+
+  const skywalk = core.resolveSkywalkDir(projectRoot);
+  const safe = core.safeChangeName(activeStage.change);
+  const tasksCandidates = [
+    path.join(projectRoot, 'openspec', 'changes', activeStage.change, 'tasks.md'),
+    path.join(projectRoot, 'changes', activeStage.change, 'tasks.md'),
+  ];
+  let tasksPath = null;
+  for (const p of tasksCandidates) {
+    if (fs.existsSync(p)) { tasksPath = p; break; }
+  }
+  if (!tasksPath) return 'regression';
+
+  try {
+    const content = fs.readFileSync(tasksPath, 'utf8');
+    const escaped = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp('### \\[' + escaped + '\\][\\s\\S]*?(?=### \\[TASK|$)');
+    const match = content.match(regex);
+    if (!match) return 'regression';
+    const block = match[0];
+    if (/测试-RED|test-red/i.test(block)) {
+      return testResult.result === 'failure' ? 'red' : 'red-passed-unexpectedly';
+    }
+    if (/实现-GREEN|impl-green/i.test(block)) return 'green';
+    if (/重构-REFACTOR|refactor/i.test(block)) return 'refactor';
+  } catch {}
+  return 'regression';
+}
+
 function inferRecord(command) {
   if (/\b(log\.cjs|log\.js)\s+record\b/.test(command)) return null;
   if (/\b(npm|pnpm|yarn)\s+(test|run\s+test)\b|\bpytest\b|\bmvn\b.*\btest\b|\bgo\s+test\b|\bcargo\s+test\b/i.test(command)) {
@@ -114,7 +147,8 @@ function recordTelemetry(projectRoot, activeStage, record, result, exitCodeKnown
       : (typeof toolResponse.exitCode === 'number'
         ? toolResponse.exitCode
         : (typeof toolResponse.success === 'boolean' ? (toolResponse.success ? 0 : 1) : null));
-    const tddPhase = toolInput.tdd_phase || input.tdd_phase || 'regression';
+    const tddPhase = toolInput.tdd_phase || input.tdd_phase ||
+      inferTddPhase(projectRoot, activeStage, inferred);
     details.test_results = {
       command: toolInput.command || record.details.command,
       tdd_phase: tddPhase,
@@ -194,6 +228,7 @@ if (require.main === module) {
 module.exports = {
   inferResult,
   inferRecord,
+  inferTddPhase,
   parseTestCounts,
   stableRunId,
   recordTelemetry,

package/templates/hooks/codebuddy/hooks/sdd-tdd-rhythm-gate.cjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * SDD TDD Rhythm Gate Hook
+ *
+ * 当 agent 修改 tasks.md 中的任务状态时，校验 TDD 证据链。
+ * 仅在 TDD 模式的 apply 阶段对 RED/GREEN/REFACTOR 任务生效。
+ *
+ * 触发点：PreToolUse(Write|Edit)
+ * 退出码：0 放行 | 2 阻断
+ */
+
+const fs = require('fs');
+const path = require('path');
+const core = require('./hook-gate-core.cjs');
+
+// ── 辅助函数 ──
+
+function loadChangeEvents(projectRoot, changeName) {
+  const skywalk = core.resolveSkywalkDir(projectRoot);
+  const safe = core.safeChangeName(changeName);
+  const dir = skywalk
+    ? path.join(skywalk, 'events', safe)
+    : 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 {}
+      }
+    } catch {}
+  }
+  return events;
+}
+
+function readTestStrategy(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)) continue;
+    try {
+      const content = fs.readFileSync(p, 'utf8');
+      const match = content.match(/test-strategy:\s*(\S+)/);
+      if (match) {
+        const strategy = match[1].toLowerCase().trim();
+        if (strategy === 'none' || strategy === 'impl-first') return strategy;
+      }
+    } catch {}
+  }
+  return 'tdd';
+}
+
+function detectTaskType(lines, taskLineIndex) {
+  for (let i = taskLineIndex; i < Math.min(taskLineIndex + 30, lines.length); i++) {
+    const line = lines[i];
+    if (/测试-RED|test-red/i.test(line)) return 'red';
+    if (/实现-GREEN|impl-green/i.test(line)) return 'green';
+    if (/重构-REFACTOR|refactor/i.test(line)) return 'refactor';
+    if (/配置|数据层|接口层|接口测试|scaffold|migration/i.test(line)) return 'non-tdd';
+    if (/^### \[TASK/.test(line) && i > taskLineIndex) break;
+  }
+  return 'unknown';
+}
+
+function findPairedRedTaskId(content, greenTaskId) {
+  const escaped = greenTaskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const regex = new RegExp(`### \\[${escaped}\\][\\s\\S]*?(?=### \\[TASK|$)`);
+  const match = content.match(regex);
+  if (!match) return null;
+  const depMatch = match[0].match(/- \*\*dependsOn\*\*:\s*(TASK-[A-Z]+-\d+)/);
+  return depMatch ? depMatch[1] : null;
+}
+
+function detectStatusChanges(oldContent, newContent) {
+  const changes = [];
+  const oldLines = oldContent.split('\n');
+  const newLines = newContent.split('\n');
+  let currentTaskId = null;
+  let currentTaskType = null;
+  for (let i = 0; i < Math.max(oldLines.length, newLines.length); i++) {
+    const oldLine = oldLines[i] || '';
+    const newLine = newLines[i] || '';
+    const taskMatch = newLine.match(/^### \[(TASK-[A-Z]+-\d+)\]/);
+    if (taskMatch) {
+      currentTaskId = taskMatch[1];
+      currentTaskType = detectTaskType(newLines, i);
+      continue;
+    }
+    if (oldLine.includes('**状态**: [ ] 未完成') &&
+        newLine.includes('**状态**: [x] 已完成')) {
+      changes.push({ taskId: currentTaskId, taskType: currentTaskType, line: i + 1 });
+    }
+  }
+  return changes;
+}
+
+// ── 主逻辑 ──
+
+if (require.main === module) {
+  const parsed = core.parseHookInput(core.readStdin(), { strict: false });
+  if (!parsed.ok) process.exit(0);
+  const input = core.normalizeHookInput(parsed.input || {});
+  const toolInput = input.tool_input || input.toolInput || {};
+  const filePath = toolInput.file_path || toolInput.filePath || '';
+
+  // 只检查 tasks.md
+  if (!filePath.endsWith('tasks.md')) process.exit(0);
+
+  const projectRoot = core.getProjectRoot(input, 'codebuddy');
+
+  // 仅在有活跃 apply 阶段时触发
+  const activeStage = core.findActiveApplyStage(projectRoot);
+  if (!activeStage) process.exit(0);
+
+  // 安全网 0: 非 TDD 模式直接放行
+  const testStrategy = readTestStrategy(projectRoot, activeStage.change);
+  if (testStrategy !== 'tdd') process.exit(0);
+
+  // 读取旧内容
+  let oldContent = '';
+  try { oldContent = fs.readFileSync(filePath, 'utf8'); } catch { process.exit(0); }
+
+  // 获取新内容
+  let newContent = '';
+  if (toolInput.content) {
+    newContent = toolInput.content;
+  } else if (toolInput.new_str) {
+    newContent = oldContent.replace(toolInput.old_str || '', toolInput.new_str);
+  } else { process.exit(0); }
+
+  // 检测状态变更
+  const changes = detectStatusChanges(oldContent, newContent);
+  if (changes.length === 0) process.exit(0);
+
+  // 加载 telemetry 事件
+  const events = loadChangeEvents(projectRoot, activeStage.change);
+
+  // 安全网 1: 无任何 test_result → post-tool 可能失败，降级为警告
+  const totalTestResults = events.filter(e => e.type === 'test_result').length;
+  const hasTddTasks = changes.some(c =>
+    c.taskType === 'red' || c.taskType === 'green' || c.taskType === 'refactor');
+  if (totalTestResults === 0 && hasTddTasks) {
+    console.log(JSON.stringify({
+      decision: 'allow',
+      message: '⚠️ [SDD TDD Rhythm Gate] 未检测到任何 test_result 遥测事件。' +
+        'sdd-post-tool.cjs 可能未正常工作。TDD 节奏检查降级为警告模式。',
+    }));
+    process.exit(0);
+  }
+
+  // G4: 批量更新检测
+  if (changes.length > 3) {
+    // 安全网 2: 全部有 task_update 遥测 → check-task 合法更新，放行
+    const allHaveTaskUpdate = changes.every(change =>
+      events.some(e => e.type === 'task_update' && e.task_id === change.taskId));
+    if (!allHaveTaskUpdate) {
+      core.blockWithReason(
+        `[SDD TDD Rhythm Gate] 检测到单次写入中 ${changes.length} 个任务状态变更，且无对应 task_update 遥测。\n\n` +
+        '⛔ 禁止批量修改任务状态。必须逐个通过 task_update → check-task 流程更新。\n' +
+        `批量变更的任务: ${changes.map(c => c.taskId).join(', ')}`);
+    }
+    process.exit(0); // 合法批量更新，放行
+  }
+
+  // 逐个检查
+  for (const change of changes) {
+    const { taskId, taskType } = change;
+
+    if (taskType === 'red') {
+      const hasRedEvidence = events.some(e =>
+        e.type === 'test_result' && e.task_id === taskId &&
+        e.result === 'failure' &&
+        e.details && e.details.test_results && e.details.test_results.tdd_phase === 'red');
+      if (!hasRedEvidence) {
+        core.blockWithReason(
+          `[SDD TDD Rhythm Gate] 任务 ${taskId} 是 RED 任务，标记完成前必须先运行测试并确认失败。\n\n` +
+          '未检测到对应的 test_result(result=failure, tdd_phase=red) 遥测事件。\n' +
+          '请先运行测试确认 RED 失败，记录 test_result 后再标记任务完成。');
+      }
+    }
+
+    if (taskType === 'green') {
+      const hasGreenEvidence = events.some(e =>
+        e.type === 'test_result' && e.task_id === taskId &&
+        e.result === 'success' &&
+        e.details && e.details.test_results && e.details.test_results.tdd_phase === 'green');
+      if (!hasGreenEvidence) {
+        core.blockWithReason(
+          `[SDD TDD Rhythm Gate] 任务 ${taskId} 是 GREEN 任务，标记完成前必须先运行测试并确认通过。\n\n` +
+          '未检测到对应的 test_result(result=success, tdd_phase=green) 遥测事件。\n' +
+          '请先运行测试确认 GREEN 通过，记录 test_result 后再标记任务完成。');
+      }
+      // G5: RED→GREEN 间隔检查
+      const pairedRedTaskId = findPairedRedTaskId(newContent, taskId);
+      if (pairedRedTaskId) {
+        const redEvent = events.find(e =>
+          e.type === 'test_result' && e.task_id === pairedRedTaskId && e.result === 'failure');
+        const greenEvent = events.find(e =>
+          e.type === 'test_result' && e.task_id === taskId && e.result === 'success');
+        if (redEvent && greenEvent) {
+          const gap = (new Date(greenEvent.timestamp).getTime() -
+            new Date(redEvent.timestamp).getTime()) / 1000;
+          if (gap < 60) {
+            core.blockWithReason(
+              `[SDD TDD Rhythm Gate] TDD 节奏异常：\n\n` +
+              `任务 ${taskId}(GREEN) 与 ${pairedRedTaskId}(RED) 的测试执行间隔仅 ${gap} 秒，建议 >60 秒。\n` +
+              '可能存在批量执行或跳过 RED 阶段的情况。');
+          }
+        }
+      }
+    }
+
+    if (taskType === 'refactor') {
+      const hasRefactorEvidence = events.some(e =>
+        e.type === 'test_result' && e.task_id === taskId &&
+        e.result === 'success' &&
+        e.details && e.details.test_results && e.details.test_results.tdd_phase === 'refactor');
+      if (!hasRefactorEvidence) {
+        core.blockWithReason(
+          `[SDD TDD Rhythm Gate] 任务 ${taskId} 是 REFACTOR 任务，` +
+          '标记完成前必须先运行测试确认全部通过（测试仍绿）。\n\n' +
+          '未检测到对应的 test_result(result=success, tdd_phase=refactor) 遥测事件。');
+      }
+    }
+
+    // 安全网 3: unknown 类型降级为警告
+    if (taskType === 'unknown') {
+      console.log(JSON.stringify({
+        decision: 'allow',
+        message: `⚠️ [SDD TDD Rhythm Gate] 任务 ${taskId} 的类型字段无法识别，已放行。` +
+          '建议补全 **类型** 字段，可选值：测试-RED | 实现-GREEN | 重构-REFACTOR | 配置 | 数据层 | 接口层 | 接口测试',
+      }));
+    }
+    // non-tdd 类型：直接放行
+  }
+
+  process.exit(0);
+}
+
+module.exports = {
+  detectStatusChanges, detectTaskType, findPairedRedTaskId,
+  loadChangeEvents, readTestStrategy,
+};

package/templates/hooks/codebuddy/settings.json

@@ -39,6 +39,10 @@
           {
             "type": "command",
             "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-apply-gate.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-tdd-rhythm-gate.cjs\""
           }
         ]
       }
@@ -50,6 +54,10 @@
           {
             "type": "command",
             "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-post-tool.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-mid-checkpoint.cjs\""
           }
         ]
       }

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

@@ -215,6 +215,19 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 > 异常路径覆盖门禁见 tdd-rules/rules/exception-path-coverage.md
 > TDD 节奏校验（执行后校验）见 `./checklist.md` §5e.1
 
+**【S2.2 TDD 纪律上下文刷新】**（每 Layer 开始时强制）：
+
+在开始每个新 Layer 的任务实施前，必须重新执行以下步骤：
+
+1. 重新读取本 SKILL.md §S2（TDD 红绿节奏 7 步骤）
+2. 重新读取 `./checklist.md` §5e.1（TDD 节奏校验）
+3. 显式声明："我将在 Layer [X] 严格遵循 RED→GREEN 串行循环"
+4. 如果本 Layer 有 >5 个 TDD 对，显示额外警告：
+   "⚠️ 大量 TDD 任务（[N] 对），注意保持节奏。每对必须：写测试→运行确认失败→中断声明→写实现→运行确认通过"
+
+> 此步骤防止上下文窗口退化导致 TDD 纪律被"挤出"。
+> 随着对话变长，早期读取的 TDD 规则可能被遗忘，必须定期刷新。
+
 **【S2.1 RED 测试质量标准】**（test-strategy=tdd 时强制）：
 
 ⛔ RED 测试质量门禁见 `./checklist.md`「§5e.2 RED 测试质量门禁」，核心包括：

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

@@ -95,6 +95,21 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 ---
 
+### §5g 中途 TDD 节奏检查点（每完成 10 个 TDD 任务后强制执行）
+
+> ⛔ 在 apply 执行过程中，每完成 10 个 TDD 任务后必须执行此检查点。
+> 此检查点由 `sdd-mid-checkpoint.cjs` hook 自动触发，但 agent 也必须主动执行。
+
+- [ ] 统计已完成的 `task_update` 事件数，与 tasks.md `[x]` 数量对比
+- [ ] 统计已记录的 `test_result` 事件数（RED + GREEN），与已完成 TDD 对数 × 2 对比
+- [ ] 如果 `task_update` 数量 < 已完成任务数：⛔ 阻断，补录缺失的 `task_update`
+- [ ] 如果 `test_result` 数量 < 已完成 TDD 对数 × 2：⛔ 阻断，补录缺失的 `test_result`
+- [ ] 显示警告："已完成 [N] 个 TDD 任务。请确认你仍在遵循严格 RED→GREEN 循环。"
+- [ ] 检查最近 3 对 RED→GREEN 的 `test_result` 时间戳间隔，均 >60 秒
+- [ ] 如果发现异常，回退到上一个检查点重新执行
+
+---
+
 ## §6.0 单元测试真实执行自检（`test-strategy` 非 `none`）
 
 > 单元测试真实执行自检见 tdd-core/reference.md §9

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

@@ -17,10 +17,12 @@ description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策
 ### task_update（每完成一个任务记录）
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<本次任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"task_update\":{\"test_event_id\":\"<同一change内成功test_result的event_id>\",\"tdd_required\":<true|false>},\"files_changed\":[]}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<本次任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"task_update\":{\"test_event_id\":\"<同一change内成功test_result的event_id>\",\"tdd_required\":<true|false>,\"tdd_pair_id\":\"<pair-N>\",\"tdd_role\":\"green\"},\"files_changed\":[]}"
+
+也可互斥使用 `test_run_id`（同 change、覆盖当前任务、唯一严格完成候选）；解析成功后会补齐规范化 `test_event_id`。
 ```
 
-**⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID。完成任务必须引用同一 change 内、`tdd_phase` 为 green/refactor/regression、退出码为 0、`failure_type=none` 的 `test_result.event_id`，并明确填写 `tdd_required=true/false`；禁止把测试计数复制进 `task_update`。
+**⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID。完成任务必须引用同一 change 内、`tdd_phase` 为 green/refactor/regression、退出码为 0、`failure_type=none` 的 `test_result.event_id`（或可唯一解析的 `test_run_id`），并明确填写 `tdd_required=true/false`；TDD 任务应写同一 `tdd_pair_id` 与 `tdd_role`；禁止把测试计数复制进 `task_update`。
 
 只有文档、纯配置说明等确实不适用测试的任务，才能显式声明：
 
@@ -46,6 +48,47 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" check-task --project=. --change
 
 **【严格证据口径】**：测试执行事实只存在于 `test_result`；`task_update` 只表达任务状态与证据引用。旧事件仍可读取，但新事件必须使用 `--strict`。
 
+### test_result（每次真实测试执行记录）
+
+> **⚠️ key 名必须是 `test_results`（复数），不是 `test_result`（单数）。**
+> `log.cjs` 的 `normalizeStrictTestResult` 校验器从 `details.test_results` 读取，单数 key 会导致 `TEST_RESULT_REQUIRED` 错误。
+> 完整 schema 亦见 `tdd-core/reference.md` §8 和 `opsx-test/SKILL.md` §4a。
+
+**RED 阶段（测试失败，预期红灯）**：
+
+```bash
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<本次真实执行的稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="<TASK-ID> TDD 红灯符合预期" --details-json='{"test_results":{"tdd_phase":"red","verified_task_ids":["<TASK-ID>"],"command":"<实际测试命令>","exit_code":<非零退出码>,"counts_known":true,"passed":<通过数>,"failed":<失败数>,"skipped":<跳过数>,"duration_ms":<实测毫秒>,"failure_type":"assertion","expected_failure":true}}'
+```
+
+**GREEN 阶段（测试通过）**：
+
+```bash
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<本次真实执行的稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success --summary="<TASK-ID> TDD 绿灯通过" --details-json='{"test_results":{"tdd_phase":"green","verified_task_ids":["<TASK-ID>"],"command":"<实际测试命令>","exit_code":0,"counts_known":true,"passed":<通过数>,"failed":0,"skipped":<跳过数>,"duration_ms":<实测毫秒>,"failure_type":"none","expected_failure":false}}'
+```
+
+**必填字段**：
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| `tdd_phase` | string | TDD 阶段 | `red`/`green`/`refactor`/`regression`/`not-applicable` |
+| `command` | string | 实际测试命令 | 如 `mvn test -Dtest=...` |
+| `result` | string | 测试结果 | `success`/`failure`（与 `exit_code` 一致） |
+| `exit_code` | integer | 退出码 | `0`=成功，非 0=失败 |
+| `counts_known` | boolean | 是否已知测试计数 | `true` 时必须填 `passed`/`failed`/`skipped` |
+| `duration_ms` | integer | 执行耗时（毫秒） | 实测值 |
+| `failure_type` | string | 失败类型 | `assertion`/`contract`/`compile`/`infrastructure`/`timeout`/`none` |
+| `run_id` | string | 稳定执行 ID | 同一次执行重试时保持不变 |
+| `task_id` | string | 关联任务 ID | 或用 `verified_task_ids` 数组 |
+| `expected_failure` | boolean | 是否预期失败 | 仅 `tdd_phase=red` 时可为 `true` |
+
+**交叉校验规则**：
+- `exit_code=0` ↔ `result=success` ↔ `failure_type=none`
+- `exit_code≠0` ↔ `result=failure` ↔ `failure_type≠none`
+- `expected_failure=true` 仅允许 `tdd_phase=red`
+- 有效 RED：`expected_failure=true` + `exit_code≠0` + `failure_type` 为 `assertion` 或 `contract`
+
+> **自动记录**：`sdd-post-tool.cjs` hook 会在 agent 运行 `mvn test`/`npm test` 等命令时自动记录 `test_result`，使用正确的 `test_results` key。但自动记录依赖 `activeStage.task_id`，若未设置则 `tdd_phase` 默认为 `regression`。需要精确标注 RED/GREEN 时建议手动记录。
+
 ### process_note（阶段内过程事件：决策/范围变化/故障与恢复）
 
 记录阶段内过程信息，供 execution-log 叙事与报告“过程记录”板块统计。新事件使用 `--strict`，`details.kind` 必填，枚举：

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

@@ -112,7 +112,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
 ```json
 {
   "maturity_evidence": {
-    "change_type": "config|document|report|composite|other",
+    "change_type": "config|transaction|report|composite",
     "e1_actual_ms": 500,
     "e1_target_ms": 600,
     "e1_type_target_met": true,