kld-sdd 2.7.3 → 2.7.8

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

@@ -5,7 +5,7 @@ argument-hint: "[change-name] [file...]"
 license: MIT
 metadata:
   author: sdd-team
-  version: "2.0"
+  version: "3.0"
 allowed-tools:
   - Bash
   - Read
@@ -13,510 +13,141 @@ allowed-tools:
   - Edit
 ---
 
-你是一个 SDD（Specification-Driven Development）Spec 双向一致性校验专家。激活本技能后，你将对比 spec 文档与代码实现，进行**双向校验**：
+> **路径约定**：`<skill-dir>` = 本文件所在目录；`<spec-root>` = spec 仓根目录（含 `skywalk-sdd/git-hooks/`）。辅助脚本：`<skill-dir>/scripts/scripts.cjs`；hook 同款采集器：`<spec-root>/skywalk-sdd/git-hooks/consistency-check-core.cjs`。
 
-- **spec → code**：验证代码是否完全符合 spec 定义（代码是否遗漏了 spec 的要求）
-- **code → spec**：验证 spec 是否准确反映代码实现（spec 是否遗漏了代码的实际行为）
+你是 SDD 一致性校验专家。任务只有一件事：**对比 diff 变更代码与 spec 的接口契约是否一致**（API 路径、HTTP 方法、请求参数、响应字段、错误码），生成 git hook 可消费的报告。除此之外的一切（业务规则深挖、关联文件扫描、多维度深度校验）都不做。
 
-> **对抗性审核原则**
->
-> 假设 spec 和代码是由其他人（或其他 AI）生成的，你的任务是**严格找出不一致、遗漏和潜在问题**，而不是确认一致性。
->
-> - 不要假设"既然 spec 这样写了，代码肯定也这样实现了"
-> - 不要假设"既然代码这样写了，spec 肯定也覆盖了"
-> - 不要跳过看似正确但未经逐行比对的细节
-> - 对每个断言都要找到**具体的证据**（代码行号或 spec 章节），找不到就标记为 missed
-> - 宁可误报（false positive），不可漏报（false negative）
+## 硬约束（违反会导致 hook 死循环或误拦，不可协商）
 
----
-
-## 技能定位
-
-| 维度 | 内容 |
-|------|------|
-| 核心问题 | spec 与代码是否双向一致（代码是否符合 spec + spec 是否反映了代码） |
-| 关键输出 | 结构化校验报告（置信度 + 双向维度详情 + 怀疑清单 + 建议） |
-| 校验维度 | 接口契约、业务规则、校验规则、错误码、前后端一致性（双向合并判定） |
-| 上游依赖 | spec.md + 代码文件 |
-| 校验方式 | **纯 AI 语义分析**（零外部依赖） |
-
----
-
-## 启动流程
-
-### 1. 【交互引导】确认校验范围和审核模式
-
-**1.1 确认校验范围**
-
-若用户提供了 change-name，读取对应变更的 spec：
-- `openspec/changes/<change-name>/specs/*/spec.md`
-- `openspec/specs/*/spec.md`（全局 spec）
-
-若用户提供了具体文件路径，只校验这些文件对应的 spec。
-
-若均未提供，执行以下流程：
-
-1. 获取活跃变更列表：
-```bash
-ls openspec/changes/ | grep -v archive
-```
-
-2. 根据变更数量处理：
-   - **0 个活跃变更** → 提示"无活跃变更，跳过校验"并结束
-   - **1 个活跃变更** → 自动选择该变更，向用户确认后执行
-   - **多个活跃变更** → **必须**使用 `AskUserQuestion` 让用户选择，禁止自动推断
-
-> **⛔ 强制约束**：多 change 场景下，禁止根据当前打开的文件、git diff 或其他上下文自动推断要校验的 change。必须由用户显式选择。
-
-**1.2 确认审核模式**
-
-| 模式 | 参数 | 说明 |
-|------|------|------|
-| **独立审核模式**（默认） | 无参数 | 对抗性审核，假设代码是别人写的，严格找问题 |
-| **自审模式** | `--mode=self-review` | 同一 AI 审核自己生成的代码，需人工确认 |
-
-若用户未指定 `--mode=self-review`，默认使用**独立审核模式**。
-
-### 2. 获取变更文件并确定校验文件范围
-
-> **关键约束**：本步骤确定两个文件列表：
-> - `CHANGED_FILES`：**所有与当前变更相关**的文件（包括暂存和未暂存的修改），是**报告输出**的范围
-> - `REFERENCE_FILES`：`CHANGED_FILES` + 直接引用的关联文件（DTO、Model、Interface 等），是 **AI 分析**的范围（用于跨文件对比）
->
-> **数据源强制约束**：必须使用 `git diff HEAD --name-only` 获取所有变更文件列表（包括暂存和未暂存的修改）。**禁止**仅使用 `git diff --cached --name-only`，因为它会遗漏未暂存的修改，导致校验结果不完整。
-
-#### 2.0 多仓库检测（强制前置步骤）
-
-> 项目可能采用多仓库结构（前端、后端各自独立仓库）。单仓库场景下本步骤无副作用。
-
-**采集流程**：
-
-1. 检查是否存在 `.sdd-workspace.yaml`，若存在则读取 `code_repos` 列表（如 `backend`、`frontend`）
-2. 对每个仓库执行 `git diff HEAD --name-only` 获取变更文件
-3. 将路径归一化为**相对于工作区根目录**的路径（如 `backend/src/main/java/.../UserController.java`）
-4. 合并为 `ALL_CHANGED_FILES`
-
-> **单仓库兼容**：若不存在 `.sdd-workspace.yaml`，直接对工作区根目录执行 `git diff HEAD --name-only`。
+1. **采集必须用 hook 同款命令**（步骤 1），禁止手工拼 git diff——两边采集不一致会导致报告盖不住 diff → hook 拦截 → 重新生成仍被拦的死循环
+2. **coveredFiles 必须与实际校验的变更文件完全一致**：path 为工作区相对路径，size/sha256 直接复用采集器输出（LF 归一化已内置），禁止估算、禁止用平台命令重算
+3. **confidence 只能 `high`/`medium`/`low`**（其他值被 hook 判非法拦截）；**generatedAt 必须本机本地时间** `YYYY-MM-DD HH:mm:ss`（禁止 UTC，hook 按本地时区做过期判断）
+4. **md + json 成对写入** `openspec/changes/<change-name>/`，单边存在会被判报告不完整并拦截
+5. **只读变更文件本身**，不扩展读 DTO/Model/配置/SQL 等关联文件；缺证据标"待人工核查"，不中断补读
+6. **无业务代码变更 → 不生成报告**，输出一句提示即结束（hook 对无业务代码提交直接放行）
+7. 生成前必须先删旧报告（步骤 2c 已内置），全量重新校验，不读旧报告做增量复用
+8. **多仓布局下 `repositories` 必填**：工作区根存在 `.sdd-workspace.yaml` 时，JSON 报告必须含 `repositories` 数组，`path` 为该 change 覆盖的代码仓名（与 `.sdd-workspace.yaml` 的 `code_repos` 条目一致）。单仓布局可省略或留空数组。hook 用此字段剥离 coveredFiles 路径前缀以对齐 diff 路径，缺失会导致路径不匹配 → 误判"无交集" → 报告形同虚设
 
