kld-sdd 2.4.19 → 2.5.0

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

@@ -0,0 +1,403 @@
+---
+description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策略、子代理派发、收尾脚本。仅在需要参考详细模板时读取。
+---
+
+# opsx-apply — 详细参考（reference）
+
+> 本文件承载 opsx-apply 的重细节模板：telemetry 命令、§1.5 worktree 全套策略、§5c 子代理派发、§5.1 AI 产出快照、§6.0 单元测试真实执行、§6.1 worktree 收尾脚本。
+> SKILL.md 保留入口骨架与指针；本文件为完整策略来源。`./worktree-setup.md` 为 worktree 快速参考，与本文件 §1.5 并存（reference=完整策略，worktree-setup=快速参考）。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+### task_update（每完成一个任务记录）
+
+```bash
+node 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}}"
+```
+
+**⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算。
+
+**🧪 TDD 测试骨架任务（`test-strategy: tdd`）**：当任务是"测试骨架"（仅编写测试用例、实现尚未编写，测试预期失败/红灯）时，`task_update` 必须在 `--details-json` 中带 `"task_kind":"test-skeleton"`，`--result=success`（骨架按 TDD 计划完成即成功），`test_results.failed` 如实记录红灯数。这样 E4 一次成码率不会把 TDD 预期红灯误判为成码失败（P3）。实现任务不带 `task_kind`（默认 implementation），按真实测试结果记录。
+
+TDD 测试骨架任务示例：
+
+```bash
+node 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> 测试骨架完成（TDD 红灯）" --details-json="{\"task_kind\":\"test-skeleton\",\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":<红灯数>,\"skipped\":0,\"duration_ms\":0}}"
+```
+
+**📄 通过文件传递大 payload**：若 `details-json` 内容过长，可先写入 `skywalk-sdd/state/<变更名称>-task-update.json`，再使用 `--details-file` 指定该文件：
+
+```bash
+node 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=skywalk-sdd/state/<变更名称>-task-update.json
+```
+
+**✅ 验证 checkbox 已更新**：`task_update` 记录成功后会自动调用 `check-task` 更新 `tasks.md` 中的任务 checkbox。需要显式校验时可执行：
+
+```bash
+node 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 数组内数量而漏计独立用例。
+
+### process_note（阶段内过程事件：修复/澄清/决策/故障）
+
+记录阶段内过程信息，供 execution-log 叙事与报告"过程记录"板块统计（U2 叙事信号源 / U3 修复可追溯 / M1 时长虚高旁证）。`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` | 用户手动操作 | 用户手动改配置 |
+
+```bash
+node 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 轮次整数>}"
+```
+
+**使用时机**：
+- **check 后用户选 B 补修复** → 每个修复动作记一条 `kind=fix`（U3，归档前修补不再黑箱）
+- **用户多轮澄清** → 每轮记一条 `kind=clarification` 带 `round`（1/2/3...，任意轮次可记）
+- **API 错误/换模型** → 记 `kind=api-error`/`model-switch`（M1 stage 时长虚高旁证，报告"过程记录"by_kind 体现）
+- **关键决策** → 记 `kind=decision`
+
+**必记节点清单**（遗漏即视为过程记录缺失，`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` | - |
+
+### ai_adoption_review（AI 产出快照）
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+
+> **【Q4 details key 规范】**：`--details-json` 中的顶层 key **必须是 `ai_adoption`**（不是 `ai_adoption_review`）。index.cjs 工具侧已兼容三 key（`ai_adoption` / `ai_code_adoption` / `ai_adoption_review`），但 skill 侧规范统一用 `ai_adoption` 以确保 P2 指标正确采集。若旧事件用了 `ai_adoption_review` key 也能正常读取（向后兼容）。
+
+> **⚠️ 采集时序（N1）**：`ai_adoption_review` 应在 apply 收尾、**所有文件就绪后**采集（含 README/CHANGELOG/dist 产物/后补文件），确保 `ai_diff.files_changed` 完整。若采集后又补文件，须补录 `--status=final` 事件更新快照，避免 ai_snapshot 时序不全导致 ai_diff 缺漏。
+
+- `--status=ai_snapshot` 用于记录 AI 初始产出快照，P2 指标在无 final 事件时会使用此快照数据
+- 若用户进行了人工 review 并确认保留率，可补录 `--status=final` 事件（`review_status: "final"`），P2 指标将优先使用 final 数据
+
+Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：
+
+```bash
+node 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\"}}"
+```
+
+### worktree_finish（收尾 Telemetry，推荐）
+
+```bash
+node skywalk-sdd/log.cjs record --type=worktree_finish \
+  --command=apply --project=. --change=<变更名称> --capability=<capability-name> \
+  --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> \
+  --result=success --summary="merge+remove completed" \
+  --details-json='{"integration_base":"<branch>","merge_commit":"<sha>","worktree_removed":true}'
+```
+
+---
+
+## §1.5 本地并行 — Worktree 与工作区（建议性策略）
+
+> **目标（本质）**：在**本地仓库**加快 SDD Apply——让**解耦**的 spec/capability 可以各自实现、互不踩目录，做完再按依赖顺序合并回你**当时所在的分支**（集成分支，如 `hotfix-1`）。
+>
+> **不是**：保护 `master`、不是「主分支只放文档」、不是远程流水线分支策略。一切基于**本地 Git + 本地 worktree**。
+
+### 两层并行（不要混为一谈）
+
+| 层级 | 手段 | 适用 |
+|------|------|------|
+| **Capability 级**（跨 spec） | 每个解耦的 capability **单独**跑一次 `/opsx-apply` + **独立** worktree/apply 分支 | proposal 中能力**可并行**、无文件/接口/数据强依赖 |
+| **Task 级**（cap 内） | **同一** worktree 内，DAG 同层子代理并行 | tasks.md 同层任务不改相同文件 |
+
+- 本技能单次仍只实施**一个** capability；「多 spec 并行」= 多个 apply 会话 + 多个 worktree，不是一次加载多个 capability 文档。
+- §5 子代理并行 **不** 再建 worktree；Capability 级并行在 §1.5 决定「本次是否建 worktree」。
+
+### 何时建议建 worktree / 按 capability 切分支？（模型判断，非强制）
+
+**倾向创建**（full 模式常见：`.worktrees/apply-<change>-<capability>` + `kld-sdd/<change>/<capability>`）：
+
+- `proposal.md` §3 中该 capability 与并行中的其他能力**无**「修改同一模块 / 共享表 / 必须先合入」等描述
+- `design.md` 显示文件路径、包、表与并行中的其他 cap **基本不重叠**
+- 用户需要在**同一集成分支**上并行推进多个 cap，且机器资源允许（多份 `node_modules`）
+
+**倾向不建 / 串行 apply**（仍在集成分支上改，或只开一个 worktree）：
+
+- proposal 写明 capability **依赖**（B 依赖 A 已合入）
+- 多 cap 改**同一文件/模块/配置**（merge 冲突几乎必然）
+- 数据库迁移、公共类型、单例注册等**顺序敏感**
+- 已有另一个 capability 的 worktree **尚未 finish merge** 到集成分支，且当前 cap 需要基于**最新**集成结果开发
+- 沙箱禁止 `git worktree add` → 回退当前目录 + 功能分支，并告知用户
+
+**full 模式「一 capability 一分支」**：是**命名与目录约定 + 建议**，须先通过下方 **§1.5 Step 0.1 校验** 再命名/建 worktree。simple 模式通常**一 change 一 worktree**。
+
+### Step 0.1 【必做】分支/隔离校验（早于 record-base 与 `git worktree add`）
+
+> 在建议分支名 `kld-sdd/<change>/<capability>` 或创建 worktree **之前**，用 `proposal.md` + 各 capability **spec 依赖信息** 做交叉校验。未通过则**不**按 full 并行策略拆分支，改为串行或本次不建 worktree。
+
+**Step A — 读变更级能力清单（允许读 proposal，不读其它 cap 的 design/tasks）**
+
+从 `changes/<change-name>/proposal.md` 提取：
+
+| 字段 | 用途 |
+|------|------|
+| frontmatter `mode` | `full` → 倾向 `apply-<change>-<cap>`；`simple` → 倾向 `apply-<change>` |
+| §3.1 / §3.2 能力列表 | 本 change 下全部 capability 名 |
+| §4.2 依赖关系图 | 能力间先后 / 上下游 |
+| §5.3 前置依赖 checkbox | 未满足则当前 cap 不宜并行 |
+
+**Step B — 读当前 capability 的 spec 依赖（§2 正式加载前仅此文件）**
+
+读取**当前** capability 的 `spec.md`（路径按 mode）：
+
+- **full**：`changes/<change>/specs/<capability>/spec.md` 或 `openspec/changes/.../specs/<capability>/spec.md`（以项目实际为准）
+- **simple**：`changes/<change>/spec.md`
+
+只重点读 spec 中：**能力边界 / 涉及模块 / §4 内部与外部依赖**（是否写明依赖其它 capability、共享表、必须先发布的接口）。
+
+**Step C — 跨 capability 轻量交叉（隔离例外，仅本节）**
+
+对 §3 中**其它** capability，**只**读取其 `spec.md` 的：
+
+- 标题与能力简述
+- **§4 依赖**（是否依赖 `<当前 capability>` 或其它 cap）
+- **涉及模块 / 数据表 / 公共配置**（若有）
+
+⛔ 禁止为校验而加载其它 cap 的 `design.md`、`tasks.md`（完整实施上下文仍遵守 §2 隔离红线）。
+
+**Step D — 判定矩阵（输出给用户）**
+
+| 校验项 | 不通过时的处理 |
+|--------|----------------|
+| proposal §4.2 / §5.3 写明当前 cap **依赖** 未完成的其它 cap | **串行**：先 finish 上游，再 apply 当前；不并行拆分支 |
+| 其它 cap 的 spec 写明 **依赖当前 cap** 且当前 cap 未 finish | 当前可并行实施，但提醒下游须等本次 finish |
+| 多 cap spec 出现**相同模块路径 / 同表 / 同配置文件** | **不并行** worktree；串行或合并为一个 apply 范围 |
+| 当前 cap spec §4 要求接口/表已由其它 cap 提供 | 若其它 cap 未 merge 到集成分支 → **不建** worktree，先完成上游 |
+| `git branch --list 'kld-sdd/<change>/*'` 已存在同名分支 | 复用既有 worktree/分支，或询问用户是否清理后重建 |
+| 沙箱 / 环境无法 `worktree add` | 不建 worktree；集成分支上直接开发 |
+
+**Step E — 分支与目录命名（校验通过后）**
+
+| mode | worktree 目录（建议） | apply 分支（建议） |
+|------|----------------------|-------------------|
+| full + 可隔离 | `.worktrees/apply-<change>-<capability>` | `kld-sdd/<change>/<capability>` |
+| simple 或 change 内单实现体 | `.worktrees/apply-<change>` | `kld-sdd/<change>/<capability>`（cap 可与 change 同名） |
+| 校验不通过但仍需隔离 | `.worktrees/apply-<change>-<capability>` 或单 worktree | 仍用 `kld-sdd/<change>/<capability>`，但**不得**与其它 cap 并行 |
+
+**报告模板**（创建 worktree 前必须输出）：
+
+```
+📋 Apply 隔离校验 — <change>/<capability>
+- mode: full | simple
+- 本 change 能力域: [cap-a, cap-b, …]
+- 与当前 cap 冲突/依赖: [无 | cap-a 必须先合入 | 与 cap-b 共享模块 X]
+- 并行建议: [可独立 worktree | 串行等待 cap-a | 不建 worktree，原地 apply]
+- 分支（建议）: kld-sdd/<change>/<capability>
+- 集成分支（将 record-base）: <当前 git 分支>
+```
+
+### 多 Capability 并行时的合并顺序（本地）
+
+1. 各 capability 在各自 worktree 内完成 + `§6.1 finish` 前，先根据 `proposal.md` 排出 **capability 依赖 DAG**。
+2. **按 DAG 顺序**依次 `finish` merge 到**同一** `integration_base`（先 A 合入，再 B；B 的 worktree 若基于旧尖端，merge 前应在 B 的 worktree 内 `merge/rebase integration_base` 或由用户选择重建 worktree）。
+3. 有依赖的 cap **不要**与上游 cap 同时 finish；无依赖的可并行实施，但 **merge 仍建议逐个** 以降低冲突。
+
+向用户简要说明判断结果：
+> "📌 并行建议：cap-A、cap-C 可并行 worktree；cap-B 依赖 A，待 A finish 后再 apply。"
+
+### 分支 / Worktree 创建时机（勿与子代理混淆）
+
+| 时机 | 做什么 | 谁执行 |
+|------|--------|--------|
+| **§1.5 Step 0.25～1（仅一次）** | 记录集成分支 → 创建 worktree + 新建 `kld-sdd/<change>/<capability>` | **主会话** |
+| §2～§4 | 读文档、解析 DAG | 主会话 |
+| **§5 子代理** | 在**已有** worktree 内实现任务 | **子代理**（不建 worktree、不建分支） |
+| **§6.1** | merge 回集成分支 → remove worktree → 删 apply 分支 | **主会话** + `apply-worktree-finish.cjs` |
+
+- 集成分支 = Apply **开始时**主仓库 `git branch --show-current`（例：用户在 `hotfix-1` 上开始，则 merge 回 `hotfix-1`）。
+- `git worktree add -b` 在主仓库处于集成分支时执行，apply 分支从该分支尖端分出。
+- **子代理禁止** `EnterWorktree` / `git worktree add` / `checkout -b`；同层并行共享**同一** worktree 与 apply 分支。
+
+### 设置流程（详见 `./worktree-setup.md`）
+
+**Step 0: 检测当前状态**
+- 若已是 Git Worktree → 跳过创建（集成分支应已在 state 文件中）
+- 若非 Git 项目（`vcs_mode=no-git`）→ 跳过
+
+**Step 0.1: 分支/隔离校验** — 见上文「Step 0.1 【必做】」，**通过后再执行** 0.25 / 0.5 / Step 1
+
+**Step 0.25: 记录集成分支（Git 项目必做，创建 worktree 之前）**
+
+在主仓库根目录、**尚未** `cd` 进 `.worktrees/` 时执行：
+
+```bash
+node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+  --change=<变更名称> \
+  --capability=<capability-name>
+```
+
+- 将当前具名分支写入 `skywalk-sdd/state/apply-<change>-<capability>.json` 的 `integration_base`
+- 若为 detached HEAD，先 `git checkout` 到具名分支再记录
+- simple 模式可省略 `--capability`（默认与 change 相同）
+
+**Step 0.5: 主仓库冲突预检（Git 项目必做）**
+- 在主仓库根目录执行 `git status`，确认**无**与本次 Apply 将修改路径冲突的**未跟踪**实现文件（如 `src/`、`package.json` 等）
+- 若存在，先移走、提交或删除；否则收尾 `merge` 会报 `untracked working tree files would be overwritten`
+- 收尾脚本默认启用 `--check-untracked` 预检并给出明确报错
+
+**Step 1: 创建隔离工作区**
+
+> 确认主仓库仍检出在 **Step 0.25 记录的集成分支**（或与其一致的尖端），再创建 worktree。
+
+- **首选**：使用 `EnterWorktree` 工具（Claude Code 原生）
+  ```
+  EnterWorktree(name="apply-<change-name>-<capability-name>")
+  ```
+- **回退**：仅当原生工具不可用时，使用 `git worktree add`
+  - **full 模式**目录：`.worktrees/apply-<change-name>-<capability-name>`
+  - **simple 模式**目录：`.worktrees/apply-<change-name>`（无 capability 后缀）
+  - **分支命名**：仅当 Step 0.1 校验通过后，使用报告中的 `kld-sdd/<change-name>/<capability-name>`（勿对强依赖 cap 强行并行拆分支）
+  ```bash
+  git worktree add .worktrees/apply-<change-name>-<capability-name> \
+    -b kld-sdd/<change-name>/<capability-name>
+  ```
+
+**Step 2: 项目设置**
+- 自动检测并安装依赖（`npm install` / `pip install` 等）
+
+**Step 3: 验证基线**
+- 运行编译/测试，确保工作区干净
+
+**报告**：
+> "✅ Worktree 就绪：`<path>`
+> 集成分支：`<integration_base>`（收尾将 merge 回此分支）
+> 基线测试通过（N 个测试，0 失败）
+> 准备实施 `<change-name>/<capability-name>`"
+
+---
+
+## §5c 子代理派发模板
+
+> **使用 Agent 工具并行派发同层任务，每个子代理负责一个任务，上下文隔离、专注高效。**
+> **⛔ 子代理阶段不创建 worktree/分支**——隔离环境已在 §1.5 就绪；子代理仅在 worktree 目录内实现 TASK。
+
+**派发准备（每个子代理）：**
+1. 从 tasks.md 中提取该任务的完整描述
+2. 从 design.md 中提取该任务相关的设计约定（类签名、数据模型、接口定义、算法逻辑）
+3. 从 overview.md 中提取相关全局规范（命名约定、目录结构、错误处理模式）
+4. 组合以上上下文 + `./implementer-prompt.md` 模板 → 子代理 prompt
+
+> 子代理 prompt 模板详见 **`./implementer-prompt.md`**（任务实现子代理提示模板）。本节不重复其内容。
+
+**同层并行派发**：
+- 同一 DAG 层级、无相互依赖的任务 → **一次性并行派发多个子代理**
+- 不同 DAG 层级 → **等待当前层全部完成后，再派发下一层**
+
+**派发示例**：
+```
+同一层级 3 个独立任务，一次性并行派发：
+
+Agent("实现 TASK-01: 创建用户数据模型", ...)
+Agent("实现 TASK-02: 创建角色数据模型", ...)
+Agent("实现 TASK-03: 创建权限数据模型", ...)
+// 三个子代理同时运行，上下文隔离，互不干扰
+```
+
+**等待所有子代理返回结果后，按状态处理**：
+
+| 子代理状态 | 控制器处理方式 |
+|-----------|---------------|
+| DONE | 进入编译/测试门禁 |
+| DONE_WITH_CONCERNS | 审查顾虑内容，判断是否需要在门禁前处理 |
+| NEEDS_CONTEXT | 提供缺失上下文，重新派发 |
+| BLOCKED | 补充上下文 / 换更强模型 / 拆分任务 / 升级给用户 |
+
+> **⛔ 严禁**忽略子代理的升级请求！不改变参数就重复派发不会解决问题。
+
+---
+
+## §5.1 记录 AI 产出快照
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+
+> **⚠️ 采集时序（N1）**：`ai_adoption_review` 应在 apply 收尾、**所有文件就绪后**采集（含 README/CHANGELOG/dist 产物/后补文件），确保 `ai_diff.files_changed` 完整。若采集后又补文件，须补录 `--status=final` 事件更新快照，避免 ai_snapshot 时序不全导致 ai_diff 缺漏。
+
+- `--status=ai_snapshot` 用于记录 AI 初始产出快照，P2 指标在无 final 事件时会使用此快照数据
+- 若用户进行了人工 review 并确认保留率，可补录 `--status=final` 事件（`review_status: "final"`），P2 指标将优先使用 final 数据
+
+Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：
+
+```bash
+node 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」。
+
+---
+
+## §6.0 单元测试真实执行（`test-strategy` 非 `none`）
+
+当 `proposal.md` 的 `test-strategy` 为 **`tdd`** 或 **`impl-first`** 时：
+
+1. **在结束 apply 或执行 §6.1 收尾之前**，必须在项目根或 worktree 内**真实运行**单元测试命令（`npm test` / `pytest` / `go test` 等）。
+2. 须留下可核验的 telemetry 证据（任选其一）：
+   - `node skywalk-sdd/log.cjs record --type=test_result ...`（`test_results.command` 非空，且 `passed`/`failed`/`duration_ms` 有实际值）
+   - `task_update` 的 `details-json` 中 `test_results` 含真实执行数据
+   - 或单独运行 `/opsx-test` 并完成 `command=test` 的 `stage_end`
+3. **Claude Code**：`sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验；无证据则**阻断**并提示补跑测试。
+
+| test-strategy | 行为 |
+|---------------|------|
+| `tdd` | 无测试证据不得结束 apply / 不得 finish worktree |
+| `impl-first` | 同上，实现后必须补跑并记录 |
+| `none` | 跳过本节与 test gate |
+
+---
+
+## §6.1 Worktree 收尾（仅当 §1.5 已创建 worktree）
+
+> **⛔ 本次 Apply 若创建了 worktree**：DAG 全部完成且 **§6.0 测试门禁（若适用）** 通过后，必须在**主仓库根目录**执行收尾脚本（禁止在 `.worktrees/...` 内执行）。
+> 若 §1.5 判定未建 worktree（串行、强依赖、沙箱回退），跳过本节。
+
+**前置条件**：
+- worktree 内 `git status` 干净（实现代码已全部 commit）
+- 主仓库无与 merge 冲突的未跟踪文件（见 §1.5 Step 0.5）
+- `test-strategy` 为 `tdd`/`impl-first` 时，§6.0 测试证据已存在
+
+**执行**（主仓库根目录）：
+```bash
+node skywalk-sdd/apply-worktree-finish.cjs \
+  --change=<变更名称> \
+  --capability=<capability-name>
+```
+
+- **默认 merge 目标**：§1.5 `--record-base` 写入的 `integration_base`（**不是**默认 master）
+- 仅当 state 缺失或需覆盖时传 `--target=<集成分支>`
+- **simple 模式**：`--capability` 可省略；目录为 `.worktrees/apply-<change>`
+- **full 模式**：目录为 `.worktrees/apply-<change>-<capability>`
+
+**脚本行为**：`checkout 集成分支` → `merge --no-ff` apply 分支 → `worktree remove` → 删临时目录 → `branch -d` apply 分支
+
+**常用 flags**：`--dry-run` 预演；`--skip-merge` 已手动 merge；`--keep-branch` 保留 apply 分支；`--no-check-untracked` 跳过未跟踪预检
+
+**回退**（仅当脚本不可用时，详见 `./worktree-setup.md`）：
+- `EnterWorktree`：`ExitWorktree(action="remove", discard_changes=false)`
+- `git worktree add`：`git worktree remove` + `git branch -D`
+
+> **与 Git 只读策略的关系**：Apply **实施过程**禁止 Agent 随意 commit；**收尾**由本脚本执行 merge/remove，属于流程必做步骤，不视为「随意提交业务代码」。

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

@@ -30,7 +30,7 @@ allowed-tools:
 | 维度 | 内容 |
 |---|---|
 | 核心问题 | 变更生命周期结束与度量收口 |
-| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`skywalk-sdd/reports/<change>-report.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>/logs/execution-log.md` |
 | 触发时机 | 任务完成、变更取消、变更搁置、或用户要求归档 |
 
 ---
@@ -91,21 +91,30 @@ node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
 
 即使用户选择“变更已完成实施”，未勾选项也不阻断归档。它可能代表任务真实未完成，也可能代表代码已完成但文档未同步；不要猜测，也不要静默忽略。最终必须让 `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」。
