kld-sdd 2.4.7 → 2.4.9

package/templates/opsx-commands/apply.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Apply
 description: "执行变更实施 - 针对单一 Capability 按 DAG 依赖顺序实现代码"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -6,8 +6,20 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
 执行变更实施 - 针对单一 Capability，按 DAG 依赖顺序逐任务实现代码。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=apply --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js 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。
+
+> **🔒 Git 策略（只读增强，不改变开发流）**
+> - Git 只作为可选度量数据源，不是 apply 前置条件。
+> - 禁止自动执行 `git init`、`git add`、`git commit`、`git checkout -b`、`git switch -c`。
+> - 若项目已有 Git，仅允许读取 `git rev-parse HEAD`、`git diff --numstat` 等只读信息。
+> - 若项目不是 Git 仓库，进入 `vcs_mode=no-git`，`base_git_sha=none`，继续实施，不得中断。
+> - 只有用户明确要求时，才允许提交或创建分支；SDD 度量本身不得主动提交。
 
 > **⚠️ 渐进式上下文加载原则**
 >
@@ -23,9 +35,37 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
 0. **【Telemetry 必做】记录阶段开始**
 
+   先以只读方式探测版本控制状态。Git 只是增强数据源，失败不得中断 apply。
+
+   **禁止事项**：
+   - 禁止自动执行 `git init`
+   - 禁止自动执行 `git add`
+   - 禁止自动执行 `git commit`
+   - 禁止自动创建或切换分支
+
+   **探测流程**：
+   ```bash
+   git rev-parse --is-inside-work-tree
+   ```
+
+   若命令成功，设置：
+   - `vcs_mode=readonly`
+   - `base_git_sha=<git rev-parse HEAD 的输出>`
+
+   只读读取基线 SHA：
+   ```bash
+   git rev-parse HEAD
+   ```
+
+   若命令失败，设置：
+   - `vcs_mode=no-git`
+   - `base_git_sha=none`
+
+   非 Git 项目必须继续实施，不得为了度量自动创建仓库或提交快照。
+
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=apply --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --git-sha=<base_git_sha_or_none>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -308,6 +348,16 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
          > - 结果: ✅ 编译成功 / ❌ 编译失败
          > - 耗时: 2.3s"
       
+      5. **记录构建 Telemetry**：
+         ```bash
+         node skywalk-sdd/log.js record --type=build_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="编译检查结果" --details-json="{\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0}}"
+         ```
+         `build_results` 字段口径：
+         - `command`: 实际执行的编译/构建命令。
+         - `success`: 构建是否成功，用于 Q3。
+         - `duration_ms`: 构建耗时，无法获取时填 `null`。
+         - `error_count`: 编译错误数，无法统计时填 `null`。
+      
       > **⚠️ 注意：编译失败的任务禁止标记为已完成！**
 
    e. **⛔【必须】测试执行门禁**
@@ -340,14 +390,22 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
       每完成一个任务后，必须立即：
       
       1. **修改 tasks.md 文件**：
-         - 将 `- **状态**: [ ] 未完成` 改为 `- **状态**: [x] 已完成`
-      2. **验证修改成功**：读取文件确认状态已更新
+         - 将该任务对应的 `- [ ]` 替换为 `- [x]`（包括任务执行拓扑图中的复选框和任务详情中的状态行）
+         - 将 `- **状态**: [ ] 未完成` 替换为 `- **状态**: [x] 已完成`
+         - **两种格式必须同步更新**，不可遗漏
+      2. **验证修改成功**：读取文件确认两种格式的复选框均已勾选
       3. **显示进度提示**：
          > "✅ **[TASK-XXX-01] 已完成** [N/M]
          > - 编译检查: ✅ 通过
          > - 已更新 tasks.md 状态: `[ ]` → `[x]`
          > - 下一层任务已解锁：[TASK-XXX-03]"
 
+      4. **记录任务级 Telemetry**：
+         ```bash
+         node skywalk-sdd/log.js 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}}"
+         ```
+         若任务失败或暂停，`--status` 使用 `failed` / `blocked`，`--result` 使用 `failure` / `partial`，并在 details 中记录失败原因。
+
    g. **继续下一个可执行任务**
       - 重新检查 DAG，找出所有依赖已满足的任务
       - 若同层有多个可执行任务，按顺序执行
