kld-sdd 2.6.16 → 2.6.21

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

@@ -153,9 +153,10 @@ if (require.main === module) {
     process.exit(0);
   }
 
-  // G4: 批量更新检测
-  if (changes.length > 3) {
-    // 安全网 2: 全部有 task_update 遥测 → check-task 合法更新，放行
+  // G4: 批量更新检测（E1 修正：不再提前退出，模式检查继续执行）
+  var skipPerTaskCheck = false;
+  if (changes.length >= 2 && hasTddTasks) {
+    // 安全网 2: 全部有 task_update 遥测 → check-task 合法更新，跳过逐个检查
     const allHaveTaskUpdate = changes.every(change =>
       events.some(e => e.type === 'task_update' && e.task_id === change.taskId));
     if (!allHaveTaskUpdate) {
@@ -164,79 +165,126 @@ if (require.main === module) {
         '⛔ 禁止批量修改任务状态。必须逐个通过 task_update → check-task 流程更新。\n' +
         `批量变更的任务: ${changes.map(c => c.taskId).join(', ')}`);
     }
-    process.exit(0); // 合法批量更新，放行
+    // E1 修正：有 task_update → 跳过逐个证据检查，但模式检查继续执行
+    skipPerTaskCheck = true;
   }
 
-  // 逐个检查
-  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 后再标记任务完成。');
-      }
-    }
+  // 逐个检查（E1 修正：批量安全网触发时跳过逐个检查，但模式检查仍执行）
+  if (!skipPerTaskCheck) {
+    for (const change of changes) {
+      const { taskId, taskType } = change;
 
-    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 后再标记任务完成。');
+      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 后再标记任务完成。');
+        }
       }
-      // 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 === '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) 遥测事件。');
+      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 | 配置 | 数据层 | 接口层 | 接口测试',
-      }));
+      // 安全网 3: unknown 类型降级为警告
+      if (taskType === 'unknown') {
+        console.log(JSON.stringify({
+          decision: 'allow',
+          message: `⚠️ [SDD TDD Rhythm Gate] 任务 ${taskId} 的类型字段无法识别，已放行。` +
+            '建议补全 **类型** 字段，可选值：测试-RED | 实现-GREEN | 重构-REFACTOR | 配置 | 数据层 | 接口层 | 接口测试',
+        }));
+      }
+      // non-tdd 类型：直接放行
     }
-    // non-tdd 类型：直接放行
+  }
+
+  // ═══ E1/E2/E3: 全局 TDD 批量执行模式检测（总是执行，不受 skipPerTaskCheck 影响） ═══
+  const batchPattern = core.detectTddBatchPattern(
+    events,
+    activeStage.timestamp,
+    newContent
+  );
+
+  if (batchPattern.has_violation && batchPattern.severity === 'critical') {
+    const criticalViolations = batchPattern.violations.filter(v => v.severity === 'critical');
+    const violationMessages = criticalViolations.map(v =>
+      `【${v.type}】${v.message}`
+    ).join('\n');
+
+    // 构建恢复引导
+    const tddTaskIds = batchPattern.tdd_events
+      .map(e => e.task_id)
+      .filter((v, i, a) => a.indexOf(v) === i);
+
+    core.blockWithReason(
+      `⛔ [SDD TDD Rhythm Gate] 检测到 TDD 批量执行违规！\n\n` +
+      `违规详情：\n${violationMessages}\n\n` +
+      `涉及任务：${tddTaskIds.join(', ')}\n\n` +
+      `━━━ 恢复步骤 ━━━\n` +
+      `1. 回退相关源代码到第一个违规任务之前的状态\n` +
+      `2. 逐对重新执行 RED→GREEN 循环（每对间隔 > 60 秒）\n` +
+      `3. 每次运行测试后记录 test_result 事件\n` +
+      `4. 全部重新执行后，再次更新 tasks.md\n\n` +
+      `注意：重新执行产生的新 test_result 事件会覆盖旧的批量事件。\n` +
+      `Hook 检查每个任务的最新事件，不会卡死。\n` +
+      `━━━━━━━━━━━━`);
+  }
+
+  if (batchPattern.has_violation && batchPattern.severity === 'warning') {
+    const warningViolations = batchPattern.violations.filter(v => v.severity === 'warning');
+    const warningMessages = warningViolations.map(v =>
+      `【${v.type}】${v.message}`
+    ).join('\n');
+    console.log(JSON.stringify({
+      decision: 'allow',
+      message: `⚠️ [SDD TDD Rhythm Gate] TDD 节奏警告：\n${warningMessages}\n` +
+        '建议检查是否批量执行了测试。',
+    }));
   }
 
   process.exit(0);

