kld-sdd 2.6.12 → 2.6.14

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

@@ -17,14 +17,20 @@ description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策
 ### task_update（每完成一个任务记录）
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-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` 内容过长，可先写入 `"$(cat .sdd-spec-root)/skywalk-sdd/state/<变更名称>-task-update.json`，再使用 `--details-file` 指定该文件：
 
@@ -38,47 +44,42 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=task_update --com
 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 "$(cat .sdd-spec-root)/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 产出快照）
 
@@ -349,7 +350,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_revie
 
 ## §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 "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=ai_adoption_revie
 
 ## §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 之后才发现测试是假的。
 

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

@@ -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` |
 | 触发时机 | 任务完成、变更取消、变更搁置、或用户要求归档 |
 
 ---
@@ -96,9 +96,45 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
 
 即使用户选择“变更已完成实施”，未勾选项也不阻断归档。它可能代表任务真实未完成，也可能代表代码已完成但文档未同步；不要猜测，也不要静默忽略。最终必须让 `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. 一步执行真实归档
 
@@ -117,7 +153,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" archive-docs --project=. --chan
 - 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 隐式注销活动变更
@@ -152,7 +189,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --event-id=<event_id> --com
 
 > 变更 `<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`
@@ -199,7 +236,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=baseline_record -
 - 归档操作执行前必须让用户确认归档原因。
 - 不要调用 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