@@ -406,7 +464,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 - **⛔ 渐进式加载**：只加载当前 Capability 的四文档链（overview + proposal + spec + design + tasks）
 - **⛔ 隔离红线**：绝对禁止加载同级其他 Capability 的文档
 - **⛔ 拓扑依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
-- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 状态，禁止批量更新
+- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 中的 `- [ ]` 为 `- [x]`，**同时修改** `**状态**: [ ] 未完成` 为 `**状态**: [x] 已完成`，两种格式不可遗漏，禁止批量更新
 - **⛔ 算法一致性门禁**：对于 IMPL 任务，检查实现代码与 design.md 伪代码的一致性，核心逻辑不一致时拦截
 - **⛔ 编译检查门禁**：每完成一个任务后，**必须运行编译检查**，编译失败禁止标记已完成
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=警告, none=跳过）
@@ -414,7 +472,17 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 - **保持任务聚焦**：每次只处理一个任务，完成后再继续下一个
 - **代码变更最小化**：每个任务只做必要的代码修改，不要超出任务范围
 - **遇到问题时暂停**：如果任务描述模糊、编译失败、测试失败或发现设计问题，暂停并询问
+- **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目使用 `vcs_mode=no-git` 继续执行
 - 若变更状态已是 `ARCHIVED`，提示用户该变更已归档，无法继续实施
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success/failure --summary="实施结果摘要" --project=<项目根目录绝对路径>`
+> 每次编译检查后，必须记录构建事件：`node skywalk-sdd/log.js record --type=build_result --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="编译检查结果" --details-json="{\"build_results\":{\"command\":\"<实际编译命令>\",\"success\":true,\"duration_ms\":0,\"error_count\":0}}"`
+> 每完成一个任务，必须记录任务级结构化事件：`node skywalk-sdd/log.js 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}}"`
+> AI 代码产出完成后，必须记录采纳率快照，但不得为了采集快照自动提交 commit。Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：`node skywalk-sdd/log.js 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\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"未自动创建 Git 仓库，未自动提交 commit；仅记录可用统计\"}}"`
+> 若后续发生人工修改并完成采纳确认，必须补录最终采纳统计；若非 Git 项目，SHA 可填 `null`，采纳行数由人工或工具统计补录：`node skywalk-sdd/log.js record --type=ai_adoption_review --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --status=final --result=success --summary="AI 代码采纳率人工确认" --details-json="{\"ai_adoption\":{\"review_status\":\"final\",\"vcs_mode\":\"<readonly|no-git>\",\"base_git_sha\":\"<base_git_sha_or_null>\",\"ai_git_sha\":\"<ai_git_sha_or_null>\",\"final_git_sha\":\"<final_git_sha_or_null>\",\"retained_lines\":0,\"rewritten_lines\":0,\"deleted_lines\":0,\"ai_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"final_diff\":{\"files_changed\":0,\"added_lines\":null,\"deleted_lines\":null},\"notes\":\"只记录行数统计，不记录源码；非 Git 项目允许 SHA 为 null\"}}"`
+> 阶段结束时执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --command=apply --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="实施结果摘要"`

package/templates/opsx-commands/archive.md

@@ -1,85 +1,146 @@
 ---
 name: OPSX: Archive
-description: "归档变更 - 将已完成或取消的变更归档，清理活动状态"
+description: "归档变更 - 将已结束的 SDD 变更真实移入 archive，并自动生成最终度量报告"
 argument-hint: "[change-name]"
 ---
 
-归档变更 - 将已完成实施或决定取消的变更移出活动状态，保留文档供后续参考。
+归档变更 - 将已结束的 SDD 变更真实移动到 `openspec/changes/archive/`，同步正式 specs，并自动生成最终 SDD 效果度量报告。
 
-> **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=archive --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> **跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
+> - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。
+> - 本命令已经集成 SkyWalk-SDD 归档逻辑，不要调用 OpenSpec 自带归档命令。
 
 ---
 
 **输入**: `/opsx:archive` 后跟变更名称（kebab-case）
 
-**执行步骤**
+**核心原则**
 
-0. **【Telemetry 必做】记录阶段开始**
+- `archive` 必须产生真实归档结果：活动目录 `openspec/changes/<name>/` 应被移出，归档目录位于 `openspec/changes/archive/<日期>-<name>/`。
+- 归档统一使用 `node skywalk-sdd/log.js archive-docs`，同时兼容 Simple 与 Full 两种文档结构。
+- 最终报告必须随着 `archive` 阶段成功结束自动生成，不再作为可选手工步骤。
+- 即使归档原因是“变更已完成实施”，未勾选的 `tasks.md/task.md` 项也不阻断归档；但必须写入 archive 详情和最终报告。
 
-   在终端执行（若命令失败必须中止本阶段，不得跳过）：
-   ```bash
-   node skywalk-sdd/log.js start --command=archive --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
-   ```
-   保存输出 JSON 中的 `event_id`，供阶段结束使用。
+---
+
+## 执行步骤
+
+### 0. 记录阶段开始
+
+```bash
+node skywalk-sdd/log.js start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+```
+
+保存输出 JSON 中的 `event_id`。
+
+### 1. 确认变更名称
+
+如未提供变更名称，列出当前变更供用户选择：
+
+```bash
+openspec list
+```
+
+如果 `openspec/changes/<name>/` 不存在，先确认是否已归档；不要创建新的空变更。
+
+### 2. 引导确认归档原因
+
+向用户确认归档原因：
+
+> 请选择归档原因：
+> - A. 变更已完成实施
+> - B. 变更已取消
+> - C. 变更已搁置
+> - D. 其他原因
+
+记录为 `<归档原因>`。
 
-1. **【交互引导】确认变更名称**
+### 3. 执行数据质量检查
 
-   若未提供，列出当前所有变更供用户选择：
-   ```bash
-   openspec list
-   ```
-   展示每个变更的状态（PENDING / IMPLEMENTING / ARCHIVED），引导用户选择。
+归档前执行 doctor：
 
-2. **获取变更状态**
+```bash
+node skywalk-sdd/log.js doctor --project=. --change=<变更名称>
+```
 
-   ```bash
-   openspec status --change "<name>" --json
-   ```
+处理规则：
+- doctor 返回 0：允许继续。
+- doctor 返回 1 且存在 `severe_issues`：暂停归档，先处理严重问题。
+- `superseded_open_stages` 和 `rework_summary` 仅作为返工/重复执行展示，不要求用户区分测试回滚还是真实返工。
 
-   检查变更当前状态：
-   - `PENDING`：尚未申请实施（提醒用户是否跳过实施直接归档）
-   - `IMPLEMENTING`：正在实施中（提醒用户确认是否全部任务已完成）
-   - `ARCHIVED`：已归档（提示用户该变更已归档，无需操作）
+### 4. 扫描 tasks 完成状态
 
-   **【状态异常处理】**：
-   - 若变更为 `PENDING`（从未实施）：
-     > "变更 `<name>` 尚未申请实施，确定要直接归档？
-     > - A. 确认归档（变更已取消/搁置）
-     > - B. 先申请实施（运行 `/opsx:apply <name>`）"
-   - 若变更为 `IMPLEMENTING`（实施中）：
-     > "变更 `<name>` 正在实施中，请确认所有 tasks.md 任务已完成：
-     > - A. 确认全部完成，归档变更
-     > - B. 取消（继续实施中状态）"
+始终扫描 Simple 和 Full 两种布局下的所有 `tasks.md/task.md`：
 
-3. **【交互引导】确认归档原因**
+```bash
+node skywalk-sdd/log.js tasks-status --project=. --change=<变更名称>
+```
 
-   > "请确认归档原因（将记录在归档日志中）：
-   > - A. 变更已完成实施 ✅（所有任务已完成并验收）
-   > - B. 变更已取消 ❌（业务原因取消）
-   > - C. 变更已搁置 ⏸（暂缓实施，保留文档）
-   > - D. 其他（请输入原因）"
+处理规则：
+- 无论归档原因是什么，都允许继续归档。
+- 如存在 `- [ ]` 未勾选项，必须在最终输出中展示数量与摘要。
+- `archive-docs` 会在归档成功后强制补齐 `stage_end.details.archive_result.task_completion`，并写入最终报告。
 
-4. **执行归档**
+### 5. 一步执行真实归档、结束阶段并生成报告
 
-   ```bash
-   openspec archive "<name>"
-   ```
+执行：
 
-5. **输出结果**
+```bash
+node skywalk-sdd/log.js archive-docs --project=. --change=<变更名称> --reason="<归档原因>" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --report-output=skywalk-sdd/reports/<变更名称>-report.md
+```
 
-   > "✅ 变更 `<name>` 已归档！
-   > - 归档原因：[用户选择的原因]
-   > - 文档路径：openspec/changes/<name>/（已保留，可随时查阅）
-   > - 如需查看所有归档变更，运行 `/opsx:explore`"
+该命令必须一次完成：
+- 移动活动变更目录到 `openspec/changes/archive/<日期>-<变更名称>/`。
+- 写入 `archive-manifest.json`。
+- 将 Full 模式的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
+- 结束 archive 阶段并写入 `stage_end`。
+- 补齐 `archive_result.task_completion`。
+- 生成中文最终报告 `skywalk-sdd/reports/<变更名称>-report.md`。
+
+如果命令失败，必须以失败状态结束 telemetry：
+
+```bash
+node skywalk-sdd/log.js end --event-id=<event_id> --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="归档失败：<失败原因>"
+```
+
+失败时不要输出“归档完成”。
+
+### 6. 输出结果
+
+成功时输出：
+
+> 变更 `<name>` 已真实归档。
+> - 归档原因：`<归档原因>`
+> - 归档目录：`openspec/changes/archive/<日期>-<name>/`
+> - 最终报告：`skywalk-sdd/reports/<name>-report.md`
+> - 未勾选任务：X 项，已记录到报告，不阻断归档
+> - 正式 specs：`openspec/specs/`
 
 ---
 
-**护栏规则**
+## 可选补录
+
+如用户愿意提供反馈，可补录问卷结果：
+
+```bash
+node skywalk-sdd/log.js record --type=survey_result --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="SDD 人工反馈" --details-json="{\"survey_result\":{\"nps\":9,\"cognitive_load\":3,\"spec_fatigue_index\":2,\"satisfaction\":8,\"respondent_role\":\"developer\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
+```
+
+如团队有传统方式工时基线，可补录 baseline：
+
+```bash
+node skywalk-sdd/log.js record --type=baseline_record --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="传统工时基线" --details-json="{\"baseline_record\":{\"traditional_hours\":10,\"sdd_hours\":6,\"task_type\":\"feature\",\"baseline_source\":\"manual-estimate\",\"collected_at\":\"<ISO时间>\",\"notes\":\"\"}}"
+```
+
+---
 
-- 归档操作执行前必须用户明确确认，不可自动执行
-- 归档后文档仍保留在 `openspec/changes/<name>/` 目录，不会删除
-- 若变更状态已是 `ARCHIVED`，提示用户直接跳过，无需重复操作
+## 护栏规则
 
-> **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success/failure --summary="归档结果摘要" --project=<项目根目录绝对路径>`
+- 归档操作执行前必须让用户确认归档原因。
+- 不要调用 OpenSpec 自带归档命令；归档统一由 `archive-docs` 负责。
+- “完成实施”归档允许 tasks 未全部勾选，但未勾选项必须进入 archive details 和最终报告。
+- 真实归档或报告生成失败时，不得输出成功文案。
+- 已归档变更不要重复移动；展示已有归档目录和报告路径即可。

