kld-sdd 2.6.21 → 2.7.8

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

@@ -15,9 +15,11 @@ allowed-tools:
   - Edit
 ---
 
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+
 你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
-> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并确认 KB 已配置（配置由 `opsx-kb-config` 负责）。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
+> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。用户已授权入库时，进入 §5.5 前读取该技能并检查目标配置；未授权或 KB 不可用时保留本地归档和待入库状态。入库成功后，`Read` `opsx-ontology-query/phase-3-postchange.md` 验证版本生效、AC 保留、关系完整性。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
 
 > **跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
@@ -59,17 +61,11 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" start --command=archive --proje
 
 保存 `event_id`。
 
-### 2. 询问归档原因
-
-使用交互问题让用户选择：
+### 2. 记录归档原因
 
-> 请选择归档原因：
-> - A. 变更已完成实施
-> - B. 变更已取消
-> - C. 变更已搁置
-> - D. 其他原因
+优先使用用户已经说明的原因。实际主任务全部完成且用户要求归档时，记录“变更已完成实施”；取消/搁置按用户明确意图记录。只有原因与当前任务状态矛盾或无法确定时才询问，不重复展示内部原因枚举。
 
-记录为 `<归档原因>`，它会进入 `archive-manifest.json`、archive telemetry 和最终报告。
+原因写入 `archive-manifest.json`、archive telemetry 和最终报告；不能把未完成任务自动写成完成。
 
 ### 2.5 确认无残留 Apply Worktree（Git 项目）
 
@@ -170,8 +166,8 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" active-change --remove
 
 ### 5.5 收尾入库（opsx-kb-ingest）
 
-1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；KB 配置（API Key / targets / project-identity.json）由 `opsx-kb-config` 统一负责，如未配置则提示运行 `/opsx-kb-config`。
-2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；也可直接使用 `kb-upload.cjs --package=<zip路径>` 上传；成功则写 `ingest-receipt.json`。
+1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；KB 配置（API Key / targets / project-identity.json）由 `opsx-kb-config` 统一负责，如未配置则记录待入库原因；用户要求配置时再运行 `/opsx-kb-config`，不阻断已完成的本地归档。
+2. 归档 zip 生成后，若用户已授权入库且目标明确，加载并执行 `opsx-kb-ingest` 上传，也可使用 `kb-upload.cjs --package=<zip路径>`。未授权或断连时保留包并报告待入库，不把本地归档成功写成发布成功。只有真实入库回执成功后才写 `ingest-receipt.json`。
 3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
 
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
@@ -234,7 +230,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=baseline_record -
 
 ## Guardrails
 
-- 归档操作执行前必须让用户确认归档原因。
+- 归档原因根据用户意图与真实任务状态记录，已有明确原因不重复询问。
 - 不要调用 OpenSpec 自带归档命令；统一由 `archive-docs` 负责真实归档、阶段结束和报告生成。
 - “完成实施”归档允许 tasks 未全部勾选；未勾选项必须进入 archive details 和最终报告。
 - 最终报告由 `archive-docs` 自动生成（Markdown + HTML + JSON 三产物，默认落归档后 archive 目录的 reports/ 子目录，可用 --report-output 自定义路径）。

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

@@ -6,7 +6,7 @@ license: MIT
 compatibility: Requires openspec CLI; depends on opsx-ontology-query for external-key validation and baseline checks.
 metadata:
   author: sdd-team
-  version: "3.0"
+  version: "3.1"
   depends-on: opsx-ontology-query
 allowed-tools:
   - Bash
@@ -15,368 +15,94 @@ allowed-tools:
   - Edit
 ---
 
