kld-sdd 2.6.17 → 2.6.21

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

@@ -1,11 +1,11 @@
 ---
 name: opsx-consistency-check
-description: "Spec 一致性校验 - 验证代码实现与 spec 文档的一致性"
+description: "Spec 双向一致性校验 - 验证代码实现与 spec 文档的双向一致性"
 argument-hint: "[change-name] [file...]"
 license: MIT
 metadata:
   author: sdd-team
-  version: "1.0"
+  version: "2.0"
 allowed-tools:
   - Bash
   - Read
@@ -13,15 +13,19 @@ allowed-tools:
   - Edit
 ---
 
-你是一个 SDD（Specification-Driven Development）Spec 一致性校验专家。激活本技能后，你将对比 spec 文档与代码实现，验证代码是否完全符合 spec 定义。
+你是一个 SDD（Specification-Driven Development）Spec 双向一致性校验专家。激活本技能后，你将对比 spec 文档与代码实现，进行**双向校验**：
+
+- **spec → code**：验证代码是否完全符合 spec 定义（代码是否遗漏了 spec 的要求）
+- **code → spec**：验证 spec 是否准确反映代码实现（spec 是否遗漏了代码的实际行为）
 
 > **对抗性审核原则**
 >
 > 假设 spec 和代码是由其他人（或其他 AI）生成的，你的任务是**严格找出不一致、遗漏和潜在问题**，而不是确认一致性。
 >
 > - 不要假设"既然 spec 这样写了，代码肯定也这样实现了"
+> - 不要假设"既然代码这样写了，spec 肯定也覆盖了"
 > - 不要跳过看似正确但未经逐行比对的细节
-> - 对每个断言都要找到**具体的代码证据**，找不到就标记为 missed
+> - 对每个断言都要找到**具体的证据**（代码行号或 spec 章节），找不到就标记为 missed
 > - 宁可误报（false positive），不可漏报（false negative）
 
 ---
@@ -30,9 +34,9 @@ allowed-tools:
 
 | 维度 | 内容 |
 |------|------|
-| 核心问题 | 代码实现是否符合 spec 定义 |
-| 关键输出 | 结构化校验报告（置信度 + 维度详情 + 怀疑清单 + 建议） |
-| 校验维度 | 接口契约、业务规则、校验规则、错误码、前后端一致性 |
+| 核心问题 | spec 与代码是否双向一致（代码是否符合 spec + spec 是否反映了代码） |
+| 关键输出 | 结构化校验报告（置信度 + 双向维度详情 + 怀疑清单 + 建议） |
+| 校验维度 | 接口契约、业务规则、校验规则、错误码、前后端一致性（双向合并判定） |
 | 上游依赖 | spec.md + 代码文件 |
 | 校验方式 | **纯 AI 语义分析**（零外部依赖） |
 
@@ -50,11 +54,20 @@ allowed-tools:
 
 若用户提供了具体文件路径，只校验这些文件对应的 spec。
 
-若均未提供，列出所有活跃变更供用户选择：
+若均未提供，执行以下流程：
+
+1. 获取活跃变更列表：
 ```bash
 ls openspec/changes/ | grep -v archive
 ```
 
+2. 根据变更数量处理：
+   - **0 个活跃变更** → 提示"无活跃变更，跳过校验"并结束
+   - **1 个活跃变更** → 自动选择该变更，向用户确认后执行
+   - **多个活跃变更** → **必须**使用 `AskUserQuestion` 让用户选择，禁止自动推断
+
+> **⛔ 强制约束**：多 change 场景下，禁止根据当前打开的文件、git diff 或其他上下文自动推断要校验的 change。必须由用户显式选择。
+
 **1.2 确认审核模式**
 
 | 模式 | 参数 | 说明 |
@@ -74,102 +87,49 @@ ls openspec/changes/ | grep -v archive
 
 #### 2.0 多仓库检测（强制前置步骤）
 
-> **背景**：项目可能采用多仓库（multi-repo）结构，即工作区内包含多个独立的 git 仓库（如前端、后端各自独立仓库，spec 文档在根仓库）。单仓库场景下本步骤无副作用。
-
-**检测与采集流程**：
+> 项目可能采用多仓库结构（前端、后端各自独立仓库）。单仓库场景下本步骤无副作用。
 