+
 ### 5. 一步执行真实归档
 
 执行唯一归档命令：
 
 ```bash
-node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reason="<归档原因>" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --report-output=skywalk-sdd/reports/<变更名称>-report.md
+node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reason="变更已完成实施" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
 ```
 
+> `--reason` 默认值为 `变更已完成实施`；如果用户选择了其他归档原因，请将上述 `--reason` 的值替换为对应原因。
+
 该命令成功后必须已经完成：
 - 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
 - 归档目录写入 `archive-manifest.json`。
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
-- 最终中文报告生成到 `skywalk-sdd/reports/<name>-report.md`。
+- 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（默认同时生成 .md 与 .html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
+- 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
+
+> 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 
 如果该命令失败，以失败状态结束 telemetry：
 
@@ -121,7 +130,8 @@ node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=.
 
 > 变更 `<name>` 已真实归档。
 > - 归档目录：`openspec/changes/archive/<日期>-<name>/`
-> - 最终报告：`skywalk-sdd/reports/<name>-report.md`
+> - 最终报告（默认同时生成 .md + .html）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`openspec/changes/archive/<日期>-<name>/reports/<name>-report.html`
+> - 执行日志：`openspec/changes/archive/<日期>-<name>/logs/execution-log.md`
 > - 未勾选任务：X 项，已记录到报告，不阻断归档
 > - 正式 specs：`openspec/specs/`
 