package/templates/opsx-commands/check.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Check
 description: "质量检查 - 验证文档完整性、一致性、算法正确性及可执行性"
 argument-hint: "[change-name] [上下文文件...]"
@@ -6,8 +6,13 @@ argument-hint: "[change-name] [上下文文件...]"
 
 执行 **质量门禁检查** - 验证 proposal → specs → design → tasks 文档链的完整性、一致性、算法正确性和可执行性。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=check --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 > **⚠️ 阶段边界提示**
 >
@@ -26,7 +31,7 @@ argument-hint: "[change-name] [上下文文件...]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=check --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -158,6 +163,21 @@ argument-hint: "[change-name] [上下文文件...]"
    - 询问用户："是否自动拆分/优化这些任务？"
    - 用户确认后，生成优化建议
 
+   ### 4.3.1 任务完成状态检查（实现后 / 归档前）
+
+   `tasks.md` 在 task 阶段天然会包含未完成项，所以**单纯存在 `- [ ]` 不代表 task 阶段错误**。但如果当前变更已经进入 apply 之后，或本次 check 发现了实现代码、测试报告、`build_result/test_result/task_update/conformance_review` 等实施证据，则必须检查任务状态是否与实施结果同步。
+
+   执行：
+
+   ```bash
+   node skywalk-sdd/log.js tasks-status --project=. --change=<变更名称>
+   ```
+
+   判定规则：
+   - 若尚未进入 apply，未勾选任务只作为计划状态展示，不计入错误。
+   - 若已经进入 apply/test/archive readiness，仍存在 `- [ ]` 或 `状态: [ ]`，至少记为 warning；即使用户准备归档“变更已完成实施”，也不把未勾选项作为归档阻断错误。
+   - 检查报告必须写明：这是“任务可能已执行但文档未勾选”或“任务真实未完成”的待确认项，AI 不能在 check 阶段自动勾选。
+
    ### 4.4 算法正确性检查（新增）
    
    **❗ 此检查针对 design.md 中的伪代码**
