kld-sdd 2.6.11 → 2.6.13

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

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

package/templates/skills/kld-sdd/opsx-apply/worktree-setup.md

@@ -72,7 +72,7 @@
 ### record-base
 
 ```bash
-node skywalk-sdd/apply-worktree-finish.cjs --record-base \
+node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" --record-base \
   --change=<change> --capability=<capability>
 ```
 
@@ -88,10 +88,10 @@ git worktree add .worktrees/apply-<change>-<capability> -b kld-sdd/<change>/<cap
 ### finish
 
 ```bash
-node skywalk-sdd/apply-worktree-finish.cjs --change=<change> --capability=<capability>
+node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs" --change=<change> --capability=<capability>
 ```
 
-状态文件：`skywalk-sdd/state/apply-<change>-<capability>.json`
+状态文件：`"$(cat .sdd-spec-root)/skywalk-sdd/state/apply-<change>-<capability>.json`
 
 ## 快速参考
 

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

@@ -21,8 +21,8 @@ allowed-tools:
 
 > **跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `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`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - 不要裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请加引号或改成正斜杠。
 > - 不要省略 `--source=opsx-command` 和 `--session-id=<会话ID>`。
@@ -35,7 +35,7 @@ allowed-tools:
 | 维度 | 内容 |
 |---|---|
 | 核心问题 | 变更生命周期结束与度量收口 |
-| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.md`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.html`、`openspec/changes/archive/<日期>-<change>/logs/execution-log.md` |
+| 关键输出 | `openspec/changes/archive/<日期>-<change>/`、`openspec/specs/`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.md`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.html`、`openspec/changes/archive/<日期>-<change>/reports/<change>-report.json`、`openspec/changes/archive/<日期>-<change>/logs/execution-log.md` |
 | 触发时机 | 任务完成、变更取消、变更搁置、或用户要求归档 |
 
 ---
@@ -53,7 +53,7 @@ openspec list
 让用户选择现有变更。确认后记录阶段开始：
 
 ```bash
-node skywalk-sdd/log.cjs start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
 ```
 
 保存 `event_id`。
@@ -78,12 +78,12 @@ node skywalk-sdd/log.cjs start --command=archive --project=. --change=<变更名
 git worktree list
 ```
 
-应仅剩主工作区；或 telemetry 中存在 `worktree_finish` + `result=success` 事件。若仍有 `.worktrees/apply-*`，先执行 `node skywalk-sdd/apply-worktree-finish.cjs` 或手工清理。
+应仅剩主工作区；或 telemetry 中存在 `worktree_finish` + `result=success` 事件。若仍有 `.worktrees/apply-*`，先执行 `node "$(cat .sdd-spec-root)/skywalk-sdd/apply-worktree-finish.cjs"` 或手工清理。
 
 ### 3. 运行 telemetry doctor
 
 ```bash
-node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" doctor --project=. --change=<变更名称>
 ```
 
 如果存在 `severe_issues`，暂停归档并说明必须先修复。`superseded_open_stages` 和 `rework_summary` 只作为返工/重复执行展示，不要求用户人工区分测试回滚或真实研发返工。
@@ -91,21 +91,57 @@ node skywalk-sdd/log.cjs doctor --project=. --change=<变更名称>
 ### 4. 扫描 tasks 完成状态
 
 ```bash
