dic-workflow-kit 1.1.2 → 1.1.4

package/README.zh-CN.md

@@ -1,76 +1,168 @@
-# 设计—实现一致性 Workflow Kit
+# 契衡 QIHENG — 设计完整性控制平面
 
-版本：`1.1.2`
+版本：`1.1.4`
 
-[更新日志](CHANGELOG.md)
+[英文版](README.md) · [执行契约](INSTRUCTION.md) · [本体模型](docs/ONTOLOGY.md) · [常见问题](docs/FAQ.md) · [更新日志](CHANGELOG.md)
 
-Design-Implementation Consistency Workflow Kit，简称 DIC Workflow Kit，是一套可移植的智能体工作流包，用于检查和修复“代码实现是否符合设计意图”。
+**让每一项设计承诺，都在代码中得到证明。**
 
-它面向 OpenSpec、设计文档、API 契约、Schema 或产品需求先行的项目。工作流从权威设计源出发，建立项目画像，映射设计与实现，识别缺口，执行小步修复，运行项目声明的验证命令，并输出可审计的一致性证据。
+契衡 QIHENG 是一套可移植的设计完整性控制平面，用于证明代码仍然符合
+权威设计意图。它支持 Codex、Claude Code、OpenCode、MiMo Code 和 BitFun，并可
+将 OpenSpec、设计文档、接口契约、数据结构、产品需求或行为场景文件作为设计源。
 
-> 项目的差异不在 Agent 数量。DIC Workflow Kit 通过设计意图、类型化交接、项目画像、验证证据和残余风险报告，证明实现仍然符合设计契约。
+## 它与普通多智能体流程的区别
+
+- **可执行交付保障框架，而不是检查清单。** 候选版本身份凭证、类型化门禁图、依赖闭合、显式适用性和内容寻址证据共同计算交付就绪度。
+- **共享本体，而不是互相隔离的智能体总结。** 需求、场景、实现单元、差距、修复、
+  验证和证据进入同一张可追溯语义图。
+- **受治理的修改。** 角色受限的动作和类型化补丁先进入 SHA-256 链式台账，
+  再通过协调操作改变本体状态。
+- **失败即关闭的证据。** 设计源、实现和验证证据都做内容寻址；文件变化或丢失会阻断通过结论。
+- **验证因果性。** 绿色结果绑定本次实际消费的设计源与实现单元
+  哈希，旧日志不能批准新代码。
+- **可移植终态证明。** 报告和签署凭证将结论绑定到快照修订、台账、
+  制品、不变量和残余风险。
+- **领导视角与审计证据同源。** 高层交付保障驾驶舱直接从机器状态生成交付决定、保障覆盖率、设计交付数字主线、风险阻断项和可下钻证据编号。
+
+因此，项目的差异不在智能体数量，而在设计、实现、验证和最终结论之间存在一条
+受治理、可检查、可失效的证据链。
+
+QIHENG 按证据职责组织角色，而不是追求智能体数量：
+
+- **观测域**：确认权威源、义务、语义冲突和影响范围。
+- **构建域**：检查、修复并验证有来源依据的一致性差距。
+- **裁决域**：挑战高风险主张、审计证据新鲜度，并作出绑定候选版本的一致性与准入决定。
+
+编排器依据当前风险选择最小适用评审组。没有独立假设、产物、下游消费者和决定权的新增智能体，不会增加可信度。
+
+## 三分钟快速开始
+
+需要 Node.js 20 或更高版本。
+
+```text
+npx dic-workflow-kit@1.1.4 install
+```
+
+为保持兼容，已发布的 npm 包名继续使用 `dic-workflow-kit` 和
+`@tonyclaw/dic-workflow-kit`。全局安装后同时提供首选命令 `qiheng` 和兼容命令
+`dic-workflow-kit`。
+
+在目标仓库中重启编码智能体，然后输入：
+
+```text
+使用 QIHENG 和 quality-review-orchestrator 审计本次交付。
+以导入的规格或变更为入口，实现前检查规格和适用设计门禁；
+实现后检查并修复设计—实现不一致，使每次修复影响的旧门禁失效并重跑；
+最后对冻结候选版本执行提交前门禁。分别给出一致性、质量、准入和残余风险。
+除非我明确批准，否则不要修改代码。
+```
+
+优先查看 `reports/final-consistency-report.md`、`reports/FINAL_RESULT.json`
+和 `reports/ontology-report.md`。终态只使用 `PASS`、`PARTIAL`、`BLOCKED`
+或 `FAIL`；测试变绿本身不等于通过。
+
+项目画像生成后，启动可执行交付保障框架：
+
+```text
+qiheng harness-init --root .
+qiheng harness-check --root . --json
+qiheng harness-report --root .
+```
+
+`reports/harness-report.md` 是面向领导的高层交付保障驾驶舱：用一页高密度视图展示交付决定、候选版本身份凭证、保障覆盖率、设计交付数字主线、门禁矩阵和精确阻断项。
+
+## 文档导航
+
+| 文档 | 用途 |
+| --- | --- |
+| [执行契约](INSTRUCTION.md) | 完整工作流、证据、交接和终态规则 |
+| [本体模型](docs/ONTOLOGY.md) | 对象、关系、动作、台账、门禁与签署凭证 |
+| [交付保障执行框架](docs/HARNESS.md) | 候选版本身份凭证、可执行门禁图、设计交付数字主线、证据记录和高层驾驶舱 |
+| [常见问题](docs/FAQ.md) | 多智能体通信、知识挂载、行为驱动开发和答辩问题 |
+| [代码证据引导](docs/答辩引导-项目特点与代码证据.md) | 将项目特点定位到实现证据 |
+| [发布指南](docs/RELEASING.md) | 维护者使用的双 npm 包发布流程 |
+| [更新日志](CHANGELOG.md) | 版本历史 |
 
 ## 通过 npm 安装
 