-**Step A — 发现所有 git 仓库**：
-```bash
-# 1. 获取根仓库的 git top-level
-git rev-parse --show-toplevel
-# 结果记为 ROOT_REPO
-
-# 2. 扫描工作区下所有子目录中的 .git（目录或文件， submodule 的 .git 是文件）
-# 找出所有独立 git 仓库（排除 ROOT_REPO 自身）
-find . -name ".git" -maxdepth 3 -not -path "./.git" | ...
-# 对每个找到的子仓库，用 git rev-parse --show-toplevel 确认其根路径
-```
-
-**Step B — 逐仓库采集变更**：
+**采集流程**：
 
-对**每个** git 仓库（包括根仓库和所有子仓库），分别执行：
-```bash
-# 进入该仓库目录
-cd <repo-root>
-# 获取该仓库的所有变更文件（暂存 + 未暂存）
-git diff HEAD --name-only
-```
+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`
 
-**Step C — 路径归一化**：
-
-将各子仓库的变更文件路径转换为**相对于工作区根目录**的绝对路径或相对路径：
-- 根仓库的文件：路径不变（如 `openspec/changes/...`）
-- 子仓库的文件：拼接子仓库相对路径 + 文件路径（如 `sdd-demo2/src/main/java/.../UserController.java`）
-
-**Step D — 合并变更列表**：
-
-将所有仓库的变更文件合并为统一的 `ALL_CHANGED_FILES` 列表，每个条目格式为：
-```
-<workspace-relative-path>  ←  <repo-root-relative-path>
-```
-例如：
-```
-sdd-demo2/src/main/java/.../UserController.java  ←  sdd-demo2 (repo)
-sdd-demo1/src/api/user.js  ←  sdd-demo1 (repo)
-```
-
-> **单仓库兼容**：若 Step A 未发现任何子仓库，则退化为仅在根仓库执行 `git diff HEAD --name-only`，行为与原有逻辑完全一致。
+> **单仓库兼容**：若不存在 `.sdd-workspace.yaml`，直接对工作区根目录执行 `git diff HEAD --name-only`。
 
 根据校验范围获取变更文件列表：
 
-**若指定了 change-name**：
-```bash
-# 按 Step A-D 采集所有仓库的变更文件，合并为 ALL_CHANGED_FILES
-```
-
-**若未指定变更**：
-```bash
-# 同样按 Step A-D 采集所有仓库的变更文件
-```
-
-**若指定了具体文件**：
-直接使用用户指定的文件列表。
+- **指定了 change-name 或未指定变更**：按上述流程采集所有仓库的变更文件，合并为 `ALL_CHANGED_FILES`
+- **指定了具体文件**：直接使用用户指定的文件列表
 
 #### 2.1 变更文件筛选（强制）
 
 > **核心原则**：变更列表中可能包含多个变更的文件，也可能包含不涉及 spec 一致性校验的文件（如文档、配置、脚本等）。必须筛选出**与当前变更相关且可进行 spec 一致性校验**的文件。
 
-**筛选规则 — 排除以下文件**：
-
-| 排除类型 | 文件模式 | 说明 |
-|---------|---------|------|
-| 非当前变更的代码 | 路径不属于当前 change-name 的 spec 覆盖范围 | 根据 spec 的模块/路径定义判断 |
-| 文档文件 | `*.md`, `*.txt`, `*.rst`（非 spec 文件） | 文档不参与一致性校验 |
-| 配置文件 | `*.yml`, `*.yaml`, `*.properties`, `*.ini`, `*.toml`, `*.json`（非路由/接口定义） | 配置文件通常不涉及 spec 接口契约校验 |
-| 脚本文件 | `*.bat`, `*.sh`, `*.cjs`, `*.mjs`, `*.ps1` | 工具脚本不参与一致性校验 |
-| 类型声明文件 | `*.d.ts`, `*.d.tsx` 等 | TypeScript 类型声明文件不涉及 spec 校验 |
-| 依赖管理 | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `*.lock`, `go.sum`, `Cargo.lock` | 锁文件不参与校验 |
-| 构建产物 | `dist/`, `build/`, `target/`, `out/`, `*.min.js`, `*.min.css` | 编译/打包产物不参与校验 |
-| 测试文件 | `*test.*`, `*spec.*`, `*_test.*`, `__tests__/`, `tests/`, `test/` | 测试代码不参与本次校验（由 opsx-test 负责） |
-| 已删除文件 | git status 为 `deleted` 的文件 | 已删除的文件无法进行校验 |
-| 工具链配置 | `.gitignore`, `.editorconfig`, `.prettierrc`, `.eslintrc.*`, `tsconfig.*`, `*.config.js/ts` | 开发工具配置不涉及业务 spec |
-
-**筛选规则 — 保留以下文件**：
-
-| 保留类型 | 文件模式 | 说明 |
-|---------|---------|------|
-| 业务代码 | 与当前变更 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`（排除 `*.d.ts`） | api, service, store, hook, component, page, controller, model, util |
+| 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 |
-| Go | `*.go`（排除 `*_test.go`） | handler, service, repository, model, controller, api |
-| Rust | `*.rs` | handler, service, model, controller, api |
-| C# | `*.cs` | Controllers, Services, Repositories, Models, DTOs |
 
 **筛选方法**：
 1. 获取变更文件完整列表（按步骤 2.0 的多仓库流程，合并为 `ALL_CHANGED_FILES`）