@@ -150,5 +160,11 @@ node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --proje
 - 归档操作执行前必须让用户确认归档原因。
 - 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
 - “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
-- 最终报告必须由 `archive-docs --report-output=...` 自动生成。
+- 最终报告由 `archive-docs` 自动生成（md+html 双产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。
 - 已归档变更不要重复移动；展示已有 archive 目录和 report 路径。
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在执行 archive 前后自检时（产物完整性、状态标记、归档迁移）。

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

@@ -0,0 +1,33 @@
+---
+name: opsx-archive-checklist
+description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive 自检时读取"
+---
+
+# opsx-archive 自检清单
+
+> 仅在执行 archive 前后做产物/日志自检时读取。日常归档流程见 `SKILL.md`。
+
+## A. 归档前自检
+
+- [ ] `node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>` 无 `severe_issues`（`superseded_open_stages`/`rework_summary` 仅展示，不阻断）
+- [ ] `node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>` 已运行；未勾选项将进入 `archive_result.task_completion`，不阻断归档但必须如实记录
+- [ ] `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 事件）
+
+## B. 归档后自检
+
+- [ ] 归档目录 `openspec/changes/archive/<日期>-<变更名称>/` 存在
+- [ ] `openspec/changes/archive/<日期>-<变更名称>/archive-manifest.json` 存在
+- [ ] 最终报告 `openspec/changes/archive/<日期>-<变更名称>/reports/<变更名称>-report.md` 存在且含「归档结果」段
+- [ ] `reports/<变更名称>-report.md` 与 `reports/<变更名称>-report.html` 都已生成（md+html 双产物）
+- [ ] html 报告含 `SDD 效果度量报告` 标题与各度量章节（执行摘要/效率/质量/过程/归档结果/说明）
+- [ ] 执行日志 `openspec/changes/archive/<日期>-<变更名称>/logs/execution-log.md` 随 change 整目录迁移到 archive（含 archive 阶段 stage_start+stage_end+✅OK）
+- [ ] 正式 specs 同步到 `openspec/specs/<capability>/spec.md`
+- [ ] `skywalk-sdd/reports/` 不再写入新报告（最终报告落 archive 目录）
+
+## C. 状态标记规范
+
+- execution-log.md 用 `✅OK` / `🟡WARN` / `❌FAIL` 三态标记
+- 未闭环阶段必须修复或标记 `partial`，不得静默留空
+- 报告「归档结果」段如实反映 `task_completion.incomplete` 数量

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

@@ -33,8 +33,9 @@ allowed-tools:
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node skywalk-sdd/log.cjs start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 检查报告生成后，必须先记录结构化检查结果：`node 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,\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
+> - 检查报告生成后，必须先记录结构化检查结果：`node 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,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"`
 > - `check_result` 记录成功后，才允许阶段结束：`node 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 或补齐文档，使三者数字自洽。
 
 ---
 
@@ -148,22 +149,37 @@ node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
 - `total`: 本次检查项总数。
 - `errors`: 必须修复的问题数。
 - `warnings`: 建议修复的问题数。
+- `warning_items`: 警告明细数组，每项 `{category, description, target}`（如 `{"category":"task_completion","description":"4.3 手动验证清单未勾选","target":"tasks.md:595"}`），用于报告已知风险区渲染具体待确认项；无明细时省略（向后兼容，旧事件仅 `warnings` 数量，报告降级显示数量）。
 - `suggestions`: 可选优化建议数。
-- `fixed_before_apply`: 进入 apply 前已通过或已确认满足质量门禁的检查项数。
+- `fixed_before_apply`: 进入 apply 前已通过或已确认满足质量门禁的检查项数。**【Q2 口径】**：apply 前第一次 check 全过则 = total（全部通过）；apply 前有 check 但 fixed_before_apply=0 不触发 P4 警示（P4 主指标已改为"apply 前是否 check"，与 fixed_before_apply 解耦）。
 - `consistency_score`: 跨文档一致性评分，取值 0-1；无法评分时填 `null`。
 - `categories`: 至少包含 `completeness`、`consistency`、`executability`。
 - `task_completion`: 从 `tasks-status` 输出整理而来；未进入 apply 时 `checked_for_archive_readiness=false`。
 
 在终端执行（必须成功）：
 ```bash