-node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
+node "$(cat .sdd-spec-root)/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」。
+- `task_completion.primary_tasks`：真正的交付任务，决定“完成/部分完成”结论。
+- `task_completion.acceptance_evidence`：测试、评审、手工验收等证据的确认情况，只提示证据缺口，不冒充任务进度。
+
+仅当 `primary_tasks.has_incomplete=true` 时，归档原因才改写为“部分完成（N 个主任务未完成）”。主任务已完成但验收证据待确认时，允许归档，但最终报告必须在“需要处理”中明确提示。
+
+> **📊 归档前 process_note（U3）**：归档前对 tasks.md checkbox 的勾选、文档补齐等修补动作，**必须**记 `process_note` 事件（`kind=recovery`，`target=tasks.md:行号`），让"check 时待确认 N 项 → archive 结案 N 项"的对照可追溯。若归档前存在拦截/失败但无 `process_note`，`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`。模板见 `opsx-apply/reference.md`「process_note」。
+
+### 4.5 可选记录成熟度证据（仅有可审计证据时）
+
+如需评估 L3/L4，必须在 `archive-docs` 生成最终报告前记录标准 `maturity_evidence`。先将以下 JSON 写入 `skywalk-sdd/state/<变更名称>-maturity-evidence.json`：
+
+```json
+{
+  "maturity_evidence": {
+    "change_type": "config|document|report|composite|other",
+    "e1_actual_ms": 500,
+    "e1_target_ms": 600,
+    "e1_type_target_met": true,
+    "code_fully_spec_generated": true,
+    "generated_files": ["src/generated.js"],
+    "manual_code_lines": 0,
+    "evidence_summary": "规约生成范围与独立复核结论",
+    "reviewer": "独立评审者标识",
+    "reviewer_independence": "independent-review",
+    "review_session_id": "review-session-id",
+    "author_session_id": "author-session-id"
+  }
+}
+```
+
+然后执行：
+
+```bash
+node skywalk-sdd/log.cjs record --type=maturity_evidence --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="成熟度证据" --details-file=skywalk-sdd/state/<变更名称>-maturity-evidence.json
+```
+
+`e1_type_target_met` 必须等于 `e1_actual_ms <= e1_target_ms` 的计算结果。仅当 `code_fully_spec_generated=true` 时，`generated_files`、`manual_code_lines=0`、证据摘要和独立评审字段才可授予 L4；`review_session_id` 必须与 `author_session_id` 不同。CLI 会硬校验这些字段，只有两个布尔断言的事件不会被报告采信。
 
 ### 5. 一步执行真实归档
 
 执行唯一归档命令：
 
 ```bash
-node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reason="变更已完成实施" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" archive-docs --project=. --change=<变更名称> --reason="变更已完成实施" --event-id=<event_id> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
 ```
 
 > `--reason` 默认值为 `变更已完成实施`；如果用户选择了其他归档原因，请将上述 `--reason` 的值替换为对应原因。
@@ -117,7 +153,8 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
-- 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（默认同时生成 .md 与 .html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
+- 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`<name>-report.html` 与 `<name>-report.json`（三份同源报告，默认归档后 archive 目录，可用 --report-output 自定义）。
+- `archive_result` 含 `report_path`、`report_html_path`、`report_json_path`；任一 companion 写入失败须记录 telemetry 警告，主 Markdown 失败仍按现有失败策略处理。
 - 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
 
 ### 5.4 隐式注销活动变更
@@ -125,7 +162,7 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 归档成功后立即执行（不询问用户）：
 
 ```bash
-node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<变更名称> --project=.
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" active-change --remove --change=<变更名称> --project=.
 ```
 
 把该 change 从 spec 仓 `sdd.config.yaml` 的 `active_changes` 移除，避免已归档 change 继续被代码 commit 写成 `Spec-Change`。该操作幂等；条目本就不存在时不报错。
@@ -136,12 +173,12 @@ node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<变更名称>
 2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；成功则写 `ingest-receipt.json`。
 3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
 
-> 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
+> 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 
 如果该命令失败，以失败状态结束 telemetry：
 
 ```bash
-node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="归档失败：<失败原因>"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=archive --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=failure --summary="归档失败：<失败原因>"
 ```
 
 失败时不要输出“归档完成”。
@@ -152,7 +189,7 @@ node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=.
 
 > 变更 `<name>` 已真实归档。
 > - 归档目录：`openspec/changes/archive/<日期>-<name>/`
-> - 最终报告（默认同时生成 .md + .html）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`openspec/changes/archive/<日期>-<name>/reports/<name>-report.html`
+> - 最终报告（Markdown + HTML + JSON 三产物）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`<name>-report.html`、`<name>-report.json`
 > - 执行日志：`openspec/changes/archive/<日期>-<name>/logs/execution-log.md`
 > - 知识库归档包：`openspec/changes/archive/<日期>-<name>.zip`
 > - 本体消费入口：`openspec/changes/archive/<日期>-<name>/canonical-facts.json`