@@ -186,10 +146,13 @@ sdd-demo1/src/api/user.js  ←  sdd-demo1 (repo)
 
 ### 3. 读取 Spec 文档
 
-按以下顺序读取 spec 内容（排除 archive 和 logs）：
+读取当前变更的 spec 和全局 spec：
 
 ```bash
-find openspec -name "*.md" -not -path "*/archive/*" -not -path "*/logs/*"
+# 变更级 spec
+find openspec/changes/<change-name>/specs -name "spec.md"
+# 全局 spec
+find openspec/specs -name "spec.md"
 ```
 
 重点提取：
@@ -197,36 +160,25 @@ find openspec -name "*.md" -not -path "*/archive/*" -not -path "*/logs/*"
 - 业务规则（条件判断、状态流转、权限控制）
 - 校验规则（字段约束、非空校验、格式要求）
 - 错误码定义（错误码、触发条件、响应格式）
+- 前后端一致性（前端请求/响应字段与后端 DTO 字段的对应关系）
 
 ### 4. 识别项目语言并确定文件范围
 
-**4.1 识别项目语言**
+**4.1 识别项目语言与关联文件扫描**
 
 > **多仓库场景**：每个子仓库可能使用不同的技术栈（如前端 Vue、后端 Java），需分别识别。
 
-| 项目标识 | 语言 | 代码文件 | 路由定义示例 |
-|---------|------|---------|-------------|
-| `pom.xml` / `build.gradle` | Java | `*.java` | `@RequestMapping` / `@PostMapping` |
-| `package.json` | TypeScript/JS | `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `router.get()` / `@Get()` / `app.get()` |
-| `requirements.txt` / `pyproject.toml` | Python | `*.py` | `@app.route()` / `@router.get()` |
-| `go.mod` | Go | `*.go` | `r.GET()` / `e.GET()` |
-| `Cargo.toml` | Rust | `*.rs` | `#[get()]` / `Router::route()` |
-| `*.csproj` / `*.sln` | C# | `*.cs` | `[HttpGet]` / `[HttpPost]` |
+| 项目标识 | 语言 | 代码文件 | 路由定义示例 | 引用语句 |
+|---------|------|---------|-------------|---------|
+| `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/引用关系，找出直接关联的文件：
-
-| 语言 | 代码文件 | 引用语句 |
-|------|---------|---------|
-| Java | `*.java` | `import` |
-| TypeScript/JS | `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `import ... from` |
-| Python | `*.py` | `import` / `from ... import` |
-| Go | `*.go` | `import "..."` |
-| Rust | `*.rs` | `use` / `mod` |
-| C# | `*.cs` | `using` |
+从 `CHANGED_FILES` 中的代码文件出发，根据上表"引用语句"列扫描 import/引用关系，找出直接关联的文件。
 
 **关联文件筛选规则**：
 - 仅包含**直接引用**的文件（一层深度，不递归）