-npm 包完整包含 7 个 Skills 和 9 个 Subagents，并支持 Codex、Claude Code、OpenCode、MiMo Code 和 BitFun 的原生目录结构。
+`dic-workflow-kit` 与 `@tonyclaw/dic-workflow-kit` 始终发布相同版本和相同
+运行时载荷。npm 包完整包含 19 个技能和 13 个子智能体，并支持 Codex、
+Claude Code、OpenCode、MiMo Code 和 BitFun 的原生目录结构。
 
 Codex 仍是默认宿主，原命令保持兼容：
 
 ```text
-npx dic-workflow-kit@1.1.2 install
+npx dic-workflow-kit@1.1.4 install
 ```
 
 安装到其他宿主时显式指定 `--host`：
 
 ```text
-npx dic-workflow-kit@1.1.2 install --host claude-code
-npx dic-workflow-kit@1.1.2 install --host opencode
-npx dic-workflow-kit@1.1.2 install --host mimo-code
-npx dic-workflow-kit@1.1.2 install --host bitfun
+npx dic-workflow-kit@1.1.4 install --host claude-code
+npx dic-workflow-kit@1.1.4 install --host opencode
+npx dic-workflow-kit@1.1.4 install --host mimo-code
+npx dic-workflow-kit@1.1.4 install --host bitfun
 ```
 
 默认是用户级安装；若只希望当前仓库使用，则增加 `--scope project`：
 
 ```text
-npx dic-workflow-kit@1.1.2 install --host claude-code --scope project
-npx dic-workflow-kit@1.1.2 install --host opencode --scope project
-npx dic-workflow-kit@1.1.2 install --host mimo-code --scope project
-npx dic-workflow-kit@1.1.2 install --host bitfun --scope project
+npx dic-workflow-kit@1.1.4 install --host claude-code --scope project
+npx dic-workflow-kit@1.1.4 install --host opencode --scope project
+npx dic-workflow-kit@1.1.4 install --host mimo-code --scope project
+npx dic-workflow-kit@1.1.4 install --host bitfun --scope project
 ```
 
 | 宿主 | 用户级目录 | 项目级目录 |
 | --- | --- | --- |
-| Codex | `~/.agents/plugins/plugins/dic-workflow-kit`，并注册 marketplace | 当前插件安装器不提供项目级模式 |
+| Codex | `~/.agents/plugins/plugins/dic-workflow-kit`，并注册插件市场 | 当前插件安装器不提供项目级模式 |
 | Claude Code | `~/.claude/{skills,agents}` | `.claude/{skills,agents}` |
 | OpenCode | `~/.config/opencode/{skills,agents}` | `.opencode/{skills,agents}` |
 | MiMo Code | 平台配置根目录下的 `mimocode/{skills,agents}` | `.mimocode/{skills,agents}` |
 | BitFun | 平台原生的 BitFun 数据/配置目录 | `.bitfun/{skills,agents}` |
 
-Windows 上 MiMo Code 的用户级根目录为 `%LOCALAPPDATA%\mimocode`；适用时也会读取 `MIMOCODE_HOME` 和 `XDG_CONFIG_HOME`。BitFun 的用户级 Skills 安装到平台数据目录下的 `BitFun/skills`，Subagents 安装到 BitFun 配置根目录下的 `bitfun/agents`；项目级安装统一使用 `.bitfun`。安装器以仓库中的 `agents/` 为唯一来源，并按宿主转换 Subagent frontmatter，避免维护多套重复内容。
+Windows 上 MiMo Code 的用户级根目录为 `%LOCALAPPDATA%\mimocode`；适用时也会读取 `MIMOCODE_HOME` 和 `XDG_CONFIG_HOME`。BitFun 的用户级技能安装到平台数据目录下的 `BitFun/skills`，子智能体安装到 BitFun 配置根目录下的 `bitfun/agents`；项目级安装统一使用 `.bitfun`。安装器以仓库中的 `agents/` 为唯一来源，并按宿主转换子智能体元数据，避免维护多套重复内容。
 
-对于 BitFun，安装器会生成其原生 custom-agent schema。检查和规划角色保持只读，只有 `code-repairer` 与 `validation-runner` 获得职责所需的写入和命令工具。
+对于 BitFun，安装器会生成其原生自定义智能体结构。检查和规划角色保持只读，只有 `code-repairer` 与 `validation-runner` 获得职责所需的写入和命令工具。
 
-也可以先全局安装 CLI：
+也可以先全局安装命令行工具：
 
 ```text
-npm install --global @tonyclaw/dic-workflow-kit@1.1.2
-dic-workflow-kit install --host opencode
+npm install --global @tonyclaw/dic-workflow-kit@1.1.4
+qiheng install --host opencode
 ```
 