-你是一个 SDD（Specification-Driven Development）质量检查专家。激活本技能后，你将对文档链执行全面的质量门禁检查。
-
-> **⚠️ 阶段边界约束**
->
-> 当前处于 **Check（检查）阶段**：
-> - ✅ **允许**：读取并检查文档、读取代码作为验证参考
-> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
->
-> 即使检查发现代码相关问题，也只记录在检查报告中，**不自动修复代码**。
-> 代码修复将在 `/opsx-apply` 阶段进行。
-
-> **KB 上下文**：check 阶段需验证外部键格式（requirement/feature/scenario 文法）、SCN 需求编号前缀一致性和历史覆盖率基线。进入相关步骤前先 `Read` `opsx-ontology-query/phase-2-during.md` §3-5，并按 `SKILL.md` → Session 启动准备 API Key + targets。
->
-> **📡 KB 就绪检查**：§2.6 在进入 KB 相关检查前会检测 KB 配置状态。若未配置，会**主动询问**用户选择「配置」或「跳过」，KB 相关检查项降级为仅本地验证。
-
-
-> **🖥️ 跨平台执行规则**
-> - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
-> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
-> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - ${SHELL_GUIDANCE}
-> - 不要省略 `--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）
-> - 下方 `check_result` 命令中的 `0` 是待替换位置，禁止原样照抄；写入前必须用本轮实测值替换，且顶层 `total` 必须是大于 0 的整数，否则 strict 记录会拒绝该事件。
-> - 检查报告生成后，必须先记录结构化检查结果：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --run-id=<本轮Check稳定ID> --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_execution_mode\":\"<subagent|main-agent-fallback>\",\"reviewer_agent_id\":\"<子代理真实ID；主Agent回退时填null>\",\"parent_session_id\":\"<父会话ID；主Agent回退时可填null>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply真实会话ID；无法确认时仅允许主Agent回退填unknown>\",\"reviewer_independence\":\"<independent-review|self-review|unknown>\",\"fallback_reason_code\":\"<主Agent回退时五类稳定码之一；子代理成功时填null>\",\"fallback_reason\":\"<主Agent回退时具体中文原因；子代理成功时填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 "$(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 或补齐文档，使三者数字自洽。
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
 
----
-
-## 技能定位
-
-| 维度 | 内容 |
-|------|------|
-| 核心问题 | 文档链质量是否达标 |
-| 关键输出 | 检查报告（通过/警告/失败） |
-| 检查维度 | 完整性、一致性、算法正确性、可执行性、TDD合规性（仅test-strategy=tdd时） |
-| 上游依赖 | proposal → specs → design → tasks 全文档链 |
-
----
-
-## 启动流程
-
-### 1. 【交互引导】确认变更名称
-
-若未提供，列出当前所有变更供用户选择：
-```bash
-openspec list
-```
-
-若变更不存在，提示用户先运行 `/opsx-propose <name>` 创建变更。
-
-### 2. 读取完整文档链
-
-按顺序读取以下文档（如存在）：
-- `proposal.md`（或 propose.md，兼容旧格式）（业务意图）
-- `specs/<capability>/spec.md`（技术契约）
-- `specs/<capability>/design.md`（实现方案）
-- `specs/<capability>/tasks.md`（或 task.md，兼容旧格式）（任务拆解）
+Check 验证工程约定是否完整、一致、可执行。程序核验结构与身份，独立评审核验语义；结果必须有真实证据。
 
-### 2.1 默认使用一个独立子代理评审
+## 执行预算与边界
 
-Check 默认启动且只启动 **一个独立子代理**。主 Agent 先确定待检查的最终文档路径、作者会话 ID 和固定输出结构，再让子代理直接读取这些最终产物；不得先把主 Agent 的判断摘要喂给子代理，也不得让评审子代理再次启动子代理或递归委派。
+- 主 Agent 负责路径、程序预检、委派和记录，**不先读取完整文档再自己评审一遍**。
+- 默认启动且只启动一个独立评审子代理；不按维度或 Capability 再拆多个评审者。
+- 一轮预检只执行一次 `semantic-check --include-tasks`，不先运行 `semantic-reconcile`，不再单独跑 tasks-status；文件改动后才重新检查。
+- 独立评审者只读 [reviewer.md](reviewer.md)、结果模板和实际相关文件；不要让它重新执行本 SKILL 的启动流程。主 Agent 不重复读取 reviewer 全部规则及业务正文来做第二次完整评审。
+- 不修改实现代码、不运行测试。只读评审与已授权的文档修复分开；修复后必须复检。
+- 报告聚焦问题、证据与未验证项，不逐条复述所有通过项。不适用项不能计为通过。
 
-${CHECK_REVIEW_DELEGATION_GUIDANCE}
-
-正常路径：
-
-1. 启动一个全新评审上下文，记录 `reviewer_agent_id`、`parent_session_id` 和 `review_session_id`。
-2. 子代理独立执行完整性、一致性、可执行性、算法正确性和 TDD 合规检查。
-3. 主 Agent 只校验返回结构、展示原始结论并记录事件，不得把主 Agent 身份写成子代理身份。
-4. 只有 `review_execution_mode=subagent`、评审者身份存在、评审会话与作者会话不同且 `reviewer_independence=independent-review` 时，Q3 才是“已独立验证”。
-
-只有子代理能力不可用或调用失败时，主 Agent 才执行同一检查。回退必须记录 `review_execution_mode=main-agent-fallback`、通俗原因，并从以下标准原因中选择一个：
+## 1. 定位与开始
 
-- `SUBAGENT_CAPABILITY_UNAVAILABLE`：当前 Agent 环境没有子代理能力。
-- `SUBAGENT_PERMISSION_DENIED`：权限策略不允许启动子代理。
-- `SUBAGENT_START_FAILED`：子代理启动失败。
-- `SUBAGENT_TIMEOUT`：子代理超时未返回。
-- `SUBAGENT_RESULT_INVALID`：子代理结果缺字段或无法解析。
+从命令参数、当前会话或已有 active change 确定变更；单一明确候选直接使用，多候选才列 `openspec list` 请用户选择。不存在则提示先 `/opsx-propose <name>`。
 
-回退时 `reviewer_independence` 只能是 `self-review` 或 `unknown`，Q3 仍可计算，但必须显示“由主 Agent 自查，未经过独立复核”及具体回退原因。
+SDD 文档根是含 openspec/ 的 spec 包裹包，不是默认 Git 根。一次解析 `.sdd-spec-root` 或使用 `skywalk-sdd/spec-root.cjs`，下文 `<spec-package>` 都替换为该绝对路径。不要逐命令重复定位或遍历所有个人项目。
 
-### 2.5 【多仓库关联配置诊断】（在五维检查之前）
-
-先执行轻量配置诊断，**不执行代码 diff**，只检查命名与引用配置：
+- ${SHELL_GUIDANCE}
+- 保存本轮稳定 run-id、阶段 event_id、父会话 ID；子代理返回的会话 ID 单独记录。
 
 ```bash