@@ -246,106 +198,131 @@ find openspec -name "*.md" -not -path "*/archive/*" -not -path "*/logs/*"
 > **范围约束（强制）**：
 > - **分析范围**：`REFERENCE_FILES`（变更文件 + 关联文件），用于理解完整上下文
 > - **报告范围**：仅 `CHANGED_FILES`，**报告中的所有差异项只能引用 `CHANGED_FILES` 中的文件**
->
-> **关键规则**：
-> - 若校验发现问题的代码位于 `REFERENCE_FILES` 但**不在** `CHANGED_FILES` 中（即该文件不属于当前变更范围），**不得**将其作为差异项报告
-> - 此类问题应归入"怀疑清单"，标注为"⚠️ 该问题位于非变更文件 `<文件路径>` 中，建议检查该文件是否属于当前变更"
-> - 例如：后端 `AuthController.java` 在 `CHANGED_FILES` 中，但前端 `authService.ts` 不在 `CHANGED_FILES` 中，则前后端不一致的问题**不能**作为差异报告，只能放入怀疑清单
+> - 若问题代码位于 `REFERENCE_FILES` 但不在 `CHANGED_FILES` 中，**不得**作为差异报告，只能放入"怀疑清单"
 
-### 6. 执行五维一致性校验
+### 6. 执行双向一致性校验
 
-基于代码内容，逐行对比 spec 定义进行校验。
+基于代码内容和 spec 定义，进行双向校验。
 
-> **对抗性审核要求**：对每个检查项，必须在代码中找到**具体行号**作为证据。找不到证据的，一律标记为 ❌ missed。不要因为"看起来应该实现了"就标记为 ✅。
+> **对抗性审核要求**：
+> - 对每个检查项，必须找到**具体证据**（代码行号或 spec 章节）。找不到证据的，标记为 ❌ 或 ⚠️。
 
 > **逐字段对比强制约束**：
 > - 响应结构必须**逐字段**对比，不允许"大致匹配"
 > - 字段名必须**精确匹配**（`token` ≠ `accessToken`，`id` ≠ `userId`）
 > - 嵌套结构的每一层都必须校验
-> - 若代码中构造响应的方式是 Map/字典/结构体/序列化对象（如 Java `Map.of()`、Python `dict`、Go `map[string]interface{}`、C# `new {}`），必须提取所有 key 并与 spec 逐一对比
+> - 若代码中构造响应的方式是 Map/字典/结构体/序列化对象（如 Java `Map.of()`、Python `dict`），必须提取所有 key 并与 spec 逐一对比
+
+> **证据标注要求**：每个检查项必须标注具体证据位置（代码文件:行号 或 spec 文件:章节），找不到证据的标记为 ❌。
 
 #### 6.1 后端接口契约校验
 
 对 `CHANGED_FILES` 中的后端代码文件 + 关联 DTO/Model 的数据，进行以下校验：
 
-- [ ] API 路径：路由定义与 spec 定义的路径一致（证据：代码文件:行号）
-- [ ] HTTP 方法：路由声明的 HTTP 方法与 spec 定义的方法匹配（证据：代码文件:行号）
-- [ ] 请求参数：请求体/查询参数的字段名、类型与 spec 定义的参数一致（证据：DTO/Model文件:行号）
-- [ ] 参数约束：字段上的校验注解/装饰器/类型约束与 spec 定义的约束一致（证据：DTO/Model文件:行号）
-- [ ] 响应结构：**逐字段**对比代码中构造的响应与 spec 定义的响应字段（证据：代码文件:行号）
-- [ ] HTTP 状态码：代码中返回的 HTTP 状态码与 spec 定义的状态码一致（证据：代码文件:行号）
-- [ ] 错误码：代码中抛出的业务错误码与 spec 定义一致（证据：代码文件:行号）
+- [ ] API 路径与 spec 一致
+- [ ] HTTP 方法与 spec 一致
+- [ ] 请求参数字段名、类型与 spec 一致
+- [ ] 参数约束（校验注解/装饰器/类型）与 spec 一致
+- [ ] 响应结构**逐字段**与 spec 一致
+- [ ] HTTP 状态码与 spec 一致
+- [ ] 错误码与 spec 一致
+- [ ] 代码中额外的接口/端点已在 spec 中记录
 
 #### 6.2 前端接口契约校验
 