-也可以直接从仓库安装同一个 CLI：
+也可以直接从仓库安装同一个命令行工具：
 
 ```text
 npm install --global git+ssh://git@gitcode.com/TonyClaw/DICWorkflowKit.git
-dic-workflow-kit install
+qiheng install
+```
+
+使用 `--dry-run` 预演目标目录，使用 `--install-root <path>` 指定隔离的宿主根目录；Codex 仍兼容 `--marketplace-root <path>`。首次创建技能或智能体目录后，请重启或重新加载对应编码智能体会话。
+
+### 检查、升级与卸载
+
+每次成功安装都会写入 `.dic-workflow-kit-install.json`，记录包版本、宿主目录、受管理文件及其 SHA-256。使用 `doctor` 检查是否存在文件缺失或被修改：
+
+```text
+qiheng doctor --host bitfun --scope project
+qiheng doctor --host opencode
+```
+
+只移除当前安装清单管理的文件：
+
+```text
+qiheng uninstall --host bitfun --scope project
 ```
 
-使用 `--dry-run` 预演目标目录，使用 `--install-root <path>` 指定隔离的宿主根目录；Codex 仍兼容 `--marketplace-root <path>`。首次创建 Skills 或 agents 目录后，请重启或重新加载对应 Coding Agent 会话。
+安装器不会默认覆盖未受管理或已被本地修改的文件；卸载器也不会默认删除已修改的受管理文件。请先检查报告中的路径，仅在确认这些修改可以丢弃时使用 `--force`。`install`、`doctor` 和 `uninstall` 都支持 `--json`，可供持续集成或自动化脚本消费。
 
 ## 用户如何使用
 
-### 1. 在项目根目录启动 Coding Agent
+### 1. 在项目根目录启动编码智能体
 
-安装完成后，进入需要检查的代码仓库，重新启动 Codex、Claude Code、OpenCode、MiMo Code 或 BitFun。第一次安装新 Skills/agents 目录时，已有会话可能无法立即发现它们。
+安装完成后，进入需要检查的代码仓库，重新启动 Codex、Claude Code、OpenCode、MiMo Code 或 BitFun。第一次安装新的技能或智能体目录时，已有会话可能无法立即发现它们。
 
 ```text
 cd /path/to/your-project
@@ -81,56 +173,56 @@ cd /path/to/your-project
 下面这条提示词适用于五种宿主：
 
 ```text
-使用 DIC Workflow Kit 检查当前项目的设计—实现一致性。
-先识别权威设计源和受保护路径，生成项目画像；
-然后建立需求义务、检查实现缺口，只对有设计证据的问题规划修复；
-运行项目声明的验证命令，最后输出一致性结论和残余风险。
+使用 QIHENG 和 quality-review-orchestrator 检查当前项目。
+以导入的规格或变更为入口，按风险选择门禁；实现前完成设计检查，
+实现后只修复有来源证据的一致性缺口，使受影响门禁失效并重跑；
+最后对冻结候选版本执行提交前准入。分别输出一致性、质量、准入和残余风险。
 ```
 
 如果只希望审计、不允许修改代码：
 
 ```text
-使用 DIC Workflow Kit 审计当前项目，但不要修改任何文件。
+使用 QIHENG 审计当前项目，但不要修改任何文件。
 输出设计义务、实现缺口、证据位置、建议修复和残余风险。
 ```
 
 如果希望检查并修复：
 
 ```text
-使用 DIC Workflow Kit 检查并修复当前项目。
+使用 QIHENG 检查并修复当前项目。
 仅修复能够追溯到权威设计源的缺口；每次修改后执行相关验证，
 验证失败时停止扩散修改并记录阻塞原因。
 ```
 
-### 3. 检查一个 OpenSpec Change
+### 3. 检查一个 OpenSpec 变更
 
-明确给出 Change ID，可以减少搜索范围并避免把历史 Change 当成当前事实：
+明确给出变更编号，可以减少搜索范围并避免把历史变更当成当前事实：
 
 ```text
-使用 DIC Workflow Kit 检查 OpenSpec Change
+使用 QIHENG 检查 OpenSpec 变更
 2026-06-09-add-ts-local-skill-source。
