kld-sdd 2.4.7 → 2.4.9

package/templates/opsx-commands/propose.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Propose
 description: "创建业务意图文档 - 定义变更的 Why 和上下文总览"
 argument-hint: "[change-name] [上下文文件...]"
@@ -6,8 +6,14 @@ argument-hint: "[change-name] [上下文文件...]"
 
 创建 **proposal.md** - 业务意图与上下文总览文档（聚焦 Why）。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=propose --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 > **⚠️ 阶段边界提示**
 >
@@ -28,7 +34,7 @@ argument-hint: "[change-name] [上下文文件...]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=propose --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -396,4 +402,4 @@ argument-hint: "[change-name] [上下文文件...]"
 - **⛔ 单阶段原则：完成 proposal.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:spec`，**绝对禁止自动执行 spec/design/task 等后续阶段**。每个阶段必须由用户主动触发。
 
 > **📊 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=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="一句话摘要"`

package/templates/opsx-commands/spec.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Spec
 description: "创建技术契约文档 - 为每个能力定义业务场景与技术规范"
 argument-hint: "[change-name] [上下文文件...]"
@@ -6,8 +6,13 @@ argument-hint: "[change-name] [上下文文件...]"
 
 创建 **specs/<capability>/spec.md** - 业务场景与技术契约文档（代码生成的唯一真理，聚焦 What）。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=spec --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=spec --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 > **⚠️ 阶段边界提示**
 >
@@ -44,7 +49,7 @@ openspec/changes/<name>/
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=spec --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=spec --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -512,5 +517,10 @@ openspec/changes/<name>/
 - **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Spec 阶段，代码操作请在完成文档后使用 `/opsx:apply` 执行。」
 - **⛔ 单阶段原则：完成 spec.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:design`，**绝对禁止自动执行 design/task 等后续阶段**。每个阶段必须由用户主动触发。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=spec --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="一句话摘要"`

package/templates/opsx-commands/task.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Task
 description: "创建任务拆解文档 - 针对单一 Capability 的 DAG 任务清单"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -6,8 +6,13 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
 创建 **tasks.md** - 针对单一 Capability 的 AI 编码引擎执行单元（支持拓扑依赖管理）。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=task --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=task --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 > **⚠️ 阶段边界提示**
 >
@@ -37,7 +42,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=task --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=task --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -286,7 +291,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
    ### [TASK-XXX-01] 任务名称
    - **类型**: 数据层 / 接口层 / UI层 / 测试
    - **依赖**: 无
-   - **状态**: [ ] 未完成
+   - **状态**: [ ] 未完成（勾选格式统一使用 GitHub 标准的 `- [ ]` / `- [x]`）
 
    #### 任务描述
    <!-- 一句话描述本任务要做什么 -->
@@ -419,5 +424,10 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 - **⛔ 阶段边界**：本阶段只创建任务清单，禁止直接执行代码操作
 - **⛔ 单阶段原则：完成 tasks.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:check` 或 `/opsx:apply`，**绝对禁止自动执行 apply/check 等后续阶段**。每个阶段必须由用户主动触发。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=task --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="一句话摘要"`

package/templates/opsx-commands/test.md

@@ -1,4 +1,4 @@
----
+---
 name: OPSX: Test
 description: "执行单元测试 - 自动检测并运行测试用例，输出测试报告"
 argument-hint: "[test-scope] [options]"
@@ -6,8 +6,13 @@ argument-hint: "[test-scope] [options]"
 
 执行单元测试 - 自动检测项目中的测试用例并运行，输出结构化测试报告。
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=test --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
 
 > **⚠️ 命令定位**
 >
@@ -23,7 +28,7 @@ argument-hint: "[test-scope] [options]"
 
    在终端执行（若命令失败必须中止本阶段，不得跳过）：
    ```bash
-   node skywalk-sdd/log.js start --command=test --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   node skywalk-sdd/log.js start --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
    ```
    保存输出 JSON 中的 `event_id`，供阶段结束使用。
 
@@ -168,6 +173,31 @@ argument-hint: "[test-scope] [options]"
    > - B. **创建测试用例** - 为当前实现生成测试
    > - C. **跳过测试** - 本次不执行测试"
 
+5. **【Telemetry 必做】整理结构化测试结果**
+
+   测试运行后，必须将结果整理为以下标准 schema：
+
+   ```json
+   {
+     "test_results": {
+       "command": "npm test",
+       "passed": 12,
+       "failed": 0,
+       "skipped": 1,
+       "coverage": 85.5,
+       "duration_ms": 40000
+     }
+   }
+   ```
+
+   **字段口径**：
+   - `command`: 实际执行的测试命令。
+   - `passed`: 通过用例数。
+   - `failed`: 失败用例数。
+   - `skipped`: 跳过用例数，没有则填 `0`。
+   - `coverage`: 覆盖率百分比，无法获取时填 `null`。
+   - `duration_ms`: 测试耗时，无法获取时填 `null`。
+
 ---
 
 **使用示例**