-对 `CHANGED_FILES` 中的前端代码文件（TypeScript/JavaScript/HTML 等），进行以下校验：
+对 `CHANGED_FILES` 中的前端代码文件（TypeScript/JavaScript/Vue 等），进行以下校验：
 
-- [ ] API 路径：HTTP 请求调用的 URL 与 spec 定义的路径一致（证据：代码文件:行号）
-- [ ] HTTP 方法：请求声明的 HTTP 方法与 spec 定义的方法匹配（证据：代码文件:行号）
-- [ ] 请求字段：请求体/查询参数中的字段名与 spec 定义的参数名一致（证据：代码文件:行号）
-- [ ] 校验规则：代码中的字段校验逻辑与 spec 定义的字段约束一致（证据：代码文件:行号）
-- [ ] 存储字段：本地存储操作的 key 与 spec 定义的响应字段对应（证据：代码文件:行号）
-- [ ] 响应处理：代码中读取响应字段的名称与后端实际返回的字段名一致（证据：代码文件:行号）
+- [ ] API 路径与 spec 一致
+- [ ] HTTP 方法与 spec 一致
+- [ ] 请求字段与 spec 一致
+- [ ] 校验规则与 spec 一致
+- [ ] localStorage keys 与 spec 响应字段对应
+- [ ] 响应字段读取与后端返回一致
+- [ ] 代码中额外的前端行为已在 spec 中记录
 
 #### 6.3 业务规则校验
 
-- [ ] spec 中的条件判断在代码中有对应实现（证据：代码文件:行号）
-- [ ] spec 中的状态流转在代码中体现（证据：代码文件:行号）
-- [ ] spec 中的权限要求在代码中有校验（证据：代码文件:行号）
-- [ ] 条件分支逻辑正确性（如 if/else 链的条件判断顺序是否导致不可达分支）
+- [ ] 条件判断与 spec 一致
+- [ ] 状态流转与 spec 一致
+- [ ] 权限要求与 spec 一致
+- [ ] 条件分支逻辑正确性（无不可达分支）
+- [ ] 代码中额外的业务逻辑已在 spec 中记录
 
 #### 6.4 校验规则
 
-- [ ] spec 中的字段约束（长度、格式、范围）在代码中有对应校验（证据：代码文件:行号）
-- [ ] spec 中标记为必填的字段有非空检查（证据：代码文件:行号）
+- [ ] 字段约束（长度、格式、范围）与 spec 一致
+- [ ] 必填字段有非空检查
+- [ ] 代码中额外的校验规则已在 spec 中记录
 
 #### 6.5 错误码校验
 
-- [ ] spec 中定义的错误码在代码中实现（证据：代码文件:行号）
-- [ ] 错误码的触发条件与 spec 描述一致（证据：代码文件:行号）
-- [ ] 错误响应格式与 spec 定义一致（证据：代码文件:行号）
+- [ ] 错误码与 spec 一致
+- [ ] 错误触发条件与 spec 一致
+- [ ] 错误响应格式与 spec 一致
+- [ ] 代码中额外的错误码已在 spec 中记录
 
 #### 6.6 前后端一致性校验
 
 对 `CHANGED_FILES` 中同时包含前端和后端文件时，进行跨文件对比：
 
-> **多仓库场景**：前端和后端可能分别位于不同的子仓库（如 `sdd-demo1/` 和 `sdd-demo2/`），但只要它们的变更文件都在 `CHANGED_FILES` 中，就可以进行跨文件对比。
-
 - [ ] 前端请求字段 vs 后端 DTO 字段：字段名必须精确匹配（如前端 `phone` vs 后端 `username` 为不匹配）
 - [ ] 前端响应字段读取 vs 后端响应构造：字段名必须精确匹配
 - [ ] 前端校验规则 vs 后端校验规则：同一字段的校验约束必须一致
 