package/templates/openspec/proposal.md

@@ -13,12 +13,16 @@ delta-state: "added"
 predecessor-version: "" # added 留空；modified/removed 指向直接前序版本
 mode: "" # full=分 Capability 产物，simple=根目录精简产物
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
-# 外部需求键（默认必填 ≥1 个合规 REQ；探索性/纯内部重构可走 numbering-waiver）
+change-type: "" # config | transaction | report | composite | unknown，由 Agent 自动分类
+change-type-source: "agent-inferred"
+change-type-confidence: "" # high | medium | low
+change-type-reason: "" # 一句中文分类理由
+# 外部需求键（默认必填 ≥1 个；编号格式：大写字母+数字+连字符+下划线，例 KLERP-001、REQ-FI-2024-001；探索性/纯内部重构可走 numbering-waiver）
 requirement-refs:
   - system: requirement-mgmt
     object-type: requirement
-    external-id: REQ-<DOMAIN>-<YEAR>-<SEQ>   # 例 REQ-FI-2024-001
-    feature-id: FEAT-<DOMAIN>-<SEQ>          # 可选，需求所属功能（需求系统权威）
+    external-id: "<外部需求编号>"   # 例 KLERP-001, REQ-FI-2024-001, 1010000
+    feature-id: "<外部功能编号>"    # 可选，需求所属功能（例 FEAT-FI-012, KLERP_F-001）
 # numbering-waiver:
 #   reason: "探索性原型，本轮不种桥"
 # Continuity：字段一律来自知识库 resolve，禁止本地 archive 文件夹名

package/templates/openspec/spec.md

@@ -34,7 +34,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
-- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<YEAR>-<SEQ>:SCN-<slug>-<NNN>
+- **external-ref**: requirement-mgmt:scenario:<外部需求编号>:SCN-<slug>-<NNN>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -43,7 +43,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
-- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<YEAR>-<SEQ>:SCN-<slug>-<NNN>
+- **external-ref**: requirement-mgmt:scenario:<外部需求编号>:SCN-<slug>-<NNN>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -63,7 +63,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <新 UUID>
 - **delta-state**: <modified|added>
 - **predecessor-version**: <modified 时填写；added 为无>
-- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<YEAR>-<SEQ>:SCN-<slug>-<NNN>
+- **external-ref**: requirement-mgmt:scenario:<外部需求编号>:SCN-<slug>-<NNN>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 

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

@@ -27,18 +27,20 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止加载同级其他 Capability 的文档
 
 > **🖥️ 跨平台执行规则**
-> - **写代码**：cwd 保持在 Git 根（含 `src/`）；**文档 / telemetry**：`--project` 指向 SDD 包裹包（`node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root` 可查看）。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包）。
+> - **写代码**：cwd 保持在 Git 根（含 `src/`）；**文档 / telemetry**：`--project` 指向 SDD 包裹包（`node <spec-package>/skywalk-sdd/spec-root.cjs` 可获取）。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始 / 阶段结束 / `task_update` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
+> - 阶段开始 / 阶段结束 / `task_update` / `final_output_snapshot` / `ai_adoption_review` / `worktree_finish` 的**完整命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
 > - 不得跳过任何 telemetry 记录；`task_update` 的 `--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算；TDD 测试骨架任务须在 `--details-json` 带 `"task_kind":"test-skeleton"`（P3，详见 `./reference.md`）。
 > - 较大的 `--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」。
 > - **严格证据链**：一次真实测试执行只写一条严格 `test_result`；任务完成事件只通过 `test_event_id` 引用成功的 green/refactor/regression 测试，并明确 `tdd_required=true/false`，不复制测试计数。测试不适用时必须写明原因。完整 schema 见 `./reference.md`。