-以该 Change 的 proposal、design、tasks 和增量 specs 为入口，
-同时核对当前稳定 specs、实现和测试，输出义务矩阵、实现缺口和验证结论。
+以该变更的提案、设计、任务和增量规格为入口，
+同时核对当前稳定规格、实现和测试，输出义务矩阵、实现缺口和验证结论。
 ```
 
-如果 Change 已归档，工作流会将归档内容作为历史上下文，并以当前已经提升的稳定 Spec 为权威基线。
+如果变更已归档，工作流会将归档内容作为历史上下文，并以当前已经提升的稳定规格为权威基线。
 
-### 4. 显式调用核心 Skill
+### 4. 显式调用核心技能
 
-支持斜杠 Skill 的宿主可以先输入：
+支持斜杠技能命令的宿主可以先输入：
 
 ```text
 /workflow-core
 ```
 
-也可以在提示词中直接写出需要使用的 Skill：
+也可以在提示词中直接写出需要使用的技能：
 
 ```text
 使用 workflow-core、workflow-intake、workflow-profile 和
 knowledge-openspec 检查当前 OpenSpec 变更。
 ```
 
-不需要手工逐个启动 9 个 Subagents。主 Agent 应按照证据依赖关系选择角色，并保证每个委派都有被下游消费的产物。
+不需要手工逐个启动 13 个子智能体。主智能体应按照证据依赖关系选择角色，并保证每个委派都有被下游消费的产物。
 
 ### 5. 查看结果
 
@@ -142,47 +234,35 @@ knowledge-openspec 检查当前 OpenSpec 变更。
 | `reports/contract-obligations.md` | 人可读的设计义务与来源 |
 | `reports/implementation-gaps.md` | 已确认的实现缺口 |
 | `reports/repair-plan.md` | 带来源锚点和停止条件的修复计划 |
+| `reports/quality/` | 适用性计划、门禁运行历史、失效原因和候选版本绑定决定 |
 | `reports/final-consistency-report.md` | 最终一致性结论与残余风险 |
 | `reports/FINAL_RESULT.json` | 机器可读的最终状态 |
-| `logs/trace/` | Intake、委派、修改和验证证据 |
+| `logs/trace/` | 入口识别、委派、修改和验证证据 |
 
-最终状态只使用 `PASS`、`PARTIAL`、`BLOCKED` 或 `FAIL`。`PASS` 表示证据链和验证均满足要求，并不只是“测试刚好通过”。
+设计一致性终态只使用 `PASS`、`PARTIAL`、`BLOCKED` 或 `FAIL`，并与专项质量状态和
+仓库准入状态分开读取。设计一致性通过表示证据链成立，不只是“测试刚好通过”，
+也不代表候选版本自动获得准入。
 
 ### 常见问题
 
-- **找不到 Skill/Subagent**：重启 Coding Agent，并使用 `--dry-run` 检查安装目标。
-- **只想当前仓库使用**：Claude Code、OpenCode、MiMo Code、BitFun 安装时增加 `--scope project`。
-- **项目没有 OpenSpec**：仍可使用设计文档、API、Schema、README 或产品需求作为权威设计源。
+- **找不到技能或子智能体**：重启编码智能体，并使用 `--dry-run` 检查安装目标。
+- **检查安装完整性**：使用与安装时相同的宿主、安装范围和根目录参数运行 `doctor`。
+- **安装提示冲突**：先检查报告中的文件，保存或重命名用户内容后再考虑 `--force`。
+- **卸载拒绝删除修改文件**：可以保留当前安装；只有备份修改后才应使用 `--force`。
+- **只想当前仓库使用**：Claude Code、OpenCode、MiMo Code、BitFun 安装时增加项目范围参数 `--scope project`。
+- **项目没有 OpenSpec**：仍可使用设计文档、接口说明、数据结构、项目说明或产品需求作为权威设计源。
 - **缺少验证工具**：记录缺失的命令和环境原因，最终状态应为 `BLOCKED` 或 `PARTIAL`，不要伪造成功。
 - **测试通过是否等于一致**：不等于。还必须确认需求、分支、状态迁移、副作用及集成流程符合设计。
 
-### 双 npm 包发布
-
-每次发布必须以相同版本、相同内容发布两个包名：
-
-- `@tonyclaw/dic-workflow-kit`
-- `dic-workflow-kit`
-
-`package.json` 是唯一版本源。版本脚本会同步 Codex 插件清单、工作流脚本、全部 Skills、全部 Subagents 和中英文 README：
-
-```text
-npm run release:set-version -- 1.1.2
-npm run release:plan
-npm run release:dual:dry-run
-npm run release:dual
-```
-
-npm 不支持两个包名之间的原子事务，因此发布协调器采用可收敛策略：先完成全部本地检查，再从临时 staging 分别发布两个包；某一侧已经存在相同版本时自动跳过，部分失败后重复运行只会补发缺失的一侧。
-
-答辩时如何讲解项目特点并定位代码证据，请参考[《答辩引导：项目特点与代码证据》](docs/答辩引导-项目特点与代码证据.md)。
+维护者请参考[双 npm 包发布指南](docs/RELEASING.md)。
 
 ## 为什么需要它
 
-Coding Agent 很擅长修改代码，但容易围绕局部报错、公开样例或最近一次失败进行优化。对于设计先行的项目，更重要的问题是：
+编码智能体很擅长修改代码，但容易围绕局部报错、公开样例或最近一次失败进行优化。对于设计先行的项目，更重要的问题是：
 
 > 当前实现是否仍然满足已确认的设计契约？
 
-DIC Workflow Kit 将这个问题转换为一条可重复执行的证据链：
+QIHENG 将这个问题转换为一条可重复执行的证据链：
 
 1. 定位权威设计源。
 2. 生成项目画像。
@@ -197,81 +277,206 @@ DIC Workflow Kit 将这个问题转换为一条可重复执行的证据链：
 | 路径 | 作用 |
 | --- | --- |
 | `INSTRUCTION.md` | 通用执行契约，定义设计—实现一致性工作流。 |
-| `skills/` | 工作流控制 Skill 和可插拔知识包。 |
-| `agents/` | 按阶段工作的 Subagent，负责生产和消费证据。 |
+| `skills/` | 工作流控制技能和可插拔知识包。 |
+| `agents/` | 按阶段工作的子智能体，负责生产和消费证据。 |
 | `adapters/` | OpenSpec、通用仓库、比赛环境等适配层。 |
-| `schemas/` | 项目画像、Agent 交接和最终结果的 JSON Schema。 |
+| `runtime/` | 本体计算、动作、台账、完整性检查、报告和签署凭证的源码实现。 |
+| `schemas/` | 项目画像、本体状态、动作、交接、签署凭证和终态结果的数据结构约束。 |
 | `scripts/` | 仅依赖 Python 标准库的辅助脚本。 |
+| `docs/` | 本体参考、常见问题、发布指南、演示文稿和代码证据引导。 |
 | `examples/` | 不同项目形态的使用示例。 |
 
-## Skills：按工作流加载顺序
+## 技能：按首次介入点索引
 
-下表按照 Skill 第一次介入默认流程的位置排列。Knowledge Skill 是条件加载项：只有项目证据或当前阶段需要时才挂载。
+下表只是索引，不是一条必须串行执行的流水线。技能按最早介入点排列；
+知识技能和专项质量技能按风险加载，可以多次执行；其输入或候选版本
+发生变化时，原决定会失效。
 
-| 顺序 | Skill | 类型 | 介入阶段 | 主要作用 |
+| 顺序 | 技能 | 类型 | 介入阶段 | 主要作用 |
 | --- | --- | --- | --- | --- |
-| 00 | `workflow-core` | 工作流机制 | 全流程 | 定义事实源优先级、证据规则、Handoff、最终状态和产物契约。 |
-| 01 | `workflow-intake` | 工作流方法 | Subagent 启动前 | 识别设计源、实现目录、测试目录、保护路径、验证命令和 Adapter 线索。 |
-| 02 | `workflow-profile` | 工作流方法 | Subagent 启动前 | 将 Intake 证据规范化为所有下游角色共同消费的项目画像。 |
-| 03 | `knowledge-openspec` | 知识包 | 读取设计源时；检测到 OpenSpec 才加载 | 理解 proposal、design、spec、scenario、task、active change 和 archived capability。 |
-| 04 | `knowledge-bdd` | 知识包 | 契约确认后；需要行为覆盖时 | 从已确认设计规则和流程契约生成 Given–When–Then 验收场景。 |
-| 05 | `workflow-repair` | 工作流方法 | 审计、修复与最终审核阶段 | 控制有来源的检查、修复计划、最小变更、验证循环和证据更新。 |
-| 06 | `knowledge-repair-distill` | 知识包 | 修复规划或模型跑偏时 | 提供缺口分类、收敛策略、模型引导提示和验证门槛。 |
+| 00 | `quality-review-orchestrator` | 质量控制 | 导入规格到提交前准入 | 维护适用性计划、门禁依赖、失效与重跑，并保留不同层次的交付结论。 |
+| 01 | `workflow-core` | 工作流机制 | 设计一致性全流程 | 定义事实源优先级、本体、证据规则、交接、终态和产物契约。 |
+| 02 | `workflow-harness` | 可执行控制平面 | 项目画像生成后到仓库准入 | 冻结候选版本、生成门禁拓扑、记录证据化决定、传播失效并计算交付就绪度。 |
+| 03 | `workflow-intake` | 工作流方法 | 子智能体启动前 | 识别设计源、实现目录、测试目录、保护路径、验证命令和适配器线索。 |
+| 04 | `workflow-profile` | 工作流方法 | 子智能体启动前 | 将入口识别证据规范化为所有下游角色共同消费的项目画像。 |
+| 05 | `knowledge-openspec` | 知识包 | 读取设计源时；检测到 OpenSpec 才加载 | 理解提案、设计、规格、场景、任务、活动变更和已归档能力。 |
+| 06 | `knowledge-bdd` | 知识包 | 存在 `.feature` 或需要行为覆盖时 | 解释已挂载的行为场景契约，或从已确认设计中生成受来源约束的“前提—行为—结果”场景。 |
+| 07 | `knowledge-change-impact` | 知识包 | 入口识别、漂移或修复后 | 追踪语义影响，只使真正依赖的证据和门禁失效。 |
+| 08 | `quality-cross-spec-consistency` | 设计质量门 | 权威源识别后；实现前 | 审计直接关联基线和语义候选中的不兼容当前规则。 |
+| 09 | `quality-spec-review` | 设计质量门 | 规格导入后；实现前 | 检查规格完整性、一致性、可测试性、可追溯性和无依据声明；规格变化后重跑。 |
+| 10 | `quality-sr-ar-review` | 架构质量门 | 影响架构的实现开始前 | 检查需求到设计覆盖、归属、接口、数据/状态、质量属性和可实现性。 |
+| 11 | `quality-ci-gate` | 交付质量门 | 实现前规划；准入前核验 | 定义必跑门禁、耗时与不稳定测试策略、证据留存并核验候选版本。 |
+| 12 | `workflow-repair` | 工作流方法 | 实现后的设计一致性循环 | 控制有来源的一致性检查、最小修复、验证和收敛。 |
+| 13 | `knowledge-repair-distill` | 知识包 | 修复规划或模型跑偏时 | 提供缺口分类、收敛策略、模型引导提示和验证门槛。 |
+| 14 | `quality-code-review` | 实现质量门 | 实现变更风险适用时 | 审查契约影响、架构、安全、性能、可靠性和可维护性。 |
+| 15 | `quality-dt-review` | 测试质量门 | 行为或测试风险适用时 | 检查需求/风险覆盖、负向路径、断言强度、确定性和变异敏感度。 |
+| 16 | `quality-adversarial-challenge` | 独立挑战门 | 普通评审后且存在高风险主张时 | 按风险选择最小挑战集，并记录可复现反例。 |
+| 17 | `quality-evidence-audit` | 证据完整性门 | 最终评审前及候选漂移后 | 验证主张是否当前、可复现、内容寻址且绑定候选版本。 |
+| 18 | `quality-repository-gate` | 提交前准入门 | 设计一致性签署与受影响门禁重跑后 | 冻结候选版本，并依据当前证据决定准入、带后续事项准入或拒绝。 |
+
+## 子智能体：设计一致性循环中的职责顺序
+
+这些子智能体实现开发完成后的设计—实现一致性循环。这里的依赖顺序不代表外围质量门
+只执行一次，也不要求无依赖的工作全部串行。
+
+| 步骤 | 子智能体 | 阶段 | 消费的输入 | 主要产物 |
+| --- | --- | --- | --- | --- |
+| 01 | `profile-builder` | 项目画像确认 | 入口识别证据和仓库结构 | `reports/project-profile.json`、权威范围和语义候选 |
+| 02 | `spec-reader` | 事实源读取 | 项目画像和权威设计源 | 带文件锚点的需求摘要、保护路径和未决问题 |
+| 03 | `semantic-conflict-auditor` | 跨规格质询 | 直接关联基线、语义候选和权威根 | 成对引用的冲突与细化结论；不修改文件 |
+| 04 | `contract-oracle` | 契约义务映射 | 已确认需求、场景和冲突结论 | 有来源依据的实现义务队列 |
+| 05 | `impact-analyst` | 变更影响分析 | 候选变更面、义务、仓库与本体依赖 | 失效决策与最小安全重跑计划 |
+| 06 | `flow-auditor` | 流程完整性审计 | 实现义务和可选行为场景 | 生命周期、状态迁移、分支、副作用和集成流程审计 |
+| 07 | `impl-inspector` | 实现检查 | 已确认义务和流程审计 | 实现缺口报告；不修改代码 |
+| 08 | `repair-planner` | 修复规划 | 缺口、保护路径和验证命令 | 包含来源锚点、停止条件和回退路径的小修复片段 |
+| 09 | `code-repairer` | 代码修复 | 已批准的修复片段 | 最小代码变更、变更文件证据和修复说明 |
+| 10 | `validation-runner` | 验证 | 项目声明的命令和变更后实现 | `logs/trace/validation/` 下的日志与验证摘要 |
+| 11 | `adversarial-challenger` | 独立挑战 | 冻结候选、高风险主张、策略和证据 | 可证伪挑战与可复现反例；不修改文件 |
+| 12 | `evidence-auditor` | 证据完整性 | 候选、主张、门禁运行、验证和内容哈希 | 主张—证据矩阵及过期或无依据主张 |
+| 13 | `final-reviewer` | 设计一致性门 | 当前证据、冲突、影响计划、验证结果和最终产物 | 候选版本绑定的一致性结论与签署凭证；不决定仓库准入 |
+
+## 默认门禁生命周期
+
+```text
+导入规格
+-> 入口识别 + 项目画像
+-> 跨规格一致性检查
+-> 规格评审
+-> [影响架构或实现设计时执行系统需求与架构评审]
+-> 持续集成门禁 [规划]
+
+推进实现
+-> 按已确认义务开发
+-> [按风险触发专项质量门]*
+
+设计一致性循环
+-> 检查设计—实现差异
+-> [规划修复 -> 实施修复 -> 验证]*
+-> 影响分析与受影响证据失效
+-> [使受影响证据失效并重跑相关门禁]*
+
+提交前
+-> 持续集成门禁 [核验并冻结候选版本]
+-> [存在实质性失败假设时执行对抗挑战]
+-> 证据审计 [候选版本绑定的主张新鲜度]
+-> 最终评审 [设计一致性 + 签署凭证]
+-> 仓库准入门 [准入 / 带后续事项准入 / 拒绝]
+```
 
-## Subagents：按实际执行顺序
+`*` 表示按风险执行零次或多次。这是带反馈回路的门禁图，不是固定执行一次的智能体
+链。跳过门禁必须记录不适用理由。规格、架构、实现、测试、测试夹具、流水线、
+策略或候选版本发生变化时，依赖它的决定立即失效，并从最早受影响边界重跑。
 
-每个 Subagent 都按默认执行顺序排列。只有留下证据时才能跳过某个阶段；只有产物被下一步消费时，该次委派才算有效。
+必须分别保留设计一致性状态 `consistencyStatus`、专项质量状态 `qualityStatus` 和仓库
+准入状态 `admissionStatus`。设计一致性通过只证明设计—实现一致，不代表所有质量域均通过，
+也不直接等于仓库准入。适用性计划、门禁运行历史、失效原因和评审决策
+应保存在 `reports/quality/` 下。
 
-| 步骤 | Subagent | 阶段 | 消费的输入 | 主要产物 |
-| --- | --- | --- | --- | --- |
-| 01 | `spec-reader` | 事实源读取 | 项目画像和权威设计源 | 带文件锚点的需求摘要、保护路径和未决问题 |
-| 02 | `profile-builder` | 项目画像确认 | Intake 证据和仓库结构 | `reports/project-profile.json` |
-| 03 | `contract-oracle` | 契约义务映射 | 已确认需求、场景和反馈假设 | 有来源依据的实现义务队列 |
-| 04 | `flow-auditor` | 流程完整性审计 | 实现义务和可选 BDD 场景 | 生命周期、状态迁移、分支、副作用和集成流程审计 |
-| 05 | `impl-inspector` | 实现检查 | 已确认义务和流程审计 | 实现缺口报告；不修改代码 |
-| 06 | `repair-planner` | 修复规划 | 缺口、保护路径和验证命令 | 包含来源锚点、停止条件和回退路径的小修复片段 |
-| 07 | `code-repairer` | 代码修复 | 已批准的修复片段 | 最小代码变更、变更文件证据和修复说明 |
-| 08 | `validation-runner` | 验证 | 项目声明的命令和变更后实现 | `logs/trace/validation/` 下的日志与验证摘要 |
-| 09 | `final-reviewer` | 最终阶段门 | 所有证据、变更文件、验证结果和最终产物 | 最终一致性结论、残余风险和结果建议 |
-
-## 默认执行链
+## 本体驱动的一致性
+
+QIHENG 将一次运行建模为可移植的语义图，而不是互相独立的智能体总结。
+`reports/ontology-snapshot.json` 保存类型化对象（设计源、需求、场景、实现单元、
+缺口、修复动作、验证和证据）以及它们之间的明确关系。
+
+每个对象都有稳定编号、生命周期和来源证据。智能体通过
+`schemas/ontology-action.schema.json` 定义的受控动作改变状态。最终审查者根据
+图上的不变量计算通过结论：有效义务必须有来源，需求必须有实现处置，义务必须有
+当前验证证据，并且不能存在未关闭的阻断缺口。
+
+本体默认以文件保存，不依赖图数据库，因此可跨 Codex、Claude Code、OpenCode、
+MiMo Code 和 BitFun 使用；后续可以增加 SQLite 或图服务索引而不改变语义契约。
+
+发布后的单文件命令行工具已内置动作校验和审计能力，但不会发布运行时源码。
+这些本体命令要求工作流已经生成 `reports/ontology-snapshot.json`、
+`reports/project-profile.json`；台账操作还需要
+`reports/ontology-actions.jsonl`。它们负责完整性与治理，不替代最初由智能体
+完成的入口识别：
 
 ```text