@@ -203,5 +233,12 @@ argument-hint: "[test-scope] [options]"
 - **不阻塞流程**：测试结果作为参考，由用户决定是否继续
 - **支持增量测试**：支持仅运行变更相关的测试，提升效率
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=test_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="测试结果摘要" --details-json="{\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"`
+> 若 spec.md 中有可识别场景 ID，且测试能映射到这些场景，建议记录 Q4 规约驱动测试覆盖率（可选，不阻塞测试流程）：`node skywalk-sdd/log.js record --type=coverage_result --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="规约场景测试覆盖率" --details-json="{\"spec_test_coverage\":{\"mappings\":[{\"scenario_id\":\"SCN-001\",\"description\":\"规约场景摘要\",\"test_ids\":[\"<测试文件或用例ID>\"],\"status\":\"covered\",\"notes\":\"\"}]}}"`
+> 阶段结束时执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --command=test --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="测试结果摘要" --details-json="{\"test_results\":{\"command\":\"<实际测试命令>\",\"passed\":0,\"failed\":0,\"skipped\":0,\"coverage\":null,\"duration_ms\":0}}"`

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-apply
 description: "变更实施技能 - 针对单一 Capability 按 DAG 依赖顺序实现代码"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -23,9 +23,21 @@ allowed-tools:
 > - **上下文**：overview.md → proposal.md → 当前 capability 的 spec/design/tasks
 > - ⛔ **隔离红线**：绝对禁止加载同级其他 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=apply --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --result=success|failure --summary="摘要" --project=<项目根目录绝对路径>`
+> - 阶段开始：`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）
+> - 阶段结束：`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="摘要"`
+
+> **🔒 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 度量本身不得主动提交。
 
 ---
 
@@ -42,6 +54,36 @@ allowed-tools:
 
 ## 启动流程
 
+### 0. 【Telemetry 必做】只读探测 Git 基线
+
+先以只读方式探测版本控制状态。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 项目必须继续实施，不得为了度量自动创建仓库或提交快照。
+
 ### 1. 【交互引导】确认变更名称和 Capability
 
 **步骤 1a - 确认变更名称**：
@@ -138,12 +180,27 @@ e. **⛔ 测试执行门禁**
    | `none` | **跳过**：不执行测试门禁 |
 
 f. **⛔ 立即更新任务状态**
-   - 修改 tasks.md：`状态: [ ] 未完成` → `状态: [x] 已完成`
+   - 修改 tasks.md：将 `- [ ]` 替换为 `- [x]`（包括拓扑图和任务详情中的复选框）
+   - 同时修改：`- **状态**: [ ] 未完成` → `- **状态**: [x] 已完成`
+   - **两种格式必须同步更新**，不可遗漏
    - 验证修改成功
    - 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
+   - 记录任务级 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}}"
+     ```
 
 g. **继续下一个可执行任务**
 
+### 5.1 【Telemetry 必做】记录 AI 产出快照
+
+当前 Capability 的 AI 代码产出完成后，必须记录 `ai_adoption_review`，但不得为了采集快照自动提交 commit。
+
+Git 可用时只读统计 SHA/diff；Git 不可用时使用 `vcs_mode=no-git` 和 `base_git_sha=null`：
+```bash
+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；仅记录可用统计\"}}"
+```
+
 ### 6. 完成或暂停时显示状态
 
 展示 DAG 执行摘要，引导下一步：
@@ -161,7 +218,8 @@ g. **继续下一个可执行任务**
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - **⛔ 编译检查门禁**：每完成一个任务后，**必须运行编译检查**，编译失败禁止标记已完成
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=警告, none=跳过）
-- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 状态
+- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 中的 `- [ ]` 为 `- [x]`，**同时修改** `**状态**: [ ] 未完成` 为 `**状态**: [x] 已完成`，两种格式不可遗漏
+- **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目使用 `vcs_mode=no-git` 继续执行
 - **显示进度反馈**：每完成一个任务，显示「✅ [TASK-ID] 已完成 [N/M]」
 - **保持任务聚焦**：每次只处理一个任务
 - **遇到问题时暂停**：任务描述模糊、编译失败、测试失败或发现设计问题时暂停询问

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

@@ -1,12 +1,12 @@
 ---
 name: opsx-archive
-description: "归档变更技能 - 将已完成或取消的变更归档，清理活动状态"
+description: "归档变更技能 - 将已结束的 SDD 变更真实移入 archive，并生成最终中文度量报告"
 argument-hint: "[change-name]"
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires skywalk-sdd/log.js.
 metadata:
   author: sdd-team
-  version: "3.0"
+  version: "3.2"
 allowed-tools:
   - Bash
   - Read
@@ -14,84 +14,131 @@ allowed-tools:
   - Edit
 ---
 
-你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你将引导用户安全地归档已完成或取消的变更。
+你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
-
-> **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.js start --command=archive --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --result=success|failure --summary="摘要" --project=<项目根目录绝对路径>`
+> **跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
+> - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。
+> - 本技能不调用 OpenSpec 自带归档命令；统一使用 SkyWalk-SDD 的 `archive-docs`。
 
 ---
 
 ## 技能定位
 
 | 维度 | 内容 |