-# 在 spec 仓库：
-node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --project=. --change=<change-key>
-
-# 在代码仓库：
-node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" diagnose-naming --project=. --mode=code-repo
+node "<spec-package>/skywalk-sdd/log.cjs" start --command=check --project="<spec-package>" --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<父会话ID>
 ```
 
-诊断结果三类：
-
-| 状态 | 含义 |
-|------|------|
-| PASS | 配置完整 |
-| FIXABLE | 修复方式唯一，用户确认后可自动修复（如安装 commit-msg Hook、设置 sdd.specPath） |
-| NEEDS_INPUT | 多候选或团队级配置，必须询问用户 |
-
-规则：
-- 只问缺失项，不重复询问已合法配置
-- 本地 Git config / Hook 可在确认后修复
-- `.sdd.yaml`、`modules.yaml`、proposal frontmatter 修改前必须展示变更摘要
-- 已被代码 commit 引用的 change-id/change-key **禁止静默重命名**
-- 用户拒绝修复时按严重程度记 warning/failure，然后继续后续文档检查
-- spec 仓诊断跳过代码仓 Hook；代码仓诊断跳过 modules/change 命名（入口分离）
-- 单仓（`.sdd.yaml` 声明 `layout: mono`，openspec 与代码同仓）：`mode=mono-repo`，命名与 Hook 一并就地检查；该布局 commit 只写 `Spec-Change`，不写 `Spec-Revision`
-- 若在个人工作目录发现未接入的新代码仓（缺 `.sdd.yaml` 或 commit-msg Hook）：
-  1. 向用户展示仓名列表；
-  2. 用户确认后执行 `kld-sdd sync-repos`（只装 Hook/关联，不装 skills）；
-  3. 用户拒绝则记 warning，不阻断五维文档检查
-- Trailer 协议：已接入仓 commit 必写 `Spec-Revision`；`Spec-Change` 来自 spec 仓 `sdd.config.yaml` 的 `active_changes`（多个则写多条），`KLD_SDD_CHANGE` 可显式覆盖，**不从分支名推断**
-- 活动变更登记表诊断：`sdd.config.yaml` 是否存在且格式合法；当前 change 是否已登记（未登记则提示执行 `active-change --register`）；登记项对应目录是否仍存在（已归档应执行 `active-change --remove`）
-
-最终检查报告必须包含「多仓库关联配置」章节（命令输出已按此格式打印）。
-
-### 2.6 【KB 就绪检查】检测并配置知识库连接
-
-在进入 KB 相关检查（外部键验证、coverage 基线）之前，检测 Engineering KB 的连接状态。
-
-1. 检查 proposal.md frontmatter 中 `kb-status` 字段：
-   - 若 `kb-status: degraded(by-user-choice)` → KB 已被用户明确跳过，本阶段 KB 相关检查降级为仅本地验证（external-key 格式校验 + 本地 semantic-check），跳过 KB API 调用。
-   - 若未标记 → 继续检查。
-2. 运行 KB 就绪检查（程序化检测，自动搜索多 IDE 目录，消除路径歧义）：
-   ```bash
-   node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --check-only
-   ```
-   - 输出 `"available": true` → KB 已配置
-   - 输出 `"available": false` → KB 未配置
-3. **若已配置** → 直接进入 §3，正常使用 KB 做 coverage 基线、predecessor 预检。
-4. **若未配置** → 使用 **AskUserQuestion** 询问：
-
-   > "📡 **知识库未配置**
-   >
-   > 知识库可以帮你做覆盖率基线检查和版本冲突预检。现在要配置吗？
-   >
-   > - A. **现在配置** — 运行 /opsx-kb-config
-   > - B. **暂不配置，先继续** — 仅做本地检查（不检查版本冲突）
-   > - C. **取消** — 终止本次操作"
-
-   - **选 A** → 引导运行 `/opsx-kb-config`，配置完成后进入 §3。
-   - **选 B** → KB 相关检查项降级：coverage 基线跳过、`current-version` 预检跳过。检查报告中标注 `kb: degraded(by-user-choice)`。
-   - **选 C** → 终止 check。
-
-### 3. 【上下文加载】识别并读取用户提供的文件
+## 2. 程序预检（在完整文档评审前）
 
-**自动识别上下文文件**：
-若用户在命令中指定了文件路径，或在对话中附加/引用了文件，**必须自动读取这些文件**。
-
-**上下文类型与检查维度**：
-| 上下文类型 | 检查用途 | 对应检查维度 |
-|------------|---------|----------|
-| 需求文档 | 验证 spec 是否完整覆盖需求 | 完整性 |
-| 代码文件 | 验证 design 可行性、锚点准确性 | 可执行性 |
-| 算法文档 | 验证算法设计正确性 | 算法正确性 |
-
-### 4. 执行五维质量检查
-
-#### 4.1 完整性检查
-
-- [ ] proposal.md 存在且包含完整章节
-- [ ] 每个 Capability 都有 spec.md
-- [ ] 每个 spec.md 都有对应 design.md
-- [ ] 每个 design.md 都有对应 tasks.md
-- [ ] 所有文档符合模板结构
-
-#### 4.2 一致性检查
-
-- [ ] proposal.md 的能力列表与 specs/ 目录一致
-- [ ] spec.md 的需求项在 design.md 中 100% 被覆盖
-- [ ] design.md 的设计点在 tasks.md 中 100% 被拆解
-- [ ] 跨文档引用路径正确
-- [ ] ⛔ **CON 覆盖一致性**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖；tasks.md 声明"100% 覆盖 CON"时必须可追溯
-- [ ] ⛔ **安全/审计要求覆盖一致性**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
-- [ ] ⛔ **AC 变体覆盖一致性**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准须列出所有变体的测试方法（规则见 `tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖）
-- [ ] ⛔ **tasks.md §4.x 验证方式表内部一致性**：§4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
-
-#### 4.3 算法正确性检查
-
-- [ ] 数据流转逻辑无矛盾
-- [ ] 异常处理覆盖所有边界
-- [ ] 性能设计满足 spec 约束
-
-#### 4.4 可执行性检查
-
-- [ ] tasks.md 中每个任务颗粒度 ≤ 5 分钟
-- [ ] DAG 无循环依赖
-- [ ] 所有外部依赖已明确状态
-- [ ] 代码锚点存在且可访问
-
-#### 4.4a TDD 合规性检查（仅 test-strategy=tdd 时执行）
-
-⛔ 执行 `tdd-core/checklist.md` §B（15 项）逐项检查。
-
-> 不在此内联复制，以 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 合规性检查，如需深度审查测试质量，必须读取：
-- tdd-review/SKILL.md（测试质量审查清单 8 项 + 缺失测试检测）
-读取后确认："已读取测试质量审查清单"。
-
-#### 4.5 任务完成状态检查（实现后 / 归档前）
-
-`task` 阶段允许 `tasks.md` 出现未完成项；这只是计划状态。但如果当前变更已经进入 apply 之后，或本次 check 发现实现代码、测试报告、`build_result/test_result/task_update/conformance_review` 等实施证据，必须检查任务勾选状态：
-
-```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --change=<变更名称>
-```
-
-判定规则：
-- 尚未进入 apply：未勾选任务只作为计划状态展示，不计入错误。
-- 已进入 apply/test/archive readiness：未勾选项至少记为 warning。
-- 若用户准备归档“变更已完成实施”：未勾选项仍只作为 warning/待确认事实展示，不阻断归档。
-- Check 阶段只读，不自动勾选；报告中必须说明这是“任务可能已执行但文档未同步”或“任务真实未完成”的待确认项。
-
-### 5. 输出检查报告
-
-> "📋 **质量检查报告**
-> 
-> | 维度 | 状态 | 详情 |
-> |------|------|------|
-> | 完整性 | ✅/⚠️/❌ | [具体问题] |
-> | 一致性 | ✅/⚠️/❌ | [具体问题] |
-> | 算法正确性 | ✅/⚠️/❌ | [具体问题] |
-> | 可执行性 | ✅/⚠️/❌ | [具体问题] |
-> | TDD合规性 | ✅/⚠️/❌/— | [仅test-strategy=tdd时检查] |
->
-> **总体结果**：✅ 通过 / ⚠️ 有警告 / ❌ 未通过
->
-> **建议操作**：
-> - [具体修复建议及对应命令]"
-
-### 5.1 【Telemetry 必做】记录结构化检查结果
-
-输出检查报告后，必须把检查结果转换为 `check_result` 事件，并在 `stage_end` 之前执行成功。禁止只记录阶段结束。
-
-字段口径：
-- `total`: 本次检查项总数。
-- `errors`: 必须修复的问题数。
-- `warnings`: 建议修复的问题数。
-- `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`: **legacy 兼容字段**（保留一个发布版本）；跨文档一致性评分 0-1，无法评分时填 `null`。
-- `reviewer`: 执行本次 check 的代理或会话标识。
-- `review_session_id`: 当前 check 会话 ID（与 `--session-id` 一致）。
-- `author_session_id`: 文档作者或 apply 阶段会话 ID；无法确定时填 `unknown`。
-- `review_execution_mode`: `subagent` 或 `main-agent-fallback`。
-- `reviewer_agent_id`: 独立子代理或独立任务标识；主 Agent 回退时省略。
-- `parent_session_id`: 启动子代理的主会话 ID。
-- `review_session_id`: 独立评审会话 ID；主 Agent 回退时为当前检查会话。
-- `author_session_id`: 文档作者会话 ID。
-- `reviewer_independence`: `independent-review` | `self-review` | `unknown`。
-- `fallback_reason_code` / `fallback_reason`: 仅主 Agent 回退时填写，原因码必须来自 §2.1 的五个标准值。
-- `categories`: 至少包含 `completeness`、`consistency`、`executability`。
-- `task_completion`: 从 `tasks-status` 输出整理而来；未进入 apply 时 `checked_for_archive_readiness=false`。
-
-下面命令中的 `0` 仅表示待填数字的位置，执行前必须全部换成本轮实测值；顶层 `total` 必须是大于 0 的整数。禁止为了通过校验而编造计数。
-
-在终端执行（必须成功）：
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=check_result --command=check --project=. --change=<变更名称> --capability=<可选capability-name> --run-id=<本轮Check稳定ID> --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_execution_mode\":\"<subagent|main-agent-fallback>\",\"reviewer_agent_id\":\"<子代理真实ID；主Agent回退时填null>\",\"parent_session_id\":\"<父会话ID；主Agent回退时可填null>\",\"review_session_id\":\"<当前check会话ID>\",\"author_session_id\":\"<文档作者/apply真实会话ID；无法确认时仅允许主Agent回退填unknown>\",\"reviewer_independence\":\"<independent-review|self-review|unknown>\",\"fallback_reason_code\":\"<主Agent回退时五类稳定码之一；子代理成功时填null>\",\"fallback_reason\":\"<主Agent回退时具体中文原因；子代理成功时填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 "<spec-package>/skywalk-sdd/log.cjs" semantic-check --project="<spec-package>" --change=<变更名称> --profile=auto --include-tasks
 ```
 
-> **⚠️ P1-1 check_result details 不得为空**：`--details-json` 必须含正整数 `total`、非负整数 `errors`、四类 `categories`、计数自洽的 `task_completion` 和 reviewer 独立性字段等，**禁止传空对象 `{}`**。空 details 导致 Q3 不可计算，并会被 strict 记录直接拒绝；历史非 strict 事件仍按兼容口径读取。
+输出 `profile / valid / revision / counts / diagnostics`、`review_inputs`（文档路径与哈希、历史身份哈希）、`task_completion` 和 `timings_ms`。程序时间不等于模型评审总耗时。
 
-> **⚠️ 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 解耦），但反映真实完成度。
+- semantic-check 已包含全量对账、工作态 JSON 原子刷新和 pending 标记；无需再调用 semantic-reconcile。pending 仅表示程序校验通过，不能宣称已完成独立评审或已入库。
+- 默认从产物推断 simple/full；用户或项目明确要求 strict 时传 `--profile=strict`，不能为通过而降级。
+- `simple` 阻断 STMT 无 AC，未生成 design/tasks 时跳过对应链路；`full` 阻断 STMT→AC→Design→Task 断链；`strict` 还要求完整来源字段。
+- 所有模式保留身份合法性、重复锚点、跨 Change/Archive 身份误复用、版本谱系、悬空引用、domain/range 和依赖成环门禁。added 使用新身份；modified/removed 复用实体并指向直接前驱；unchanged 引用历史版本且不复制正文。
+- Continuity、external_ref 与 `ontology/continuity-resolution.json` 必须一致。`CONTINUITY_DECISION_REQUIRED` / `CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT` 和编号诊断原样进入报告；不得临时改身份来绕过门禁。
+- 文件观察结果只作提示，不复用历史“通过”代替本轮全量校验。命令失败、诊断 error 或 valid=false 时先展示具体问题，在授权内修复后重试；无需模型再读全仓来重复确认确定性错误。若缺业务决定则本轮结束为 failure、说明“预检阻断，尚未独立评审”，保留阶段日志，不伪造 check_result。用户明确要求同时审阅其余问题时可继续独立评审，但总体仍失败。
 
-若当前已有实现代码，并且能够验证 spec 断言，还应记录 `conformance_review`（用于 Q1 规约符合度）：
-```bash
-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 规约符合度会据此标注「自评，待人工确认」。
+对已解析的 spec 包执行 `ontology/cli.cjs diagnose-naming --project="<spec-package>" --change=<change-key>`。只对 affected-modules 和实际代码锚点涉及的仓库定向诊断，单个仓每轮一次；同一连续任务已有结果且配置/引用未变时复用。同一 spec 包关联多个代码仓也只做一次语义检查。
 