+> - **任务涉及文件必记**：每条严格 `task_update` 必须在 `task_update.files` 写本任务实际修改的仓库相对路径；本任务确实没有改文件时，改填具体的 `no_file_change_reason`。两者至少有一个。
+> - **最终交付文件必记**：apply 所有文件就绪后记录严格 `final_output_snapshot`，其中 `final_output_snapshot.files` 是最终交付文件的仓库相对路径清单。报告把它与逐任务文件分开说明；旧 `ai_adoption_review.ai_diff.files` 只作兼容来源。
 > - **process_note 必记**：用户决策、范围变化、API/模型/测试异常及恢复动作必须写严格 `process_note`；范围、模式、测试策略选择统一用 `kind=user_decision` 并标注 `decision_type`。
 
 > **🔒 Git 策略（只读增强，不改变开发流）**
@@ -254,9 +256,9 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 
 此自检确保 tasks.md 的 checkbox 与实际代码状态完全同步。
 
-### 5.1 【Telemetry 必做】记录 AI 产出快照
+### 5.1 【Telemetry 必做】记录最终交付文件与 AI 产出快照
 
-当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。**完整命令模板与说明见 `./reference.md`「§5.1 记录 AI 产出快照」**。
+当前 Capability 的全部文件就绪后，先记录 `final_output_snapshot` 作为“最终交付文件”权威口径；如需 AI 采纳率指标，再记录 `ai_adoption_review`。不得为了采集快照自动提交 commit。**完整命令模板与说明见 `./reference.md`「§5.1 记录最终交付文件与 AI 产出快照」**。
 
 ### 6. 完成或暂停时显示状态
 
@@ -316,6 +318,6 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 ## 渐进披露
 
 - Read `checklist.md` 仅在执行 apply 需要校验门禁/自检时 — 含 §1.2 Check 门禁检查点、§5d/§5e 编译/测试门禁自检、§5e.1 TDD 节奏校验、§5f.1 checkbox 全量同步校验、§6.0 单元测试真实执行自检、§6.1 worktree 收尾前置条件、Guardrails ⛔ 强制项勾选表。
-- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end/task_update/ai_adoption_review/worktree_finish）、§1.5 worktree 全套策略（Step 0.1-3 + record-base + 多 cap 合并顺序）、§5c 子代理派发、§5.1 AI 产出快照、§6.0 单元测试、§6.1 worktree 收尾脚本。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end/task_update/final_output_snapshot/ai_adoption_review/worktree_finish）、§1.5 worktree 全套策略（Step 0.1-3 + record-base + 多 cap 合并顺序）、§5c 子代理派发、§5.1 最终交付文件与 AI 产出快照、§6.0 单元测试、§6.1 worktree 收尾脚本。
 - `implementer-prompt.md` 为子代理派发提示模板（§5c 派发时组合 tasks/design/overview 上下文使用）。
 - `worktree-setup.md` 为 worktree 快速参考（§1.5 策略的精简版，与 reference.md §1.5 完整版并存：reference=完整策略，worktree-setup=快速参考）。

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

@@ -82,6 +82,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] “验收证据”与主任务进度分开统计；必须由真实测试、人工验收或评审证据确认，不自动勾选
 - [ ] 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
 - [ ] 记录严格任务事件：`task_update` 必须含 `--task-id`、`--run-id`，完成时引用成功的 green/refactor/regression `test_event_id` 并明确 `tdd_required=true/false`；测试不适用时写明 `verification_not_applicable_reason`
+- [ ] 每条 `task_update` 已记录本任务实际修改的 `files`；确实无文件修改时已填写具体 `no_file_change_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 全量同步校验
@@ -92,6 +93,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] `acceptance_evidence` 单独报告已确认/待确认数量，不将其混入任务完成率
 - [ ] 手动验证清单（如有）仅在真实完成后勾选
 - [ ] 文档更新项（如有）已完成或显式标注推迟
+- [ ] 所有文件就绪后已记录严格 `final_output_snapshot`：`snapshot_kind=final`，`vcs_mode=readonly|no-git`，`files_changed` 等于 `files` 去重数量，新增/删除行数符合 VCS 模式；无交付文件时 `files=[]`、`files_changed=0` 且有具体 `no_output_reason`
 
 ---
 

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

@@ -17,7 +17,7 @@ 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>,\"tdd_pair_id\":\"<pair-N>\",\"tdd_role\":\"green\"},\"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\":[\"<本任务实际修改的仓库相对路径>\"]}}"
 
 也可互斥使用 `test_run_id`（同 change、覆盖当前任务、唯一严格完成候选）；解析成功后会补齐规范化 `test_event_id`。
 ```
