immune-brain 4.5.0 → 5.0.0

package/README.zh-CN.md

@@ -11,10 +11,10 @@
 Immune-Brain 为 AI 编程工具（**Pi** 与 **Claude Code**）提供结构化的工程工作流保障：
 
 - **日常对话零负担** — 普通问答、单点代码修改与探索性对话完全保持 Host 原生体验，不拦截、不强加流程。
-- **需要严谨时显式启用** — 遇到复杂功能开发或高保证任务时，显式调用 `imm-brainstorm`、`imm-planner` 或 `imm-loop`。
+- **需要严谨时显式启用** — 遇到复杂功能开发或高保证任务时，显式调用 `imm-brainstorm`、`imm-planner` 或 `imm-run`。
 - **计划变为可追踪的任务**（`TaskIntent` + `TaskRecord`） — 进度落盘持久化（Git + `.imm/`），会话重启或上下文清理后仍可无缝恢复。
 - **质量由代码强制保障** — 自动化 QA 验收与隔离式 Reviewer 审查必须通过，任务才会结算完成。
-- **已就绪的 Initiative 可以整批运行** — 一次确认的 Batch Authorization 让 `imm-loop` 串行推进已发布 Initiative 的各个 child，而每个 child 仍然独立 Enrollment、独立 QA/Review、独立结算。
+- **已就绪的 Initiative 可以整批运行** — 一次确认的 Batch Authorization 让 `imm-run` 串行推进已发布 Initiative 的各个 child，而每个 child 仍然独立 Enrollment、独立 QA/Review、独立结算。
 
 Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。Claude Code 最低版本为 `2.1.236`，这是已通过交互式 server-initiated MCP elicitation 验证的最低版本。当前真实 Host 证据见 `docs/verification/claude-native-elicitation-authority-conformance.md`；历史报告归档于 `docs/verification/archive/`。
 