-> **【L4 conformance_review details-json 完整 schema】**：
-> - `reviewer` 必须带引号（字符串），如 `"reviewer": "claude-code"`
-> - `assertions[].files` 是必填数组，每项为实际文件路径字符串，如 `"files": ["src/auth.js", "test/auth.test.js"]`；空数组 `[]` 须配合 `evidence` 文本作为降级证据（如浏览器自动化/手动验收摘要）。`files` 含测试文件路径（`test/`、`.test.`、`.spec.`）**或** `evidence` 非空，二者至少满足其一，否则空口断言被工具侧记录时硬校验拒绝（详见 `skywalk-sdd/index.cjs`）
-> - `assertions[].judge_status` 枚举：`matched` / `partial` / `missed`
-> - `assertions[].human_status` 枚举：`matched` / `partial` / `missed` / 省略（默认跟随 judge_status）
+- spec 仓用默认模式；代码仓使用工具包中的 `ontology/cli.cjs diagnose-naming --project="<code-repo>" --mode=code-repo`；同仓 `.sdd.yaml layout: mono` 用 `--mode=mono-repo`。
+- PASS：配置完整；FIXABLE：唯一修复方案；NEEDS_INPUT：多候选/团队配置须明确。已授权的本地 Hook/config 修复可执行；没有该授权时展示具体修改后询问。
+- `.sdd.yaml`、`modules.yaml`、proposal 的修改展示摘要；已被 commit 引用的 change-id/change-key 不静默重命名。只问缺项。
+- 检查当前 change 是否登记在 `sdd.config.yaml active_changes`；未登记用 active-change --register，已归档的登记用 --remove。Spec-Change 来自此登记或 KLD_SDD_CHANGE，不从分支推断。
+- 分仓代码 commit 写 Spec-Revision 与 Spec-Change；mono 只写 Spec-Change。发现相关代码仓未接入时列明缺项，在授权内用 `kld-sdd sync-repos` 安装 Hook/关联。不要扫描无关兄弟仓来寻找更多任务。
+- 报告包含「多仓库关联配置」、涉及仓库及未核验项。配置 warning 不能伪装通过，但可继续文档评审。
 