@@ -27,9 +27,17 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_upd
 只有文档、纯配置说明等确实不适用测试的任务，才能显式声明：
 
 ```json
-{"task_update":{"verification_not_applicable":true,"verification_not_applicable_reason":"<为什么本任务无需测试的具体原因>"}}
+{"task_update":{"verification_not_applicable":true,"verification_not_applicable_reason":"<为什么本任务无需测试的具体原因>","files":["<本任务实际修改的仓库相对路径>"]}}
 ```
 
+若本任务只完成分析、验证或等待，没有修改任何文件，必须明确写：
+
+```json
+{"task_update":{"no_file_change_reason":"<本任务为何没有修改文件的具体原因>"}}
+```
+
+`task_update.files` 与 `no_file_change_reason` 至少提供一个；不要用空数组掩盖未采集。
+
 **🧪 TDD 测试骨架任务（`test-strategy: tdd`）**：当任务是"测试骨架"时，`task_update` 必须在 `--details-json` 中带 `"task_kind":"test-skeleton"`。
 
 > 完整 test-skeleton telemetry 模板见 tdd-rules/rules/test-skeleton-telemetry.md
@@ -37,7 +45,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_upd
 **📄 通过文件传递大 payload**：若 `details-json` 内容过长，可先写入 `"$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json`，再使用 `--details-file` 指定该文件：
 
 ```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-file="$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json"
+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-file="$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json"
 ```
 
 **✅ 验证 checkbox 已更新**：`task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的任务 checkbox。需要显式校验时可执行：
@@ -124,7 +132,17 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=process_
 | 模型故障 | `model_error` | - |
 | 测试环境异常 | `test_exception` | - |
 
-### ai_adoption_review（AI 产出快照）
+### final_output_snapshot（最终交付文件）
+
+所有实现、测试和文档文件就绪后记录一次严格最终快照：
+
+```bash
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=final_output_snapshot --command=apply --project=. --change=<变更名称> --capability=<capability-name> --run-id=<最终快照稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success --summary="最终交付文件快照" --details-json="{\"final_output_snapshot\":{\"snapshot_kind\":\"final\",\"vcs_mode\":\"<readonly|no-git>\",\"files\":[\"<仓库相对路径1>\",\"<仓库相对路径2>\"],\"files_changed\":<N>,\"added_lines\":<只读Git统计值或null>,\"deleted_lines\":<只读Git统计值或null>}}"
+```
+
+这是报告“最终交付文件”的权威来源。`files_changed` 必须等于 `files` 去重后的数量；`vcs_mode=readonly` 时新增/删除行数必须是非负整数，`vcs_mode=no-git` 时两者可为 `null`。确实没有交付文件时，使用空 `files`、`files_changed=0` 并补充具体 `no_output_reason`。清单只能使用仓库相对路径，不得使用绝对路径或 `..`。旧 `ai_adoption_review.ai_diff.files` 继续兼容读取，但新流程不得用逐任务文件清单冒充最终交付快照。
+
+### ai_adoption_review（AI 产出快照，采纳率兼容口径）
 
 当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
 
@@ -372,9 +390,13 @@ Agent("实现 TASK-03: 创建权限数据模型", ...)
 
 ---
 
-## §5.1 记录 AI 产出快照
+## §5.1 记录最终交付文件与 AI 产出快照
 
-当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+当前 Capability 的全部文件就绪后，必须先记录 `final_output_snapshot`；如需 AI 采纳率指标，再记录 `ai_adoption_review`。不得为了采集快照自动提交 commit。
+
+```bash
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=final_output_snapshot --command=apply --project=. --change=<变更名称> --capability=<capability-name> --run-id=<最终快照稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success --summary="最终交付文件快照" --details-json="{\"final_output_snapshot\":{\"snapshot_kind\":\"final\",\"vcs_mode\":\"<readonly|no-git>\",\"files\":[\"<仓库相对路径1>\",\"<仓库相对路径2>\"],\"files_changed\":<N>,\"added_lines\":<只读Git统计值或null>,\"deleted_lines\":<只读Git统计值或null>}}"
+```
 
 > **⚠️ 采集时序（N1）**：`ai_adoption_review` 应在 apply 收尾、**所有文件就绪后**采集（含 README/CHANGELOG/dist 产物/后补文件），确保 `ai_diff.files_changed` 完整。若采集后又补文件，须补录 `--status=final` 事件更新快照，避免 ai_snapshot 时序不全导致 ai_diff 缺漏。
 
@@ -387,7 +409,7 @@ Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git`
 node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=ai_snapshot --result=success --summary="AI 代码产出快照" --details-json="{\"ai_adoption\":{\"review_status\":\"ai_snapshot\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"ai_diff\":{\"files_changed\":<N>,\"files\":[\"<产出文件路径1>\",\"<产出文件路径2>\"],\"added_lines\":<git_diff_numstat_HEAD_取值或0>,\"deleted_lines\":<同左>},\"notes\":\"未自动提交 commit；vcs_mode=readonly 时 added_lines 用只读 git diff --numstat HEAD 取值（不得填 null，工具侧硬校验）；vcs_mode=no-git 时可填 null\"}}"
 ```
 
-> 该命令亦见上文「📊 Telemetry 命令模板 → ai_adoption_review」。
+> 两种命令亦见上文「📊 Telemetry 命令模板 → final_output_snapshot / ai_adoption_review」。
 
 ---
 

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

@@ -17,14 +17,15 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
-> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
+> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并确认 KB 已配置（配置由 `opsx-kb-config` 负责）。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
 
 > **跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
+> - **PowerShell 禁忌**（Windows 用户必读）：禁止 `| cat`（直接执行或用 `node -e`）；禁止 `curl`（HTTP 请求走 `context-client.cjs` / `kb-upload.cjs` 或用 `Invoke-RestMethod`）；禁止 `Get-Content` / `Out-File` 读写 JSON（用 write_to_file 工具或 Node.js `fs`，避免 BOM 污染）。
 > - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。
 > - 本技能不调用 OpenSpec 自带归档命令；统一使用 SkyWalk-SDD 的 `archive-docs`。
 
@@ -169,8 +170,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" active-change --remove
 
 ### 5.5 收尾入库（opsx-kb-ingest）
 
-1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；按该技能完成 API Key / targets。
-2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；成功则写 `ingest-receipt.json`。
+1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；KB 配置（API Key / targets / project-identity.json）由 `opsx-kb-config` 统一负责，如未配置则提示运行 `/opsx-kb-config`。
+2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；也可直接使用 `kb-upload.cjs --package=<zip路径>` 上传；成功则写 `ingest-receipt.json`。
 3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
 
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。

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

@@ -4,10 +4,10 @@ description: "质量检查技能 - 验证文档完整性、一致性、算法正
 argument-hint: "[change-name] [上下文文件...]"
 license: MIT
 compatibility: Requires openspec CLI; depends on opsx-ontology-query for external-key validation and baseline checks.
-  depends-on: opsx-ontology-query
 metadata:
   author: sdd-team
   version: "3.0"
+  depends-on: opsx-ontology-query
 allowed-tools:
   - Bash
   - Read
@@ -26,21 +26,22 @@ allowed-tools:
 > 即使检查发现代码相关问题，也只记录在检查报告中，**不自动修复代码**。
 > 代码修复将在 `/opsx-apply` 阶段进行。
 
-> **KB 上下文**：check 阶段需验证外部键格式（REQ/FEAT/SCN 文法）、SCN REQ 前缀一致性和历史覆盖率基线。进入相关步骤前先 `Read` `opsx-ontology-query/phase-2-during.md` §3-5，并按 `SKILL.md` → Session 启动准备 API Key + targets。
+> **KB 上下文**：check 阶段需验证外部键格式（requirement/feature/scenario 文法）、SCN 需求编号前缀一致性和历史覆盖率基线。进入相关步骤前先 `Read` `opsx-ontology-query/phase-2-during.md` §3-5，并按 `SKILL.md` → Session 启动准备 API Key + targets。
 >
 > **📡 KB 就绪检查**：§2.6 在进入 KB 相关检查前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，KB 相关检查项降级为仅本地验证。
 
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 检查报告生成后，必须先记录结构化检查结果：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"warning_dispositions\":[{\"warning\":\"<稳定编号>\",\"disposition\":\"fixed|accepted|waived|needs_input|open\",\"reason\":\"<处置依据>\"}],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"reviewer\":\"<reviewer-identifier>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply会话ID或unknown>\",\"reviewer_independence\":\"independent-review|self-review|unknown\",\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
+> - 下方 `check_result` 命令中的 `0` 是待替换位置，禁止原样照抄；写入前必须用本轮实测值替换，且顶层 `total` 必须是大于 0 的整数，否则 strict 记录会拒绝该事件。
+> - 检查报告生成后，必须先记录结构化检查结果：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --run-id=<本轮Check稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"warning_dispositions\":[{\"warning\":\"<稳定编号>\",\"disposition\":\"fixed|accepted|waived|needs_input|open\",\"reason\":\"<处置依据>\"}],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"reviewer\":\"<reviewer-identifier>\",\"review_execution_mode\":\"<subagent|main-agent-fallback>\",\"reviewer_agent_id\":\"<子代理真实ID；主Agent回退时填null>\",\"parent_session_id\":\"<父会话ID；主Agent回退时可填null>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply真实会话ID；无法确认时仅允许主Agent回退填unknown>\",\"reviewer_independence\":\"<independent-review|self-review|unknown>\",\"fallback_reason_code\":\"<主Agent回退时五类稳定码之一；子代理成功时填null>\",\"fallback_reason\":\"<主Agent回退时具体中文原因；子代理成功时填null>\",\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
 > - `check_result` 记录成功后，才允许阶段结束：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="摘要"`
 > - **【B1 摘要数字校验】** `stage_end --summary` 中的数字（如「N 个场景」「N 层 DAG」「N 个任务」）必须与 `spec.md`/`tasks.md`/`test-scenarios.md` 的实统计交叉校验一致后再填写，不得凭记忆自填。典型失真：summary 写「11 个场景」实际 spec 含 13 条断言、「5 层 DAG」实际 tasks 修复后为 6 层。check 阶段发现不一致时，修正 summary 或补齐文档，使三者数字自洽。
 