-node 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,\"suggestions\":0,\"fixed_before_apply\":0,\"consistency_score\":null,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"passed\":0,\"total\":0}},\"task_completion\":{\"completed\":0,\"incomplete\":0,\"total\":0,\"has_incomplete\":false,\"checked_for_archive_readiness\":false}}}"
+node 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,\"categories\":{\"completeness\":{\"passed\":0,\"total\":0},\"consistency\":{\"passed\":0,\"total\":0},\"executability\":{\"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` 必须含 `consistency_score` / `categories` / `task_completion` 等字段，**禁止传空对象 `{}`**。空 details 会导致 report 的 Q5 跨文档一致性得分、P4b 修复率为 null（工具侧虽有 state fallback 兜底，但事件 details 是主数据源）。
+
+> **⚠️ 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 解耦），但反映真实完成度。
+
 若当前已有实现代码，并且能够验证 spec 断言，还应记录 `conformance_review`（用于 Q1 规约符合度）：
 ```bash
-node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="规约符合度人工确认" --details-json="{\"conformance_review\":{\"method\":\"llm-as-judge+manual\",\"manual_confirmed\":true,\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
+node skywalk-sdd/log.cjs record --type=conformance_review --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="规约符合度评审" --details-json="{\"conformance_review\":{\"method\":\"llm-as-judge\",\"agent_confirmed\":true,\"human_status\":\"unverified\",\"reviewer\":\"<reviewer-identifier>\",\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
 ```
 