-根据校验范围获取变更文件列表：
+## 执行流程（4 步）
 
-- **指定了 change-name 或未指定变更**：按上述流程采集所有仓库的变更文件，合并为 `ALL_CHANGED_FILES`
-- **指定了具体文件**：直接使用用户指定的文件列表
+### 1. 采集变更文件（脚本，秒级）
 
-#### 2.1 变更文件筛选（强制）
-
-> **核心原则**：变更列表中可能包含多个变更的文件，也可能包含不涉及 spec 一致性校验的文件（如文档、配置、脚本等）。必须筛选出**与当前变更相关且可进行 spec 一致性校验**的文件。
-
-**筛选规则**：
-
-| 操作 | 文件模式 | 说明 |
-|------|---------|------|
-| 保留 | 业务代码（`*.java` / `*.ts` / `*.tsx` / `*.js` / `*.jsx` / `*.vue` / `*.py`，排除 `*.d.ts`） | 与当前变更 spec 直接相关的源代码 |
-| 排除 | `*.md`, `*.txt`, `*.rst`（非 spec 文件） | 文档不参与校验 |
-| 排除 | `*.yml`, `*.yaml`, `*.properties`, `*.ini`, `*.toml`, `*.json`（非路由/接口定义） | 配置文件不涉及接口契约 |
-| 排除 | `*.bat`, `*.sh`, `*.cjs`, `*.mjs`, `*.ps1` | 工具脚本不参与校验 |
-| 排除 | `*.d.ts`, `*.d.tsx` | 类型声明文件不涉及 spec 校验 |
-| 排除 | `*.lock`, `package-lock.json` 等 | 锁文件不参与校验 |
-| 排除 | `dist/`, `build/`, `target/`, `out/`, `*.min.js`, `*.min.css` | 构建产物不参与校验 |
-| 排除 | `*test.*`, `*spec.*`, `*_test.*`, `__tests__/`, `tests/`, `test/` | 测试代码由 opsx-test 负责 |
-| 排除 | git status 为 `deleted` 的文件 | 已删除文件无法校验 |
-| 排除 | `.gitignore`, `.editorconfig`, `.prettierrc`, `.eslintrc.*`, `tsconfig.*` 等 | 工具链配置不涉及业务 spec |
-| 排除 | 路径不属于当前 change-name 的 spec 覆盖范围的文件 | 非当前变更的代码 |
-
-**各语言业务代码识别**：
-
-| 语言 | 业务代码扩展名 | 典型目录模式（参考） |
-|------|--------------|-------------------|
-| Java | `*.java` | controller, service, repository, model, dto, entity, config, filter, handler |
-| TypeScript/JavaScript | `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.vue`（排除 `*.d.ts`） | api, service, store, hook, component, page, controller, model, util |
-| Python | `*.py` | views, controllers, services, models, serializers, handlers, routers |
-
-**筛选方法**：
-1. 获取变更文件完整列表（按步骤 2.0 的多仓库流程，合并为 `ALL_CHANGED_FILES`）
-2. 读取当前 change-name 的 spec 文件，提取其覆盖的模块/路径范围
-3. 对每个变更文件：
-   - 判断是否为业务代码（根据语言扩展名和目录模式）
-   - 判断是否属于当前 spec 覆盖范围（根据文件路径、包名、模块名等）
-   - 若两者都满足，则保留；否则排除
-4. 不属于的文件从 `CHANGED_FILES` 中移除，不纳入校验范围，也不在报告中出现
-
-**最终输出**：
-- `CHANGED_FILES` — 筛选后的变更文件列表（仅包含与当前变更相关且可校验的文件），路径为工作区相对路径
-- `REFERENCE_FILES` — 在步骤 4 中通过扫描 import/引用关系扩展得出
-
-### 3. 读取 Spec 文档
-
-读取当前变更的 spec 和全局 spec：
+> **禁止环境预探测**：不要 Test-Path 探测 git 仓、不要列目录确认脚本存在——采集器自动处理单仓/多仓布局（多仓读 `.sdd-workspace.yaml` 的 code_repos 逐仓 diff），命令失败自会报错。首轮回复直接并行发起：① 采集命令 ② `list-changes`（两者无依赖）。
 
 ```bash
-# 变更级 spec
-find openspec/changes/<change-name>/specs -name "spec.md"
-# 全局 spec
-find openspec/specs -name "spec.md"
+node <spec-root>/skywalk-sdd/git-hooks/consistency-check-core.cjs --collect --business-only --hash --project=<工作区根或代码仓根>
+node <skill-dir>/scripts/scripts.cjs list-changes
 ```
 