-workflow-core
--> workflow-intake
--> workflow-profile
--> [knowledge-openspec：检测到 OpenSpec 时]
--> spec-reader
--> profile-builder
--> contract-oracle
--> [knowledge-bdd：需要行为覆盖时]
--> workflow-repair
--> flow-auditor
--> impl-inspector
--> [knowledge-repair-distill：修复规划或执行跑偏时]
--> repair-planner
--> code-repairer
--> validation-runner
--> final-reviewer
+qiheng ontology-check --root . --status PASS
+qiheng action-check --root . --action reports/actions/repair.json
+qiheng action-record --root . --action reports/actions/repair.json
+qiheng ontology-reconcile --root .
+qiheng ontology-ledger-check --root . --json
+qiheng ontology-evidence-check --root . --json
+qiheng ontology-validation-check --root . --json
+qiheng ontology-implementation-check --root . --json
+qiheng ontology-query --root . --query impact --id <object-id>
+qiheng ontology-drift --root .
+qiheng ontology-plan --root . --json
+qiheng ontology-explain --root . --id <object-id> --json
+qiheng ontology-report --root . --status PASS
+qiheng ontology-attest --root . --status PASS --summary "已验证"
+qiheng ontology-attestation-check --root .
 ```
 
-也可以将它理解为四个证据阶段：
+`action-record` 将带 SHA-256 的不可变记录追加到
+`reports/ontology-actions.jsonl`，并拒绝越权角色、无效目标、缺失证据、
+保护路径重叠和动作编号冲突。
 
-```text
-发现上下文
-workflow-intake -> workflow-profile
+新记录采用第二版台账：包含序号、前一记录哈希、基准快照修订、动作
+哈希和整条记录哈希，可检测重排、插入、修改和过期状态落账，同时兼容连续的
+第一版历史前缀。使用 `ontology-ledger-check` 查看链头和整文件哈希。
 