+> **human_status 说明（T3.4）**：`conformance_review.human_status` 标识本次评审是否经真实人工确认：`unverified`（AI 自评，待人工确认，默认）或 `matched`（已由人工评审确认）。**仅当真实人工评审时才填 `matched`**，避免 AI 自评被误标为已确认。报告 Q1 规约符合度会据此标注「自评，待人工确认」。
+
+> **【L4 conformance_review details-json 完整 schema】**：
+> - `reviewer` 必须带引号（字符串），如 `"reviewer": "claude-code"`
+> - `assertions[].files` 是必填数组，每项为实际文件路径字符串，如 `"files": ["src/auth.js", "test/auth.test.js"]`；空数组 `[]` 须配合 `evidence` 文本作为降级证据（如浏览器自动化/手动验收摘要）。`files` 含测试文件路径（`test/`、`.test.`、`.spec.`）**或** `evidence` 非空，二者至少满足其一，否则空口断言被工具侧记录时硬校验拒绝（详见 `skywalk-sdd/index.cjs`）
+> - `assertions[].judge_status` 枚举：`matched` / `partial` / `missed`
+> - `assertions[].human_status` 枚举：`matched` / `partial` / `missed` / 省略（默认跟随 judge_status）
+
+> **reviewer 与 reviewer_independence 说明**：`reviewer` 用于标识实际执行本次符合度评审的代理或会话（例如 agent 名称、会话 ID）。渲染报告时会比较 `reviewer` 与 apply 阶段记录的 `apply_agent`：若两者相同，则 `reviewer_independence` 显示为 `self-review`；否则显示为 `independent-review`。建议尽可能由独立评审方执行 check，以提升结果可信度。
+
 ### 6. 【交互引导】根据结果引导下一步
 
 **全部通过**：