@@ -76,6 +77,29 @@ openspec list
 - `specs/<capability>/design.md`（实现方案）
 - `specs/<capability>/tasks.md`（或 task.md，兼容旧格式）（任务拆解）
 
+### 2.1 默认使用一个独立子代理评审
+
+Check 默认启动且只启动 **一个独立子代理**。主 Agent 先确定待检查的最终文档路径、作者会话 ID 和固定输出结构，再让子代理直接读取这些最终产物；不得先把主 Agent 的判断摘要喂给子代理，也不得让评审子代理再次启动子代理或递归委派。
+
+${CHECK_REVIEW_DELEGATION_GUIDANCE}
+
+正常路径：
+
+1. 启动一个全新评审上下文，记录 `reviewer_agent_id`、`parent_session_id` 和 `review_session_id`。
+2. 子代理独立执行完整性、一致性、可执行性、算法正确性和 TDD 合规检查。
+3. 主 Agent 只校验返回结构、展示原始结论并记录事件，不得把主 Agent 身份写成子代理身份。
+4. 只有 `review_execution_mode=subagent`、评审者身份存在、评审会话与作者会话不同且 `reviewer_independence=independent-review` 时，Q3 才是“已独立验证”。
+
+只有子代理能力不可用或调用失败时，主 Agent 才执行同一检查。回退必须记录 `review_execution_mode=main-agent-fallback`、通俗原因，并从以下标准原因中选择一个：
+
+- `SUBAGENT_CAPABILITY_UNAVAILABLE`：当前 Agent 环境没有子代理能力。
+- `SUBAGENT_PERMISSION_DENIED`：权限策略不允许启动子代理。
+- `SUBAGENT_START_FAILED`：子代理启动失败。
+- `SUBAGENT_TIMEOUT`：子代理超时未返回。
+- `SUBAGENT_RESULT_INVALID`：子代理结果缺字段或无法解析。
+
+回退时 `reviewer_independence` 只能是 `self-review` 或 `unknown`，Q3 仍可计算，但必须显示“由主 Agent 自查，未经过独立复核”及具体回退原因。
+
 ### 2.5 【多仓库关联配置诊断】（在五维检查之前）
 
 先执行轻量配置诊断，**不执行代码 diff**，只检查命名与引用配置：