-重点提取：
-- 接口定义（路径、方法、参数、响应）
-- 业务规则（条件判断、状态流转、权限控制）
-- 校验规则（字段约束、非空校验、格式要求）
-- 错误码定义（错误码、触发条件、响应格式）
-- 前后端一致性（前端请求/响应字段与后端 DTO 字段的对应关系）
-
-### 4. 识别项目语言并确定文件范围
-
-**4.1 识别项目语言与关联文件扫描**
-
-> **多仓库场景**：每个子仓库可能使用不同的技术栈（如前端 Vue、后端 Java），需分别识别。
-
-| 项目标识 | 语言 | 代码文件 | 路由定义示例 | 引用语句 |
-|---------|------|---------|-------------|---------|
-| `pom.xml` / `build.gradle` | Java | `*.java` | `@RequestMapping` / `@PostMapping` | `import` |
-| `package.json` | TypeScript/JS/Vue | `*.ts`/`*.tsx`/`*.js`/`*.jsx`/`*.vue` | `router.get()` / `@Get()` / `app.get()` | `import ... from` |
-| `requirements.txt` / `pyproject.toml` | Python | `*.py` | `@app.route()` / `@router.get()` | `import` / `from ... import` |
-
-**重要**：后端项目必须同时校验前端 TypeScript/JavaScript 文件（若存在），确保前后端字段对齐。
-
-**4.2 扫描关联文件**
-
-从 `CHANGED_FILES` 中的代码文件出发，根据上表"引用语句"列扫描 import/引用关系，找出直接关联的文件。
-
-**关联文件筛选规则**：
-- 仅包含**直接引用**的文件（一层深度，不递归）
-- 仅包含**同项目**内的文件（排除 node_modules、第三方库、vendor、site-packages 等）
-- **多仓库场景**：关联文件扫描限制在**同一子仓库**内，不跨仓库扫描（因为跨仓库的引用关系无法通过 import 语句直接追踪）
-- 优先提取：DTO / Request / Response / Schema、Model / Entity、Interface / Type、Repository / Service
-
-**4.3 标记文件来源**
-
-- `changed`：变更文件，问题归因到此类文件
-- `referenced`：关联文件，仅用于跨文件对比，不报告其问题
-
-### 5. 读取代码文件
-
-读取 `REFERENCE_FILES` 中的所有代码文件作为上下文。
-
-> **范围约束（强制）**：
-> - **分析范围**：`REFERENCE_FILES`（变更文件 + 关联文件），用于理解完整上下文
-> - **报告范围**：仅 `CHANGED_FILES`，**报告中的所有差异项只能引用 `CHANGED_FILES` 中的文件**
-> - 若问题代码位于 `REFERENCE_FILES` 但不在 `CHANGED_FILES` 中，**不得**作为差异报告，只能放入"怀疑清单"
-
-### 6. 执行双向一致性校验
-
-基于代码内容和 spec 定义，进行双向校验。
-
-> **对抗性审核要求**：
-> - 对每个检查项，必须找到**具体证据**（代码行号或 spec 章节）。找不到证据的，标记为 ❌ 或 ⚠️。
-
-> **逐字段对比强制约束**：
-> - 响应结构必须**逐字段**对比，不允许"大致匹配"
-> - 字段名必须**精确匹配**（`token` ≠ `accessToken`，`id` ≠ `userId`）
-> - 嵌套结构的每一层都必须校验
-> - 若代码中构造响应的方式是 Map/字典/结构体/序列化对象（如 Java `Map.of()`、Python `dict`），必须提取所有 key 并与 spec 逐一对比
+输出 `businessFiles`（对象数组，含 path/size/sha256，机械筛选已内置）+ `deletedFiles`。命令失败（退出码非 0）= git diff 采集失败，如实报错终止，禁止降级为"无变更"。
 