-|------|------|
-| 核心问题 | 变更生命周期管理 - 归档已结束的变更 |
-| 关键输出 | 变更状态变为 ARCHIVED |
-| 触发时机 | 所有任务已完成 / 变更被取消 / 变更被搁置 |
+|---|---|
+| 核心问题 | 变更生命周期结束与度量收口 |
+| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`skywalk-sdd/reports/<change>-report.md` |
+| 触发时机 | 任务完成、变更取消、变更搁置、或用户要求归档 |
 
 ---
 
 ## 启动流程
 
-### 1. 【交互引导】确认变更名称
+### 1. 确认变更名称并记录阶段开始
+
+如果未提供变更名，运行：
 
-若未提供，列出当前所有变更供用户选择：
 ```bash
 openspec list
 ```
-展示每个变更的状态（PENDING / IMPLEMENTING / ARCHIVED），引导用户选择。
 
-### 2. 获取变更状态
+让用户选择现有变更。确认后记录阶段开始：
 
 ```bash
-openspec status --change "<name>" --json
+node skywalk-sdd/log.js start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
 ```
 
-检查变更当前状态：
-- `PENDING`：尚未申请实施（提醒用户是否跳过实施直接归档）
-- `IMPLEMENTING`：正在实施中（提醒用户确认是否全部任务已完成）
-- `ARCHIVED`：已归档（提示用户该变更已归档，无需操作）
+保存 `event_id`。
+
+### 2. 询问归档原因
+
+使用交互问题让用户选择：
+
+> 请选择归档原因：
+> - A. 变更已完成实施
+> - B. 变更已取消
+> - C. 变更已搁置
+> - D. 其他原因
+
+记录为 `<归档原因>`，它会进入 `archive-manifest.json`、archive telemetry 和最终报告。
+
+### 3. 运行 telemetry doctor
+
+```bash
+node skywalk-sdd/log.js doctor --project=. --change=<变更名称>
+```
 
-**【状态异常处理】**：
+如果存在 `severe_issues`，暂停归档并说明必须先修复。`superseded_open_stages` 和 `rework_summary` 只作为返工/重复执行展示，不要求用户人工区分测试回滚或真实研发返工。
 
-若变更为 `PENDING`（从未实施）：
-> "变更 `<name>` 尚未申请实施，确定要直接归档？
-> - A. 确认归档（变更已取消/搁置）
-> - B. 先申请实施（运行 `/opsx:apply <name>`）"
+### 4. 扫描 tasks 完成状态
 
-若变更为 `IMPLEMENTING`（实施中）：
-> "变更 `<name>` 正在实施中，请确认所有 tasks.md 任务已完成：
-> - A. 确认全部完成，归档变更
-> - B. 取消（继续实施中状态）"
+```bash
+node skywalk-sdd/log.js tasks-status --project=. --change=<变更名称>
+```
 
-### 3. 【交互引导】确认归档原因
+即使用户选择“变更已完成实施”，未勾选项也不阻断归档。它可能代表任务真实未完成，也可能代表代码已完成但文档未同步；不要猜测，也不要静默忽略。最终必须让 `archive-docs` 将其写入 `archive_result.task_completion` 和报告。
 
-使用 **AskUserQuestion** 让用户选择：
-> "请确认归档原因（将记录在归档日志中）：
-> - A. 变更已完成实施 ✅（所有任务已完成并验收）
-> - B. 变更已取消 ❌（业务原因取消）
-> - C. 变更已搁置 ⏸（暂缓实施，保留文档）
-> - D. 其他（请输入原因）"
+### 5. 一步执行真实归档
 
-### 4. 执行归档
+执行唯一归档命令：
 
 ```bash
-openspec archive "<name>"
+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
 ```
 