-确认设计
-spec-reader -> profile-builder -> contract-oracle
+完成态动作必须携带声明式 `ontologyPatch`。每种动作只能增加被允许的对象、
+关系和生命周期迁移。`ontology-reconcile` 会校验台账哈希、跳过已经应用的
+动作、重放剩余补丁、重新计算不变量，并且只在候选状态完整有效时替换快照。
 
-检查与修复
-flow-auditor -> impl-inspector -> repair-planner -> code-repairer
+`ontology-query` 提供四类查询：未覆盖义务、开放差距、无证据验证，以及从指定
+对象出发的有限深度影响链。
 
-验证与审核
-validation-runner -> final-reviewer
-```
+`ontology-evidence-check` 会验证当前验证所需的每个证据是否指向
+项目内真实文件，以及当前字节是否匹配记录的 SHA-256。只有生命周期有效且
+`properties.status: PASS` 的验证对象才能通过 `VERIFIED_BY` 满足通过条件。
+
+`ontology-validation-check` 用来堵住“旧绿灯日志批准新代码”的漏洞。每个
+验证对象必须记录 `executedAt`，并通过 `{ objectId, contentHash }` 绑定本次
+运行实际消费的设计源与实现单元。输入缺失或哈希过期会阻断
+通过结论，并使最终签署凭证失效。
+
+`ontology-implementation-check` 会将每个必需实现单元与项目内文件及
+记录的 SHA-256 比较。既有代码通过 `ObserveImplementation` 记录；
+`ApplyRepair` 只表示获批修复实际创建或修改的实现。
+
+`ontology-drift` 会将设计源当前内容与快照中的 SHA-256 来源记录进行比较；
+变更或丢失的设计源返回非零状态，其对象 ID 可以直接用于影响链查询。
+
+`ontology-plan` 将设计源、实现文件、证据漂移和影响链组合成最小重跑计划。
+设计变化从入口识别与契约映射重跑，实现漂移从实现检查与验证重跑，
+仅证据漂移则只重跑验证与最终评审。
+
+生成或重放后的快照包含规范化 `snapshotRevision`。直接修改语义状态会导致修订
+哈希失效；协调操作也会拒绝覆盖执行期间已经发生变化的快照。设计源漂移已经
+接入通过门禁，因此旧的绿色验证证据不能批准已经变化的设计。
+
+`ontology-explain` 会返回对象属性、来源、直接关系和有限深度证据链，便于说明
+某个结论来自哪一行设计、对应哪个实现、差距、修复、验证和证据。
+
+`ontology-report` 直接从快照生成高信息密度文档视图。
+`ontology-attest` 生成内容寻址的终态证明，将结论绑定到快照修订、动作台账
+哈希、设计源哈希、证据制品哈希、实现单元哈希和门禁结果；
+`ontology-attestation-check` 会重新计算这些绑定，因此设计源、实现文件、
+证据文件、台账、快照或证明被改动后都会失败关闭。
+应将输出的 `contentHash` 保存到持续集成或发布元数据，并通过
+`--expected-hash` 进行外部锚定；仅在同一文件内保存哈希只能证明完整性，
+不能证明真实性。
+
+## 行为驱动开发作为本体入口
+
+源码辅助工具会识别常见的功能、行为、规格和测试目录中的 `.feature` 文件，
+并支持英文及常见中文行为场景关键字：
+
+- 功能映射为需求。
+- 场景和场景大纲映射为场景对象。
+- 背景步骤继承到每个场景。
+- 示例表、标签、行号和来源哈希完整保留。
+- `DERIVED_FROM` 连接设计源，`REFINES` 连接功能需求。
+
+场景被解析不代表验证通过；仍需通过 `RunValidation` 和 `AttachEvidence` 挂载
+当前执行证据。
 
-Skills 提供全局控制或阶段知识；Subagents 消费边界明确的输入并产出类型化证据。少量但有效的 Handoff，优于没有产物被消费的装饰性 Agent 链。
+显式选择某个 OpenSpec 变更时，只挂载被该变更引用的行为场景文件；
+其他检测到的文件保持可发现，但不会静默扩大变更的义务范围。
 
 ## OpenSpec 适配重点
 
@@ -282,7 +487,7 @@ Skills 提供全局控制或阶段知识；Subagents 消费边界明确的输入
 | `openspec/changes/**/design.md` | 技术设计和约束。 |
 | `openspec/changes/**/tasks.md` | 实现任务和完成证据。 |
 | `openspec/changes/**/specs/**/spec.md` | 活跃变更中的增量需求。 |
-| archived specs | 历史上下文，不能覆盖当前有效 Spec。 |
+| 已归档规格 | 历史上下文，不能覆盖当前有效规格。 |
 
 ## 默认输出契约
 
@@ -290,6 +495,10 @@ Skills 提供全局控制或阶段知识；Subagents 消费边界明确的输入
 reports/project-profile.json
 reports/contract-obligations.json
 reports/contract-obligations.md
+reports/ontology-snapshot.json
+reports/ontology-actions.jsonl
+reports/ontology-report.md
+reports/ontology-attestation.json
 reports/implementation-gaps.md
 reports/repair-plan.md
 reports/final-consistency-report.md
@@ -298,17 +507,20 @@ result/output.md
 logs/trace/
 ```
 