@@ -288,12 +308,19 @@ argument-hint: "[change-name] [上下文文件...]"
    - 总任务数：X
    - 可执行任务：X
    - 需优化任务：X
+   - 已勾选完成项：X
+   - 未勾选项：X
    
    ### 问题任务清单
    | 任务 | 问题 | 优化建议 |
    |-----|------|---------|
    | | | |
 
+   ## 任务完成状态
+   - 检查命令：`node skywalk-sdd/log.js tasks-status --project=. --change=<name>`
+   - 状态口径：task 阶段允许未勾选；apply/test/archive readiness 阶段不得把未勾选项静默视为完成。
+   - 未勾选项清单：列出文件、行号、原文。
+
    ## 修复建议
    1. [优先级：高] [具体建议]
    2. [优先级：中] [具体建议]
@@ -329,6 +356,92 @@ argument-hint: "[change-name] [上下文文件...]"
      - 检查通过："✅ 质量检查通过！可以运行 `/opsx:apply` 开始实现"
      - 有问题："⚠️  发现 X 个问题，请查看检查报告并修复后重新检查"
 
+11. **【Telemetry 必做】整理结构化检查结果**
+
+   在记录 Telemetry 前，必须将检查结果整理为以下标准 schema：
+
+   ```json
+   {
+     "check_results": {
+       "total": 10,
+       "errors": 0,
+       "warnings": 1,
+       "suggestions": 2,
+       "fixed_before_apply": 8,
+       "consistency_score": 0.87,
+       "categories": {
+         "completeness": {"passed": 3, "total": 3},
+         "consistency": {"passed": 4, "total": 5},
+         "executability": {"passed": 2, "total": 2}
+       },
+       "task_completion": {
+         "completed": 0,
+         "incomplete": 0,
+         "total": 0,
+         "has_incomplete": false,
+         "checked_for_archive_readiness": false
+       }
+     }
+   }
+   ```
+
+   **字段口径**：
+   - `total`: 本次检查项总数。
+   - `errors`: 必须修复的问题数。
+   - `warnings`: 建议修复的问题数。
+   - `suggestions`: 可选优化建议数。
+   - `fixed_before_apply`: 在进入 apply 前已修复或已确认满足质量门禁的检查项数，用于 P4。
+   - `consistency_score`: 跨文档一致性评分，取值 0-1，用于 Q5；无法评分时填 `null`。
+   - `categories`: 分维度通过情况，至少包含 `completeness`、`consistency`、`executability`。
+   - `task_completion`: 从 `tasks-status` 输出整理而来；若尚未进入 apply，可填写 `checked_for_archive_readiness=false`。
+
+   **强制落盘规则**：
+   - 生成检查报告后，必须先记录 `check_result`，再记录阶段 `end`。
+   - 禁止只执行 `stage_end`；若无法精确统计，也必须按下方 schema 填入保守统计值，不能跳过。
+   - `result` 口径：存在 error 时填 `failure`；仅 warning/suggestion 时填 `partial`；全部通过时填 `success`。
+
+   在终端执行（必须成功）：
+   ```bash
+   node skywalk-sdd/log.js 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}}}"
+   ```
+
+12. **【Telemetry 建议】记录规约符合度 Q1**
+
+   若当前变更已有实现代码，必须将 `spec.md` 中的关键需求拆成可验证断言，并进行 LLM-as-Judge 初筛与人工确认：
+
+   ```json
+   {
+     "conformance_review": {
+       "method": "llm-as-judge+manual",
+       "manual_confirmed": true,
+       "assertions": [
+         {
+           "id": "ASSERT-001",
+           "description": "规约中的可验证断言",
+           "judge_status": "matched",
+           "human_status": "matched",
+           "evidence": "代码、测试或文档证据摘要",
+           "files": ["src/example.js"],
+           "notes": ""
+         }
+       ]
+     }
+   }
+   ```
+
+   **状态口径**：
+   - `matched`: 代码/测试已满足该断言。
+   - `partial`: 部分满足，仍有边界、异常或覆盖缺口。
+   - `missed`: 未满足或未发现实现证据。
+   - `human_status` 优先于 `judge_status`，Q1 只作为质量洞察，不作为第一期硬门禁。
+
+   在终端执行（若存在实现代码则必须成功）：
+   ```bash
+   node skywalk-sdd/log.js 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\":\"\"}]}}"
+   ```
+
+   若当前尚未进入实现阶段或无法验证代码，允许跳过 `conformance_review`，但需要在检查报告中说明原因。
+
 ---
 
 **护栏规则**