-> **证据标注要求**：每个检查项必须标注具体证据位置（代码文件:行号 或 spec 文件:章节），找不到证据的标记为 ❌。
+- **无业务文件** → 提示"无代码变更，跳过校验"并结束
+- **有业务文件但无活跃 change** → 报错终止，提示先执行 opsx-propose
+- **多 change 且未指定 change-name** → 按 spec 覆盖范围把文件归属到各 change，每个 change 独立出报告；同一文件被多个 change 归属时只在首个 change 完整校验、其余复用结论（coveredFiles 仍完整包含）。**单 change 或已指定 change-name** → 全部文件归入，跳过归属逻辑
+- **用户指定了具体文件** → 交给 `consistency-check-core.cjs --filter` 机械筛选，哈希用 `prepare-report --files-from=<列表文件>` 补算
 
-#### 6.1 后端接口契约校验
+### 2. 读上下文（a/b/c 同一回复并行发起，禁止分批等待）
 
-对 `CHANGED_FILES` 中的后端代码文件 + 关联 DTO/Model 的数据，进行以下校验：
+a. **定位并读 spec**：`node <skill-dir>/scripts/scripts.cjs find-specs <change-name>` 拿文件列表，**禁止全量读**（近百个 spec 全读既慢又撑爆上下文）。API 路径由 AI 从已读 Controller 原生提取（任何语言的路由写法都直接认识，禁止用正则 grep 代码提取），再用**字面量片段**（如 `/api/user`；禁止含 `|`、`"`、`\`、`()` 的正则——Windows cmd 会拆解管道符与引号导致 0 命中）grep spec 目录：
 
-- [ ] API 路径与 spec 一致
-- [ ] HTTP 方法与 spec 一致
-- [ ] 请求参数字段名、类型与 spec 一致
-- [ ] 参数约束（校验注解/装饰器/类型）与 spec 一致
-- [ ] 响应结构**逐字段**与 spec 一致
-- [ ] HTTP 状态码与 spec 一致
-- [ ] 错误码与 spec 一致
-- [ ] 代码中额外的接口/端点已在 spec 中记录
+   ```bash
+   node <skill-dir>/scripts/scripts.cjs grep-code "/api/user" <openspec-dir> --glob=spec.md -i
+   ```
 
-#### 6.2 前端接口契约校验
+   **grep 省略条件（省一轮往返）**：`find-specs` 命中的变更级 spec 文件总数 ≤ 5 个时，跳过 grep 直接读这些文件（变更级 spec 本来就是该 change 的契约文档，命中概率极高）；命中 > 5 个或需在全局 spec 中定位时才 grep。只读命中文件；命中 0 → 回退读变更级 spec（`changes/<name>/specs/`），仍不读全局 spec 全集。
 
-对 `CHANGED_FILES` 中的前端代码文件（TypeScript/JavaScript/Vue 等），进行以下校验：
+b. **读代码（按契约角色分层，同一回复并行发起）**：首轮把全部变更文件按契约角色分三层，**全文 Read 与 grep 混排在同一回复一次发齐**（不产生额外往返；禁止的是"grep 定位后再补读"的两段式，不是 grep 本身）：
+   - **契约核心（全文 Read）**：Controller、DTO/VO/QueryDTO、全局异常处理器（`*Controller`、`*DTO`、`*VO`、`*ExceptionHandler` 等，按语言现场识别）——接口契约的直接载体，必须逐字段比对
+   - **契约相关（grep 取证，不读全文）**：Service/ServiceImpl、Repository——只 grep 方法签名 + 响应构造 + 错误码，模式按语言现场定（Java `return`/`Map.of`、Python `return {`/`jsonify`、Go `c.JSON`）
+   - **无契约面（grep 确认后跳过）**：Application 启动类、`*Config`/`*Properties`、`*Util`、`BusinessException`、`*Mapper` 接口等——grep 端点声明（路由注解/路径常量）+ 业务错误码字面量，**零命中 → 结论"无契约面"，不进入步骤 3 逐字段比对**；有命中 → 升级按上一条 grep 取证处理
+   - **前端**（.ts/.tsx/.vue/.js）：只 grep API 调用路径 + HTTP 方法，与 spec 路径比对
+   - **coveredFiles 不受分层影响**：全部变更文件照常列入报告（硬约束 2），分层只决定"读多深"，不决定"盖不盖"
+   - **例外**：契约核心文件单文件 ≥ 800 行时，先 grep 定位端点区域，再分段读相关区间
 
-- [ ] API 路径与 spec 一致
-- [ ] HTTP 方法与 spec 一致
-- [ ] 请求字段与 spec 一致
-- [ ] 校验规则与 spec 一致
-- [ ] localStorage keys 与 spec 响应字段对应
-- [ ] 响应字段读取与后端返回一致
-- [ ] 代码中额外的前端行为已在 spec 中记录
+c. **prepare-report**：`node <skill-dir>/scripts/scripts.cjs prepare-report openspec/changes/<change-name>` —— 清理旧报告 + 输出本地时间戳（`timestamp` 直接作为 generatedAt；该命令绝不读 stdin，不会挂起）。
 
-#### 6.3 业务规则校验
+> **报告落点（固定，无需确认）**：报告必须写在 **spec 根**下的 `openspec/changes/<change-name>/`（hook 的 `findReportJson` 只在 `<spec-root>/openspec/changes/<name>/` 找报告，写到别处 = 报告缺失 = 拦截）。`prepare-report` 已自动按 spec 根解析相对路径，输出 JSON 的 **`changeDir` 字段就是解析后的实际目录**——写报告直接用它拼接文件名，禁止自行按 cwd 推导路径，也无需读脚本源码确认。coveredFiles.path 由采集器原样输出（多仓布局带仓前缀如 `user-info-mgmt/src/...`）。hook 在代码仓根运行、diff 路径无前缀，靠 `repositories[].path` 剥离 coveredFiles 前缀才能对齐——故多仓布局下 `repositories` 必填（见硬约束 8）。
 
-- [ ] 条件判断与 spec 一致
-- [ ] 状态流转与 spec 一致
-- [ ] 权限要求与 spec 一致
-- [ ] 条件分支逻辑正确性（无不可达分支）
-- [ ] 代码中额外的业务逻辑已在 spec 中记录
+> **子代理分派规则（按活跃 change 数机械判定，禁止裁量）**：
+> - **多 change（≥2 个）→ 必须并行**：每个 change 一个子代理，同一回复全部分派（上限 2 个，两 change 恰好一批）。**禁止**主线程逐 change 串行校验，**禁止**以"宿主并发能力不确定"为由跳过——派发在最坏情况（宿主排队串行）下也只是无收益，结果照常回收，无损害；实测多 change 串行是步骤 3 最大耗时来源（两仓各 5 分钟级推理串行叠加），并行后总耗时取单 change 最大值
+> - **单 change → 按文件量分组**（仅适用于恰好 1 个活跃 change 的场景，不得套用到多 change 的单个 change 上）：≤ 15 个文件主线程直接校验（无需子代理）；> 15 个按 8-10 个/组分派子代理，逐组执行
+> - **禁止**：主线程自己串行逐文件校验（36 文件 = 36 轮往返，是最大耗时来源）；一次回复分派超过 2 个子代理（并发过高导致宿主排队 + 结果交错，实际更慢）
+> - **派发提示必须自带分层读取规则**：子代理不读 SKILL.md，只知派发提示里写的内容——分派时必须把步骤 2b 的三层策略（契约核心全文读 / Service·Repository grep 取证 / 无契约面 grep 确认后跳过）原文写入提示。漏写则子代理退回全量读全文（实测发生：子代理全文读 ServiceImpl/Mapper/Config，上下文膨胀拖慢推理与汇总生成）
+> - 每个子代理完成"读 spec 命中集 + 按契约角色分层读本组代码 + 步骤 3 校验"，返回差异清单 + 计数，主线程汇总生成报告；公共文件只在首个归属 change 的子代理中完整校验，其余复用
 
-#### 6.4 校验规则
+### 3. 校验（AI 推理，唯一核心工作）
 
-- [ ] 字段约束（长度、格式、范围）与 spec 一致
-- [ ] 必填字段有非空检查
-- [ ] 代码中额外的校验规则已在 spec 中记录
+对每个变更文件，对照 spec 回答一个问题：**接口契约是否一致？**
 
-#### 6.5 错误码校验
+**检查项（双向）**：
+- **spec → code**：spec 定义的路径/方法/参数/响应字段/错误码，代码是否实现且一致
+- **code → spec**：代码中的端点、响应字段 key、业务错误码是否已在 spec 记录（**仅枚举业务契约面**；工具方法、日志、防御性代码、DTO 转换等纯技术实现不枚举、不降级）
 
-- [ ] 错误码与 spec 一致
-- [ ] 错误触发条件与 spec 一致
-- [ ] 错误响应格式与 spec 一致
-- [ ] 代码中额外的错误码已在 spec 中记录
+**要求**：
+- 响应结构**逐字段**对比，字段名精确匹配（`token` ≠ `accessToken`）；`Map.of()`/字典/结构体构造必须提取所有 key 逐一比对
+- 每条差异定位到 `文件:行号 + spec 章节`，不贴代码原文片段
+- 找不到证据的标 ❌/⚠️，不假设一致
 
-#### 6.6 前后端一致性校验
+**置信度判定**：
+- **high**：无差异，或仅技术实现未记录
+- **medium**：辅助性差异（非关键端点/字段缺失或不一致）
+- **low**：关键契约不一致、spec 有关键功能代码没有、代码有业务功能 spec 没有
 
-对 `CHANGED_FILES` 中同时包含前端和后端文件时，进行跨文件对比：
+### 4. 生成报告（纯模板填充，零推理）
 
-- [ ] 前端请求字段 vs 后端 DTO 字段：字段名必须精确匹配（如前端 `phone` vs 后端 `username` 为不匹配）
-- [ ] 前端响应字段读取 vs 后端响应构造：字段名必须精确匹配
-- [ ] 前端校验规则 vs 后端校验规则：同一字段的校验约束必须一致
+结论确定后直接写文件，**禁止**重新核对证据或推演差异。md + json 在**同一回复并行写入**（多 change 的全部报告同批写）。**禁止任何计时打点**（步骤起止时长、执行统计、额外的 `now` 调用）——报告 `generatedAt` 已由步骤 2c 的 prepare-report 输出，流程内不需要其他时间戳；执行时长统计只在用户显式要求时做，默认不做。
 
-> **强制约束**：若跨文件校验涉及的某个文件不在 `CHANGED_FILES` 中，**不得**将其作为差异项报告，只能归入"怀疑清单"。
-
-#### 6.7 生成怀疑清单
-
-校验完成后，**必须**生成一份怀疑清单。清单中的差异项**必须**使用判定标准中定义的四类问题分类（见"一、问题分类"），潜在风险使用补充类型。
-
-**核心差异分类**（必须使用，与判定标准一致）：
-
-| 类型 | 说明 | 置信度影响 |
-|------|------|-----------|
-| **代码有 spec 没有（业务）** | 代码实现了业务功能但 spec 未描述 | 业务功能→low，辅助功能→medium |
-| **代码有 spec 没有（技术）** | 代码实现了纯技术支撑逻辑，不涉及业务契约 | 不降级 |
-| **spec 有代码没有** | spec 定义了但代码未实现 | 关键→low，非关键→medium |
-| **不一致** | 代码和 spec 都有但不匹配 | 关键→low，非关键→medium |
-
-**补充怀疑类型**（用于潜在风险，不影响置信度）：
-
-| 类型 | 说明 |
-|------|------|
-| Spec 歧义 | spec 中描述模糊、可能有多种理解的点 |
-| 隐含假设 | spec 未明确定义但代码做了假设的点 |
-| 边界遗漏 | spec 未覆盖但代码可能遇到的边界条件 |
-| 命名不一致 | 前后端字段名、错误码命名风格差异 |
-| 跨 Spec 矛盾 | 不同 spec 之间可能存在的定义冲突 |
-| **非变更文件问题** | 校验中发现的问题涉及的文件不在 `CHANGED_FILES` 中（不属于当前变更范围），无法作为差异报告，需提醒用户检查该文件 |
-| **技术实现建议** | 代码中的纯技术实现（工具方法、防御性代码、日志等）虽不影响置信度，但若存在可优化空间，可在此记录建议 |
-
-每条怀疑项标注风险等级（P0-P3）和建议验证方式。
-
-### 7. 输出校验报告
-
-**所有场景（high/medium/low）都必须生成报告文件**，便于追溯和审计。
-
-
-> **无代码变更场景**：当 `CHANGED_FILES` 为空（所有变更文件均为文档/配置等非代码文件）时，仍需生成报告文件：
-> - 置信度：`high`
-> - 所有维度：`pass`
-> - summary 所有计数：`0`
-> - 报告中注明"本次变更无代码文件，跳过一致性校验"
-
-#### 7.0 清理旧报告（强制前置步骤）
-
-生成新报告前，**必须先删除**该 change-name 下所有已存在的报告文件，避免两种模式的报告同时存在导致 git hook 报错：
-
-```bash
-# 删除所有可能的报告文件（若存在）
-rm -f openspec/changes/<change-name>/consistency-report.md
-rm -f openspec/changes/<change-name>/consistency-report-result.json
-rm -f openspec/changes/<change-name>/consistency-report-self-review.md
-rm -f openspec/changes/<change-name>/consistency-report-self-review-result.json
-```
-
-> **原因**：git hook 检测到同一 change-name 下同时存在独立审核和自审模式的报告时，会拒绝提交/推送并要求用户手动删除。
-
-#### 7.1 生成 Markdown 报告
-
-将报告写入 md 文件，按审核模式区分文件名：
-
-| 审核模式 | 报告路径 |
-|---------|---------|
-| 独立审核（默认） | `openspec/changes/<change-name>/consistency-report.md` |
-| 自审模式（`--mode=self-review`） | `openspec/changes/<change-name>/consistency-report-self-review.md` |
-
-#### 7.2 生成 JSON 结果文件（强制）
-
-**必须同时生成 JSON 结果文件**，供 git hook 解析置信度进行拦截判定。
-
-JSON 文件路径与 md 报告对应：
-
-| 审核模式 | JSON 路径 |
-|---------|---------|
-| 独立审核（默认） | `openspec/changes/<change-name>/consistency-report-result.json` |
-| 自审模式（`--mode=self-review`） | `openspec/changes/<change-name>/consistency-report-self-review-result.json` |
-
-JSON 文件结构（必须严格遵循）：
+**JSON**（`consistency-report-result.json`，hook 唯一消费源，schema 固定）：
 
 ```json
 {
   "changeName": "<change-name>",
   "confidence": "high | medium | low",
-  "overallResult": "pass | warning | fail",
-  "reviewMode": "independent-review | self-review",
-  "humanConfirmed": false,
-  "generatedAt": "<YYYY-MM-DD HH:mm:ss>",
+  "generatedAt": "<YYYY-MM-DD HH:mm:ss 本地时间>",
   "repositories": [
-    { "name": "<仓库名或路径>", "path": "<仓库相对路径>", "changedFiles": 0 }
+    { "path": "<代码仓名>" }
+  ],
+  "coveredFiles": [
+    { "path": "<工作区相对路径>", "size": 2341, "sha256": "<64位十六进制>" }
   ],
   "dimensions": {
     "interfaceContract": { "status": "pass | warning | fail", "issues": 0 },
-    "businessRules": { "status": "pass | warning | fail", "issues": 0 },
-    "validationRules": { "status": "pass | warning | fail", "issues": 0 },
-    "errorCodes": { "status": "pass | warning | fail", "issues": 0 },
-    "frontendBackendConsistency": { "status": "pass | warning | fail", "issues": 0 }
+    "businessRules": { "status": "pass", "issues": 0 },
+    "validationRules": { "status": "pass", "issues": 0 },
+    "errorCodes": { "status": "pass | warning | fail", "issues": 0 }
   },
   "summary": {
-    "totalChecks": 0,
-    "passed": 0,
-    "failed": 0,
-    "warnings": 0,
-    "undocumentedBusiness": 0,
-    "undocumentedTechnical": 0,
-    "specMissing": 0,
-    "inconsistent": 0
+    "totalChecks": 0, "passed": 0, "failed": 0, "warnings": 0,
+    "undocumentedBusiness": 0, "undocumentedTechnical": 0, "specMissing": 0, "inconsistent": 0
   }
 }
 ```
 
-**字段说明**：
-- `confidence`：`high` / `medium` / `low`
-- `overallResult`：`pass` / `warning` / `fail`
-- `reviewMode`：`independent-review` / `self-review`
-- `humanConfirmed`：自审模式下必填，用户确认断言后设为 `true`；独立审核模式可省略
-- `generatedAt`：`YYYY-MM-DD HH:mm:ss`
-- `repositories`：参与校验的仓库列表
-- `dimensions`：各维度校验结果（`status` + `issues`）
-- `summary`：按四类问题分类计数（`undocumentedBusiness` / `undocumentedTechnical` / `specMissing` / `inconsistent`）
+`businessRules`/`validationRules` 固定 `pass:0`（简化校验不做深度检查）；`summary` 按差异清单逐条归类（一条差异只计一次），`failed + warnings` 与各维度 `issues` 合计一致。
 
-> **强制约束**：JSON 文件必须与 md 报告同时生成，供 git hook 读取置信度进行门禁判定。
-
-报告模板：
-
-> **时间格式强制约束**：`生成时间` 必须通过时间工具（如 MCP `get_current_time` 或系统命令 `date`）获取当前精确时间，格式为 `YYYY-MM-DD HH:mm:ss`。**禁止**仅填写日期而省略时分秒。
+**MD**（`consistency-report.md`，极简，禁止凑数空章节）：
 
 ```markdown
-# Spec 双向一致性校验报告
-
-**变更名称**：<change-name>
-**生成时间**：<YYYY-MM-DD HH:mm:ss>（必须通过时间工具获取，禁止仅填日期）
-**审核模式**：独立审核（independent-review）
-**仓库结构**：<单仓库 / 多仓库（列出各仓库路径）>
-**校验范围**：<diff 涉及的文件列表，多仓库场景下标注各文件所属仓库>
-
-## 校验结果
-
-| 维度 | 状态 | 详情 | 证据 |
-|------|------|------|------|
-| 接口契约 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
-| 业务规则 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
-| 校验规则 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
-| 错误码 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
-| 前后端一致性 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
-
-> 置信度为 medium 或 low 时，在此说明原因（如：接口契约=warning，因缺少辅助接口 /api/export 的 spec 记录）
-
-### 差异与怀疑清单
+# Spec 一致性校验报告
 
-> 以下列出代码与 spec 之间的所有差异，以及校验过程中发现的潜在风险。
-> **类型**必须使用判定标准中定义的四类问题分类（见"一、问题分类"）。
+**变更**：<change-name>　**生成时间**：<YYYY-MM-DD HH:mm:ss>
+**校验范围**：<N 个文件>　**置信度**：<high/medium/low>
 
-| # | 类型 | 风险等级 | 位置 | 描述 | 建议操作 |
-|---|------|---------|------|------|---------|
-| 1 | 代码有 spec 没有（业务） | P0-P3 | [代码文件:行号] | [代码实现了业务功能但 spec 未描述] | 补充到 spec [章节] |
-| 2 | 代码有 spec 没有（技术） | — | [代码文件:行号] | [代码实现了纯技术支撑逻辑，不涉及业务契约] | 无需补充 spec（纯技术实现不要求覆盖） |
-| 3 | spec 有代码没有 | P0-P3 | [spec 文件:章节] | [spec 定义了但代码未实现] | 补充代码实现或更新 spec |
-| 4 | 不一致 | P0-P3 | [代码文件:行号 / spec 文件:章节] | [代码和 spec 都有但不匹配] | 修改代码或 spec 使之一致 |
-| 5 | Spec 歧义 | P2 | [spec 文件:章节] | [描述模糊，可能有多种理解] | 明确 spec 描述 |
-| 6 | 隐含假设 | P1 | [代码文件:行号] | [spec 未明确定义但代码做了假设] | 补充到 spec 或确认假设正确 |
-| 7 | 边界遗漏 | P2 | [代码文件:行号] | [spec 未覆盖但代码可能遇到的边界条件] | 补充边界处理到 spec |
-| 8 | 非变更文件问题 | P1 | [文件路径] | [问题涉及的文件不在当前变更范围] | 检查该文件是否属于当前变更 |
+## 结果
 
-**置信度**：high / medium / low
+<全部通过时只写一行：接口契约与错误码全部一致，无差异。>
 
-**总体结果**：✅ 通过 / ⚠️ 有警告 / ❌ 未通过
-
-## 代码差异
-
-> 列出所有代码变更，标注是否符合 spec
-
-### <变更 1 标题>
-
-**Spec 期望**（<spec 文件路径:行号>）：
-```json
-<spec 定义的响应结构>
-```
+<有差异时列下表：>
 
-**实际实现**（<代码文件路径:行号>）：
-```diff
-- // spec 期望的代码
-+ // 实际实现的代码
+| # | 类型 | 风险 | 位置 | 描述 | 建议 |
+|---|------|------|------|------|------|
+| 1 | 不一致 | P0 | File.java:42 / spec §2.1 | <差异描述> | <改代码或改 spec> |
 ```
 
-**校验结果**：✅ 符合 / ❌ 不符合
-
-## 建议操作
-
-- [具体修复建议及对应文件:行号]
-- [spec 补充建议及对应章节]
-```
-
-> **注意**：若使用自审模式（`--mode=self-review`），报告需额外包含"人工确认"章节：
->
-> ```markdown
-> ## 人工确认（自审模式）
->
-> > ⚠️ 本报告为 AI 自审结果，以下关键断言需要人工确认：
->
-> | # | 断言描述 | AI 判定 | 人工确认 |
-> |---|---------|--------|---------|
-> | 1 | [断言] | ✅/❌ | [待确认] |
->
-> **人工确认方式**：
-> - 逐条核对上述断言，在"人工确认"列填写 `✅ 已确认` 或 `❌ 有误`
-> - 全部确认后，将 JSON 结果文件中的 `humanConfirmed` 字段设为 `true`
-> - **git hook 会检查此字段**：自审模式下 `humanConfirmed` 不为 `true` 将阻止提交
-> ```
-
-同时在对话中输出报告摘要。
-
-### 8. 【交互引导】根据结果引导下一步
-
-**全部通过**：
-> "✅ 代码符合 spec 规范！建议下一步：
-> - A. 继续实施其他任务
-> - B. 运行 `/opsx:test` 执行测试验证"
-
-**有问题**：
-> " 发现 [N] 个问题需要处理：
-> - 代码有 spec 没有（业务）：[M] 项 → [简要描述]
-> - spec 有代码没有：[M] 项 → [简要描述]
-> - 不一致：[M] 项 → [简要描述]
->
-> 请选择：
-> - A. 逐个修复
-> - B. 忽略警告继续"
-
----
-
-## 判定标准
-
-> 详见 [./reference.md](./reference.md)，包含：问题分类、置信度判定规则、关键性判断标准、维度判定参考、示例。
-
----
-
-## Guardrails
-
-- 本 Skill 是**只读检查**操作，不修改任何代码或 spec 文件
-- 只校验与当前变更相关的代码，不对未变更代码做判断
-- 如果 spec 中没有定义某个接口/规则，不误报为不匹配
-- **纯技术实现不要求 spec 覆盖**：工具方法、防御性代码、日志打印、框架样板、DTO 转换、配置类等不影响业务契约的代码，归类为"代码有 spec 没有（技术）"，不降级置信度
-- 对于 medium 和 low 的情况，必须给出具体的差异说明和改进建议
-- 如果只涉及文档变更（无代码变更），**仍需生成报告文件**（置信度 high，所有维度 pass，summary 全为 0），确保 git hook 能正常通过
-- **响应结构必须逐字段对比**，字段名必须精确匹配，不允许"大致匹配"
-- **前后端字段名必须精确匹配**，不允许语义等价判断（如 `phone` ≠ `username`）
-- **报告范围强制约束**：报告中的所有差异项只能引用 `CHANGED_FILES` 中的文件。若问题代码位于关联文件（`REFERENCE_FILES` 但不在 `CHANGED_FILES` 中），不得作为差异报告，只能放入怀疑清单并提示用户检查该文件是否属于当前变更
-- **多仓库路径约束**：多仓库场景下，报告中的文件路径必须使用**工作区相对路径**（如 `sdd-demo2/src/main/java/.../UserController.java`），而非子仓库内的相对路径
+类型四选一：`代码有 spec 没有（业务）` / `代码有 spec 没有（技术）` / `spec 有代码没有` / `不一致`。
 
 ---
 
 ## 渐进披露
 
-- Read `reference.md` 仅在需要参考判定标准时 — 含问题分类、置信度判定规则、关键性判断标准、维度判定参考、示例。
+- Read `references/reference.md` 仅在遇到置信度摘要未覆盖的边界案例时（如技术实现与业务实现难以区分、关键性拿不准）— **禁止预防性读取**（主文档摘要已覆盖 90% 场景）；含问题分类、置信度判定规则、关键性判断标准、维度判定参考、示例

package/templates/skills/kld-sdd/opsx-consistency-check/{reference.md → references/reference.md}

@@ -107,7 +107,6 @@
 | **业务规则** | 所有规则一致 | 非关键规则不一致 | 规则不一致；代码有**业务逻辑**但 spec 未记录 |
 | **校验规则** | 所有约束一致 | 非关键约束不一致 | 必填字段无校验；代码有**业务校验逻辑**但 spec 未记录 |
 | **错误码** | 所有错误码一致 | 非关键错误码缺失 | 错误码不一致；代码有**业务错误码**但 spec 未记录 |
-| **前后端一致性** | 所有字段匹配 | 非核心字段不匹配 | 核心字段不匹配 |
 
 > **注意**：纯技术实现（工具方法、防御性代码、日志、框架样板、DTO 转换、配置类）不影响维度判定，各维度均为 pass。