-> **强制约束**：
-> - 若跨文件校验涉及的某个文件不在 `CHANGED_FILES` 中，**不得**将其作为差异项报告
-> - 此类问题应归入"怀疑清单"，标注为"⚠️ 该问题涉及非变更文件 `<文件路径>`，建议检查该文件是否属于当前变更"
-> - 例如：后端 Controller 在 `CHANGED_FILES` 中，但前端 service 不在，则前后端字段不一致的问题不能报告为差异
+> **强制约束**：若跨文件校验涉及的某个文件不在 `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 文件，按审核模式区分文件名：
@@ -374,6 +351,7 @@ JSON 文件结构（必须严格遵循）：
   "confidence": "high | medium | low",
   "overallResult": "pass | warning | fail",
   "reviewMode": "independent-review | self-review",
+  "humanConfirmed": false,
   "generatedAt": "<YYYY-MM-DD HH:mm:ss>",
   "repositories": [
     { "name": "<仓库名或路径>", "path": "<仓库相对路径>", "changedFiles": 0 }
@@ -389,28 +367,33 @@ JSON 文件结构（必须严格遵循）：
     "totalChecks": 0,
     "passed": 0,
     "failed": 0,
-    "warnings": 0
+    "warnings": 0,
+    "undocumentedBusiness": 0,
+    "undocumentedTechnical": 0,
+    "specMissing": 0,
+    "inconsistent": 0
   }
 }
 ```
 
 **字段说明**：
-- `confidence`：整体置信度，必须为 `high` / `medium` / `low` 之一（与 md 报告中的置信度一致）
-- `overallResult`：总体结果，`pass`（high 置信度）/ `warning`（medium 置信度）/ `fail`（low 置信度）
-- `reviewMode`：审核模式，`independent-review` 或 `self-review`
-- `generatedAt`：生成时间，格式 `YYYY-MM-DD HH:mm:ss`
-- `repositories`：参与校验的仓库列表（多仓库场景），每项包含仓库名、相对路径、变更文件数；单仓库场景仅包含根仓库
-- `dimensions`：各维度校验结果
-- `summary`：校验统计摘要
+- `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`）
 