@@ -14,17 +14,20 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 - [ ] `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. 归档后自检
 
 - [ ] 归档目录 `openspec/changes/archive/<日期>-<变更名称>/` 存在
 - [ ] `openspec/changes/archive/<日期>-<变更名称>/` 下 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和 `archive-manifest.json` 均存在
-- [ ] 活动 change 目录下的 `artifacts/*.ontology.json` 与 `artifact-index.json` 已随归档目录一并迁移
+- [ ] 活动 change 目录下的 `artifacts/*.ontology.json` 与 `ontology/artifact-index.json` 已随归档目录一并迁移
 - [ ] `archive-manifest.json` 为 `kld-sdd-archive-manifest/v2`，且 `files` 精确覆盖 ZIP 内除 manifest 自身外的全部文件
 - [ ] `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

@@ -40,7 +40,7 @@ allowed-tools:
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
 > - 阶段开始：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 检查报告生成后，必须先记录结构化检查结果：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-json="{\"check_results\":{\"total\":0,\"errors\":0,\"warnings\":0,\"warning_items\":[],\"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\":[],\"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 或补齐文档，使三者数字自洽。
 
@@ -171,7 +171,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --proj
 - [ ] 跨文档引用路径正确
 - [ ] ⛔ **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 "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --proj
 
 #### 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 任务完成状态检查（实现后 / 归档前）
@@ -244,16 +244,20 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
 - `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 "$(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,\"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 解耦），但反映真实完成度。
 
@@ -270,7 +274,11 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
 > - `assertions[].judge_status` 枚举：`matched` / `partial` / `missed`
 > - `assertions[].human_status` 枚举：`matched` / `partial` / `missed` / 省略（默认跟随 judge_status）
 
-> **reviewer 与 reviewer_independence 说明**：`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 "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
 > - 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」。
 
 ---
 
@@ -297,7 +305,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
 `opsx-check` **不联网提问**。Agent 应在 propose/spec 已问完；本阶段只验证并入既有 apply 前门禁：
 
 - Continuity=`iteration` 时每个 CAP 具备 KB 回传 `entity-id` / `version-id`
-- 已写 spec 的 Capability：场景 `external-ref` 与 `continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
+- 已写 spec 的 Capability：场景 `external-ref` 与 `ontology/continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
 - 用户选「原对象」却仍用新 id、或选「新对象」却仍共用旧锚点 → 失败（`CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT`）
 - 决议缺失 / pending / 与产物不一致 → `CONTINUITY_DECISION_REQUIRED`
 - **编号诊断码**（并入五维报告与 apply gate）：
@@ -325,7 +333,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-check --project=. --ch
 - `added` 必须使用全新实体/版本 UUID；`modified/removed` 必须复用实体 UUID并指向直接前序版本；`unchanged` 必须复用历史实体和版本 UUID且不得复制历史正文。
 - 文件观察结果只能作为快速上下文，check 必须重新全量 semantic-reconcile。
 - propose/spec/design/task 对应工作态 JSON 应已在各作者阶段生成；check 不负责首次生成业务事实，只重新解析 Markdown、核对各 JSON 与同一 revision，并在全部通过时把派生 revision 更新为 `review_status=pending`。
-- Check 只读是指不修改 proposal/spec/design/tasks 原文；允许原子刷新 `openspec/changes/<变更名称>/` 下可再生的 `working-ontology.json`、`artifact-index.json` 与 `artifacts/*.ontology.json`。
+- Check 只读是指不修改 proposal/spec/design/tasks 原文；允许原子刷新 `openspec/changes/<变更名称>/` 下可再生的 `ontology/working-ontology.json`、`ontology/artifact-index.json` 与 `artifacts/*.ontology.json`。
 
 ## Guardrails
 

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

@@ -20,10 +20,11 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 - [ ] `warnings`: 建议修复的问题数
 - [ ] `suggestions`: 可选优化建议数
 - [ ] `fixed_before_apply`: 进入 apply 前已通过/已确认满足门禁的检查项数
-- [ ] `consistency_score`: 跨文档一致性评分 0-1；无法评分填 `null`
+- [ ] `consistency_score`: legacy 兼容字段；跨文档一致性评分 0-1，无法评分填 `null`
+- [ ] `reviewer` / `review_session_id` / `author_session_id` / `reviewer_independence`: Q3 独立性元数据已填写；优先独立 evaluator，不可用时标 `self-review` 或 `unknown`（Q3 provisional）
 - [ ] `categories`: 至少含 `completeness` / `consistency` / `executability`
 - [ ] `task_completion`: 从 `tasks-status` 整理；未进入 apply 时 `checked_for_archive_readiness=false`
-- [ ] **P1-1**：`check_result` 事件 `details` 非空且含 `consistency_score` 键（禁止空 `{}`，否则 Q5 为 null）
+- [ ] **P1-1**：`check_result` 事件 `details` 非空且含 `categories` 等必填键（禁止空 `{}`，否则 Q3 不可计算）
 - [ ] **P2-3**：`has_incomplete=true` 时 `check_result.result=partial` 且 `warning_items` 含 task_completion 项
 
 ## C. execution-log 状态标记
@@ -40,15 +41,15 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 - [ ] **CON 覆盖**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖
 - [ ] **安全/审计要求覆盖**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
-- [ ] **AC 变体覆盖**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准列出所有变体的测试方法（引用 `opsx-tdd-rules/rules/multi-validation-split.md`）
+- [ ] **AC 变体覆盖**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准列出所有变体的测试方法（引用 `tdd-rules/rules/multi-validation-split.md`）
 - [ ] **§4.x 验证方式表内部一致性**：tasks.md §4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
 
 ## E. TDD 合规性检查（仅 test-strategy=tdd 时）
 
-⛔ 执行 `opsx-tdd-core/checklist.md` §B（11 项）逐项检查。
+⛔ 执行 `tdd-core/checklist.md` §B（11 项）逐项检查。
 
-> 不在此内联复制，以 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`（异常路径覆盖门禁）。
 
 **检查项适用阶段**：
 - **apply 前可验证**（文档级）：§B 中除"GREEN 任务输出不含未测试的 Controller/Filter/Config"外的所有检查项（含 Controller 策略声明和测试任务生成）
@@ -56,5 +57,5 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 ## F. 语义门禁与工作态
 
-- [ ] `openspec/changes/<变更名称>/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `working-ontology.json` revision 一致
+- [ ] `openspec/changes/<变更名称>/ontology/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `ontology/working-ontology.json` revision 一致
 - [ ] 全部语义门禁通过时工作态 JSON 已从 draft 刷新为 pending；check 未修改任何 Markdown 原文

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

@@ -141,7 +141,7 @@ openspec list
 
 **输出路径**：`changes/<name>/specs/<capability>/design.md`
 
-**⛔ DES 步骤级标注（TDD 模式强制）**：当 `test-strategy=tdd` 时，被多个 RED/GREEN 对映射的 DES 元素必须标注步骤级任务归属。规则详见 `opsx-tdd-rules/rules/des-step-annotation.md`
+**⛔ DES 步骤级标注（TDD 模式强制）**：当 `test-strategy=tdd` 时，被多个 RED/GREEN 对映射的 DES 元素必须标注步骤级任务归属。规则详见 `tdd-rules/rules/des-step-annotation.md`
 
 ### 6.5 【version 正则注释】允许前导零
 

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

@@ -29,7 +29,7 @@ description: opsx-design 的阶段强制检查点与自检清单。仅在执行
 - [ ] 外部依赖已列出
 - [ ] 异常处理策略已定义
 - [ ] 文档末尾包含质量红线检查清单
-- [ ] ⛔ **DES 步骤级标注（TDD 模式）**：当 test-strategy=tdd 时，被多个 RED/GREEN 对映射的 DES 元素已标注步骤级 `[GREEN-N]` 归属（规则见 `opsx-tdd-rules/rules/des-step-annotation.md`）
+- [ ] ⛔ **DES 步骤级标注（TDD 模式）**：当 test-strategy=tdd 时，被多个 RED/GREEN 对映射的 DES 元素已标注步骤级 `[GREEN-N]` 归属（规则见 `tdd-rules/rules/des-step-annotation.md`）
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。**
 

package/templates/skills/kld-sdd/opsx-kb-ingest/SKILL.md

@@ -49,6 +49,20 @@ Task Progress:
 
 入库时：用户指定目标 KB（从 `targets` 中选择），仅对选中的 KB 执行上传。
 
+### 3.5 兜底：确保 project-identity.json 存在（上传前必做）
+
+> 正常情况下 `project-identity.json` 已在 `opsx-ontology-query` 首次配置 KB 时创建。
+> 本步是兜底：如果用户跳过了 ontology-query（如选择 archive 降级路径），直接来做入库，需要确保文件存在且 `project_id` 正确。
+
+1. 读取 spec 包裹包路径：
+   ```bash
+   SPEC_ROOT=$(node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root)
+   ```
+2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json`：
+   - **不存在** → 从 `targets[0].spaceKey` 创建（格式同 `opsx-ontology-query` Step 3.5）
+   - **已存在但 `project_id !== targets[0].spaceKey`** → 提示用户：`⚠️ project_id 与 Space spaceKey 不一致，入库将报 PROJECT_SPACE_MISMATCH。是否更新？`
+   - **已存在且一致** → 跳过
+
 ### 4. 入库操作
 
 路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`

package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md

@@ -56,6 +56,37 @@ Task Progress:
 
 **选择空间/KB**：`GET $API/v1/spaces?tenantKey=…` → 对每个 space `GET …/knowledge-bases` → 展示清单**允许多选** → 写入共享 `../.shared/kb-state.json` 的 `targets`。
 
+### 3.5 写入项目身份文件（首次配置 Space 后）
+
+> `project-identity.json` 是 spec 仓 Git 中的**团队共享**文件，记录 `project_id`（= KB Space 的 `spaceKey`）。Archive 阶段 `archive-docs` 读取此文件生成 `archive-manifest.json`，kb-ingest 上传时 KB 校验 `project_id === spaceKey`。
+
+选择 Space 完成后（Step 3 写入 `targets` 后），执行以下逻辑：
+
+1. 读取 spec 包裹包路径：
+   ```bash
+   SPEC_ROOT=$(node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root)
+   ```
+2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json` 是否已存在
+3. **不存在** → 创建（取 `targets[0].spaceKey` 作为 `project_id`）：
+   ```json
+   {
+     "schema_version": "kld-sdd-project-identity/v1",
+     "project_id": "<targets[0].spaceKey>",
+     "created_at": "<ISO timestamp>",
+     "kb_space_id": "<targets[0].spaceId>",
+     "kb_space_name": "<targets[0].spaceName>"
+   }
+   ```
+   输出：`✓ 已创建 skywalk-sdd/project-identity.json（project_id: <spaceKey>），请提交到 spec 仓 Git 以便团队共享`
+4. **已存在但 `project_id` 与 `targets[0].spaceKey` 不一致** → 用 AskUserQuestion 询问：
+   > "project-identity.json 中的 project_id 与当前选择的 KB Space spaceKey 不一致：
+   > - 文件中：`<existing project_id>`
+   > - 当前 Space：`<spaceKey>`
+   > 是否更新？"
+   - 用户确认 → 更新 `project_id` + `kb_space_id` + `kb_space_name`
+   - 用户拒绝 → 保留原值（可能入库时报 `PROJECT_SPACE_MISMATCH`）
+5. **已存在且一致** → 跳过，不输出
+
 > state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
 
 ## 查询

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

@@ -41,6 +41,7 @@ allowed-tools:
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）** — 阶段开始 / 阶段结束**命令模板**见 `./reference.md`「📊 Telemetry 命令模板」。
+> - 用户确认变更范围、`mode`、`test-strategy` 或方案 A/B/C 时，记录严格 `process_note`：`kind=user_decision`，并分别填写 `decision_type=scope|mode|test_strategy|other`。同一决定只记录一次，后续改变范围时改用 `kind=scope_change`。
 
 ---
 
@@ -228,9 +229,9 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
 5. 若申报了 feature-id：额外 `objectType=feature` resolve 一次，展示「该功能下已有能力 n 个（存活 m / 失效 k）」辅助勾选 CAP 范围；不改变 Continuity 判定优先级。
 6. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
 7. 写入 proposal frontmatter：`requirement-refs`（含 `feature-id`）/ `numbering-waiver` + `continuity`。**禁止**写本地 archive 文件夹名作为 `base-archive`。
-8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `continuity-resolution.json` 的 `capabilities[]`。
+8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `ontology/continuity-resolution.json` 的 `capabilities[]`。
 9. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。KB degraded（用户选择跳过）时走路径 B（archive 降级）：
-   - 扫描 `openspec/changes/archive/*/ontology-identities.json` 匹配 canonicalKey
+   - 扫描 `openspec/changes/archive/*/ontology/ontology-identities.json` 匹配 canonicalKey
    - path B 的所有 entity-id 来源在 sdd-output.md 知识库使用表中必须标注 `source: archive(degraded)`，与 `source: KB current` 明确区分。
    - ⚠️ **降级风险**：archive 中的 version-id 可能已过时（如果该 capability 在 archive 之后又有新版本入库到 KB）。path B 的 predecessor-version 不保证是 KB current。入库时可能触发 `VERSION_CONFLICT`。
 10. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份；**不得**铸/改 REQ/FEAT 号。
@@ -253,7 +254,7 @@ resolve(canonicalKey=CAP-USER-REGISTRATION) → CREATE_NEW
 ```
 # 扫描归档（仅 KB degraded 时）
 Read openspec/changes/archive/*/proposal.md 的能力分解章节