-> **reviewer 与 reviewer_independence 说明（check_result）**：执行 check 前先读取文档作者/阶段会话信息；默认启动且只启动一个独立子代理。仅当 `review_execution_mode=subagent`、`reviewer_agent_id` 存在、`reviewer_independence=independent-review` 且 `review_session_id` 与 `author_session_id` 不同时，Q3 才为 `verified`；主 Agent 回退或无法确认时 Q3 标 `provisional` 但仍可计算分数。
+### KB 基线边界
 
-> **报告用语**：`verified` 展示为“已独立验证”；`provisional` 展示为“已有计算结果，尚未独立验证”。不要使用 “self-review” 作为用户可见说明；应写成“由主 Agent 自查，未经过独立复核”。不得仅用颜色区分，也不得把尚未独立验证的结果写成最终可信结论。
+仅需远程 coverage/predecessor 时读取 `../opsx-ontology-query/phase-2-during.md` 的相关段落并查询已有目标。复用本轮上下文；已经断连或显式离线时记录 `kb-status: degraded`、原因和待在线确认基线，不重复 readiness、不逐阶段问配置。
 
-> **reviewer 与 reviewer_independence 说明（conformance_review）**：`reviewer` 用于标识实际执行本次符合度评审的代理或会话（例如 agent 名称、会话 ID）。渲染报告时会比较 `reviewer` 与 apply 阶段记录的 `apply_agent`：若两者相同，则 `reviewer_independence` 显示为 `self-review`；否则显示为 `independent-review`。建议尽可能由独立评审方执行 check，以提升结果可信度。
+未执行的远程检查不计为通过；本地编写和实现可继续，正式发布前重新在线核对真实基线。外部键格式/作用域/编号、Continuity 决议仍由本地程序校验，不靠模型逐条重算。
 
-### 6. 【交互引导】根据结果引导下一步
+## 3. 一次独立评审
 