-> **强制约束**：JSON 文件必须与 md 报告同时生成。缺少 JSON 文件时，git hook 将输出警告但仍放行（向后兼容）。
+> **强制约束**：JSON 文件必须与 md 报告同时生成，供 git hook 读取置信度进行门禁判定。
 
 报告模板：
 
 > **时间格式强制约束**：`生成时间` 必须通过时间工具（如 MCP `get_current_time` 或系统命令 `date`）获取当前精确时间，格式为 `YYYY-MM-DD HH:mm:ss`。**禁止**仅填写日期而省略时分秒。
 
 ```markdown
-# Spec 一致性校验报告
+# Spec 双向一致性校验报告
 
 **变更名称**：<change-name>
 **生成时间**：<YYYY-MM-DD HH:mm:ss>（必须通过时间工具获取，禁止仅填日期）
@@ -418,45 +401,33 @@ JSON 文件结构（必须严格遵循）：
 **仓库结构**：<单仓库 / 多仓库（列出各仓库路径）>
 **校验范围**：<diff 涉及的文件列表，多仓库场景下标注各文件所属仓库>
 
-## 后端接口契约
-
-| 接口 | 路径 | 方法 | 请求参数 | 响应类型 | 响应字段 | HttpStatus |
-|------|------|------|---------|---------|---------|------------|
-| [接口名] | [路径] | [方法] | [DTO名] | [类型] | [字段列表] | [状态码] |
-
-### 后端契约校验
-
-| 检查项 | 代码实际值 | Spec 期望值 | 状态 |
-|--------|-----------|------------|------|
-| [检查项] | [值] | [值] | ✅/❌ |
-
-## 前端接口契约
-
-| 函数 | URL | 方法 | body 字段 | 正则表达式 | localStorage keys |
-|------|-----|------|----------|-----------|------------------|
-| [函数名] | [URL] | [方法] | [字段列表] | [正则] | [key列表] |
-
-### 前端契约校验
-
-| 检查项 | 代码实际值 | Spec 期望值 | 状态 |
-|--------|-----------|------------|------|
-| [检查项] | [值] | [值] | ✅/❌ |
-
-## DTO 字段约束
-
-| DTO | 字段 | 类型 | 约束 |
-|-----|------|------|------|
-| [DTO名] | [字段名] | [类型] | [注解/约束] |
-
 ## 校验结果
 
 | 维度 | 状态 | 详情 | 证据 |
 |------|------|------|------|
-| 接口契约 | ✅/⚠️/❌ | [具体问题] | [代码文件:行号] |
-| 业务规则 | ✅/⚠️/❌ | [具体问题] | [代码文件:行号] |
-| 校验规则 | ✅/⚠️/❌ | [具体问题] | [代码文件:行号] |
-| 错误码 | ✅/⚠️/❌ | [具体问题] | [代码文件:行号] |
-| 前后端一致性 | ✅/⚠️/❌ | [具体问题] | [代码文件:行号] |
+| 接口契约 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
+| 业务规则 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
+| 校验规则 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
+| 错误码 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
+| 前后端一致性 | ✅/⚠️/❌ | [具体问题] | [文件:行号/章节] |
+
+> 置信度为 medium 或 low 时，在此说明原因（如：接口契约=warning，因缺少辅助接口 /api/export 的 spec 记录）
+
+### 差异与怀疑清单
+
+> 以下列出代码与 spec 之间的所有差异，以及校验过程中发现的潜在风险。
+> **类型**必须使用判定标准中定义的四类问题分类（见"一、问题分类"）。
+
+| # | 类型 | 风险等级 | 位置 | 描述 | 建议操作 |
+|---|------|---------|------|------|---------|
+| 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
 
@@ -481,18 +452,10 @@ JSON 文件结构（必须严格遵循）：
 
 **校验结果**：✅ 符合 / ❌ 不符合
 
-## 怀疑清单
-
-> 以下列出校验过程中发现的潜在风险，需要人工确认或进一步验证。
-
-| # | 怀疑类型 | 风险等级 | 描述 | 建议验证方式 |
-|---|---------|---------|------|-------------|
-| 1 | Spec 歧义 | P2 | [描述] | [建议] |
-| 2 | 隐含假设 | P1 | [描述] | [建议] |
-
 ## 建议操作
 
 - [具体修复建议及对应文件:行号]
+- [spec 补充建议及对应章节]
 ```
 
 > **注意**：若使用自审模式（`--mode=self-review`），报告需额外包含"人工确认"章节：
@@ -508,6 +471,8 @@ JSON 文件结构（必须严格遵循）：
 >
 > **人工确认方式**：
 > - 逐条核对上述断言，在"人工确认"列填写 `✅ 已确认` 或 `❌ 有误`