-Read openspec/changes/archive/*/ontology-identities.json
+Read openspec/changes/archive/*/ontology/ontology-identities.json
 
 # 匹配结果示例：
 # "账号锁定从内存迁到DB" → 匹配归档 CAP-ACCOUNT-LOCKOUT (entity-id: 3d18c60e, version: 29e7f242)
@@ -267,6 +268,12 @@ Read openspec/changes/archive/*/ontology-identities.json
 
 **❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。
 
+### 7.5 【交互引导】变更类型确认
+
+**❗ 必须主动询问用户，不得默认选择**。在模式与测试策略选择附近，基于需求给出 `change-type` **推荐**并让用户确认；Auto 只能推荐，**禁止无提示静默写入**。
+
+允许值固定为：`config | document | report | composite | other`（写入 proposal.md YAML frontmatter 的 `change-type` 字段）。AskUserQuestion 文案与类型说明见 `./reference.md`「§7.5 变更类型选择」。
+
 ### 8. 【交互引导】测试策略选择
 
 **❗ 必须主动询问用户，不得默认选择**。TDD / Impl-First / None 三种策略的 DAG 结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§8 测试策略选择」。根据用户选择设置 `test-strategy: tdd | impl-first | none`，记录到 proposal.md 的 YAML frontmatter。
@@ -333,10 +340,11 @@ Read openspec/changes/archive/*/ontology-identities.json
 - **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
 - **⛔ 单阶段原则**：完成 proposal.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
 - **⛔ Frontmatter 规范（L7）**：YAML frontmatter 中禁止写 `#` 注释（YAML 注释在 frontmatter 中可能导致解析问题）。如需说明，在 frontmatter 之前或之后用正文描述。