@@ -168,21 +205,21 @@ node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=.
 如用户愿意提供反馈，可补录问卷结果：
 
 ```bash
-node skywalk-sdd/log.cjs 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\":\"\"}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" 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.cjs 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\":\"\"}}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" 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\":\"\"}}"
 ```
 
 ---
 
 ## 本体语义归档门禁
 
-- 归档前必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
-- 随后必须运行 `node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
+- 归档前必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
+- 随后必须运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
 - Archive 不负责首次生成 propose/spec/design/tasks 的工作态事实；它重新解析原文核对 pending revision，补充 `OntologySnapshot/project_id/archive_id` 后冻结为 confirmed。
 - `archive-docs` 成功后必须在归档目录生成 `archive-ontology.json`，并将 `review_status` 标记为 `confirmed`。
 - 生产端必须把 confirmed 本体转换为 `canonical-facts.json`；实体固定为 `fact_kind=semantic`、`assertion_type=asserted`、`review_status=confirmed`，关系必须补齐对应语义边界字段。
@@ -199,7 +236,8 @@ node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --proje
 - 归档操作执行前必须让用户确认归档原因。
 - 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
 - “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
-- 最终报告由 `archive-docs` 自动生成（md+html 双产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。
+- 最终报告由 `archive-docs` 自动生成（Markdown + HTML + JSON 三产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。
+- 双周/月度周期跟踪为**归档后或项目级独立入口**，不阻塞单变更归档；示例：`node skywalk-sdd/log.cjs report --project=. --period=biweekly --date-from=YYYY-MM-DD --date-to=YYYY-MM-DD`
 - 已归档变更不要重复移动；展示已有 archive 目录和 report 路径。
 
 ---

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

@@ -9,11 +9,13 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 
 ## 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`，不阻断归档但必须如实记录
+- [ ] `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" doctor --project=. --change=<变更名称>` 无 `severe_issues`（`superseded_open_stages`/`rework_summary` 仅展示，不阻断）
+- [ ] `node "$(cat .sdd-spec-root)/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 事件）
+- [ ] 如需评估 L3/L4，已在归档报告生成前记录标准 `maturity_evidence`；不得只提交 `e1_type_target_met` / `code_fully_spec_generated` 两个布尔断言
+- [ ] `maturity_evidence` 的 E1 实测/目标可复算；声称完整规约生成时，`generated_files` 非空、`manual_code_lines=0`，且 `review_session_id` 与 `author_session_id` 不同
 
 ## B. 归档后自检
 
@@ -24,7 +26,8 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 - [ ] `openspec/changes/archive/<日期>-<变更名称>.zip` 存在并可由知识库 `ArchivePackageReader` 读取
 - [ ] canonical facts 中每个实体/关系均能通过 `source.file`、`source.anchor_id`、`source.content_hash` 定向展开到包内原文
 - [ ] 最终报告 `openspec/changes/archive/<日期>-<变更名称>/reports/<变更名称>-report.md` 存在且含「归档结果」段
-- [ ] `reports/<变更名称>-report.md` 与 `reports/<变更名称>-report.html` 都已生成（md+html 双产物）
+- [ ] `reports/<变更名称>-report.md`、`<变更名称>-report.html` 与 `<变更名称>-report.json` 均已生成（Markdown + HTML + JSON 三产物同源）
+- [ ] `archive_result` 或报告「归档结果」段含 `report_path`、`report_html_path`、`report_json_path`
 - [ ] html 报告含 `SDD 效果度量报告` 标题与各度量章节（执行摘要/效率/质量/过程/归档结果/说明）
 - [ ] 执行日志 `openspec/changes/archive/<日期>-<变更名称>/logs/execution-log.md` 随 change 整目录迁移到 archive（含 archive 阶段 stage_start+stage_end+✅OK）
 - [ ] 正式 specs 同步到 `openspec/specs/<capability>/spec.md`

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

@@ -33,15 +33,15 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node skywalk-sdd/openspec-shim.cjs list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - `skywalk-sdd/log.cjs` / `ontology/cli.cjs`：`--project=.` 在 Git 根/工作区根会自动解析；也可 `node skywalk-sdd/ontology/cli.cjs spec-root` 查看路径。
+> - `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`。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--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,\"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},\"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 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="摘要"`
+> - 阶段开始：`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` 记录成功后，才允许阶段结束：`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 或补齐文档，使三者数字自洽。
 
 ---
@@ -82,10 +82,10 @@ openspec list
 
 ```bash
 # 在 spec 仓库：