@@ -180,6 +196,8 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 > - A. 逐个修复（引导到对应命令）
 > - B. 忽略警告继续"
 
+> **📊 过程记录（U3）**：若用户选择 A 逐个修复，或在 check 后、归档前补充修复（补 README/CHANGELOG、勾 checkbox 等），每个修复动作**必须**记 `process_note` 事件（`kind=fix`，`command=check`），归档前修补不再黑箱。**若本阶段存在失败/门禁拦截但无对应 `process_note`，`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`（不阻断，但报告过程质量信号会标红）。** 必记节点清单见 `opsx-apply/reference.md`「process_note」。
+
 ---
 
 ## Guardrails
@@ -189,3 +207,9 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 - 检查报告必须结构化、可操作
 - 支持增量检查（只检查指定 Capability）
 - **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
+
+---
+
+## 渐进披露
+
+- Read `checklist.md` 仅在 check 阶段日志自检时（check_result 记录、execution-log 状态标记、字段口径）。

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

@@ -0,0 +1,37 @@
+---
+name: opsx-check-checklist
+description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读取"
+---
+
+# opsx-check 自检清单
+
+> 仅在 check 阶段做日志/结果自检时读取。日常检查流程见 `SKILL.md`。
+
+## A. check_result 事件记录
+
+- [ ] `check_result` 事件已记录：`skywalk-sdd/events/<变更名称>/*.jsonl` 含 `type=check_result` 条目
+- [ ] `openspec/changes/<变更名称>/logs/execution-log.md` 含 check 阶段条目（`stage_start` / `check_result` / `stage_end`）
+- [ ] `check_result` 在 `stage_end` 之前记录成功（禁止只记录阶段结束）
+
+## B. check_result 字段口径
+
+- [ ] `total`: 本次检查项总数（非 0 占位）
+- [ ] `errors`: 必须修复的问题数
+- [ ] `warnings`: 建议修复的问题数
+- [ ] `suggestions`: 可选优化建议数
+- [ ] `fixed_before_apply`: 进入 apply 前已通过/已确认满足门禁的检查项数
+- [ ] `consistency_score`: 跨文档一致性评分 0-1；无法评分填 `null`
+- [ ] `categories`: 至少含 `completeness` / `consistency` / `executability`
+- [ ] `task_completion`: 从 `tasks-status` 整理；未进入 apply 时 `checked_for_archive_readiness=false`
+- [ ] **P1-1**：`check_result` 事件 `details` 非空且含 `consistency_score` 键（禁止空 `{}`，否则 Q5 为 null）
+- [ ] **P2-3**：`has_incomplete=true` 时 `check_result.result=partial` 且 `warning_items` 含 task_completion 项
+
+## C. execution-log 状态标记
+
+- [ ] execution-log.md 状态标记规范：`✅OK` / `🟡WARN` / `❌FAIL`
+- [ ] check 阶段结果与 `check_result.result` 一致（success→✅OK / partial→🟡WARN / failure→❌FAIL）
+
+## D. 检查报告四维
+
+- [ ] 完整性、一致性、算法正确性、可执行性四维均已输出
+- [ ] 报告问题对应修复建议（spec/design/task）