-### 5. 输出结果
+该命令成功后必须已经完成：
+- 活动目录 `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`。
+
+如果该命令失败，以失败状态结束 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="归档失败：<失败原因>"
+```
 
-> "✅ 变更 `<name>` 已归档！
-> - 归档原因：[用户选择的原因]
-> - 文档路径：openspec/changes/<name>/（已保留，可随时查阅）
-> - 如需查看所有归档变更，运行 `/opsx:explore`"
+失败时不要输出“归档完成”。
+
+### 6. 输出给用户
+
+成功时只输出真实产物路径：
+
+> 变更 `<name>` 已真实归档。
+> - 归档目录：`openspec/changes/archive/<日期>-<name>/`
+> - 最终报告：`skywalk-sdd/reports/<name>-report.md`
+> - 未勾选任务：X 项，已记录到报告，不阻断归档
+> - 正式 specs：`openspec/specs/`
+
+被 doctor 阻断、真实归档失败或报告生成失败时，不要说“归档完成”。
+
+---
+
+## 可选补录
+
+如用户愿意提供反馈，可补录问卷结果：
+
+```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\":\"\"}}"
+```
 
 ---
 
 ## Guardrails
 
-- 归档操作执行前必须用户明确确认，不可自动执行
-- 归档后文档仍保留在 `openspec/changes/<name>/` 目录，不会删除
-- 若变更状态已是 `ARCHIVED`，提示用户直接跳过，无需重复操作
+- 归档操作执行前必须让用户确认归档原因。
+- 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
+- “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
+- 最终报告必须由 `archive-docs --report-output=...` 自动生成。
+- 已归档变更不要重复移动；展示已有 archive 目录和 report 路径。

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-check
 description: "质量检查技能 - 验证文档完整性、一致性、算法正确性及可执行性"
 argument-hint: "[change-name] [上下文文件...]"
@@ -26,9 +26,15 @@ allowed-tools:
 > 代码修复将在 `/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 start --command=check --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --result=success|failure --summary="摘要" --project=<项目根目录绝对路径>`
+> - 阶段开始：`node skywalk-sdd/log.js start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 检查报告生成后，必须先记录结构化检查结果：`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="摘要"`
 
 ---
 
@@ -104,6 +110,20 @@ openspec list
 - [ ] 所有外部依赖已明确状态
 - [ ] 代码锚点存在且可访问
 
+#### 4.5 任务完成状态检查（实现后 / 归档前）
+
+`task` 阶段允许 `tasks.md` 出现未完成项；这只是计划状态。但如果当前变更已经进入 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。
+- 若用户准备归档“变更已完成实施”：未勾选项仍只作为 warning/待确认事实展示，不阻断归档。
+- Check 阶段只读，不自动勾选；报告中必须说明这是“任务可能已执行但文档未同步”或“任务真实未完成”的待确认项。
+
 ### 5. 输出检查报告
 
 > "📋 **质量检查报告**
@@ -120,6 +140,30 @@ openspec list
 > **建议操作**：
 > - [具体修复建议及对应命令]"
 
+### 5.1 【Telemetry 必做】记录结构化检查结果
+
+输出检查报告后，必须把检查结果转换为 `check_result` 事件，并在 `stage_end` 之前执行成功。禁止只记录阶段结束。
+
+字段口径：
+- `total`: 本次检查项总数。
+- `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`。
+
+在终端执行（必须成功）：
+```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}}}"
+```
+
+若当前已有实现代码，并且能够验证 spec 断言，还应记录 `conformance_review`（用于 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\":\"\"}]}}"
+```
+
 ### 6. 【交互引导】根据结果引导下一步
 
 **全部通过**：

package/templates/skills/opsx-design/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: opsx-design
 description: "技术设计文档技能 - 针对单一 Capability 创建局部技术实现方案"
 argument-hint: "[change-name] [capability-name] [上下文文件...]"
@@ -34,9 +34,14 @@ allowed-tools:
 > - ⛔ **隔离红线**：绝对禁止跨目录读取同级其他 Capability 的 spec 或 design
 
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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 end --event-id=<event_id> --result=success|failure --summary="摘要" --project=<项目根目录绝对路径>`
+> - 阶段开始：`node skywalk-sdd/log.js start --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 

package/templates/skills/opsx-explore/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: opsx-explore
 description: "浏览变更技能 - 查看所有变更状态和 SDD 文档完整性概览"
 argument-hint: "[change-name]"
@@ -17,9 +17,14 @@ allowed-tools:
 你是一个 SDD（Specification-Driven Development）变更浏览专家。激活本技能后，你将展示项目中所有变更的状态概览，并引导用户执行下一步操作。
 
 
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `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 end --event-id=<event_id> --result=success|failure --summary="摘要" --project=<项目根目录绝对路径>`
+> - 阶段开始：`node skywalk-sdd/log.js start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---