+> - 全部确认后，将 JSON 结果文件中的 `humanConfirmed` 字段设为 `true`
+> - **git hook 会检查此字段**：自审模式下 `humanConfirmed` 不为 `true` 将阻止提交
 > ```
 
 同时在对话中输出报告摘要。
@@ -520,9 +485,10 @@ JSON 文件结构（必须严格遵循）：
 > - B. 运行 `/opsx:test` 执行测试验证"
 
 **有问题**：
-> "❌ 发现 [N] 个不一致项需要修复：
-> - 问题 1：[描述] → 建议修改 [文件:行号]
-> - 问题 2：[描述] → 建议修改 [文件:行号]
+> " 发现 [N] 个问题需要处理：
+> - 代码有 spec 没有（业务）：[M] 项 → [简要描述]
+> - spec 有代码没有：[M] 项 → [简要描述]
+> - 不一致：[M] 项 → [简要描述]
 >
 > 请选择：
 > - A. 逐个修复
@@ -532,50 +498,7 @@ JSON 文件结构（必须严格遵循）：
 
 ## 判定标准
 
-### 一、维度内部判定
-
-| 维度 | pass | warning | fail |
-|------|------|---------|------|
-| **接口契约** | 所有检查项 ✅ | 有 ⚠️ 但无 ❌ | 有任何 ❌ |
-| **业务规则** | 所有规则实现 | 非关键规则缺失 | 关键规则缺失 |
-| **校验规则** | 所有约束实现 | 非关键约束缺失 | 必填字段无校验 |
-| **错误码** | 所有错误码实现 | 非关键错误码缺失 | 关键错误码缺失 |
-| **前后端一致性** | 所有字段匹配 | 部分字段不匹配 | 核心字段不匹配 |
-
-### 二、整体置信度判定
-
-```
-low（拒绝）：
-  - 接口契约 = fail
-  - 或 业务规则 = fail（关键规则缺失）
-  - 或 校验规则 = fail（必填字段无校验）
-
-medium（警告）：
-  - 接口契约 ≠ fail
-  - 且 任一维度 = warning 或 fail（非关键）
-
-high（通过）：
-  - 所有维度 = pass
-```
-
-### 三、关键 vs 非关键 定义
-
-| 维度 | 关键（→ low） | 非关键（→ medium） |
-|------|--------------|-------------------|
-| **业务规则** | 认证、授权、加密、核心业务流程 | 日志记录、审计、性能优化 |
-| **校验规则** | 必填字段、安全相关约束（如密码强度） | 格式美化、长度限制 |
-| **错误码** | 影响前端决策的错误码（如 401、403） | 提示性错误码（如参数格式提示） |
-| **前后端一致性** | 核心字段（token、userId、username） | 次要字段（createdAt 格式、可选字段） |
-
-### 四、示例
-
-| 场景 | 各维度状态 | 置信度 | 原因 |
-|------|-----------|--------|------|
-| 响应字段名错误 | 接口契约=fail | **low** | 接口契约一票否决 |
-| 缺少密码复杂度校验 | 校验规则=fail | **low** | 安全相关约束缺失 |
-| 缺少某个提示性错误码 | 错误码=warning | **medium** | 非关键错误码缺失 |
-| 前端字段名与后端不一致 | 前后端一致性=warning | **medium** | 非核心字段不匹配 |
-| 所有维度完美匹配 | 全部=pass | **high** | 完全符合 spec |
+> 详见 [./reference.md](./reference.md)，包含：问题分类、置信度判定规则、关键性判断标准、维度判定参考、示例。
 
 ---
 
@@ -584,9 +507,16 @@ high（通过）：
 - 本 Skill 是**只读检查**操作，不修改任何代码或 spec 文件
 - 只校验与当前变更相关的代码，不对未变更代码做判断
 - 如果 spec 中没有定义某个接口/规则，不误报为不匹配
+- **纯技术实现不要求 spec 覆盖**：工具方法、防御性代码、日志打印、框架样板、DTO 转换、配置类等不影响业务契约的代码，归类为"代码有 spec 没有（技术）"，不降级置信度
 - 对于 medium 和 low 的情况，必须给出具体的差异说明和改进建议
-- 如果只涉及文档变更（无代码变更），直接返回 high
+- 如果只涉及文档变更（无代码变更），**仍需生成报告文件**（置信度 high，所有维度 pass，summary 全为 0），确保 git hook 能正常通过
 - **响应结构必须逐字段对比**，字段名必须精确匹配，不允许"大致匹配"
 - **前后端字段名必须精确匹配**，不允许语义等价判断（如 `phone` ≠ `username`）
 - **报告范围强制约束**：报告中的所有差异项只能引用 `CHANGED_FILES` 中的文件。若问题代码位于关联文件（`REFERENCE_FILES` 但不在 `CHANGED_FILES` 中），不得作为差异报告，只能放入怀疑清单并提示用户检查该文件是否属于当前变更
 - **多仓库路径约束**：多仓库场景下，报告中的文件路径必须使用**工作区相对路径**（如 `sdd-demo2/src/main/java/.../UserController.java`），而非子仓库内的相对路径
+
+---
+
+## 渐进披露
+
+- Read `reference.md` 仅在需要参考判定标准时 — 含问题分类、置信度判定规则、关键性判断标准、维度判定参考、示例。