-node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --change=<change-key>
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --project=. --change=<change-key>
 
 # 在代码仓库：
-node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
+node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --project=. --mode=code-repo
 ```
 
 诊断结果三类：
@@ -122,7 +122,7 @@ node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
    - 若未标记 → 继续检查。
 2. 运行 KB 就绪检查（程序化检测，自动搜索多 IDE 目录，消除路径歧义）：
    ```bash
-   node skywalk-sdd/context-client.cjs --check-only
+   node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
    ```
    - 输出 `"available": true` → KB 已配置
    - 输出 `"available": false` → KB 未配置
@@ -171,7 +171,7 @@ node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
 - [ ] 跨文档引用路径正确
 - [ ] ⛔ **CON 覆盖一致性**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖；tasks.md 声明"100% 覆盖 CON"时必须可追溯
 - [ ] ⛔ **安全/审计要求覆盖一致性**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
-- [ ] ⛔ **AC 变体覆盖一致性**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准须列出所有变体的测试方法（规则见 `opsx-tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖）
+- [ ] ⛔ **AC 变体覆盖一致性**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准须列出所有变体的测试方法（规则见 `tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖）
 - [ ] ⛔ **tasks.md §4.x 验证方式表内部一致性**：§4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
 
 #### 4.3 算法正确性检查
@@ -189,17 +189,17 @@ node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
 
 #### 4.4a TDD 合规性检查（仅 test-strategy=tdd 时执行）
 
-⛔ 执行 `opsx-tdd-core/checklist.md` §B（15 项）逐项检查。
+⛔ 执行 `tdd-core/checklist.md` §B（15 项）逐项检查。
 
-> 不在此内联复制，以 opsx-tdd-core/checklist.md §B 为唯一真相源。
-> 额外补充：还需检查 `opsx-tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）。
+> 不在此内联复制，以 tdd-core/checklist.md §B 为唯一真相源。
+> 额外补充：还需检查 `tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）。
 
 **检查项适用阶段**：§B 中部分检查项在 apply 前后均可验证（文档级），部分仅在 apply 后可验证（代码级）：
 - **apply 前可验证**（文档级）：RED 验收标准包含"测试运行失败"、无"断言为空"、GREEN 为行为级粒度、DAG 存在 RED→GREEN 循环对、非 TDD 模块未拆红绿、GREEN 验收标准为"让对应 RED 通过"、已声明 Controller 策略、Controller 两种策略都生成测试任务、每个 RED 含测试方法名、每个 GREEN 含 YAGNI 围栏、每个 REFACTOR 列出重构点
 - **apply 后可验证**（代码级）：GREEN 任务输出不含未测试的 Controller/Filter/Config
 
 ⛔ BEFORE 完成 TDD 合规性检查，如需深度审查测试质量，必须读取：
-- opsx-tdd-review/SKILL.md（测试质量审查清单 8 项 + 缺失测试检测）
+- tdd-review/SKILL.md（测试质量审查清单 8 项 + 缺失测试检测）
 读取后确认："已读取测试质量审查清单"。
 
 #### 4.5 任务完成状态检查（实现后 / 归档前）
@@ -207,7 +207,7 @@ node skywalk-sdd/ontology/cli.cjs diagnose-naming --project=. --mode=code-repo
 `task` 阶段允许 `tasks.md` 出现未完成项；这只是计划状态。但如果当前变更已经进入 apply 之后，或本次 check 发现实现代码、测试报告、`build_result/test_result/task_update/conformance_review` 等实施证据，必须检查任务勾选状态：
 
 ```bash