+- **⛔ change-type 必采**：frontmatter 必须含 `change-type`，取值仅限 `config | document | report | composite | other`；Agent 可推荐但须经用户确认后写入，禁止静默默认。
 
 ---
 
 ## 渐进披露
 
 - Read `checklist.md` 仅在执行 propose 需要校验时 — 含阶段边界⛔（Propose 阶段约束）、§6 需求完整性检查、Guardrails ⛔ 强制项勾选表。
-- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§7.5 变更类型（config/document/report/composite/other）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。

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

@@ -4,7 +4,7 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 
 # opsx-propose — 详细参考（reference）
 
-> 本文件承载 opsx-propose 的重细节模板：telemetry 命令、§7 文档拆分模式说明、§8 测试策略说明、§10 质量红线自检清单。
+> 本文件承载 opsx-propose 的重细节模板：telemetry 命令、§7 文档拆分模式说明、§7.5 变更类型说明、§8 测试策略说明、§10 质量红线自检清单。
 > SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
 
 ---
@@ -48,6 +48,31 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 
 ---
 
+## §7.5 变更类型选择
+
+**❗ 必须主动询问用户，不得默认选择；Auto 仅给推荐，禁止无提示写入**
+
+分析需求后，Agent 先给出推荐类型，再使用 **AskUserQuestion** 让用户确认：
+
+> "📊 **变更类型（用于 V3 指标分层统计）**
+>
+> 根据本次需求，推荐类型：**[config | document | report | composite | other]** — [一句话理由]
+>
+> 请选择或确认：
+> - **config** — 配置/开关/环境/依赖调整，几乎不改业务逻辑
+> - **document** — 文档、规范、模板、注释类变更
+> - **report** — 报告、度量、仪表盘、采集契约类变更
+> - **composite** — 跨多类能力的组合变更
+> - **other** — 以上均不合适时使用
+>
+> A) 采用推荐  B) 手动选择其他类型"
+
+根据用户确认，在 proposal.md YAML frontmatter 写入 `change-type: <值>`。允许值固定：`config | document | report | composite | other`。
+
+> 历史 proposal 缺该字段时，报告侧归为 `unknown`；本阶段不得替用户猜测补写。
+
+---
+
 ## §8 测试策略选择
 
 **❗ 必须主动询问用户，不得默认选择**