@@ -129,15 +153,15 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --proj
 3. **若已配置** → 直接进入 §3，正常使用 KB 做 coverage 基线、predecessor 预检。
 4. **若未配置** → 使用 **AskUserQuestion** 询问：
 
-   > "📡 **Engineering KB 未配置**
+   > "📡 **知识库未配置**
    >
-   > KB 可以提供覆盖率基线检查、predecessor 版本预检（防止入库冲突）。是否现在配置？
+   > 知识库可以帮你做覆盖率基线检查和版本冲突预检。现在要配置吗？
    >
-   > - A. **配置 KB**
-   > - B. **跳过 KB**，仅执行本地检查（semantic-check + external-key 格式校验），入库前无 predecessor 预检
-   > - C. **取消操作**"
+   > - A. **现在配置** — 运行 /opsx-kb-config
+   > - B. **暂不配置，先继续** — 仅做本地检查（不检查版本冲突）
+   > - C. **取消** — 终止本次操作"
 
-   - **选 A** → 配置 → 进入 §3。
+   - **选 A** → 引导运行 `/opsx-kb-config`，配置完成后进入 §3。
    - **选 B** → KB 相关检查项降级：coverage 基线跳过、`current-version` 预检跳过。检查报告中标注 `kb: degraded(by-user-choice)`。
    - **选 C** → 终止 check。
 