-**全部通过**：
-> "✅ 质量检查通过！建议下一步：
-> - A. 运行 `/opsx-apply` 开始实施
-> - B. 再次确认某个文档细节"
+程序预检后交给评审者：`review_inputs` 对应的最终文件路径、profile/test-strategy、任务状态、程序诊断、用户指定的上下文路径、检查范围和作者会话 ID。只传客观输入，不传作者对话或主 Agent 的结论摘要。主 Agent 从 proposal 元数据确定测试策略即可，无需预读正文。
 
-**有问题**：
-> "❌ 发现 [N] 个问题需要修复：
-> - 问题 1：[描述] → 建议运行 `/opsx-spec` 修复
-> - 问题 2：[描述] → 建议运行 `/opsx-design` 修复
->
-> 请选择：
-> - A. 逐个修复（引导到对应命令）
-> - B. 忽略警告继续"
+${CHECK_REVIEW_DELEGATION_GUIDANCE}
 
-> **📊 过程记录（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」。
+评审者依据 [reviewer.md](reviewer.md) 自行读取最终原文一次，覆盖完整性、一致性、算法正确性、可执行性、TDD 合规性（仅 test-strategy=tdd）。不得让评审子代理再次启动子代理或递归委派。主 Agent 只检查返回结构、来源与计数；仅对歧义或证据缺失定向补查，不整篇重做。
 
----
+只在真实能力不可用或调用失败时，主 Agent 读取 reviewer.md 执行同样检查，并写 `review_execution_mode=main-agent-fallback` 和真实原因：
 
-## Continuity / external_ref / 编号确定性门禁
+- SUBAGENT_CAPABILITY_UNAVAILABLE：无子代理能力。
+- SUBAGENT_PERMISSION_DENIED：权限策略不允许。
+- SUBAGENT_START_FAILED：启动失败。
+- SUBAGENT_TIMEOUT：实际等待超时。
+- SUBAGENT_RESULT_INVALID：返回结构无法使用；先要求原评审者补齐一次缺项，仍无效才回退，不反复新建评审者。
 
-`opsx-check` **不联网提问**。Agent 应在 propose/spec 已问完；本阶段只验证并入既有 apply 前门禁：
+成功委派记录 `reviewer_agent_id / parent_session_id / review_session_id / author_session_id / reviewer_independence`。仅 subagent、有真实身份、评审会话不同于作者会话且 independence=independent-review 时，Q3 才是“已独立验证”。作者身份未知不能伪造独立性；回退写 self-review/unknown，并展示“由主 Agent 自查，未经过独立复核”及原因；Q3 显示“已有计算结果，尚未独立验证”。
 
-- Continuity=`iteration` 时每个 CAP 具备 KB 回传 `entity-id` / `version-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）：
-  - `EXTERNAL_KEY_FORMAT_INVALID` — external_id / feature_id 不合规
-  - `EXTERNAL_KEY_SCOPE_MISMATCH` — 场景键需求编号前缀不在 `requirement-refs`
-  - `EXTERNAL_KEY_FEATURE_UNDECLARED` — feature↔requirement.`feature_id` 配对断裂
-  - `EXTERNAL_KEY_SEQ_REUSED` — 本 Change 内 SCN 重复或复用 removed 墓碑号
-  - `NUMBERING_WAIVER_ACTIVE`（warning）— 豁免生效，本轮不种桥
-- `requirement-refs` 为空且无有效 waiver → `CONTINUITY_DECISION_REQUIRED` 级阻断
-- CI/非交互：失败即非零退出并打印修复说明，不挂起等待输入
+## 4. 一次记录与结束
 
-## 本体语义关系门禁
+评审完成后，主 Agent 读取 [reference.md](reference.md)，将结构化结果按 [result-template.json](result-template.json) 写入本轮临时 details 文件，执行唯一的 strict check_result 命令，再执行 end。不要在 shell 中手工转义大段 JSON。
 
-在其他质量检查前必须运行：
+顶层 `total` 必须是大于 0 的整数且来自实测，不能照抄模板的 0。空 details 导致 Q3 不可计算，strict 会拒绝。consistency_score 是 legacy 兼容字段，不可评分填 null。未执行项不能计入通过；warning 记录明细和处置理由。
 
 ```bash