@@ -66,8 +91,8 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 
 **将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
 
-> 完整策略定义见 opsx-tdd-core/SKILL.md §5
-> 交互引导文案见 opsx-tdd-rules/rules/tdd-strategy-selection.md
+> 完整策略定义见 tdd-core/SKILL.md §5
+> 交互引导文案见 tdd-rules/rules/tdd-strategy-selection.md
 
 ---
 
@@ -82,5 +107,6 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 - [ ] 前置依赖使用 checkbox 格式
 - [ ] 文档末尾包含质量红线检查清单
 - [ ] 能力分解章节已明确（决定后续 specs 文件夹结构）
+- [ ] frontmatter 含 `change-type`，取值为 `config | document | report | composite | other` 之一且经用户确认
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。**

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

@@ -1,6 +1,8 @@
 # opsx-rules 参考 — 落位矩阵与格式模板
 
 > **权威源说明**：本文件是 skill **运行时**的落位矩阵真相源（部署到目标项目后无法 `require` kld-sdd 的 `lib/`）。`lib/tool-profiles.js` 中的 `rulesDir` / `rulesFormat` / `rulesWiring` 为 **init 契约与测试断言**；变更时须与本表同步，以本表为准写入规则文件。
+>
+> **边界**：SkyWalk Telemetry 的事件 schema、`run_id`、`test_event_id` 等属于 SDD 工具协议，不属于业务项目规则。生成或 review 五类项目规则时，不把 telemetry 命令或事件字段写入规则正文。
 
 ## 落位矩阵
 
@@ -80,7 +82,7 @@ trigger: always_on
 |------|--------|----------|----------|
 | 架构规范 | `architecture` | 目录分层、模块边界、入口 | 分层约定、禁止循环依赖、新代码落位 |
 | 编码规范 | `coding-style` | 语言、lint、缩进 | 命名、缩进、注释语言、CommonJS/ESM |
-| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望（见 opsx-tdd-core/SKILL.md §5） |
+| 测试约定 | `testing` | test 目录、框架 | 测试命令、命名、TDD 期望（见 tdd-core/SKILL.md §5） |
 | 数据安全 | `database-safety` | ORM/迁移目录 | 无 DB 时降级为「禁止危险文件操作/敏感数据提交」 |
 | Git 提交 | `git-commit` | git log 风格、CI | 提交前确认、message 风格、禁止 force push |