-Adapter 可以扩展输出契约。例如比赛环境可能要求固定的 `result/output.md`，内部 CI 则可以将 JSON 证据发布到制品存储。
+适配器可以扩展输出契约。例如比赛环境可能要求固定的 `result/output.md`，内部持续集成系统则可以将结构化证据发布到制品存储。
 
 ## 平台无关要求
 
 - 不硬编码本机绝对路径。
 - 不假设 Windows、Linux、macOS、PowerShell、Bash 或 `cmd`。
-- 从 `INSTRUCTION.md`、项目画像或 Adapter 配置解析路径。
-- Python helper 只依赖标准库。
+- 从 `INSTRUCTION.md`、项目画像或适配器配置解析路径。
+- Python 辅助工具只依赖标准库。
 - `git`、`mvn`、`npm`、`pnpm`、`pytest`、`openspec` 等外部工具仅在验证需要时从目标环境 `PATH` 解析。
 - 工具缺失属于环境证据，不等同于设计失败。
 
 ## 当前状态
 
-该仓库包含从比赛场景中抽取出的第一版通用化设计—实现一致性工作流骨架，目标是成为 OpenSpec 和其他设计先行 Coding Agent 工作流的可复用上游能力。
+QIHENG 已经是一套正式发布的跨宿主工作流包，具备安全安装生命周期、
+OpenSpec 与行为驱动开发入口识别、本体治理动作、内容寻址验证、防篡改台账、自动报告
+和终态签署凭证。后续扩展应保持这些契约，并继续增强适配器、存储后端和
+持续集成外部信任锚。