-node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --change=<变更名称>
 ```
 
 判定规则：
@@ -244,22 +244,26 @@ node skywalk-sdd/log.cjs tasks-status --project=. --change=<变更名称>
 - `warning_items`: 警告明细数组，每项 `{category, description, target}`（如 `{"category":"task_completion","description":"4.3 手动验证清单未勾选","target":"tasks.md:595"}`），用于报告已知风险区渲染具体待确认项；无明细时省略（向后兼容，旧事件仅 `warnings` 数量，报告降级显示数量）。
 - `suggestions`: 可选优化建议数。
 - `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`。
+- `consistency_score`: **legacy 兼容字段**（保留一个发布版本）；跨文档一致性评分 0-1，无法评分时填 `null`。
+- `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`。
 - `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,\"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},\"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 --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}}}"
 ```
 
-> **⚠️ P1-1 check_result details 不得为空**：`--details-json` 必须含 `consistency_score` / `categories` / `task_completion` 等字段，**禁止传空对象 `{}`**。空 details 会导致 report 的 Q5 跨文档一致性得分、P4b 修复率为 null（工具侧虽有 state fallback 兜底，但事件 details 是主数据源）。
+> **⚠️ P1-1 check_result details 不得为空**：`--details-json` 必须含 `categories` / `task_completion` / reviewer 独立性字段等，**禁止传空对象 `{}`**。空 details 导致 Q3 不可计算（工具侧虽有 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\",\"agent_confirmed\":true,\"human_status\":\"unverified\",\"reviewer\":\"<reviewer-identifier>\",\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
+node "$(cat .sdd-spec-root)/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 规约符合度会据此标注「自评，待人工确认」。
@@ -270,7 +274,11 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 > - `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，以提升结果可信度。
+> **reviewer 与 reviewer_independence 说明（check_result）**：执行 check 前先读取文档作者/阶段会话信息；**能使用独立 evaluator 时必须使用**。`reviewer_independence=independent-review` 且 `review_session_id` 与 `author_session_id` 不同时，Q3 为 `verified`；自评或无法确认时为 `self-review` 或 `unknown`，Q3 标 `provisional` 但仍可计算分数。
+
+> **报告用语**：`verified` 展示为“已验证”，表示有独立复核；`provisional` 展示为“临时”，表示已有数值但仍需独立复核。不得仅用颜色区分，也不得把临时结果写成最终可信结论。
+
+> **reviewer 与 reviewer_independence 说明（conformance_review）**：`reviewer` 用于标识实际执行本次符合度评审的代理或会话（例如 agent 名称、会话 ID）。渲染报告时会比较 `reviewer` 与 apply 阶段记录的 `apply_agent`：若两者相同，则 `reviewer_independence` 显示为 `self-review`；否则显示为 `independent-review`。建议尽可能由独立评审方执行 check，以提升结果可信度。
 
 ### 6. 【交互引导】根据结果引导下一步
 
@@ -288,7 +296,7 @@ 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」。
+> **📊 过程记录（U3）**：若用户选择 A 逐个修复，或在 check 后、归档前补充修复（补 README/CHANGELOG、勾 checkbox 等），每个修复动作**必须**记 `process_note` 事件（`kind=recovery`，`command=check`），归档前修补不再黑箱。**若本阶段存在失败/门禁拦截但无对应 `process_note`，`sdd-apply-test-gate` 会记 `telemetry_warning(process_note_missing)`（不阻断，但报告过程质量信号会标红）。** 必记节点清单见 `opsx-apply/reference.md`「process_note」。
 
 ---
 
@@ -314,8 +322,8 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 在其他质量检查前必须运行：
 
 ```bash
-node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称> --profile=<simple|full|strict>
-node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称> --profile=<simple|full|strict>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-reconcile --project=. --change=<变更名称> --profile=<simple|full|strict>
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-check --project=. --change=<变更名称> --profile=<simple|full|strict>
 ```
 
 - `simple` 必须阻断 STMT 无 AC；没有 design/tasks 时跳过对应链路，不得误报。