@@ -248,16 +272,24 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
 - `reviewer`: 执行本次 check 的代理或会话标识。
 - `review_session_id`: 当前 check 会话 ID（与 `--session-id` 一致）。
 - `author_session_id`: 文档作者或 apply 阶段会话 ID；无法确定时填 `unknown`。
-- `reviewer_independence`: `independent-review`（独立 evaluator 且会话与作者不同）| `self-review` | `unknown`。优先使用独立 evaluator；不可用时继续检查但标 `self-review` 或 `unknown`，报告中 Q3 为 `provisional`。
+- `review_execution_mode`: `subagent` 或 `main-agent-fallback`。
+- `reviewer_agent_id`: 独立子代理或独立任务标识；主 Agent 回退时省略。
+- `parent_session_id`: 启动子代理的主会话 ID。
+- `review_session_id`: 独立评审会话 ID；主 Agent 回退时为当前检查会话。
+- `author_session_id`: 文档作者会话 ID。
+- `reviewer_independence`: `independent-review` | `self-review` | `unknown`。
+- `fallback_reason_code` / `fallback_reason`: 仅主 Agent 回退时填写，原因码必须来自 §2.1 的五个标准值。
 - `categories`: 至少包含 `completeness`、`consistency`、`executability`。
 - `task_completion`: 从 `tasks-status` 输出整理而来；未进入 apply 时 `checked_for_archive_readiness=false`。
 