-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>
+node "<spec-package>/skywalk-sdd/log.cjs" end --event-id=<event_id> --command=check --project="<spec-package>" --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<父会话ID> --result=success/partial/failure --summary="本轮实测摘要"
 ```
 
-- `simple` 必须阻断 STMT 无 AC；没有 design/tasks 时跳过对应链路，不得误报。
-- `full` 必须阻断 STMT→AC→Design→Task 任一断链。
-- `strict` 在 full 基础上要求完整来源字段并提升可选警告。
-- 所有 profile 都必须阻断重复人工锚点、UUID 缺失/非法、跨 Change 或 Archive 的实体 UUID 误复用、版本 UUID 重用、版本谱系断裂、悬空引用、非法 domain/range 和 Task 依赖成环。
-- `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/<变更名称>/` 下可再生的 `ontology/working-ontology.json`、`ontology/artifact-index.json` 与 `artifacts/*.ontology.json`。
-
-## Guardrails
-
-- Check 是**只读检查**操作，不修改任何文档内容
-- 发现问题时推荐修复命令但不自动执行
-- 检查报告必须结构化、可操作
-- 支持增量检查（只检查指定 Capability）
-- **⛔ 阶段边界**：禁止执行任何代码创建/修改操作
-
----
+结束命令仍执行一次全量对账，核验评审期间文件/历史身份的变化；这次复核有时间边界意义，保留它。默认 auto 模式对照返回 semantic_state.revision 与预检 revision；不一致时不能宣称刚审过的版本仍有效，重新预检并复核变动及受影响的依赖，另记新一轮结果。显式 strict 时 end 的 auto revision 不能直接与 strict revision 比较；最终额外运行一次 --profile=strict 的 semantic-check 并比较 strict revision，auto 结果不能替代 strict 门禁。
 
-## 渐进披露
+报告输出五维结论、多仓配置、KB 状态、证据与未执行项，说明覆盖范围。只请求检查则结束；已授权实现且无阻断项时进入 apply。修复文档后再检查相关依赖，禁止携带旧结论直接通过；不把 Capability 局部评审写成全 Change 通过。
 
-- Read `checklist.md` 仅在 check 阶段日志自检时（check_result 记录、execution-log 状态标记、字段口径）。
+[checklist.md](checklist.md) 仅供日志异常/自检时读取，正常路径不再完整加载一遍。

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

@@ -25,7 +25,7 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 - [ ] `review_execution_mode` / `reviewer_agent_id` / `parent_session_id` / `review_session_id` / `author_session_id` / `reviewer_independence`: Q3 独立性元数据已填写
 - [ ] 主 Agent 回退时已记录 `fallback_reason_code` 和通俗 `fallback_reason`，原因码属于 `SUBAGENT_CAPABILITY_UNAVAILABLE` / `SUBAGENT_PERMISSION_DENIED` / `SUBAGENT_START_FAILED` / `SUBAGENT_TIMEOUT` / `SUBAGENT_RESULT_INVALID`
 - [ ] `categories`: 含 `completeness` / `consistency` / `executability` / `tdd_compliance`；四类 `total` 合计等于顶层 `total`，四类未通过数合计等于 `errors`
-- [ ] `task_completion`: 从 `tasks-status` 整理；未进入 apply 时 `checked_for_archive_readiness=false`
+- [ ] `task_completion`: 复用 `semantic-check --include-tasks` 的结果（与 tasks-status 同一扫描器）；未进入 apply 时 `checked_for_archive_readiness=false`
 - [ ] **P1-1**：`check_result` 事件 `details` 非空且含 `categories` 等必填键（禁止空 `{}`，否则 Q3 不可计算）
 - [ ] **P2-3**：`has_incomplete=true` 时 `check_result.result=partial` 且 `warning_items` 含 task_completion 项
 
@@ -34,12 +34,12 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 - [ ] execution-log.md 状态标记规范：`✅OK` / `🟡WARN` / `❌FAIL`
 - [ ] check 阶段结果与 `check_result.result` 一致（success→✅OK / partial→🟡WARN / failure→❌FAIL）
 
-## D. 检查报告四维
+## D. 检查报告五维
 
 - [ ] 完整性、一致性、算法正确性、可执行性、TDD合规性（仅test-strategy=tdd时）五维均已输出
 - [ ] 报告问题对应修复建议（spec/design/task）
 
-## D2. 一致性补充检查（SKILL.md §4.2 扩展）
+## D2. 一致性补充检查（reviewer.md §4.2）
 
 - [ ] **CON 覆盖**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖
 - [ ] **安全/审计要求覆盖**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
@@ -48,7 +48,7 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 ## E. TDD 合规性检查（仅 test-strategy=tdd 时）
 
-⛔ 执行 `tdd-core/checklist.md` §B（11 项）逐项检查。
+⛔ 执行 `../tdd-core/checklist.md` §B 的适用项，不重复维护固定项数。
 
 > 不在此内联复制，以 tdd-core/checklist.md §B 为唯一真相源。
 > 额外补充：还需检查 `tdd-rules/rules/exception-path-coverage.md`（异常路径覆盖门禁）。
@@ -61,3 +61,6 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 - [ ] `openspec/changes/<变更名称>/ontology/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `ontology/working-ontology.json` revision 一致
 - [ ] 全部语义门禁通过时工作态 JSON 已从 draft 刷新为 pending；check 未修改任何 Markdown 原文
+- [ ] 预检只执行一次 semantic-check，没有先执行 semantic-reconcile；结束时的全量对账仍保留
+- [ ] 主 Agent 未预读全文再重复评审；评审者未重跑启动/记账流程
+- [ ] 文件在评审期间改变时已重新预检和复核，局部评审没有被声明为全 Change 通过

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

@@ -0,0 +1,58 @@
+# Check 结果记录（主 Agent 在评审完成后读取）
+
+收到实际评审结果后，必须把结果转换为 `check_result` 事件，并在 `stage_end` 之前执行成功。禁止用 stage_end 代替已执行评审的证据。程序预检阻断且未开展评审时，只记录阶段 failure 与真实原因，不伪造 reviewer 或零项评审。
+
+字段口径：
+- `total`: 本次检查项总数。
+- `errors`: 必须修复的问题数。
+- `warnings`: 建议修复的问题数。
+- `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`: **legacy 兼容字段**（保留一个发布版本）；跨文档一致性评分 0-1，无法评分时填 `null`。
+- `reviewer`: 执行本次 check 的代理或会话标识。
+- `review_execution_mode`: `subagent` 或 `main-agent-fallback`。
+- `reviewer_agent_id`: 独立子代理或独立任务标识；主 Agent 回退时省略。
+- `parent_session_id`: 启动子代理的主会话 ID。
+- `review_session_id`: 独立评审会话 ID；主 Agent 回退时为当前检查会话。
+- `author_session_id`: 文档作者会话 ID。
+- `reviewer_independence`: `independent-review` | `self-review` | `unknown`。
+- `fallback_reason_code` / `fallback_reason`: 仅主 Agent 回退时填写，原因码必须来自 SKILL.md §3 的五个标准值。
+- `categories`: 必须包含 `completeness`、`consistency`、`executability`、`tdd_compliance`；四类 total 合计等于顶层 total，四类未通过数合计等于 errors。算法正确性计入 consistency，文字报告单列，避免重复计数。
+- `task_completion`: 复用本轮 `semantic-check --include-tasks` 的输出（使用 tasks-status 同一扫描器），只取模板中的计数字段；未进入 apply 时 `checked_for_archive_readiness=false`。
+
+将评审结果写为 UTF-8 JSON：`skywalk-sdd/state/<变更名称>-check-<run-id>.json`，结构见 [result-template.json](result-template.json)。其中 `0` 是待替换位置，执行前换成本轮实测值，顶层 `total` 必须是大于 0 的整数。不要直接把安装目录中的模板传给命令（details 文件成功读取后默认清理）。
+
+```bash
+node "<spec-package>/skywalk-sdd/log.cjs" record --strict --type=check_result --command=check --project="<spec-package>" --change=<变更名称> --capability=<可选capability-name> --run-id=<本轮Check稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<父会话ID> --result=success/partial/failure --summary="检查结果摘要" --details-file=skywalk-sdd/state/<变更名称>-check-<run-id>.json
+```
+
+外层事件 `--session-id` 是执行记录的主 Agent 会话；JSON `review_session_id` 是实际评审会话。两者不要混填。使用 details-file 避免跨平台 shell JSON 转义与重试；同一轮写入重试复用 run-id，不另开一轮评审。记录失败时修复真实字段后重试，不绕过 strict。
+
+> **⚠️ P1-1 check_result details 不得为空**：details JSON 必须含正整数 `total`、非负整数 `errors`、四类 `categories`、计数自洽的 `task_completion` 和 reviewer 独立性字段等，**禁止传空对象 `{}`**。空 details 导致 Q3 不可计算，并会被 strict 记录直接拒绝；历史非 strict 事件仍按兼容口径读取。
+
+> **⚠️ P2-3 check 纳入 task_completion 判定**：复用任务状态后，若 `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 "<spec-package>/skywalk-sdd/log.cjs" record --type=conformance_review --command=check --project="<spec-package>" --change=<变更名称> --capability=<可选capability-name> --agent=<Agent类型> --source=manual --session-id=<会话ID> --result=success --summary="规约符合度评审" --details-json="{\"conformance_review\":{\"method\":\"llm-as-judge\",\"agent_confirmed\":true,\"human_status\":\"unverified\",\"reviewer\":\"<reviewer-identifier>\",\"assertions\":[{\"id\":\"ASSERT-001\",\"description\":\"规约中的可验证断言\",\"judge_status\":\"matched\",\"human_status\":\"matched\",\"evidence\":\"代码、测试或文档证据摘要\",\"files\":[],\"notes\":\"\"}]}}"
+```
+
+> **human_status 说明（T3.4）**：`conformance_review.human_status` 标识本次评审是否经真实人工确认：`unverified`（AI 自评，待人工确认，默认）或 `matched`（已由人工评审确认）。**仅当真实人工评审时才填 `matched`**，避免 AI 自评被误标为已确认。报告 Q1 规约符合度会据此标注「自评，待人工确认」。
+
+> **【L4 conformance_review details-json 完整 schema】**：
+> - `reviewer` 必须带引号（字符串），如 `"reviewer": "claude-code"`
+> - `assertions[].files` 是必填数组，每项为实际文件路径字符串，如 `"files": ["src/auth.js", "test/auth.test.js"]`；空数组 `[]` 须配合 `evidence` 文本作为降级证据（如浏览器自动化/手动验收摘要）。`files` 含测试文件路径（`test/`、`.test.`、`.spec.`）**或** `evidence` 非空，二者至少满足其一，否则空口断言被工具侧记录时硬校验拒绝（详见 `skywalk-sdd/index.cjs`）
+> - `assertions[].judge_status` 枚举：`matched` / `partial` / `missed`
+> - `assertions[].human_status` 枚举：`matched` / `partial` / `missed` / 省略（默认跟随 judge_status）
+
+> **reviewer 与 reviewer_independence 说明（check_result）**：执行 check 前先读取文档作者/阶段会话信息；默认启动且只启动一个独立子代理。仅当 `review_execution_mode=subagent`、`reviewer_agent_id` 存在、`reviewer_independence=independent-review` 且 `review_session_id` 与 `author_session_id` 不同时，Q3 才为 `verified`；主 Agent 回退或无法确认时 Q3 标 `provisional` 但仍可计算分数。
+
+> **报告用语**：`verified` 展示为“已独立验证”；`provisional` 展示为“已有计算结果，尚未独立验证”。不要使用 “self-review” 作为用户可见说明；应写成“由主 Agent 自查，未经过独立复核”。不得仅用颜色区分，也不得把尚未独立验证的结果写成最终可信结论。
+
+> **reviewer 与 reviewer_independence 说明（conformance_review）**：`reviewer` 用于标识实际执行本次符合度评审的代理或会话（例如 agent 名称、会话 ID）。渲染报告时会比较 `reviewer` 与 apply 阶段记录的 `apply_agent`：若两者相同，则 `reviewer_independence` 显示为 `self-review`；否则显示为 `independent-review`。建议尽可能由独立评审方执行 check，以提升结果可信度。
+
+
+## 完成与修复
+
+`stage_end --summary` 中的场景、任务和 DAG 数量来自本轮实测结果（B1），不能凭记忆填。已有授权范围内的文档修复单独执行并记录 `process_note`（kind=recovery、command=check），不得夹在独立只读评审中悄悄修改。业务歧义集中询问。修复改变输入后重新预检，并复核变动及受影响的文档链。实现代码修复进入 apply。