@@ -25,6 +25,7 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 - [安装](#安装)
 - [快速开始](#快速开始)
 - [如何使用](#如何使用)
+- [核心设计哲学：把“判断”变成“查表”](#核心设计哲学把判断变成查表用确定性工程驾驭多模型)
 - [7 个 Skills](#7-个-skills)
 - [生命周期](#生命周期)
 - [无人值守批次运行](#无人值守批次运行)
@@ -51,7 +52,7 @@ Pi 通过 `package.json`（或全局 Pi 配置）自动发现 Skills 与扩展
 }
 ```
 
-无需额外 server 配置，通过 Pi 安装本 package 后 6 个 Skill 即自动可用。
+无需额外 server 配置，通过 Pi 安装本 package 后 7 个 Skill 即自动可用。
 
 ### 在 Claude Code 中使用
 
@@ -95,8 +96,8 @@ Planner 会在 `docs/plans/` 生成 `TaskIntent` 与 living Spec（锁定文件
 
 检查无误并确认后，才会正式锁定范围并开放执行权限。
 
-**3. 用 `imm-loop` 自动执行与验收：**
-输入 `/imm-loop`（或 "开始 imm-loop"），工作流引擎会自动：
+**3. 用 `imm-run` 自动执行与验收：**
+输入 `/imm-run`（或 "开始 imm-run"），工作流引擎会自动：
 - 调度 Executor 仅在锁定的 scope 范围内编写代码。
 - 自动运行确定性 QA 验收命令。
 - 对 material/critical 任务分发隔离的 Reviewer 子代理审查代码。
@@ -113,18 +114,18 @@ Immune-Brain 提供两种清晰的工作模式：日常轻量编码走 **Host-na
 | 日常编码、快速改动、普通问答 | 正常自然语言对话（"帮我改下文案"、"解释这段代码"） | **Host-native**：标准 Pi / Claude Code 行为，零流程开销 |
 | 想法模糊，需要梳理边界与风险 | `/imm-brainstorm` "帮我梳理一下通知系统的方案" | → `imm-brainstorm` 提问澄清、分析约束与风险（只读，不改代码） |
 | 目标明确，需要正规计划与规格 | `/imm-planner` "规划一下深色模式功能" | → `imm-planner` 产出 `TaskIntent` + Spec，包含可执行验收条件 |
-| 计划已确认，准备执行与验证 | `/imm-loop` | → Executor 在范围内实现 → 确定性 QA 验收 → 隔离 Review 审查 → 任务结算 |
-| 会话中断或需恢复未完成任务 | `/imm-loop` | → 从磁盘状态（`.imm/`）无缝恢复，以 Kernel projection 为准 |
+| 计划已确认，准备执行与验证 | `/imm-run` | → Executor 在范围内实现 → 确定性 QA 验收 → 隔离 Review 审查 → 任务结算 |
+| 会话中断或需恢复未完成任务 | `/imm-run` | → 从磁盘状态（`.imm/`）无缝恢复，以 Kernel projection 为准 |
 | 已发布的 Initiative 可以整批跑了 | "把 initiative `<slug>` 无人值守跑完" | → Host 的 `start_unattended_batch`：一次原生确认绑定有序 plan digest，child 串行执行 |
-| 跨 Host 协作（Claude 规划 + Pi 编码） | 在 Claude Code 中调 `/imm-planner`，切到 Pi 输入 `/imm-loop` | → Spec 与 TaskIntent 共享于 Git，Pi 原生弹窗准入并执行 QA/Review 闭环 |
+| 跨 Host 协作（Claude 规划 + Pi 编码） | 在 Claude Code 中调 `/imm-planner`，切到 Pi 输入 `/imm-run` | → Spec 与 TaskIntent 共享于 Git，Pi 原生弹窗准入并执行 QA/Review 闭环 |
 | PR 被评论 / CI 挂了 | 对该 PR 使用 `/imm-pr-fix` | → 独立修复：在当前 PR 内针对性修复，不创建新 managed 任务 |
 | 文档过时需要清理 | `/imm-doc-prune` | → 只读审计过时文档，仅删除经哈希审批的条目 |
-| Agent 指令文件膨胀 | `/imm-agent-doc-maintain` | → 将 tracked `AGENTS.md` / `CLAUDE.md` 压到最小必要上下文 |
-| 想知道哪个模型的改动总被审查 | `/imm-review-retro` | → 按模型排名审查负载，并从 session logs 汇报项目使用量 |
+| Agent 指令文件膨胀 | `/imm-doc-slim` | → 将 tracked `AGENTS.md` / `CLAUDE.md` 压到最小必要上下文 |
+| 想知道哪个模型的改动总被审查 | `/imm-retro` | → 按模型排名审查负载，并从 session logs 汇报项目使用量 |
 
 > **核心原则：Skill 显式调用**
 > - **普通输入保持 Host-native**：自然语言提问绝不自动绑架流程或发起 Enrollment。你完全自主决定何时开启严格工程保障。
-> - **Managed 工作流显式启动**：需要澄清用 `imm-brainstorm`，制定计划用 `imm-planner`，执行与恢复用 `imm-loop`。
+> - **Managed 工作流显式启动**：需要澄清用 `imm-brainstorm`，制定计划用 `imm-planner`，执行与恢复用 `imm-run`。
 
 ### 跨 Host 协作：Claude Code 规划 + Pi 编码执行
 
@@ -135,7 +136,7 @@ Immune-Brain 的核心状态与契约完全去会话化（Session-neutral），
 ```text
 ┌───────────────────────────────────┐    Git 追踪制品（落盘共享）    ┌───────────────────────────────────┐
 │         Claude Code 终端          │ ───────────────────────────> │              Pi 终端              │
-│  1. /imm-brainstorm (澄清与约束)    │     docs/specs/*.spec.md     │  1. /imm-loop (原生 TUI 弹窗准入)   │
+│  1. /imm-brainstorm (澄清与约束)    │     docs/specs/*.spec.md     │  1. /imm-run (原生 TUI 弹窗准入)   │
 │  2. /imm-planner    (编写计划/规格) │    docs/plans/*.intent.json  │  2. Executor 编码 + QA 自动化验收   │
 └───────────────────────────────────┘                              └───────────────────────────────────┘
 ```
@@ -150,7 +151,7 @@ Immune-Brain 的核心状态与契约完全去会话化（Session-neutral），
    - **暂存至 Git**：规划完成后停在 Enrollment 之前，将生成的 Spec 和 TaskIntent 加入 Git 暂存（`git add docs/`）。
 2. **切换到 Pi 中进行代码编写与闭环执行**
    - **启动 Pi**：在同一个项目工作区中打开 Pi。
-   - **确认准入并执行**：运行 `/imm-loop`。Pi 会自动检测到暂存的 `TaskIntent`，并在 Pi 原生 TUI 弹窗中提示 Enrollment 确认。
+   - **确认准入并执行**：运行 `/imm-run`。Pi 会自动检测到暂存的 `TaskIntent`，并在 Pi 原生 TUI 弹窗中提示 Enrollment 确认。
    - **自动执行与验收**：
      - Executor 角色严格在 `scope_hint` 限定的文件内编写代码。
      - Kernel 自动运行 acceptance 命令进行确定性 QA 验收，不依赖口头汇报。
@@ -158,7 +159,117 @@ Immune-Brain 的核心状态与契约完全去会话化（Session-neutral），
      - 验证全部通过后，Kernel 原子落盘证据至 `.imm/audit/<task-id>/` 并释放工作区锁定。
 3. **为什么可以无缝切换？**
    - **状态落盘，解耦会话**：所有任务契约（TaskIntent）、设计规格（Spec）和执行状态（`.imm/state/kernel.sqlite`）均持久化在磁盘上，不绑定任何特定 AI 会话的上下文。
-   - **双向断点恢复**：无论在哪个 Host 暂停或关闭会话，随时可以在 Pi 或 Claude Code 中重新输入 `/imm-loop` 无缝恢复，Kernel projection 确保进度与证据不丢失。
+   - **双向断点恢复**：无论在哪个 Host 暂停或关闭会话，随时可以在 Pi 或 Claude Code 中重新输入 `/imm-run` 无缝恢复，Kernel projection 确保进度与证据不丢失。
+
+---
+
+## 核心设计哲学：把“判断”变成“查表”，用确定性工程驾驭多模型
+
+大模型（尤其是轻量/高性价比的 Fast 档模型）在工程落地中最容易失败的原因，不是代码语法不过关，而是死在**语义含糊、过度发挥**与**逃避严格验证**上。
+
+Immune-Brain 的核心假设是：**不要让弱模型做架构决策，把它变成精准执行的查表机；关键的门禁与审核则交由代码规则与强模型把关。**
+
+```text
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│ 1. 方案规划 (Brainstorm) & 2. 计划制定 (Planner)                                       │
+│ 工具: Claude Code | 模型: 强推理旗舰模型 (Strong Tier)                                 │
+│ 职责: 澄清约束、架构推演，把“判断”收敛为精确到行号的 Living Spec 与可执行 TaskIntent      │
+└───────────────────────────────────────────┬────────────────────────────────────────────┘
+                                            │ Git 追踪制品共享 (docs/specs, docs/plans)
+                                            ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│ 3. 代码实现 (Executor)                                                                 │
+│ 工具: Pi | 模型: 高吞吐/经济型模型 (Fast / Mid Tier)                                    │
+│ 职责: 冻结 Scope 内“按图索骥”，严格镜像既有代码模式填空，无设计决策负担                │
+└───────────────────────────────────────────┬────────────────────────────────────────────┘
+                                            │ 本地代码与状态交付
+                                            ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│ 4. QA 确认 (Deterministic QA)                                                          │
+│ 工具: Pi / Kernel Native                                                               │
+│ 职责: 零 LLM 干预，真机执行 Verification Descriptor v2 命令，机器判决 Pass/Fail         │
+└───────────────────────────────────────────┬────────────────────────────────────────────┘
+                                            │ 自动化测试真实跑通后触发
+                                            ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│ 5. 代码审查 (Isolated Review)                                                          │
+│ 工具: Pi Subagent | 模型: 强推理/高智商审查模型 (Strong Tier)                           │
+│ 职责: 基于不可变 Git blob 打包的 ReviewBundle，结合 Devil's Advocate 规则审查代码      │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 1. 把“判断”变成“查表”：挤干含糊空间，弱模型按图索骥
+
+约束弱模型最有效的一招，是在 Spec 阶段彻底消除含糊：
+
+- **坐标级精准定位**：在 Spec 中直接给出既有实现的参考锚点（如 `kernel.ts:1219`），明确要求 *"mirror this exact shape"* 沿用既有实现模式。
+- **零自由度契约**：连报错文案、返回状态码与错误类型都要求照抄既有格式（如复制现有 `throw new VerificationDescriptorError(...)`，仅替换具体的命令名与字段名），不留任何自由措辞或抽象发挥的空间。
+- **物理冻结与负向清单（Exclusion List）**：在 Spec 的 Scope 章节中明确列出 Exclude 清单（严禁改动哪些文件、特定 receipt 路径禁止复用）。弱模型不需要自行推断架构影响面，只需在限定红线内按图索骥。
+
+### 2. “做完”的定义是可执行的，不是文字汇报
+
+口头汇报（Text-based Promise）是幻觉与蒙混过关的温床。Immune-Brain 的 Kernel 强制要求所有完成标准全部代码化、物理化：
+
+- **Verification Descriptor v2 强契约**：
+  `TaskIntent` 中每个验收条件（AC）都不是泛泛的自然语言，而是强类型的机器执行描述符（`assurance_kernel/verification_descriptor/v2`）：
+  ```json
+  {
+    "contract": "assurance_kernel/verification_descriptor/v2",
+    "command": {
+      "executable": "bun",
+      "argv": ["test", "tests/kernel-migrate-to-vnext.test.ts"],
+      "cwd": ".",
+      "timeout_ms": 30000,
+      "max_output_bytes": 262144
+    },
+    "environment": { "prepare": null, "writable_paths": [] }
+  }
+  ```
+  模型无法靠“我已经实现并测试通过”的话术过关；测试必须由 Kernel 子进程在隔离沙箱中真机拉起，根据真实的 exit code、stdout 与超时时限判定胜负。
+- **物理级 Scope 冻结**：
+  在 Enrollment 准入时，Kernel 通过 `captureGitWorkspaceSnapshot` 对 Git 树和 dirty files 进行基线快照。如果候选任务的 scope 已经变脏，或 Executor 试图修改 `scope_hint` 允许范围外的文件（`assertNoEnvelopeEscape`），Kernel 直接 fail-closed 拦截并拒绝推进。
+- **独立 QA 与隔离 Reviewer 强制 Gate**：
+  代码修改完成后，QA 阶段由本地命令执行器严格校验；对于 `material` 和 `critical` 任务，必须经由独立的 Reviewer 子代理审计并签批。任何试图跳过门禁的幻觉行为都会被底层状态机拦下。
+
+### 3. Devil's Advocate Audit 与代码级防御：封死偷懒路径
+
+弱模型在面对复杂逻辑和优化压力时，极易选择走阻力最小的“偷懒捷径”。Immune-Brain 从 Spec 到代码层面构建了层层阻尼：
+
+- **防虚荣验证（Verification Vanity）**：
+  在 Devil's Advocate Audit 中明确立规：“`--check` 跑通不等于真跑能成功”。静态检查、类型声明或空跑（dry-run）绝不能替代带断言的真实运行测试。
+- **防规格稀释（Spec Dilution）**：
+  严禁模型因为实现困难而悄悄删减需求，例如：“不许在没有 v1 数据的环境中凭空编造虚假的 v1→v2 转换逻辑”来伪造兼容性。
+- **代码强制的确定性风险兜底（Deterministic Risk-Tier Floor）**：
+  模型可能会自作聪明地将高危任务自评为 `routine`（常规），企图绕过代码审查。在 `kernel/intent.ts` 中，系统硬编码了底线规则：
+  > 只要 `scope_hint` 触及 `kernel/`、`assurance/`、`claude/` 或 `.pi-extension` 等核心权威路径，无论作者声明的风险多么轻微，Kernel 会强制将风险等级锁定至至少 `material`，由代码物理强制触发隔离审查。
+- **客观反证机制（Live Counterevidence & Refuted Findings）**：
+  审查模型并非百分之百可信。当 Reviewer 提出怀疑某个 acceptance 存在缺陷的主观 finding 时，若 Kernel 拥有一份针对当前 `diff_hash` 和 `intent_hash` 真实跑通的新鲜 QA 凭证（Attestation），Kernel 会直接将该 finding 标记为 `refuted`（反证驳回），避免审查模型的幻觉阻碍任务落地；而一旦代码产生新改动使凭证过期（stale），该 finding 又会立即重新激活阻塞。
+
+### 4. Token 经济学与成本杠杆：没有 Cost Lever，成本会复合爆炸
+
+如果缺乏精细的成本杠杆（Cost Lever），多 Agent 系统的成本会随着任务拆解呈几何级数（Compound）激增：
+
+- **先 Plan 后 Implement（“量两次，裁一次”）**：
+  一份几百 token 的精准 Spec 与 TaskIntent 成本，远低于一次方向做错后推倒重来、反复 debug 烧掉的上万 token。“量两次裁一次”在多 Agent 协作中是字面意义的真金白银。
+- **冻结 Scope 掐断 Token 黑洞**：
+  弱模型最爱“顺手重构无关文件”或“格式化全工程”。在 Immune-Brain 中，每多碰一个文件不仅增加额外的 token 消耗，还会让 Reviewer 和 Git Diff 负担翻倍。基于哈希的 Scope 边界硬性杜绝了模型过度发挥。
+- **Model Tier 分档流水线（`subagent-model-tier-pipeline`）**：
+  将模型按能力与成本精细分档：
+  - **Fast 档（如 Flash / 4o-mini）**：专跑无设计决策的机械填充、局部测试修复、固定模板编码。
+  - **Mid 档**：负责可靠性审计（`reliability-reviewer`）与常规代码审查。
+  - **Strong 档（如 Sonnet / Opus）**：仅用于前期 Brainstorming、Spec 架构推演与高危安全审计（`security-reviewer`）。
+
+### 5. 典型协作全景：跨 Host 与多模型落地
+
+在 Immune-Brain 的跨 Host 协作模式中，各阶段工具与模型能力得以实现最优配置：
+
+| 阶段 | 参与工具 / 宿主 | 模型档位推荐 | 职责与确定性保障 |
+|---|---|---|---|
+| **1. 方案规划 (Brainstorm)** | Claude Code (`/imm-brainstorm`) | **Strong Tier** (旗舰模型) | 利用长上下文与强推理，与开发者深入讨论方案、挖掘隐性约束并排除伪需求。 |
+| **2. 计划制定 (Planner)** | Claude Code (`/imm-planner`) | **Strong Tier** (旗舰模型) | 编写精确到文件行号的 Living Spec，生成携带 `VerificationDescriptor` 的 `TaskIntent`，完成 Devil's Advocate 预审。 |
+| **3. 代码实现 (Executor)** | Pi (`imm-run`) | **Fast / Mid Tier** (经济模型) | 在 Pi TUI 弹窗确认冻结 Scope 后，小模型在信封内按图索骥写代码，遵守 YAGNI 极简红线。 |
+| **4. QA 确认 (Verification)** | 本地进程 / Kernel Native | **无需模型 (零 LLM)** | 由 Kernel 直接执行测试脚本（如 `bun test`），严格依照退出码和标准输出出具不可篡改的 Attestation。 |
+| **5. 代码审查 (Review)** | Pi Subagent (`immune-brain-reviewer`) | **Strong Tier** (高智力模型) | 调度隔离的只读审查子代理，基于不可变 Git blob 打包的 `ReviewBundle` 进行对抗性审计，通过后 Kernel 结算归档。 |
 
 ---
 
@@ -168,15 +279,15 @@ Immune-Brain 的核心状态与契约完全去会话化（Session-neutral），
 |---|---|---|---|
 | `imm-brainstorm` | Managed 入口 | 需求存在实质歧义 | 框架化问题、提出开放问题，不做实现 |
 | `imm-planner` | Managed 入口 | 目标清晰 | 编写/修订 `TaskIntent` 与 spec，不负责 Enrollment 与构建 |
-| `imm-loop` | Managed 协调器 | 计划已验证 | 通过 foreground Tools 协调 执行 → QA → Review → 收尾 |
+| `imm-run` | Managed 协调器 | 计划已验证 | 通过 foreground Tools 协调 执行 → QA → Review → 收尾 |
 | `imm-pr-fix` | 独立 | PR 需修复 | 原地修复单个 PR，不触及 managed authority |
 | `imm-doc-prune` | 独立 | 清理过时文档 | 仅删除哈希绑定的 manifest 条目 |
-| `imm-agent-doc-maintain` | 独立 | Agent instruction 膨胀 | 将 tracked AGENTS/CLAUDE/GEMINI.md 压到最小必要上下文 |
-| `imm-review-retro` | 独立 | 比较模型的审查负载 | 排名被审查代码的作者并汇报项目使用量 |
+| `imm-doc-slim` | 独立 | Agent instruction 膨胀 | 将 tracked AGENTS/CLAUDE/GEMINI.md 压到最小必要上下文 |
+| `imm-retro` | 独立 | 比较模型的审查负载 | 排名被审查代码的作者并汇报项目使用量 |
 
-Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，无需手动调用。
+Executor、QA、Review、Compounder 等为 `imm-run` 内部调度的角色，无需手动调用。
 
-所有 7 个 Skill 均显式调用。新需求开发时：若需求含糊先调 `imm-brainstorm`，目标清晰直接调 `imm-planner`，完成确认后调 `imm-loop` 推进闭环。
+所有 7 个 Skill 均显式调用。新需求开发时：若需求含糊先调 `imm-brainstorm`，目标清晰直接调 `imm-planner`，完成确认后调 `imm-run` 推进闭环。
 
 ### Managed Path 入口（brainstorm → planner → loop）
 
@@ -196,9 +307,9 @@ Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，
 - **边界：** 不编写业务实现代码、不经 revision 流程不覆盖已 Enrolled 的 TaskIntent，不擅自赋予执行权限 — 仅当前 Host 原生确认窗口具备授权能力。
 - **产出：** 纳入 Git 版本控制、等待 Enrollment 确认的 `TaskIntent`。
 
-#### `imm-loop` — Managed 执行与质量保障
+#### `imm-run` — Managed 执行与质量保障
 
-- **触发方式：** 显式调用 `/imm-loop`（启动、恢复或检查 managed 任务）。
+- **触发方式：** 显式调用 `/imm-run`（启动、恢复或检查 managed 任务）。
 - **职责：** 通过前台 Tool 驱动任务端到端闭环 — Executor 仅在冻结的 scope 内修改代码，确定性 QA 逐项运行验收条件，隔离的 Reviewer 子代理审计 material/critical 任务，最后由 Kernel 结算落盘凭证。会话中断后从磁盘状态自动恢复，以 Kernel projection 为真源。
 - **边界：** 绝不跳过或弱化失败检查、无用户原生授权绝不执行、遇到版本或权限偏移立即 fail-closed。
 - **Finding 证据：** 每一项 Review finding 均携带可机器核验的 provenance（`trigger`、`caller_chain`、`violated`）。若新鲜且通过的 QA 证据已证明某项 finding 声称的 acceptance 通过，则标记为 `refuted`，仅在证据过期时才会重新阻塞。
@@ -219,12 +330,12 @@ Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，
 - **触发方式：** 显式要求清理当前过时的文档。
 - **职责：** 只读审计文档时效性，根据用户明确审批的哈希绑定 manifest 进行精准删除，每次修改后立即重验。
 
-#### `imm-agent-doc-maintain` — Agent 指令文件瘦身
+#### `imm-doc-slim` — Agent 指令文件瘦身
 
 - **触发方式：** 显式要求精简版本控制下的 `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`。
 - **职责：** 遵循与 `imm-doc-prune` 相同的「只读审计 + 哈希清单审批」模式，仅保留无法直接推导的必要规则。
 
-#### `imm-review-retro` — 审查负载与项目使用回顾
+#### `imm-retro` — 审查负载与项目使用回顾
 
 - **触发方式：** 显式要求跨模型审查复盘或项目使用量回顾。
 - **职责：** 从 pi session logs 按模型排名被审查代码的作者，并汇报 sessions/turns/编辑量/工具分布。只读；不审查 diff。
@@ -245,7 +356,7 @@ flowchart TD
         EG -->|确认| KS[(".imm/state/kernel.sqlite<br/>原子生成 TaskRecord<br/>独占 Workspace Claim")]
     end
 
-    subgraph Loop ["3. 执行与验证循环 (imm-loop)"]
+    subgraph Loop ["3. 执行与验证循环 (imm-run)"]
         KS --> EX["Executor 角色<br/>在 scope_hint 范围内修改代码"]
         EX --> FRZ["advance_assurance<br/>制品冻结 (active:frozen)"]
         FRZ --> QA["确定性 QA 引擎<br/>原子运行 acceptance 校验命令<br/>生成 QA Attestation"]
@@ -268,25 +379,28 @@ flowchart TD
     end
 ```
 
-### 核心逻辑三要素
+### 核心架构与确定性保证
 
 1. **双轨制 (Two Paths)**
    - **Host-native Path**：日常对话、代码检视、单点修改，不触碰 Kernel 权限，零流程开销。
-   - **Managed Path**：由 `imm-brainstorm` / `imm-planner` / `imm-loop` 显式驱动，全程受 Kernel 约束。
+   - **Managed Path**：由 `imm-brainstorm` / `imm-planner` / `imm-run` 显式驱动，全程受 Kernel 约束。
 
 2. **权限与契约 (Authority & Contract)**
-   - **TaskIntent (`.intent.json`)**：机器契约本体，严格锁定 `scope_hint`（文件修改范围）、`risk`（风险层级）与 `acceptance`（确定性断言）。
-   - **Native Gate (Enrollment)**：唯一一次人工介入确认，Kernel 原子抢占工作区所有权（SQLite CAS），防止多任务并发冲突与范围漂移。
-
-3. **客观验证 (Deterministic Assurance)**
-   - **QA 优先**：由 Kernel 直接前台执行命令并校验退出码/输出，不依赖 LLM 口头汇报。
-   - **按险定级**：`routine` 仅需 QA；`material`/`critical` 必须追加独立只读 Reviewer 产出结构化裁决。
+   - **TaskIntent (`.intent.json`)**：机器契约本体，严格锁定 `scope_hint`（文件修改范围）、`risk`（风险层级）与 `acceptance`（绑定 Verification Descriptor v2 的确定性断言）。
+   - **Native Gate (Enrollment)**：唯一一次人工介入确认，Kernel 原子抢占工作区所有权（基于 SQLite CAS），防止多任务并发冲突与范围漂移。
+   - **Git 物理基线快照 (Physical Baseline)**：准入时记录真实的 Git HEAD 与 dirty 文件状态（`enrollment-baseline.json`），任何超出 `scope_hint` 的物理逃逸（`assertNoEnvelopeEscape`）都会直接阻断执行。
+
+3. **客观验证与不可变证据链 (Deterministic Assurance & Evidence Trail)**
+   - **QA 优先与真实进程调用**：由 Kernel 直接前台拉起子进程执行测试命令，校验退出码、标准输出并施加超时上限，不依赖 LLM 口头汇报。
+   - **按险定级与确定性兜底**：`routine` 仅需 QA；`material`/`critical` 必须追加独立只读 Reviewer 产出结构化裁决。触碰核心权威路径强制定级为 `material`。
+   - **反证机制 (Live Refutation)**：主观 Review finding 可由真实通过的新鲜 QA 证据反证驳回；代码发生改动后反证自动失效并重新阻塞。
+   - **不可变审计落盘**：任务结项时，完整的 `TaskRecord`、Git blob 打包的 `ReviewBundle`、QA Attestation 凭证原子沉淀至 `.imm/audit/<task-id>/` 并受 Git 追踪。
    - **批处理 (Unattended Batch)**：基于 GitHub Issue / `plan_digest` 串行推进，每个子任务独立走完 Enrollment → QA → Review → Commit 闭环。
 
 核心不变量：
 
 - **一次仅一个活跃步骤**，编辑仅在步骤边界内。
-- **范围（`scope_hint`）在 enrollment 时冻结**，范围外文件被忽略。
+- **范围（`scope_hint`）在 enrollment 时冻结**，范围外文件被物理忽略与拦截。
 - **先记录证据再关闭** — 只有 QA 能关闭步骤。
 - **Finding 必须携带证据** — 被反证的 Review finding 只在绑定它的 QA 证据对当前 revision、intent hash 与 diff 仍然新鲜时压制工作；证据过期后 finding 重新阻塞，且这个失效过程不重写任何已存状态。
 - **批次必须显式授权且有边界** — 只有你确认 Host 的 `start_unattended_batch` 之后才存在无人值守批次；每个 child 仍各自 Enrollment、QA、Review 与结算。
@@ -298,7 +412,7 @@ flowchart TD
 
 当一个 Initiative 下已经有多个就绪的 child，可以把它们作为一批串行跑完，而不用逐个任务手动推进。
 
-- **入口显式：** Host 的 privileged tool `start_unattended_batch`（参数为 Initiative slug）。未调用之前不存在任何 batch state、分支或授权；未调用时 `imm-loop` 行为与逐任务 Enrollment 完全一致。
+- **入口显式：** Host 的 privileged tool `start_unattended_batch`（参数为 Initiative slug）。未调用之前不存在任何 batch state、分支或授权；未调用时 `imm-run` 行为与逐任务 Enrollment 完全一致。
 - **一次确认、一个 digest：** 原生 gate（Pi TUI 弹窗或 Claude MCP elicitation）展示有序 child 列表与共享 plan digest，这一次 literal-user 确认就是全部 Batch Authorization。
 - **每个 child 的 authority 不变：** 每个 child 仍由 Kernel 单独 Enrollment、冻结、QA、Review 并以自己的 `TaskRecord` 结算。批次只是一次授权的覆盖范围，不是新的授权层级。
 - **边界：** 只跑已发布且非 `critical` 的 child，在专属 batch 分支上串行执行；一旦某个 child 需要人决策，或遇到预算/截止时间/授权/提交失败就暂停，被阻塞 child 的依赖项标记为跳过而不是调序。runner 不 push、不开 PR、不代替用户结算 decision、也不创建/切换/删除 Git worktree。
@@ -333,7 +447,7 @@ Immune-Brain **没有独立配置文件**，偏好设置写在仓库根目录下
 package.json                          # Pi package manifest（skills + extensions）
 plugins/immune-brain/
 ├── .pi-extension/                    # Pi TUI + Kernel 扩展
-├── skills/                           # 6 个公开 Skills（触发 shim）
+├── skills/                           # 7 个公开 Skills（触发 shim）
 ├── dist/                             # 构建后的 skill 契约与参考文档
 ├── runtime/                          # Bun + TypeScript 运行时与 Kernel
 └── bin/                              # CLI wrappers（→ runtime/v4_runtime.ts）
@@ -351,19 +465,25 @@ docs/specs/                           # Living specs（原地更新）
 
 ## 常见问题
 
-**需要记住所有 Skill 吗？** 不需要。日常开发核心只需两个：`/imm-planner`（规划与确认任务）和 `/imm-loop`（执行与验证）。需求模糊时用 `/imm-brainstorm`，维护类任务（如 `/imm-pr-fix`）按需使用。普通问答与即时小修改无需任何 Skill。
+**需要记住所有 Skill 吗？** 不需要。日常开发核心只需两个：`/imm-planner`（规划与确认任务）和 `/imm-run`（执行与验证）。需求模糊时用 `/imm-brainstorm`，维护类任务（如 `/imm-pr-fix`）按需使用。普通问答与即时小修改无需任何 Skill。
 
-**中途关闭会话会怎样？** 状态已落盘保存（`.imm/` + TaskIntent）。在 Pi 或 Claude Code 中重新输入 `/imm-loop` 即可恢复，以 Kernel projection 状态为准。
+**中途关闭会话会怎样？** 状态已落盘保存（`.imm/` + TaskIntent）。在 Pi 或 Claude Code 中重新输入 `/imm-run` 即可恢复，以 Kernel projection 状态为准。
 
 **为什么 enrollment 要弹窗确认？** 所有风险等级（`routine`/`material`/`critical`）在获得执行授权前都必须经由人工显式确认。在 Pi 中是原生 TUI 对话框，在 Claude Code 中是原生 MCP elicitation 弹窗。确认界面绑定 staged digest，让你清楚看到被锁定的文件范围和验收要求。
 
-**QA 失败怎么办？** QA 返回 `rework` 或 `replan_required`，`imm-loop` 会自动路由回 Executor 或 `imm-planner` 调整范围，无需手动重置。
+**QA 失败怎么办？** QA 返回 `rework` 或 `replan_required`，`imm-run` 会自动路由回 Executor 或 `imm-planner` 调整范围，无需手动重置。
 
 **Review finding 突然不再阻塞了？** 它被反证了：新鲜的确定性 QA 证据表明它声称的 acceptance 是通过的。反证绑定到那份具体证据，所以证据一旦对当前 revision、intent hash 或 diff 失效，该 finding 会重新阻塞。
 
 **能不能整个 Initiative 不用我盯着？** 只能在你授权范围内。用 Initiative slug 确认 `start_unattended_batch` 后，runner 会在一个 batch 分支上串行推进已发布且非 `critical` 的 child — 一旦某个 child 需要人决策，或遇到预算/截止时间/授权/提交失败就暂停。它不会替你 push、开 PR 或结算用户决策。
 
-**可以在不同 Host 之间切换吗（例如 Claude Code 规划、Pi 编码）？** 可以。Immune-Brain 的契约与状态完全落盘于代码仓库，解耦了会话上下文。你可以用 Claude Code 进行深度推理与制定 Spec，再切换到 Pi 跑 `imm-loop` 编码并完成 QA 闭环；中途随时可以用 `/imm-loop` 双向恢复。
+**可以在不同 Host 之间切换吗（例如 Claude Code 规划、Pi 编码）？** 可以。Immune-Brain 的契约与状态完全落盘于代码仓库，解耦了会话上下文。你可以用 Claude Code 进行深度推理与制定 Spec，再切换到 Pi 跑 `imm-run` 编码并完成 QA 闭环；中途随时可以用 `/imm-run` 双向恢复。
+
+**任务执行中途发现 Scope 不够用怎么办？** Executor 遵循严格的 Fail-closed 极简红线，严禁自行越界修改范围外文件。若发现必须扩充范围，Executor 会主动停止并返回 `replan_required` 路线；随后由 `imm-planner` 修订 Spec 与 `TaskIntent` 并生成新的 diff，重新弹出原生确认窗口经由人工授权（Replan）后，方可继续执行。
+
+**任务结算后的审计凭证（Audit Trail）保存在哪里？** 保存在仓库的 `.imm/audit/<task-id>/` 目录下，并作为 Git-tracked 资产提交。其中包含最终的 `TaskRecord`、绑定的代码 `diff_hash`、真实执行的 QA 退出码/输出 Attestation、以及 Reviewer 签署的验证凭据，保证交付全流程可追溯、可审计。
+
+**偏好配置为什么写在 AGENTS.md / CLAUDE.md 而不是独立配置文件？** 遵循“零外部负担、宿主原生”原则。将偏好（如 Initiative 载体、交互语言）声明在项目根目录受版本控制的指令文件中，既能在不同 Host 之间透明生效，又避免了本地全局配置文件容易漂移、团队成员无法共享的痛点。
 
 **支持哪些 AI 编程工具？** Pi 与 Claude Code 是支持的宿主（Claude Code 最低版本为 `2.1.236`）。两者共享同一套确定性 Kernel 核心、质量保障机制与工具链。
 
@@ -391,7 +511,7 @@ npm publish --access public   # 需 npm login / NPM_TOKEN
 # 或
 bun run changeset:publish
 ```
-包名为 `immune-brain`（当前版本 `3.6.7`），已配置 `publishConfig.access=public`。首次发布后，后续所有版本均通过 changesets 管理。
+包名为 `immune-brain`（当前版本 `4.6.0`），已配置 `publishConfig.access=public`。首次发布后，后续所有版本均通过 changesets 管理。
 
 详见 `CHANGELOG.md` 与 `.changeset/config.json`（changelog: `@changesets/changelog-github`，repo: `dereknex/immune-brain`）。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "4.5.0",
+  "version": "5.0.0",
   "description": "Immune-Brain agent skill system",
   "publishConfig": {
     "access": "public",

package/plugins/immune-brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "4.5.0",
+  "version": "5.0.0",
   "description": "Immune-Brain Claude Code Host: native Enrollment, QA, Review, and Kernel settlement.",
   "author": {
     "name": "Immune-Brain Team"

package/plugins/immune-brain/.pi-extension/imm-canary-enroll.ts

@@ -9,27 +9,24 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { createHash, randomUUID } from "node:crypto";
 import { resolve } from "node:path";
-// The Kernel runtime graph is never type-checked from this extension: static
-// imports resolve to ./runtime-stub.ts (relative so the Pi extension loader
-// can resolve them at runtime), and the stub forwards to the real Kernel
-// modules via dynamic import.
+// The Pi adapter imports the host-neutral runtime modules statically, exactly
+// as the Claude adapter does. Kernel prepare is reached only through the
+// shared Enrollment boundary (runtime/assurance/enrollment), never directly
+// from the Kernel's own prepare module.
+import { LITERAL_USER_ACTOR_ID } from "../runtime/kernel/actor_identity";
+import { createEnrollmentAuthorityRegistry } from "../runtime/kernel/enrollment_authority";
+import { preparePiCanary, revalidatePiCanary } from "../runtime/assurance/enrollment";
+import { evaluateCanaryEligibility } from "../runtime/kernel/canary_eligibility";
+import { enrollTask, EnrollmentRehearsalError } from "../runtime/kernel/enrollment";
+import { reconcileKernelAuthority, withKernelStoreLock } from "../runtime/kernel/storage";
+import { inspectStorageLayout } from "../runtime/kernel/storage_paths";
+import { migrateLegacyLayout } from "../runtime/kernel/storage_layout_migration";
 import {
-	LITERAL_USER_ACTOR_ID,
-	createEnrollmentAuthorityRegistry,
-	preparePiCanary,
-	revalidatePiCanary,
-	evaluateCanaryEligibility,
-	reconcileKernelAuthority,
-	readTaskIntent,
-	runEnrollmentRehearsal,
-	enrollCanaryTask,
-	withKernelStoreLock,
-	inspectStorageLayout,
-	migrateLegacyLayout,
 	inspectEnrollmentGitBase,
 	enrollmentGitBaseNotice,
 	initializeEnrollmentGitBase,
-} from "./runtime-stub";
+} from "../runtime/assurance/enrollment_git_base";
+import { readTaskIntentForRecord } from "./imm-canary-work";
 import {
 	presentTaskRail,
 	presentTaskRailResult,
@@ -253,7 +250,7 @@ async function classifyCommitFailure(
 				"completed",
 				"committing",
 				`Kernel enrollment committed for ${taskId}; terminal receipt was recovered from authoritative owners`,
-				"continue with imm-loop",
+				"continue with imm-run",
 			);
 		}
 		if (
@@ -315,7 +312,7 @@ async function executeForegroundEnrollment(
 		signal.throwIfAborted();
 		progress("preparing", uxText(UX_LANG, `Preparing immutable Kernel owners for ${taskId}`, `正在为 ${taskId} 准备不可变 Kernel 所有者`));
 		const now = new Date().toISOString();
-		let taskIntent: Awaited<ReturnType<typeof readTaskIntent>>;
+		let taskIntent: Awaited<ReturnType<typeof readTaskIntentForRecord>>;
 
 		// Storage-layout gate (BR-REQ-005/006): enrollment is the stateful
 		// mutation boundary. Kernel transaction markers recover under the
@@ -387,10 +384,10 @@ async function executeForegroundEnrollment(
 		}
 
 		try {
-			taskIntent = await readTaskIntent(root, taskId);
+			taskIntent = await readTaskIntentForRecord(root, taskId);
 		} catch (error) {
 			const message = errorMessage(error);
-			// `readTaskIntent` reports an absent sidecar semantically now, so the
+			// `readTaskIntentForRecord` reports an absent sidecar semantically now, so the
 			// "missing" classification must recognise that wording as well as the raw
 			// filesystem errors; otherwise a missing file is misreported as a schema
 			// defect and the operator is told to repair fields that do not exist.
@@ -406,7 +403,7 @@ async function executeForegroundEnrollment(
 				"route_incumbent",
 				stage,
 				`Kernel task ${authority.owner_task_id} already owns this workspace`,
-				`continue ${authority.owner_task_id} through imm-loop without re-enrollment`,
+				`continue ${authority.owner_task_id} through imm-run without re-enrollment`,
 			);
 		if (authority.state === "repairable_stale_claim")
 			return terminal(
@@ -518,7 +515,7 @@ async function executeForegroundEnrollment(
 		{
 			let liveEarly: string | null = null;
 			try {
-				liveEarly = (await readTaskIntent(resolve(root), taskId)).content_hash;
+				liveEarly = (await readTaskIntentForRecord(resolve(root), taskId)).content_hash;
 			} catch {
 				liveEarly = null;
 			}
@@ -529,7 +526,7 @@ async function executeForegroundEnrollment(
 		{
 			let liveContentHash: string | null = null;
 			try {
-				liveContentHash = (await readTaskIntent(resolve(root), taskId)).content_hash;
+				liveContentHash = (await readTaskIntentForRecord(resolve(root), taskId)).content_hash;
 			} catch {
 				liveContentHash = null;
 			}
@@ -557,40 +554,40 @@ async function executeForegroundEnrollment(
 			preparation_digest: preparation.digest,
 			actor_id: LITERAL_USER_ACTOR_ID,
 			confirmation_ref: `pi-confirm-${createHash("sha256").update(`${taskId}\0${now}\0${nonce}`).digest("hex").slice(0, 16)}`,
-			expires_at: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
 			nonce,
 		};
-		const capability = registry.issue(binding);
-		const input = {
-			task_id: taskId,
-			intent_path: binding.intent_path,
-			intent_revision: binding.intent_revision,
-			preparation_digest: binding.preparation_digest,
-			capability,
-			capability_binding: binding,
-			now,
-		};
 
 		progress("rehearsing", uxText(UX_LANG, "Running the zero-write Kernel owner rehearsal", "正在执行 Kernel 所有者零写入预演"));
-		const rehearsal = await runEnrollmentRehearsal(root, input, capability, registry);
-		if (!rehearsal.rehearsed || rehearsal.evidence.outcome !== "ready")
-			return terminal(action, taskId, "failed", stage, `Kernel enrollment rehearsal failed: ${rehearsal.evidence.blockers.join("; ")}${gitBaseNote}`, "resolve the final-lock preconditions and retry");
-		if (signal.aborted) return cancelled();
-		if (!beginCommit()) return cancelled();
-
-		stage = "committing";
-		onUpdate?.(updateResult(action, taskId, stage, "Kernel enrollment commit owns settlement and is no longer cancellable"));
 		try {
-			const result = await enrollCanaryTask(root, input, registry);
+			// The single Enrollment entry owns issue -> rehearse -> checkpoint ->
+			// commit. The checkpoint keeps the Tool's abort/begin-commit gate
+			// between rehearsal and commit: a declined checkpoint cancels with
+			// zero writes, and once it accepts, commit is no longer cancellable.
+			const outcome = await enrollTask(root, registry, {
+				binding,
+				now,
+				checkpoint: () => {
+					if (signal.aborted) return false;
+					if (!beginCommit()) return false;
+					stage = "committing";
+					onUpdate?.(updateResult(action, taskId, stage, "Kernel enrollment commit owns settlement and is no longer cancellable"));
+					return true;
+				},
+			});
+			if (outcome.outcome === "cancelled") return cancelled();
+			const result = outcome.result;
 			return terminal(
 				action,
 				taskId,
 				"completed",
 				stage,
 				`Kernel enrollment completed: task ${result.record.task_id} state=${result.record.lifecycle}:${result.record.artifact_state} backend=${result.backend_claim.backend}`,
-				"continue with imm-loop",
+				"continue with imm-run",
 			);
 		} catch (error) {
+			if (error instanceof EnrollmentRehearsalError)
+				return terminal(action, taskId, "failed", stage, `${error.message}${gitBaseNote}`, "resolve the final-lock preconditions and retry");
+			if (stage !== "committing") throw error;
 			const failure = await classifyCommitFailure(root, action, taskId, now, error);
 			failure.summary += gitBaseNote;
 			return failure;