+下面命令中的 `0` 仅表示待填数字的位置，执行前必须全部换成本轮实测值；顶层 `total` 必须是大于 0 的整数。禁止为了通过校验而编造计数。
+
 在终端执行（必须成功）：
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"reviewer\":\"<reviewer-identifier>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply会话ID或unknown>\",\"reviewer_independence\":\"independent-review|self-review|unknown\",\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --run-id=<本轮Check稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"reviewer\":\"<reviewer-identifier>\",\"review_execution_mode\":\"<subagent|main-agent-fallback>\",\"reviewer_agent_id\":\"<子代理真实ID；主Agent回退时填null>\",\"parent_session_id\":\"<父会话ID；主Agent回退时可填null>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply真实会话ID；无法确认时仅允许主Agent回退填unknown>\",\"reviewer_independence\":\"<independent-review|self-review|unknown>\",\"fallback_reason_code\":\"<主Agent回退时五类稳定码之一；子代理成功时填null>\",\"fallback_reason\":\"<主Agent回退时具体中文原因；子代理成功时填null>\",\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0},\"tdd_compliance\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
 ```
 
-> **⚠️ P1-1 check_result details 不得为空**：`--details-json` 必须含 `categories` / `task_completion` / reviewer 独立性字段等，**禁止传空对象 `{}`**。空 details 导致 Q3 不可计算（工具侧虽有 state fallback 兜底，但事件 details 是主数据源）。
+> **⚠️ P1-1 check_result details 不得为空**：`--details-json` 必须含正整数 `total`、非负整数 `errors`、四类 `categories`、计数自洽的 `task_completion` 和 reviewer 独立性字段等，**禁止传空对象 `{}`**。空 details 导致 Q3 不可计算，并会被 strict 记录直接拒绝；历史非 strict 事件仍按兼容口径读取。
 
 > **⚠️ P2-3 check 纳入 task_completion 判定**：执行 `tasks-status` 后，若 `has_incomplete=true`，`check_result` 的 `--result` 应标 `partial` 并在 `warning_items` 记录未勾选项（`{category:"task_completion", description:"N 项验收未勾选", target:"tasks.md:行号"}`）。不阻断 apply（P4 已与 fixRate 解耦），但反映真实完成度。
 
@@ -274,9 +306,9 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
 > - `assertions[].judge_status` 枚举：`matched` / `partial` / `missed`
 > - `assertions[].human_status` 枚举：`matched` / `partial` / `missed` / 省略（默认跟随 judge_status）
 
-> **reviewer 与 reviewer_independence 说明（check_result）**：执行 check 前先读取文档作者/阶段会话信息；**能使用独立 evaluator 时必须使用**。`reviewer_independence=independent-review` 且 `review_session_id` 与 `author_session_id` 不同时，Q3 为 `verified`；自评或无法确认时为 `self-review` 或 `unknown`，Q3 标 `provisional` 但仍可计算分数。
+> **reviewer 与 reviewer_independence 说明（check_result）**：执行 check 前先读取文档作者/阶段会话信息；默认启动且只启动一个独立子代理。仅当 `review_execution_mode=subagent`、`reviewer_agent_id` 存在、`reviewer_independence=independent-review` 且 `review_session_id` 与 `author_session_id` 不同时，Q3 才为 `verified`；主 Agent 回退或无法确认时 Q3 标 `provisional` 但仍可计算分数。
 
-> **报告用语**：`verified` 展示为“已验证”，表示有独立复核；`provisional` 展示为“临时”，表示已有数值但仍需独立复核。不得仅用颜色区分，也不得把临时结果写成最终可信结论。
+> **报告用语**：`verified` 展示为“已独立验证”；`provisional` 展示为“已有计算结果，尚未独立验证”。不要使用 “self-review” 作为用户可见说明；应写成“由主 Agent 自查，未经过独立复核”。不得仅用颜色区分，也不得把尚未独立验证的结果写成最终可信结论。
 
 > **reviewer 与 reviewer_independence 说明（conformance_review）**：`reviewer` 用于标识实际执行本次符合度评审的代理或会话（例如 agent 名称、会话 ID）。渲染报告时会比较 `reviewer` 与 apply 阶段记录的 `apply_agent`：若两者相同，则 `reviewer_independence` 显示为 `self-review`；否则显示为 `independent-review`。建议尽可能由独立评审方执行 check，以提升结果可信度。
 
@@ -310,7 +342,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
 - 决议缺失 / pending / 与产物不一致 → `CONTINUITY_DECISION_REQUIRED`
 - **编号诊断码**（并入五维报告与 apply gate）：
   - `EXTERNAL_KEY_FORMAT_INVALID` — external_id / feature_id 不合规
-  - `EXTERNAL_KEY_SCOPE_MISMATCH` — 场景键 REQ 前缀不在 `requirement-refs`
+  - `EXTERNAL_KEY_SCOPE_MISMATCH` — 场景键需求编号前缀不在 `requirement-refs`
   - `EXTERNAL_KEY_FEATURE_UNDECLARED` — feature↔requirement.`feature_id` 配对断裂
   - `EXTERNAL_KEY_SEQ_REUSED` — 本 Change 内 SCN 重复或复用 removed 墓碑号
   - `NUMBERING_WAIVER_ACTIVE`（warning）— 豁免生效，本轮不种桥