@@ -340,5 +453,11 @@ argument-hint: "[change-name] [上下文文件...]"
 - 检查报告本身也是文档，需保持清晰、可追踪
 - **⛔ 阶段边界**：本阶段仅执行检查，禁止自动修复代码。若发现代码问题，记录到检查报告并提示用户：「代码修复请使用 `/opsx:apply` 执行。」
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success/failure --summary="检查结果摘要" --project=<项目根目录绝对路径>`
+> 生成检查报告后，必须先记录结构化检查结果：`node skywalk-sdd/log.js 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}}}"`
+> `check_result` 记录成功后，才允许执行阶段结束：`node skywalk-sdd/log.js 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="检查结果摘要" --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}}}"`

package/templates/opsx-commands/design.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Design
 description: "创建局部技术实现方案 - 针对单一 Capability 的设计文档"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -6,8 +6,13 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
 创建 **design.md** - 针对单一 Capability 的局部技术实现方案（渐进式上下文加载）。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=design --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=design --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 > **⚠️ 阶段边界提示**
 >
@@ -36,7 +41,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=design --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=design --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -556,5 +561,10 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 - **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作
 - **⛔ 单阶段原则：完成 design.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:task`，**绝对禁止自动执行 task/apply 等后续阶段**。每个阶段必须由用户主动触发。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success/failure --summary="一句话摘要" --project=<项目根目录绝对路径>`
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --command=design --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="一句话摘要"`

package/templates/opsx-commands/explore.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Explore
 description: "浏览变更 - 查看所有变更状态和 SDD 文档完整性概览"
 argument-hint: "[change-name]"
@@ -6,8 +6,13 @@ argument-hint: "[change-name]"
 
 浏览变更状态和文档链进度 - 快速掌握项目中所有变更的 SDD 文档完整性，并引导下一步操作。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=explore --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 ---
 
@@ -19,7 +24,7 @@ argument-hint: "[change-name]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=explore --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -85,5 +90,10 @@ argument-hint: "[change-name]"
 - 发现文档缺失时，推荐对应命令但不自动执行
 - 若某变更 applyRequires 中有未完成项，在概览表中以 ⚠️ 标注
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success --summary="浏览结果摘要" --project=<项目根目录绝对路径>`
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success --summary="浏览结果摘要"`