kld-sdd 2.6.12 → 2.6.13

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

@@ -3,8 +3,8 @@
 
 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');
@@ -26,19 +26,54 @@ function latestActiveStage(projectRoot) {
 function inferResult(input) {
   const response = input.tool_response || input.toolResponse || {};
   if (typeof response.exit_code === 'number') {
-    return { result: response.exit_code === 0 ? 'success' : 'failure', exit_code_known: true };
+    return { result: response.exit_code === 0 ? 'success' : 'failure', exit_code_known: true, exit_code: response.exit_code };
   }
   if (typeof response.exitCode === 'number') {
-    return { result: response.exitCode === 0 ? 'success' : 'failure', exit_code_known: true };
+    return { result: response.exitCode === 0 ? 'success' : 'failure', exit_code_known: true, exit_code: response.exitCode };
   }
   if (typeof response.success === 'boolean') {
-    return { result: response.success ? 'success' : 'failure', exit_code_known: true };
+    return { result: response.success ? 'success' : 'failure', exit_code_known: true, exit_code: response.success ? 0 : 1 };
   }
   const out = String(response.stdout || response.stderr || '');
   if (/BUILD FAILED|error TS\d+|ERR_/i.test(out)) {
-    return { result: 'failure', exit_code_known: false };
+    return { result: 'failure', exit_code_known: false, exit_code: null };
   }
-  return { result: 'partial', exit_code_known: false };
+  return { result: 'partial', exit_code_known: false, exit_code: null };
+}
+
+function parseTestCounts(output) {
+  const text = String(output || '');
+  const tapPass = text.match(/#\s*pass(?:ed)?\s+(\d+)/i);
+  const tapFail = text.match(/#\s*fail(?:ed)?\s+(\d+)/i);
+  const tapSkip = text.match(/#\s*skip(?:ped)?\s+(\d+)/i);
+  if (tapPass || tapFail) {
+    return {
+      counts_known: true,
+      passed: Number(tapPass?.[1] || 0),
+      failed: Number(tapFail?.[1] || 0),
+      skipped: Number(tapSkip?.[1] || 0),
+    };
+  }
+  const summary = text.match(/Tests?\s+.*?(\d+)\s+passed(?:.*?(\d+)\s+failed)?(?:.*?(\d+)\s+skipped)?/i);
+  if (summary) {
+    return {
+      counts_known: true,
+      passed: Number(summary[1] || 0),
+      failed: Number(summary[2] || 0),
+      skipped: Number(summary[3] || 0),
+    };
+  }
+  return { counts_known: false };
+}
+
+function stableRunId(input, activeStage, command) {
+  const explicit = input.tool_use_id || input.toolUseId || input.tool_call_id || input.toolCallId;
+  if (explicit) return String(explicit);
+  const response = input.tool_response || input.toolResponse || {};
+  return `hook-${crypto.createHash('sha256')
+    .update(JSON.stringify([activeStage.event_id || '', activeStage.session_id || '', command, response]))
+    .digest('hex')
+    .slice(0, 20)}`;
 }
 
 function inferRecord(command) {
@@ -69,6 +104,34 @@ function recordTelemetry(projectRoot, activeStage, record, result, exitCodeKnown
   const toolInput = (input && (input.tool_input || input.toolInput)) || {};
   const toolResponse = (input && (input.tool_response || input.toolResponse)) || {};
   const details = { [record.detailsKey]: { ...record.details } };
+  let strictTestEvent = false;
+  let runId = null;
+  if (record.type === 'test_result') {
+    const output = String(toolResponse.stdout || '') + '\n' + String(toolResponse.stderr || '');
+    const counts = parseTestCounts(output);
+    const exitCode = typeof toolResponse.exit_code === 'number'
+      ? toolResponse.exit_code
+      : (typeof toolResponse.exitCode === 'number'
+        ? toolResponse.exitCode
+        : (typeof toolResponse.success === 'boolean' ? (toolResponse.success ? 0 : 1) : null));
+    const tddPhase = toolInput.tdd_phase || input.tdd_phase || 'regression';
+    details.test_results = {
+      command: toolInput.command || record.details.command,
+      tdd_phase: tddPhase,
+      exit_code: exitCode,
+      counts_known: counts.counts_known,
+      ...(counts.counts_known ? {
+        passed: counts.passed,
+        failed: counts.failed,
+        skipped: counts.skipped,
+      } : {}),
+      duration_ms: Number.isFinite(toolResponse.duration_ms) ? toolResponse.duration_ms : 0,
+      failure_type: result === 'failure' ? (exitCode == null ? 'infrastructure' : 'assertion') : 'none',
+      expected_failure: tddPhase === 'red' && result === 'failure' && exitCode != null,
+    };
+    strictTestEvent = exitCode != null && Boolean(activeStage.task_id);
+    runId = stableRunId(input || {}, activeStage, details.test_results.command);
+  }
   if (record.type === 'build_result') {
     details.build_results.success = result === 'success';
     details.build_results.error_count = result === 'success' ? 0 : null;
@@ -82,7 +145,7 @@ function recordTelemetry(projectRoot, activeStage, record, result, exitCodeKnown
     logCli,
     'record',
     `--type=${record.type}`,
-    `--command=${toolInput.command || activeStage.command || activeStage.stage || 'unknown'}`,
+    `--command=${activeStage.command || activeStage.stage || 'unknown'}`,
     `--project=${projectRoot}`,
     `--change=${activeStage.change || 'general'}`,
     `--agent=${activeStage.agent_type || 'codebuddy'}`,
@@ -91,14 +154,22 @@ function recordTelemetry(projectRoot, activeStage, record, result, exitCodeKnown
     `--summary=CodeBuddy hook captured ${record.type}`,
     `--details-json=${JSON.stringify(details)}`,
   ];
+  if (strictTestEvent) {
+    args.push(
+      '--strict',
+      `--run-id=${runId}`,
+      `--session-id=${activeStage.session_id || `stage-${activeStage.event_id}`}`,
+    );
+  }
   if (activeStage.capability) args.push(`--capability=${activeStage.capability}`);
   if (activeStage.task_id) args.push(`--task-id=${activeStage.task_id}`);
-  if (activeStage.session_id) args.push(`--session-id=${activeStage.session_id}`);
+  if (!strictTestEvent && activeStage.session_id) args.push(`--session-id=${activeStage.session_id}`);
   const run = runner || ((a) => execFileSync('node', a, { cwd: projectRoot, stdio: 'ignore' }));
   run(args);
 }
 
 if (require.main === module) {
+  const core = require('./hook-gate-core.cjs');
   const parsed = core.parseHookInput(core.readStdin(), { strict: false });
   const input = core.normalizeHookInput(parsed.input || {});
   const toolInput = input.tool_input || {};
@@ -120,4 +191,11 @@ if (require.main === module) {
   }
 }
 
-module.exports = { inferResult, inferRecord, recordTelemetry, latestActiveStage };
+module.exports = {
+  inferResult,
+  inferRecord,
+  parseTestCounts,
+  stableRunId,
+  recordTelemetry,
+  latestActiveStage,
+};

package/templates/hooks/codebuddy/hooks/sdd-prompt.cjs

@@ -54,8 +54,10 @@ const activeStages = readActiveStages(projectRoot)
 
 const lines = [
   'SDD Telemetry reminder:',
+  '- Resolve the exact change key first; every standard OPSX start/end command must include --change=<change-key>.',
   '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start before the OPSX stage work begins.',
-  '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end before stopping the stage.',
+  '- Run node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end with the same change, stage, session and event identity before stopping.',
+  '- change=general is reserved for explicitly allowed explore events and must later use scope_link for historical attribution.',
   '- Hooks are only an enhancement; OPSX skill instructions remain authoritative.',
 ];
 

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

@@ -38,7 +38,8 @@ allowed-tools:
 > - 较大的 `--details-json` 负载可先写入文件，再通过 `--details-file="$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-<type>.json"` 传递（例如 `task_update` 对应 `<变更名称>-task-update.json`）。
 > - `task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的 checkbox；录入成功后，agent 可以通过 `check-task` 命令验证该 checkbox 已更新。
 > - **⚠️ P1-2 ai_adoption_review 必填 ai_diff**：记录 AI 产出快照时，`--details-json` 必须含 `ai_diff.files_changed`（即使=0）与 `ai_diff.files`（产出文件路径数组，非空），**不得只发 `assertions`**。`vcs_mode=readonly` 时 `ai_diff.added_lines` 不得为 null——用只读 `git diff --numstat HEAD` 取值（apply Git 只读策略允许）；`vcs_mode=no-git` 时可填 null。工具侧已加记录时硬校验：`files` 空数组或 `readonly` 下 `added_lines=null` 将 **拒绝记录**（与 conformance_review 校验对称）。缺失 `ai_diff` 会导致 report 变更文件数为 null（工具侧已加 `assertions[].files` 兜底，但 `ai_diff` 是主数据源）。完整模板见 `./reference.md`「§5.1」。
-> - **⚠️ P1-3 process_note 必记**：阶段内发生 修复/澄清/决策/API 故障/换模型 时，**必须**记 `process_note` 事件（`kind` 见 `./reference.md`「必记节点清单」）。全程 0 条 process_note 视为过程记录缺失，report 过程记录区显示空。
+> - **严格证据链**：一次真实测试执行只写一条严格 `test_result`；任务完成事件只通过 `test_event_id` 引用成功的 green/refactor/regression 测试，并明确 `tdd_required=true/false`，不复制测试计数。测试不适用时必须写明原因。完整 schema 见 `./reference.md`。
+> - **process_note 必记**：用户决策、范围变化、API/模型/测试异常及恢复动作必须写严格 `process_note`；范围、模式、测试策略选择统一用 `kind=user_decision` 并标注 `decision_type`。
 
 > **🔒 Git 策略（只读增强，不改变开发流）**
 > - Git 只作为可选度量数据源，不是 apply 前置条件。
@@ -205,29 +206,29 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 3. **GREEN**：读取 RED 失败原因 → 执行 GREEN Scope 声明 → 逐条确认 YAGNI 围栏 → 写最少代码让测试通过 → 禁止捆绑未测试代码
 4. **GREEN Scope 门禁**：Verify GREEN 之后，检查生产代码无越界逻辑分支（属于后续 RED 的行为 → 删除）
 5. **REFACTOR**：在测试全绿状态下重构 → 运行全部测试确认仍绿
-6. **可选：TDD 审查子代理**：GREEN 任务完成后，可派发独立审查子代理执行 `opsx-tdd-review/SKILL.md` §7（子代理审查提示模板），检测"测试通过但没测到关键点"。implementer 自审查 ≠ 独立审查。
+6. **可选：TDD 审查子代理**：GREEN 任务完成后，可派发独立审查子代理执行 `tdd-review/SKILL.md` §7（子代理审查提示模板），检测"测试通过但没测到关键点"。implementer 自审查 ≠ 独立审查。
 7. 再进入下一个任务
 
-> 完整执行步骤见 opsx-tdd-core/reference.md §1-§3
-> 合理化预防表见 opsx-tdd-core/SKILL.md §7
-> REFACTOR 检查点见 opsx-tdd-rules/rules/refactor-checklist.md
-> 异常路径覆盖门禁见 opsx-tdd-rules/rules/exception-path-coverage.md
+> 完整执行步骤见 tdd-core/reference.md §1-§3
+> 合理化预防表见 tdd-core/SKILL.md §7
+> REFACTOR 检查点见 tdd-rules/rules/refactor-checklist.md
+> 异常路径覆盖门禁见 tdd-rules/rules/exception-path-coverage.md
 > TDD 节奏校验（执行后校验）见 `./checklist.md` §5e.1
 
 **【S2.1 RED 测试质量标准】**（test-strategy=tdd 时强制）：
 
 ⛔ RED 测试质量门禁见 `./checklist.md`「§5e.2 RED 测试质量门禁」，核心包括：
-- Mock 边界（引用 opsx-tdd-quality/SKILL.md §2）
-- 测试命名与结构（引用 opsx-tdd-quality/SKILL.md §3-§4）
-- 断言深度（引用 opsx-tdd-anti-patterns/SKILL.md §4 反模式 14）
-- RED 阶段反模式检查（引用 opsx-tdd-anti-patterns/SKILL.md §3）
+- Mock 边界（引用 tdd-quality/SKILL.md §2）
+- 测试命名与结构（引用 tdd-quality/SKILL.md §3-§4）
+- 断言深度（引用 tdd-anti-patterns/SKILL.md §4 反模式 14）
+- RED 阶段反模式检查（引用 tdd-anti-patterns/SKILL.md §3）
 
 ⛔ BEFORE 编写 RED 测试，必须读取：
-- opsx-tdd-anti-patterns/SKILL.md §3（RED 阶段 3 种反模式 + 门禁函数）
+- tdd-anti-patterns/SKILL.md §3（RED 阶段 3 种反模式 + 门禁函数）
 读取后在报告中确认："已读取 RED 阶段反模式检查表"。
 
-> 完整 Mock 边界矩阵见 opsx-tdd-quality/SKILL.md §2
-> 完整 15 种反模式见 opsx-tdd-anti-patterns/SKILL.md §3-§4
+> 完整 Mock 边界矩阵见 tdd-quality/SKILL.md §2
+> 完整 15 种反模式见 tdd-anti-patterns/SKILL.md §3-§4
 
 ### 5f. 【S3 apply 结束前 checkbox 全量自检】
 

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

@@ -34,7 +34,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 ### §5e 测试执行门禁（按 `proposal.md` 的 `test-strategy`）
 
-> 测试执行门禁策略见 opsx-tdd-rules/rules/test-execution-gate.md
+> 测试执行门禁策略见 tdd-rules/rules/test-execution-gate.md
 
 - [ ] `tdd` → ⛔ 强制执行（RED 确认失败、GREEN 确认通过、REFACTOR 全部测试仍绿）
 - [ ] `impl-first` → ⚠️ 警告模式
@@ -42,10 +42,10 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 ### §5e.1 TDD 执行合规自检（仅 test-strategy=tdd 时）
 
-⛔ 每完成一个 RED/GREEN/REFACTOR 任务后，必须执行 `opsx-tdd-core/checklist.md` §A（11 项）逐项勾选。
+⛔ 每完成一个 RED/GREEN/REFACTOR 任务后，必须执行 `tdd-core/checklist.md` §A（11 项）逐项勾选。
 
-> 不在此内联复制，以 opsx-tdd-core/checklist.md §A 为唯一真相源。
-> 额外补充：REFACTOR 任务还需执行 `opsx-tdd-rules/rules/refactor-checklist.md`（7 项重构检查点）。
+> 不在此内联复制，以 tdd-core/checklist.md §A 为唯一真相源。
+> 额外补充：REFACTOR 任务还需执行 `tdd-rules/rules/refactor-checklist.md`（7 项重构检查点）。
 
 ⛔ **TDD 节奏校验**（RED→GREEN 严格串行的执行后校验）：
 - [ ] 连续的 RED-N `task_update` 与 GREEN-N `task_update` 之间有可验证的执行间隔（建议 >60 秒），若时间戳差距过小视为批量执行信号
@@ -54,50 +54,50 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 ### §5e.2 RED 测试质量门禁（仅 test-strategy=tdd 时，RED 任务完成后强制检查）
 
-⛔ 核心原则（引用 opsx-tdd-quality/SKILL.md §2）：Mock 边界，不 Mock 行为
+⛔ 核心原则（引用 tdd-quality/SKILL.md §2）：Mock 边界，不 Mock 行为
 - [ ] 未 mock 被测行为本身
 - [ ] Mock 仅用于系统边界依赖（Mapper/HTTP）
 - [ ] RED 测试 Given 是真实输入
 
-⛔ 测试命名与结构（引用 opsx-tdd-quality/SKILL.md §3-§4）：
+⛔ 测试命名与结构（引用 tdd-quality/SKILL.md §3-§4）：
 - [ ] 测试方法名符合 `{method}_{state}_{outcome}` 格式
 - [ ] 测试包含 `// Given` / `// When` / `// Then` 注释结构
 - [ ] 一测一场景（测试方法名不含 "and"）
 
-⛔ 断言深度（引用 opsx-tdd-anti-patterns/SKILL.md §4 反模式 14）：
+⛔ 断言深度（引用 tdd-anti-patterns/SKILL.md §4 反模式 14）：
 - [ ] 每个测试至少有一个具体值断言（assertEquals），而非仅 assertNotNull
 - [ ] 异常测试使用 `assertThrows(BusinessException.class, ...)` 并验证错误码（而非 RuntimeException.class）
 
 ⛔ BEFORE 标记 RED 任务完成，必须读取：
-- opsx-tdd-anti-patterns/SKILL.md §3（RED 阶段反模式检查）
+- tdd-anti-patterns/SKILL.md §3（RED 阶段反模式检查）
 读取后确认："已检查 RED 阶段反模式"。
 
-> 完整质量门禁见 opsx-tdd-quality/SKILL.md §2-§6
-> 完整 15 种反模式见 opsx-tdd-anti-patterns/SKILL.md §3-§4
+> 完整质量门禁见 tdd-quality/SKILL.md §2-§6
+> 完整 15 种反模式见 tdd-anti-patterns/SKILL.md §3-§4
 
 ### 任务状态实时更新
 
-- [ ] tasks.md：`- [ ]` → `- [x]`（拓扑图和任务详情中的复选框）
-- [ ] 同时：`- **状态**: [ ] 未完成` → `- **状态**: [x] 已完成`
-- [ ] 两种格式同步更新，不可遗漏
+- [ ] 每个主任务只保留一条规范状态行：`- **状态**: [ ] 未完成` → `- **状态**: [x] 已完成`
+- [ ] 自动同步仅更新任务块内的 `- **状态**:` 行，不改标题复选框、场景列表或验收清单
+- [ ] “验收证据”与主任务进度分开统计；必须由真实测试、人工验收或评审证据确认，不自动勾选
 - [ ] 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
-- [ ] 记录任务级 Telemetry（`task_update`，`--task-id=<TASK-ID>` 必填，否则 E4 指标无法计算）；TDD 测试骨架任务须在 `--details-json` 带 `"task_kind":"test-skeleton"`（P3，避免红灯误判拉低 E4）
-- [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `node "$(cat .sdd-spec-root)/skywalk-sdd/index.cjs" check-task --project=. --change=<变更名称> --task-id=<TASK-ID>` 确认 tasks.md 中对应行已从 `- [ ]` 变为 `- [x]`；若未更新，手动修改 tasks.md 并报告
+- [ ] 记录严格任务事件：`task_update` 必须含 `--task-id`、`--run-id`，完成时引用成功的 green/refactor/regression `test_event_id` 并明确 `tdd_required=true/false`；测试不适用时写明 `verification_not_applicable_reason`
+- [ ] ⛔ **task_update 后必须验证状态已更新**：执行 `node "$(cat .sdd-spec-root)/skywalk-sdd/index.cjs" check-task --project=. --change=<变更名称> --task-id=<TASK-ID>`，确认对应规范状态行已变为 `[x]`
 
 ### §5f.1 apply 结束前 checkbox 全量同步校验
 
 > ⛔ 在 `stage_end` telemetry 记录前必须执行此校验，防止任务状态滞后到 archive 阶段。
 
-- [ ] 对比 telemetry `task_update` 记录的已完成任务数与 tasks.md 中 `[x]` 数量，不一致则补齐
-- [ ] tasks.md 中所有 `- [ ]` / `- [x]` 与 `**状态**: [ ]` / `[x]` 两种格式已同步
-- [ ] 手动验证清单（如有）已勾选
+- [ ] 对比 telemetry `task_update` 已完成任务数与 `primary_tasks.completed`，不一致则修正任务状态或事件
+- [ ] `acceptance_evidence` 单独报告已确认/待确认数量，不将其混入任务完成率
+- [ ] 手动验证清单（如有）仅在真实完成后勾选
 - [ ] 文档更新项（如有）已完成或显式标注推迟
 
 ---
 
 ## §6.0 单元测试真实执行自检（`test-strategy` 非 `none`）
 
-> 单元测试真实执行自检见 opsx-tdd-core/reference.md §9
+> 单元测试真实执行自检见 tdd-core/reference.md §9
 
 - [ ] 真实运行单元测试命令并留 telemetry 证据
 - [ ] `tdd`：无测试证据不得结束 apply / 不得 finish worktree
@@ -126,7 +126,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] ⛔ **DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - [ ] ⛔ **编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成
 - [ ] ⛔ **测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据
-- [ ] ⛔ **RED 测试质量门禁**：见 §5e.2（引用 opsx-tdd-quality + opsx-tdd-anti-patterns，不在此内联复制）
+- [ ] ⛔ **RED 测试质量门禁**：见 §5e.2（引用 tdd-quality + tdd-anti-patterns，不在此内联复制）
 - [ ] ⛔ **必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式（`- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]`）同步
 - [ ] ⛔ **apply 结束前 checkbox 全量同步校验**：见 §5f.1，`stage_end` 前对比 telemetry `task_update` 记录数与 tasks.md `[x]` 数量
 - [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `check-task` 确认 tasks.md 对应行已变更；未更新则手动修改

package/templates/skills/kld-sdd/opsx-apply/implementer-prompt.md

@@ -14,26 +14,26 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
 2. 编写测试代码：Given-When-Then 结构 + 真实断言
 3. 运行测试，确认失败（失败原因必须是功能未实现）
 4. 如果测试通过：说明测试无效或功能已存在，重新编写
-5. ⛔ 检查异常路径覆盖：每个 orElseThrow/边界检查须有对应测试方法（见 `opsx-tdd-rules/rules/exception-path-coverage.md`）
+5. ⛔ 检查异常路径覆盖：每个 orElseThrow/边界检查须有对应测试方法（见 `tdd-rules/rules/exception-path-coverage.md`）
 
 ⛔ BEFORE 编写测试代码，必须读取对应语言的规则文件：
-- Java：opsx-tdd-quality/rules/java/java-test-template.md + argument-matching.md + domain-service-rules.md
-- TypeScript：opsx-tdd-quality/rules/typescript/ts-test-template.md
-- Python：opsx-tdd-quality/rules/python/py-test-template.md
-- 通用：opsx-tdd-quality/rules/general/naming-conventions.md + given-when-then.md + no-logic-in-tests.md
+- Java：tdd-quality/rules/java/java-test-template.md + argument-matching.md + domain-service-rules.md
+- TypeScript：tdd-quality/rules/typescript/ts-test-template.md
+- Python：tdd-quality/rules/python/py-test-template.md
+- 通用：tdd-quality/rules/general/naming-conventions.md + given-when-then.md + no-logic-in-tests.md
 读取后在报告中列出已读取的规则文件路径。
 
 ### 执行 实现-GREEN 任务
 1. 读取对应 RED 任务的失败原因
-2. 【Scope 声明】按 `opsx-tdd-rules/rules/green-scope-declaration.md` 执行 Scope 声明步骤
+2. 【Scope 声明】按 `tdd-rules/rules/green-scope-declaration.md` 执行 Scope 声明步骤
 3. 编写最少代码——仅实现 Scope 声明中标记为"属于当前 RED"的步骤
 4. 【Scope 自检】检查生产代码中是否有未被任何当前 RED 断言覆盖的逻辑路径？有则删除
 5. 不提前实现没有测试要求的功能（YAGNI）
 6. 禁止捆绑未测试的代码（Controller/Filter/Config）
 
-> 完整执行步骤见 opsx-tdd-core/reference.md §1-§3
-> 完整质量标准见 opsx-tdd-quality/SKILL.md §2
-> Scope 声明规则见 opsx-tdd-rules/rules/green-scope-declaration.md
+> 完整执行步骤见 tdd-core/reference.md §1-§3
+> 完整质量标准见 tdd-quality/SKILL.md §2
+> Scope 声明规则见 tdd-rules/rules/green-scope-declaration.md
 
 ### 执行 重构-REFACTOR 任务
 1. 在所有测试通过的状态下开始
@@ -41,9 +41,9 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
 3. 运行**全部测试**：`mvn test`（或项目对应命令）
 4. 确认所有测试仍通过
 5. 如果任何测试失败：回退重构，重新尝试
-6. ⛔ 执行 `opsx-tdd-rules/rules/refactor-checklist.md`（7 项重构检查点）
+6. ⛔ 执行 `tdd-rules/rules/refactor-checklist.md`（7 项重构检查点）
 
-> 完整 REFACTOR 检查点见 opsx-tdd-rules/rules/refactor-checklist.md
+> 完整 REFACTOR 检查点见 tdd-rules/rules/refactor-checklist.md
 
 ## 派发格式
 
@@ -94,7 +94,7 @@ Agent (general-purpose):
     3. 遵循 overview.md 的全局规范
     4. 保持变更最小化，不超出任务范围
     5. **当任务类型为 测试-RED 时**：编写带真实断言的测试，运行并确认失败，记录失败原因
-    6. **当任务类型为 实现-GREEN 时**：读取对应 RED 的失败原因，按 `opsx-tdd-rules/rules/green-scope-declaration.md` 执行 Scope 声明，仅实现标记为"属于"的步骤，写最少代码让测试通过，不提前实现未要求的功能
+    6. **当任务类型为 实现-GREEN 时**：读取对应 RED 的失败原因，按 `tdd-rules/rules/green-scope-declaration.md` 执行 Scope 声明，仅实现标记为"属于"的步骤，写最少代码让测试通过，不提前实现未要求的功能
     7. **当任务类型为 重构-REFACTOR 时**：在测试全绿状态下优化代码，运行全部测试确认仍绿
     8. 自我审查（见下方）
     9. 报告结果

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

@@ -17,14 +17,20 @@ description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策
 ### task_update（每完成一个任务记录）
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"files_changed\":[],\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0},\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"
+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\":[]}"
 ```
 
-**⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算。
+**⚠️ 注意**：`--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`。
+
+只有文档、纯配置说明等确实不适用测试的任务，才能显式声明：
+
+```json
+{"task_update":{"verification_not_applicable":true,"verification_not_applicable_reason":"<为什么本任务无需测试的具体原因>"}}
+```
 
 **🧪 TDD 测试骨架任务（`test-strategy: tdd`）**：当任务是"测试骨架"时，`task_update` 必须在 `--details-json` 中带 `"task_kind":"test-skeleton"`。
 
-> 完整 test-skeleton telemetry 模板见 opsx-tdd-rules/rules/test-skeleton-telemetry.md
+> 完整 test-skeleton telemetry 模板见 tdd-rules/rules/test-skeleton-telemetry.md
 
 **📄 通过文件传递大 payload**：若 `details-json` 内容过长，可先写入 `"$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json`，再使用 `--details-file` 指定该文件：
 
@@ -38,47 +44,42 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --com
 node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" check-task --project=. --change=<变更名称> --task-id=<TASK-ID>
 ```
 
-**【Q3 details schema 字段说明】**：`details-json` 中的 `test_results` 和 `build_results` 字段非强制，但提供后能让 E4 一次成码率更准确：
-- `test_results`: `{ command, passed, failed, skipped, coverage, duration_ms }`
-- `build_results`: `{ command, success, duration_ms, error_count }`
-- 若 agent 只记 `--status=completed` 不带 build/test（tools 兼容），index.cjs 会 fallback 用 status=completed 作为 success=true（Q3 修复）
-
-**【L6 test_count 口径】**：`test_results.passed + failed + skipped` 含全部用例（含 cases 数组外的单独用例）。不要只计 cases 数组内数量而漏计独立用例。
+**【严格证据口径】**：测试执行事实只存在于 `test_result`；`task_update` 只表达任务状态与证据引用。旧事件仍可读取，但新事件必须使用 `--strict`。
 
-### process_note（阶段内过程事件：修复/澄清/决策/故障）
+### process_note（阶段内过程事件：决策/范围变化/故障与恢复）
 
-记录阶段内过程信息，供 execution-log 叙事与报告"过程记录"板块统计（U2 叙事信号源 / U3 修复可追溯 / M1 时长虚高旁证）。`details.kind` 必填，枚举：
+记录阶段内过程信息，供 execution-log 叙事与报告“过程记录”板块统计。新事件使用 `--strict`，`details.kind` 必填，枚举：
 
 | kind | 场景 | 示例 |
 |------|------|------|
-| `fix` | check/apply/test 后修复动作 | 补 README/CHANGELOG、勾 checkbox、修配置 |
-| `clarification` | 用户澄清/多轮交流（带 `round`） | 用户要求补充 CHANGELOG（R1/R2...） |
-| `decision` | 关键设计/实现决策 | 选方案 A 而非 B |
-| `api-error` | API 故障（M1 stage 时长虚高旁证） | Connection closed mid response |
-| `model-switch` | 换模型 | kimi-k2.7-code → glm-5.2 |
-| `manual-action` | 用户手动操作 | 用户手动改配置 |
+| `user_decision` | 用户确认关键选择 | 范围、执行模式、测试策略、方案 A/B |
+| `scope_change` | 已确认范围发生变化 | 新增或移除交付项 |
+| `api_error` | API 或外部服务故障 | 连接中断、限流 |
+| `model_error` | 模型执行故障 | 输出中断、工具调用异常 |
+| `recovery` | 对故障或失败的恢复动作 | 修复配置后重试 |
+| `test_exception` | 测试执行异常 | 环境缺依赖、超时 |
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=process_note --command=<stage> --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --summary="<人读摘要>" --details-json="{\"kind\":\"<fix|clarification|decision|api-error|model-switch|manual-action>\",\"target\":\"<可选，关联对象>\",\"round\":<可选，clarification 轮次整数>}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=process_note --command=<stage> --project=. --change=<变更名称> --capability=<capability-name> --run-id=<本次过程事件稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --summary="<人读摘要>" --details-json="{\"kind\":\"<user_decision|scope_change|api_error|model_error|recovery|test_exception>\",\"decision_type\":\"<user_decision时可填scope|mode|test_strategy|other>\",\"target\":\"<可选关联对象>\"}"
 ```
 
 **使用时机**：
-- **check 后用户选 B 补修复** → 每个修复动作记一条 `kind=fix`（U3，归档前修补不再黑箱）
-- **用户多轮澄清** → 每轮记一条 `kind=clarification` 带 `round`（1/2/3...，任意轮次可记）
-- **API 错误/换模型** → 记 `kind=api-error`/`model-switch`（M1 stage 时长虚高旁证，报告"过程记录"by_kind 体现）
-- **关键决策** → 记 `kind=decision`
+- **用户确认范围/模式/测试策略** → `kind=user_decision`，并用 `decision_type` 说明是哪类选择
+- **范围后来改变** → `kind=scope_change`
+- **API/模型/测试环境故障** → 分别记录 `api_error` / `model_error` / `test_exception`
+- **修复后恢复执行** → `kind=recovery`
 
 **必记节点清单**（遗漏即视为过程记录缺失，`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`）：
 
 | 节点 | kind | target |
 |------|------|--------|
-| 门禁拦截（apply 被门禁阻断） | `decision` | stage |
-| frontmatter/文档补齐 | `fix` | 文件:行 |
-| 编辑失败重试 | `fix` | 文件 |
-| 归档前 checkbox 勾选 | `fix` | tasks.md:行 |
-| 用户交互决策点（选 A/B/C 等） | `decision` | - |
-| API 故障 | `api-error` | - |
-| 换模型 | `model-switch` | - |
+| 门禁拦截后的处理选择 | `user_decision` | stage |
+| frontmatter/文档补齐后恢复 | `recovery` | 文件:行 |
+| 编辑失败并重试 | `recovery` | 文件 |
+| 用户交互决策点（范围/模式/测试策略） | `user_decision` | - |
+| API 故障 | `api_error` | - |
+| 模型故障 | `model_error` | - |
+| 测试环境异常 | `test_exception` | - |
 
 ### ai_adoption_review（AI 产出快照）
 
@@ -349,7 +350,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_revie
 
 ## §6.0 单元测试真实执行（`test-strategy` 非 `none`）
 
-> 单元测试真实执行见 opsx-tdd-core/reference.md §9
+> 单元测试真实执行见 tdd-core/reference.md §9
 
 当 `test-strategy` 为 `tdd` 或 `impl-first` 时，必须真实运行单元测试并留 telemetry 证据。`sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验。
 
@@ -357,7 +358,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_revie
 
 ## §6.0a 测试反模式检查（TDD 模式下）
 
-> 完整 9 种反模式检测见 opsx-tdd-anti-patterns/SKILL.md §3-§4 + reference.md
+> 完整 9 种反模式检测见 tdd-anti-patterns/SKILL.md §3-§4 + reference.md
 
 ⛔ RED 阶段就必须检查，不要等到 GREEN 之后才发现测试是假的。
 

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

@@ -35,7 +35,7 @@ allowed-tools:
 | 维度 | 内容 |
 |---|---|
 | 核心问题 | 变更生命周期结束与度量收口 |
-| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.md`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.html`、`openspec/changes/archive/<日期>-<change>/logs/execution-log.md` |
+| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.md`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.html`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.json`、`openspec/changes/archive/<日期>-<change>/logs/execution-log.md` |
 | 触发时机 | 任务完成、变更取消、变更搁置、或用户要求归档 |
 
 ---
@@ -96,9 +96,45 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
 
 即使用户选择“变更已完成实施”，未勾选项也不阻断归档。它可能代表任务真实未完成，也可能代表代码已完成但文档未同步；不要猜测，也不要静默忽略。最终必须让 `archive-docs` 将其写入 `archive_result.task_completion` 和报告。
 
-> **⚠️ P2-2 归档原因反映真实完成度**：`has_incomplete=true` 时，`archive-docs` 会自动将归档原因改写为"部分完成（N 项验收未勾选）"，**不得手动传 `--reason=变更已完成实施` 覆盖**。归档 reason 必须与 task_completion 状态一致，避免"已完成实施"与未勾选项矛盾。
+归档结果必须分别输出：
 
-> **📊 归档前 process_note（U3）**：归档前对 tasks.md checkbox 的勾选、文档补齐等修补动作，**必须**记 `process_note` 事件（`kind=fix`，`target=tasks.md:行号`），让"check 时待确认 N 项 → archive 结案 N 项"的对照可追溯。若归档前存在拦截/失败但无 `process_note`，`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`。模板见 `opsx-apply/reference.md`「process_note」。
+- `task_completion.primary_tasks`：真正的交付任务，决定“完成/部分完成”结论。
+- `task_completion.acceptance_evidence`：测试、评审、手工验收等证据的确认情况，只提示证据缺口，不冒充任务进度。
+
+仅当 `primary_tasks.has_incomplete=true` 时，归档原因才改写为“部分完成（N 个主任务未完成）”。主任务已完成但验收证据待确认时，允许归档，但最终报告必须在“需要处理”中明确提示。
+
+> **📊 归档前 process_note（U3）**：归档前对 tasks.md checkbox 的勾选、文档补齐等修补动作，**必须**记 `process_note` 事件（`kind=recovery`，`target=tasks.md:行号`），让"check 时待确认 N 项 → archive 结案 N 项"的对照可追溯。若归档前存在拦截/失败但无 `process_note`，`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`。模板见 `opsx-apply/reference.md`「process_note」。
+
+### 4.5 可选记录成熟度证据（仅有可审计证据时）
+
+如需评估 L3/L4，必须在 `archive-docs` 生成最终报告前记录标准 `maturity_evidence`。先将以下 JSON 写入 `skywalk-sdd/state/<变更名称>-maturity-evidence.json`：
+
+```json
+{
+  "maturity_evidence": {
+    "change_type": "config|document|report|composite|other",
+    "e1_actual_ms": 500,
+    "e1_target_ms": 600,
+    "e1_type_target_met": true,
+    "code_fully_spec_generated": true,
+    "generated_files": ["src/generated.js"],
+    "manual_code_lines": 0,
+    "evidence_summary": "规约生成范围与独立复核结论",
+    "reviewer": "独立评审者标识",
+    "reviewer_independence": "independent-review",
+    "review_session_id": "review-session-id",
+    "author_session_id": "author-session-id"
+  }
+}
+```
+
+然后执行：
+
+```bash
+node skywalk-sdd/log.cjs record --type=maturity_evidence --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="成熟度证据" --details-file=skywalk-sdd/state/<变更名称>-maturity-evidence.json
+```
+
+`e1_type_target_met` 必须等于 `e1_actual_ms <= e1_target_ms` 的计算结果。仅当 `code_fully_spec_generated=true` 时，`generated_files`、`manual_code_lines=0`、证据摘要和独立评审字段才可授予 L4；`review_session_id` 必须与 `author_session_id` 不同。CLI 会硬校验这些字段，只有两个布尔断言的事件不会被报告采信。
 
 ### 5. 一步执行真实归档
 
@@ -117,7 +153,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" archive-docs --project=. --chan
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
-- 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（默认同时生成 .md 与 .html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
+- 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`<name>-report.html` 与 `<name>-report.json`（三份同源报告，默认归档后 archive 目录，可用 --report-output 自定义）。
+- `archive_result` 含 `report_path`、`report_html_path`、`report_json_path`；任一 companion 写入失败须记录 telemetry 警告，主 Markdown 失败仍按现有失败策略处理。
 - 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
 
 ### 5.4 隐式注销活动变更
@@ -152,7 +189,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --com
 
 > 变更 `<name>` 已真实归档。
 > - 归档目录：`openspec/changes/archive/<日期>-<name>/`
-> - 最终报告（默认同时生成 .md + .html）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`openspec/changes/archive/<日期>-<name>/reports/<name>-report.html`
+> - 最终报告（Markdown + HTML + JSON 三产物）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`<name>-report.html`、`<name>-report.json`
 > - 执行日志：`openspec/changes/archive/<日期>-<name>/logs/execution-log.md`
 > - 知识库归档包：`openspec/changes/archive/<日期>-<name>.zip`
 > - 本体消费入口：`openspec/changes/archive/<日期>-<name>/canonical-facts.json`
@@ -199,7 +236,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=baseline_record -
 - 归档操作执行前必须让用户确认归档原因。
 - 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
 - “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
-- 最终报告由 `archive-docs` 自动生成（md+html 双产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。
+- 最终报告由 `archive-docs` 自动生成（Markdown + HTML + JSON 三产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。
+- 双周/月度周期跟踪为**归档后或项目级独立入口**，不阻塞单变更归档；示例：`node skywalk-sdd/log.cjs report --project=. --period=biweekly --date-from=YYYY-MM-DD --date-to=YYYY-MM-DD`
 - 已归档变更不要重复移动；展示已有 archive 目录和 report 路径。
 
 ---

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

@@ -14,6 +14,8 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 - [ ] `openspec/changes/<变更名称>/logs/execution-log.md` 各阶段条目齐全：propose/spec/design/task/check/apply/test/archive 的 `stage_start`/`stage_end` 闭环
 - [ ] execution-log 状态标记规范：成功 `✅OK`、部分 `🟡WARN`、失败 `❌FAIL`；未闭环阶段已修复或标记 partial
 - [ ] 无残留 Apply worktree（`git worktree list` 仅主工作区，或 telemetry 存在 `worktree_finish`+success 事件）
+- [ ] 如需评估 L3/L4，已在归档报告生成前记录标准 `maturity_evidence`；不得只提交 `e1_type_target_met` / `code_fully_spec_generated` 两个布尔断言
+- [ ] `maturity_evidence` 的 E1 实测/目标可复算；声称完整规约生成时，`generated_files` 非空、`manual_code_lines=0`，且 `review_session_id` 与 `author_session_id` 不同
 
 ## B. 归档后自检
 
@@ -24,7 +26,8 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 - [ ] `openspec/changes/archive/<日期>-<变更名称>.zip` 存在并可由知识库 `ArchivePackageReader` 读取
 - [ ] canonical facts 中每个实体/关系均能通过 `source.file`、`source.anchor_id`、`source.content_hash` 定向展开到包内原文
 - [ ] 最终报告 `openspec/changes/archive/<日期>-<变更名称>/reports/<变更名称>-report.md` 存在且含「归档结果」段
-- [ ] `reports/<变更名称>-report.md` 与 `reports/<变更名称>-report.html` 都已生成（md+html 双产物）
+- [ ] `reports/<变更名称>-report.md`、`<变更名称>-report.html` 与 `<变更名称>-report.json` 均已生成（Markdown + HTML + JSON 三产物同源）
+- [ ] `archive_result` 或报告「归档结果」段含 `report_path`、`report_html_path`、`report_json_path`
 - [ ] html 报告含 `SDD 效果度量报告` 标题与各度量章节（执行摘要/效率/质量/过程/归档结果/说明）
 - [ ] 执行日志 `openspec/changes/archive/<日期>-<变更名称>/logs/execution-log.md` 随 change 整目录迁移到 archive（含 archive 阶段 stage_start+stage_end+✅OK）
 - [ ] 正式 specs 同步到 `openspec/specs/<capability>/spec.md`