immune-brain 3.6.7 → 3.6.9

package/README.md

@@ -1,6 +1,6 @@
 # Immune-Brain
 
-> Deterministic workflow & quality engine for [Pi](https://github.com/badlogic/pi) — turn vague ideas into shipped code with planning, execution, QA, and review.
+> Deterministic workflow & quality engine for [Pi](https://github.com/badlogic/pi) and [Claude Code](https://claude.ai/code) — turn vague ideas into shipped code with planning, execution, QA, and review.
 
 **Language:** **English** | [中文](./README.zh-CN.md)
 
@@ -8,12 +8,13 @@
 
 ## What Is This?
 
-Immune-Brain adds a structured engineering workflow on top of Pi:
+Immune-Brain brings a structured engineering workflow to AI coding assistants (**Pi** and **Claude Code**):
 
-- **You describe what you want** in natural language — the agent figures out whether to clarify, plan, or execute.
-- **Plans become trackable tasks** (`TaskIntent` + `TaskRecord`) so progress survives across sessions, not just chat history.
-- **Quality is enforced by code, not promises** — automated QA and isolated review must pass before a task is marked done.
-- **Ready Initiatives can run as a batch** — one confirmed batch authorization lets `imm-loop` work through a published Initiative's children serially, while every child is still enrolled, QA'd, reviewed, and settled on its own.
+- **Zero overhead for normal chat & coding** — Ordinary questions, quick edits, and exploratory chat stay 100% host-native. Immune-Brain never interrupts normal conversation.
+- **Explicit trigger when rigor matters** — When you want engineering discipline, invoke `imm-brainstorm`, `imm-planner`, or `imm-loop`.
+- **Plans become trackable tasks** (`TaskIntent` + `TaskRecord`) — Progress lives on disk (Git + `.imm/`), surviving restarts and context wipes.
+- **Quality is enforced by code, not promises** — Automated QA and isolated review subagents must pass before a task can complete.
+- **Ready Initiatives can run as a batch** — One confirmed batch authorization lets `imm-loop` work through a published Initiative's children serially, while every child is still enrolled, QA'd, reviewed, and settled on its own.
 
 Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupported. Minimum Claude Code is `2.1.236`, the lowest version verified with interactive server-initiated MCP elicitation. Current real-Host evidence is recorded in [Claude native elicitation conformance](docs/verification/claude-native-elicitation-authority-conformance.md); historical reports remain under [docs/verification/archive/](docs/verification/archive/). Either host can use the model provider you configure — Immune-Brain works on top of Kernel authority, not a vendor chat.
 
@@ -24,7 +25,7 @@ Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupport
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [How to Use](#how-to-use)
-- [The 6 Skills](#the-6-skills)
+- [The 7 Skills](#the-7-skills)
 - [Lifecycle](#lifecycle)
 - [Unattended Batch Runs](#unattended-batch-runs)
 - [Configuration](#configuration)
@@ -36,9 +37,11 @@ Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupport
 
 ## Installation
 
-**Prerequisites:** [Pi](https://github.com/badlogic/pi) installed, Node.js 20+, `bun` for tests.
+**Prerequisites:** [Pi](https://github.com/badlogic/pi) or [Claude Code](https://claude.ai/code) (>= 2.1.236), Node.js 20+, `bun` for tests.
 
-This repo is a Pi package — Pi discovers Skills and extensions from `package.json`:
+### In Pi
+
+Pi discovers Skills and extensions from `package.json` (or your global Pi configuration):
 
 ```json
 // package.json → pi.skills / pi.extensions
@@ -48,7 +51,24 @@ This repo is a Pi package — Pi discovers Skills and extensions from `package.j
 }
 ```
 
-No extra server config is needed. Installing the package via Pi makes all 6 Skills available automatically. Verify with:
+No extra server config is needed. Installing the package via Pi makes all 6 Skills available automatically.
+
+### In Claude Code
+
+Add the plugin from the marketplace:
+
+```bash
+claude plugin marketplace add dereknex/immune-brain
+claude plugin install immune-brain
+```
+
+Or load the local directory directly:
+
+```bash
+claude --plugin-dir ./plugins/immune-brain
+```
+
+### Verification
 
 ```bash
 bun test                          # run all tests
@@ -60,43 +80,54 @@ mise run check-dist-sync           # verify generated docs are in sync
 
 ## Quick Start
 
-**1. Describe the change you want** — just talk to Pi in natural language:
+Immune-Brain follows a **Skill-explicit** model: ordinary conversation is just standard, lightweight AI coding. The managed workflow activates **only when you explicitly invoke a skill**.
 
-> "Add dark mode to the settings page"
+**1. Call a skill when you need structured engineering**:
+- Fuzzy idea that needs scoping? Run `/imm-brainstorm` (or ask the agent to use `imm-brainstorm`).
+- Ready to design and build? Run `/imm-planner` (or ask the agent to use `imm-planner`).
 
-Pi routes it automatically: vague requests go to clarification, clear requests go to planning.
+*(Ordinary questions like "What does this function do?" or "Fix this typo" stay host-native — zero workflow ceremony.)*
 
-**2. Confirm the plan** — Planner writes a `TaskIntent` (scope, risk, acceptance checks). Review it, then confirm enrollment in the TUI dialog (required for all risk levels). No writes happen before you confirm.
+**2. Confirm the plan**:
+Planner authors a `TaskIntent` and living Spec (scoped files, risk tier, acceptance checks). A native confirmation dialog opens directly:
+- In **Pi**: native TUI modal dialog.
+- In **Claude Code**: native MCP elicitation confirmation.
 
-**3. Let it run** — `imm-loop` executes the plan, runs QA, and triggers review. Stage your owned files when prompted:
-
-```bash
-git add -- <file-owned-by-task> <another-file>
-```
+Review the scope and confirm enrollment. No code or authority writes happen before your explicit confirmation.
 
-QA and review run as foreground tools and report back to the host. When the tool returns `phase=done`, the task is complete.
+**3. Run and verify with `imm-loop`**:
+Run `/imm-loop` (or say "Start imm-loop"). The engine will:
+- Dispatch an Executor to write code strictly within the frozen scope.
+- Run deterministic QA acceptance checks.
+- Dispatch an isolated Review subagent for material/critical changes.
+- Settle the completed proof into `.imm/audit/<task-id>/`.
 
 ---
 
 ## How to Use
 
-You rarely need to remember skill names — **just describe your intent**:
+Immune-Brain provides two clean modes: **Host-native** for daily coding, and **Managed Path** for structured, high-assurance tasks:
 
 | Your situation | What to say / do | What happens |
 |---|---|---|
-| Idea is fuzzy, needs scoping | "Help me think through a notification system" | → `imm-brainstorm` clarifies questions, no code changes |
-| Goal is clear, needs a plan | "Plan the dark-mode feature" or let Pi route there | → `imm-planner` writes `TaskIntent` + specs in `docs/plans/` |
-| Plan is approved, ready to build | "Start building" / `imm-loop` | → Executor builds, QA verifies, Review checks |
-| A published Initiative is ready to run | "Run initiative `<slug>` unattended" | → Host's `start_unattended_batch`: one native confirmation covers the ordered plan digest, children run serially |
-| PR needs fixes after review | `imm-pr-fix` on that PR | → Standalone repair, no new managed task |
-| Docs are stale after changes | `imm-doc-prune` with manifest | → Prunes only approved stale docs |
-| Agent instruction files are bloated | `imm-agent-doc-maintain` with manifest | → Keeps only necessary non-discoverable rules |
-
-> **Rule:** Managed work (brainstorm → plan → loop) starts only from explicit `imm-brainstorm`, `imm-planner`, or `imm-loop`. Ordinary Q&A or read-only requests stay host-native and never enroll a task.
+| Daily coding, quick fix, general Q&A | Normal conversation ("Fix typo in README", "Explain this function") | **Host-native**: Standard Pi / Claude Code behavior. Zero workflow overhead. |
+| Fuzzy idea, needs scoping & risk analysis | `/imm-brainstorm` "Help me think through webhook support" | → `imm-brainstorm` frames requirements, constraints, and risks (read-only, no code edits) |
+| Clear goal, want formal plan & specs | `/imm-planner` "Plan the webhook feature" | → `imm-planner` writes `TaskIntent` + Specs with testable acceptance checks |
+| Plan confirmed, ready to build & verify | `/imm-loop` | → Executor builds within scope → deterministic QA verifies → isolated Review checks → task settles |
+| Session interrupted or resuming a task | `/imm-loop` | → Resumes existing task seamlessly from on-disk state (`.imm/`) |
+| Ready Initiative to run unattended | "Run initiative `<slug>` unattended" | → Host's `start_unattended_batch`: one native confirmation covers ordered plan digest, children run serially |
+| PR has review comments or failing CI | `/imm-pr-fix` on that PR | → Standalone repair: minimal scoped fix in place, no managed task created |
+| Project docs out of date | `/imm-doc-prune` | → Read-only audit; deletes only user-approved stale docs from manifest |
+| Agent instructions bloated | `/imm-agent-doc-maintain` | → Minimizes tracked `AGENTS.md` / `CLAUDE.md` to essential non-discoverable rules |
+| Which model's edits keep coming back for review | `/imm-review-retro` | → Ranks models by review load and reports project usage from session logs |
+
+> **Core Principle: Skill-Explicit Entry**
+> - **Ordinary input stays host-native**: Natural language queries never automatically start planning or task enrollment. You choose when to turn on engineering rigor.
+> - **Managed work starts with explicit skills**: Use `imm-brainstorm` to clarify, `imm-planner` to plan, and `imm-loop` to execute and resume.
 
 ---
 
-## The 6 Skills
+## The 7 Skills
 
 | Skill | Type | When to use | What it does |
 |---|---|---|---|
@@ -106,10 +137,11 @@ You rarely need to remember skill names — **just describe your intent**:
 | `imm-pr-fix` | Standalone | CI failed / review comments on a PR | Repairs one PR in place, no managed authority |
 | `imm-doc-prune` | Standalone | Stale current docs | Deletes only the hash-approved manifest entries |
 | `imm-agent-doc-maintain` | Standalone | Bloated agent instructions | Minimizes tracked AGENTS/CLAUDE/GEMINI.md to necessary context |
+| `imm-review-retro` | Standalone | Compare models by review load | Ranks authors of reviewed code and reports project usage |
 
 Internal roles (Executor, QA, Review, Compounder) are dispatched by `imm-loop` — you never invoke them directly.
 
-**Recommended default:** let natural-language routing pick brainstorm vs. planner for you. Explicitly invoke a skill only when you want to force that phase.
+All 7 skills are invoked explicitly. For new features, start with `imm-brainstorm` (if requirements are uncertain) or `imm-planner` (if requirements are clear), then proceed to `imm-loop` once enrolled.
 
 ### Managed Path entries (brainstorm → planner → loop)
 
@@ -117,21 +149,21 @@ The three Managed skills form one continuous pipeline with a single authority mo
 
 #### `imm-brainstorm` — requirement clarification
 
-- **Trigger:** explicit `imm-brainstorm`, or a vague request Pi routes to clarification.
+- **Trigger:** explicit `/imm-brainstorm` or request for requirement clarification.
 - **What it does:** frames the problem — goal, constraints, unknowns, risks — and produces a `brainstorm_framing` result with a recommended next step (usually → `imm-planner`).
 - **What it never does:** read-only by design. No code, test, or runtime edits; no Spec, Plan, or workflow-state writes.
 - **Exit:** a framed, answerable problem statement you can hand to the Planner.
 
 #### `imm-planner` — Spec & TaskIntent planning
 
-- **Trigger:** explicit `imm-planner`, or a clear goal Pi routes to planning.
+- **Trigger:** explicit `/imm-planner` or request for Spec & TaskIntent planning.
 - **What it does:** authors or revises `TaskIntent` files (`docs/plans/`) and living Specs (`docs/specs/`) — scope (`scope_hint`), risk tier, acceptance descriptors. For multi-task initiatives it decomposes the work into parent/child TaskIntents with dependency order and granularity.
 - **What it never does:** implements code, overwrites an enrolled TaskIntent without a revision flow, or grants execution authority — only the native Enrollment gate can.
 - **Exit:** Git-tracked `TaskIntent` awaiting enrollment confirmation.
 
 #### `imm-loop` — managed execution & assurance
 
-- **Trigger:** explicit `imm-loop` (start, resume, or check a managed task).
+- **Trigger:** explicit `/imm-loop` (start, resume, or check a managed task).
 - **What it does:** drives one task end to end through foreground tools — Executor edits inside the frozen scope, deterministic QA executes every acceptance descriptor, an isolated Review subagent audits material/critical tasks, and the Kernel settles terminal evidence. Interrupted workflows resume from on-disk state; the Kernel projection is authoritative.
 - **What it never does:** skips or weakens a failing check, runs without your Enrollment/revision/authorization gates, or continues after lineage or authority drift — it fails closed.
 - **Finding evidence:** every Review finding carries machine-checkable provenance (`trigger`, `caller_chain`, `violated`). A claim that fresh passing QA evidence already contradicts is recorded as `refuted` and only blocks again if that evidence goes stale.
@@ -157,24 +189,37 @@ The three repair/maintenance skills are host-native: they never create a managed
 - **Trigger:** explicit request to minimize tracked `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`.
 - **What it does:** keeps only the necessary non-discoverable rules in agent instruction files, under the same read-only-audit + hash-bound-manifest-approval model as `imm-doc-prune`.
 
+#### `imm-review-retro` — review load and project usage
+
+- **Trigger:** explicit request for a cross-model review retro or project usage look-back.
+- **What it does:** ranks models by how much review their own edits triggered, plus sessions/turns/edits/tool mix, from pi session logs. Read-only. Not a diff review.
+
 ---
 
 ## Lifecycle
 
 ```
-You: natural language request
-        │
-        ├─── vague ──→ imm-brainstorm (clarify, no edits)
-        │
-        └─── clear ──→ imm-planner ──→ TaskIntent (Git-tracked)
-                              │
-                         TUI confirm (enrollment)
-                              │
-                          imm-loop
-                              ├── Executor (edits inside scope)
-                              ├── QA (deterministic checks must pass)
-                              ├── Review (material/critical: isolated subagent)
-                              └── done
+Ordinary request: normal coding / Q&A (Host-native, zero overhead)
+                       │
+Explicit skill call (/imm-brainstorm or /imm-planner)
+                       │
+        ┌──────────────┴──────────────┐
+        ▼                             ▼
+  imm-brainstorm                 imm-planner
+(clarify requirements,         (author Spec + TaskIntent,
+  read-only framing)             define acceptance checks)
+        │                             │
+        └──────────────┬──────────────┘
+                       ▼
+            Native Host Confirmation
+        (Pi TUI dialog / Claude MCP elicitation)
+                       │
+                       ▼
+                    imm-loop
+        ├── Executor (edits strictly inside scope)
+        ├── Deterministic QA (runs all acceptance checks)
+        ├── Isolated Review (independent subagent audit)
+        └── Settled (.imm/audit/<task-id>/)
 ```
 
 Key invariants:
@@ -227,7 +272,7 @@ See [`docs/reference/immune-brain-config.md`](docs/reference/immune-brain-config
 package.json                          # Pi package manifest (skills + extensions)
 plugins/immune-brain/
 ├── .pi-extension/                    # Pi TUI + Kernel authority extension
-├── skills/                           # 6 public Skills (trigger shims)
+├── skills/                           # 7 public Skills (trigger shims)
 ├── dist/                             # Built skill contracts & references
 ├── runtime/                          # Bun + TypeScript runtime & Kernel
 └── bin/                              # CLI wrappers (→ runtime/v4_runtime.ts)
@@ -245,11 +290,11 @@ docs/specs/                           # Living specs (updated in place)
 
 ## FAQ
 
-**Do I need to learn all 6 skills?** No. Just describe what you want — Pi routes to the right skill. Learn `imm-planner` and `imm-loop` first; the other four are occasional.
+**Do I need to learn all 6 skills?** No. Most of the time you only need `/imm-planner` (to plan and enroll a task) and `/imm-loop` (to build and verify it). Use `imm-brainstorm` when requirements need clarifying first, and the maintenance skills (`imm-pr-fix`, etc.) only when specific repair needs arise. Ordinary chat and simple edits don't need any skills at all.
 
-**What if I interrupt or close Pi mid-task?** State is on disk (`.imm/` + TaskIntent). Re-enter `imm-loop` to resume — the Kernel projection is authoritative.
+**What if I interrupt or close the session mid-task?** State is safely stored on disk (`.imm/` + TaskIntent). In Pi or Claude Code, simply re-enter `/imm-loop` to resume — the Kernel projection is authoritative.
 
-**Why does enrollment show a TUI dialog?** All risk levels (`routine`/`material`/`critical`) require explicit confirmation. It binds the staged digest so you see exactly what will be tracked.
+**Why does enrollment show a confirmation dialog?** All risk levels (`routine`/`material`/`critical`) require explicit human confirmation before execution authority is granted. In Pi, this is a native TUI modal dialog; in Claude Code, it is a native MCP elicitation gate. It binds the staged digest so you see exactly what will be tracked.
 
 **QA failed — what now?** QA returns `rework` or `replan_required`. `imm-loop` routes back to the executor or to `imm-planner` for scope changes. No manual reset needed.
 
@@ -257,7 +302,7 @@ docs/specs/                           # Living specs (updated in place)
 
 **Can it run a whole Initiative without me?** Only as far as you authorize. Confirm `start_unattended_batch` with the Initiative slug and the runner works through the published, non-`critical` children serially on one batch branch — parking as soon as a child needs a human decision or the run hits a budget, deadline, authorization, or commit failure. It never pushes, opens PRs, or settles user decisions for you.
 
-**Can I use it outside Pi?** Yes. Local interactive Claude Code is supported from version `2.1.236`; its plugin uses a digest-bound native MCP elicitation gate for the same Kernel-backed workflow.
+**Which AI coding assistants are supported?** Pi and Claude Code are the supported hosts (Claude Code version >= `2.1.236`). Both hosts run on the exact same Kernel authority, assurance guarantees, and multi-skill pipeline.
 
 ---
 
@@ -283,7 +328,7 @@ npm publish --access public   # requires npm login / NPM_TOKEN
 # or
 bun run changeset:publish
 ```
-The package publishes to npm as `immune-brain` (current release `3.6.6`) with `publishConfig.access=public` already set. After the initial publish, all future releases go through changesets.
+The package publishes to npm as `immune-brain` (current release `3.6.7`) with `publishConfig.access=public` already set. After the initial publish, all future releases go through changesets.
 
 See `CHANGELOG.md` and `.changeset/config.json` (changelog: `@changesets/changelog-github`, repo: `dereknex/immune-brain`).
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # Immune-Brain
 
-> 面向 [Pi](https://github.com/badlogic/pi) 的确定性工程工作流与质量保障引擎 — 把模糊想法变成可交付代码，覆盖规划、执行、QA 与审查。
+> 面向 [Pi](https://github.com/badlogic/pi) 与 [Claude Code](https://claude.ai/code) 的确定性工程工作流与质量保障引擎 — 把模糊想法变成可交付代码，覆盖规划、执行、QA 与审查。
 
 **语言：** [English](./README.md) | **中文**
 
@@ -8,11 +8,12 @@
 
 ## 这是什么？
 
-Immune-Brain 在 Pi 之上提供结构化的工程工作流：
+Immune-Brain 为 AI 编程工具（**Pi** 与 **Claude Code**）提供结构化的工程工作流保障：
 
-- **你用自然语言描述需求**，Agent 自动判断是先澄清、先规划，还是直接执行。
-- **计划变为可追踪的任务**（`TaskIntent` + `TaskRecord`），进度落盘持久化，不依赖对话历史。
-- **质量由代码强制保障** — 自动化 QA 与隔离式 Review 必须通过，任务才会完成。
+- **日常对话零负担** — 普通问答、单点代码修改与探索性对话完全保持 Host 原生体验，不拦截、不强加流程。
+- **需要严谨时显式启用** — 遇到复杂功能开发或高保证任务时，显式调用 `imm-brainstorm`、`imm-planner` 或 `imm-loop`。
+- **计划变为可追踪的任务**（`TaskIntent` + `TaskRecord`） — 进度落盘持久化（Git + `.imm/`），会话重启或上下文清理后仍可无缝恢复。
+- **质量由代码强制保障** — 自动化 QA 验收与隔离式 Reviewer 审查必须通过，任务才会结算完成。
 - **已就绪的 Initiative 可以整批运行** — 一次确认的 Batch Authorization 让 `imm-loop` 串行推进已发布 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/`。
@@ -24,7 +25,7 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 - [安装](#安装)
 - [快速开始](#快速开始)
 - [如何使用](#如何使用)
-- [6 个 Skills](#6-个-skills)
+- [7 个 Skills](#7-个-skills)
 - [生命周期](#生命周期)
 - [无人值守批次运行](#无人值守批次运行)
 - [配置](#配置)
@@ -36,9 +37,11 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 
 ## 安装
 
-**前置要求：** 已安装 [Pi](https://github.com/badlogic/pi)、Node.js 20+、`bun`（用于测试）。
+**前置要求：** 已安装 [Pi](https://github.com/badlogic/pi) 或 [Claude Code](https://claude.ai/code)（>= 2.1.236）、Node.js 20+、`bun`（用于测试）。
 
-本仓库是一个 Pi Package，Pi 通过 `package.json` 自动发现 Skills 与扩展：
+### 在 Pi 中使用
+
+Pi 通过 `package.json`（或全局 Pi 配置）自动发现 Skills 与扩展：
 
 ```json
 // package.json → pi.skills / pi.extensions
@@ -48,7 +51,24 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 }
 ```
 
-无需额外 server 配置，通过 Pi 安装本 package 后 6 个 Skill 即自动可用。验证：
+无需额外 server 配置，通过 Pi 安装本 package 后 6 个 Skill 即自动可用。
+
+### 在 Claude Code 中使用
+
+从 Marketplace 安装插件：
+
+```bash
+claude plugin marketplace add dereknex/immune-brain
+claude plugin install immune-brain
+```
+
+或在本地开发时直接加载插件目录：
+
+```bash
+claude --plugin-dir ./plugins/immune-brain
+```
+
+### 验证安装
 
 ```bash
 bun test                    # 全量测试
@@ -60,43 +80,54 @@ mise run check-dist-sync    # 校验生成文档同步
 
 ## 快速开始
 
-**1. 用自然语言描述你要做的改动：**
-
-> "给设置页加上深色模式"
+Immune-Brain 遵循 **显式 Skill 触发（Skill-explicit）** 模型：日常对话就是轻量自然的 AI 编程，只有显式调用对应 Skill 时才会开启严格工程管理。
 
-Pi 会自动路由：需求模糊走澄清，目标明确走规划。
+**1. 当你需要严谨工程流程时，显式调用 Skill：**
+- 需求模糊想先梳理？输入 `/imm-brainstorm`（或对 Agent 说 "用 imm-brainstorm 梳理需求"）。
+- 目标明确准备制定方案？输入 `/imm-planner`（或对 Agent 说 "用 imm-planner 规划深色模式功能"）。
 
-**2. 确认计划** — Planner 会在 `docs/plans/` 生成 `TaskIntent`（范围、风险等级、验收条件）。检查无误后由当前 Host 的原生 gate 确认 Enrollment（所有风险等级都需要确认，确认前零 authority 写入）。
+*(日常提问如 "这个函数什么意思"、"改个 typo" 保持完全原生，没有任何流程弹窗和开销。)*
 
-**3. 开始执行** — `imm-loop` 按计划执行、跑 QA、触发 Review。按提示暂存任务拥有的文件：
+**2. 确认计划：**
+Planner 会在 `docs/plans/` 生成 `TaskIntent` 与 living Spec（锁定文件范围、风险等级与自动化验收条件）。随后弹出当前 Host 的原生确认界面：
+- 在 **Pi** 中：原生 TUI 对话框；
+- 在 **Claude Code** 中：原生 MCP elicitation 确认弹窗。
 
-```bash
-git add -- <任务拥有的文件> <另一个文件>
-```
+检查无误并确认后，才会正式锁定范围并开放执行权限。
 
-QA 与 Review 以 foreground Tool 形式运行并回传结果，返回 `phase=done` 即完成。
+**3. 用 `imm-loop` 自动执行与验收：**
+输入 `/imm-loop`（或 "开始 imm-loop"），工作流引擎会自动：
+- 调度 Executor 仅在锁定的 scope 范围内编写代码。
+- 自动运行确定性 QA 验收命令。
+- 对 material/critical 任务分发隔离的 Reviewer 子代理审查代码。
+- 全部通过后落盘结算凭证至 `.imm/audit/<task-id>/`，任务完成。
 
 ---
 
 ## 如何使用
 
-大多数情况下**无需记忆 Skill 名称**，直接描述意图即可：
+Immune-Brain 提供两种清晰的工作模式：日常轻量编码走 **Host-native**，复杂高保证任务走 **Managed Path**：
 
-| 你的情况 | 你说什么 / 做什么 | 会发生什么 |
+| 你的情况 | 你做什么 / 说什么 | 会发生什么 |
 |---|---|---|
-| 想法模糊，需要收敛 | "帮我梳理一下通知系统的方案" | → `imm-brainstorm` 提问澄清，不改代码 |
-| 目标明确，需要计划 | "规划一下深色模式功能" 或让 Pi 自动路由 | → `imm-planner` 产出 `TaskIntent` + spec |
-| 计划已确认，准备开干 | "开始构建" / `imm-loop` | → Executor 构建 → QA 验证 → Review 审查 |
+| 日常编码、快速改动、普通问答 | 正常自然语言对话（"帮我改下文案"、"解释这段代码"） | **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 为准 |
 | 已发布的 Initiative 可以整批跑了 | "把 initiative `<slug>` 无人值守跑完" | → Host 的 `start_unattended_batch`：一次原生确认绑定有序 plan digest，child 串行执行 |
-| PR 被评论 / CI 挂了 | 对该 PR 使用 `imm-pr-fix` | → 独立修复，不创建新 managed 任务 |
-| 文档过时需要清理 | `imm-doc-prune` + manifest | → 仅删除已审批的过时文档 |
-| Agent instruction 文件膨胀 | `imm-agent-doc-maintain` + manifest | → 只保留不可直接推导的必要规则 |
+| 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 汇报项目使用量 |
 
-> **规则：** Managed 工作流（brainstorm → plan → loop）仅由显式的 `imm-brainstorm`、`imm-planner`、`imm-loop` 启动。普通问答、只读解释不会 Enrollment。
+> **核心原则：Skill 显式调用**
+> - **普通输入保持 Host-native**：自然语言提问绝不自动绑架流程或发起 Enrollment。你完全自主决定何时开启严格工程保障。
+> - **Managed 工作流显式启动**：需要澄清用 `imm-brainstorm`，制定计划用 `imm-planner`，执行与恢复用 `imm-loop`。
 
 ---
 
-## 6 个 Skills
+## 7 个 Skills
 
 | Skill | 类型 | 何时使用 | 职责 |
 |---|---|---|---|
@@ -106,29 +137,89 @@ QA 与 Review 以 foreground Tool 形式运行并回传结果，返回 `phase=do
 | `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` | 独立 | 比较模型的审查负载 | 排名被审查代码的作者并汇报项目使用量 |
 
 Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，无需手动调用。
 
-**推荐默认：** 让自然语言路由自动选择 brainstorm 还是 planner，仅在想强制进入某阶段时才显式调用 Skill。
+所有 7 个 Skill 均显式调用。新需求开发时：若需求含糊先调 `imm-brainstorm`，目标清晰直接调 `imm-planner`，完成确认后调 `imm-loop` 推进闭环。
+
+### Managed Path 入口（brainstorm → planner → loop）
+
+这三个 Managed Skill 组成连续的工作流管道，拥有统一的 authority 模型：在你于原生确认窗口授权前绝不执行任何写入，每一次状态转换均由 Kernel 权威结算。
+
+#### `imm-brainstorm` — 需求与问题澄清
+
+- **触发方式：** 显式调用 `/imm-brainstorm` 或明确提出需求澄清。
+- **职责：** 梳理问题框架 — 目标、约束、未知项与风险 — 产出 `brainstorm_framing` 结论及下一步建议（通常指向 `imm-planner`）。
+- **边界：** 纯只读设计。不修改代码、不修改测试、不写入运行态、不创建 Spec 或 TaskIntent。
+- **产出：** 结构清晰、可解答的问题框架，作为 Planner 的输入。
+
+#### `imm-planner` — Spec 与 TaskIntent 规划
+
+- **触发方式：** 显式调用 `/imm-planner` 或明确提出规划请求。
+- **职责：** 编写或修订 `TaskIntent` 文件（`docs/plans/`）与 living Spec（`docs/specs/`） — 划定文件范围（`scope_hint`）、风险等级与验收条件。对于多任务 Initiative，负责按依赖顺序和粒度拆解为 parent/child TaskIntent。
+- **边界：** 不编写业务实现代码、不经 revision 流程不覆盖已 Enrolled 的 TaskIntent，不擅自赋予执行权限 — 仅当前 Host 原生确认窗口具备授权能力。
+- **产出：** 纳入 Git 版本控制、等待 Enrollment 确认的 `TaskIntent`。
+
+#### `imm-loop` — Managed 执行与质量保障
+
+- **触发方式：** 显式调用 `/imm-loop`（启动、恢复或检查 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`，仅在证据过期时才会重新阻塞。
+- **产出：** 带有完整 QA + Review 签批、保存在 `.imm/audit/<task-id>/` 的 `done` 状态 TaskRecord。
+
+### 独立维护入口
+
+三个维护类 Skill 保持 Host-native：不创建 managed 任务、不推进 Managed 工作流、尊重已有的 Managed owner。
+
+#### `imm-pr-fix` — PR 修复
+
+- **触发方式：** 显式要求修复 GitHub PR 的 review 意见、合并冲突或 CI 失败。
+- **职责：** 原地修复单个 PR — 诊断 review/冲突/CI 证据，实施最小范围修复，并重跑相关检查。
+- **边界：** 严格限定在 PR 原有范围内；将远端文本视为不可信数据；修复不授予合入或批准权限。
+
+#### `imm-doc-prune` — 过时文档清理
+
+- **触发方式：** 显式要求清理当前过时的文档。
+- **职责：** 只读审计文档时效性，根据用户明确审批的哈希绑定 manifest 进行精准删除，每次修改后立即重验。
+
+#### `imm-agent-doc-maintain` — Agent 指令文件瘦身
+
+- **触发方式：** 显式要求精简版本控制下的 `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`。
+- **职责：** 遵循与 `imm-doc-prune` 相同的「只读审计 + 哈希清单审批」模式，仅保留无法直接推导的必要规则。
+
+#### `imm-review-retro` — 审查负载与项目使用回顾
+
+- **触发方式：** 显式要求跨模型审查复盘或项目使用量回顾。
+- **职责：** 从 pi session logs 按模型排名被审查代码的作者，并汇报 sessions/turns/编辑量/工具分布。只读；不审查 diff。
 
 ---
 
 ## 生命周期
 
 ```
-你：自然语言请求
-        │
-        ├── 模糊 ──→ imm-brainstorm（澄清，不改代码）
-        │
-        └── 明确 ──→ imm-planner ──→ TaskIntent（Git-tracked）
-                              │
-                         TUI 确认（enrollment）
-                              │
-                          imm-loop
-                              ├── Executor（仅在 scope 内编辑）
-                              ├── QA（确定性检查必须通过）
-                              ├── Review（material/critical：隔离 subagent）
-                              └── done
+普通请求：日常编程 / 问答（Host-native，零流程开销）
+                       │
+显式调用 Skill（/imm-brainstorm 或 /imm-planner）
+                       │
+        ┌──────────────┴──────────────┐
+        ▼                             ▼
+  imm-brainstorm                 imm-planner
+（澄清需求、约束与风险，        （编写 Spec + TaskIntent，
+  只读输出 framing）             定义可自动化验证的验收条件）
+        │                             │
+        └──────────────┬──────────────┘
+                       ▼
+               当前 Host 原生确认
+        （Pi TUI 弹窗 / Claude MCP elicitation）
+                       │
+                       ▼
+                    imm-loop
+        ├── Executor（严格在 scope 内修改代码）
+        ├── 确定性 QA（前台逐项执行验收命令）
+        ├── 隔离式 Review（独立 subagent 审查代码）
+        └── 落盘结算（.imm/audit/<task-id>/）
 ```
 
 核心不变量：
@@ -199,11 +290,11 @@ docs/specs/                           # Living specs（原地更新）
 
 ## 常见问题
 
-**需要记住所有 Skill 吗？** 不需要，直接描述需求即可，Pi 会自动路由。先掌握 `imm-planner` 和 `imm-loop`，另外四个按需使用。
+**需要记住所有 Skill 吗？** 不需要。日常开发核心只需两个：`/imm-planner`（规划与确认任务）和 `/imm-loop`（执行与验证）。需求模糊时用 `/imm-brainstorm`，维护类任务（如 `/imm-pr-fix`）按需使用。普通问答与即时小修改无需任何 Skill。
 
-**中途关闭 Pi 会怎样？** 状态已落盘（`.imm/` + TaskIntent），重新进入 `imm-loop` 即可恢复，以 Kernel projection 为准。
+**中途关闭会话会怎样？** 状态已落盘保存（`.imm/` + TaskIntent）。在 Pi 或 Claude Code 中重新输入 `/imm-loop` 即可恢复，以 Kernel projection 状态为准。
 
-**为什么 enrollment 要弹窗确认？** 所有风险等级（`routine`/`material`/`critical`）都需要显式确认，弹窗绑定 staged digest，让你清楚看到将被追踪的内容。
+**为什么 enrollment 要弹窗确认？** 所有风险等级（`routine`/`material`/`critical`）在获得执行授权前都必须经由人工显式确认。在 Pi 中是原生 TUI 对话框，在 Claude Code 中是原生 MCP elicitation 弹窗。确认界面绑定 staged digest，让你清楚看到被锁定的文件范围和验收要求。
 
 **QA 失败怎么办？** QA 返回 `rework` 或 `replan_required`，`imm-loop` 会自动路由回 Executor 或 `imm-planner` 调整范围，无需手动重置。
 
@@ -211,7 +302,7 @@ docs/specs/                           # Living specs（原地更新）
 
 **能不能整个 Initiative 不用我盯着？** 只能在你授权范围内。用 Initiative slug 确认 `start_unattended_batch` 后，runner 会在一个 batch 分支上串行推进已发布且非 `critical` 的 child — 一旦某个 child 需要人决策，或遇到预算/截止时间/授权/提交失败就暂停。它不会替你 push、开 PR 或结算用户决策。
 
-**可以在 Pi 之外使用吗？** 可以从 `2.1.236` 起在本地交互式 Claude Code 中使用同一套 Kernel；Claude plugin 通过绑定 digest 的原生 MCP elicitation gate 获取 authority，未声明的适配器不受支持。
+**支持哪些 AI 编程工具？** Pi 与 Claude Code 是支持的宿主（Claude Code 最低版本为 `2.1.236`）。两者共享同一套确定性 Kernel 核心、质量保障机制与工具链。
 
 ---
 
@@ -237,7 +328,7 @@ npm publish --access public   # 需 npm login / NPM_TOKEN
 # 或
 bun run changeset:publish
 ```
-包名为 `immune-brain`（当前版本 `3.6.6`），已配置 `publishConfig.access=public`。首次发布后，后续所有版本均通过 changesets 管理。
+包名为 `immune-brain`（当前版本 `3.6.7`），已配置 `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": "3.6.7",
+  "version": "3.6.9",
   "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": "3.6.7",
+  "version": "3.6.9",
   "description": "Immune-Brain Claude Code Host: native Enrollment, QA, Review, and Kernel settlement.",
   "author": {
     "name": "Immune-Brain Team"

package/plugins/immune-brain/.pi-extension/package.json

@@ -1,11 +1,12 @@
 {
   "name": "immune-brain-pi-extension",
   "private": true,
-  "description": "Explicit extension entry manifest for the Immune-Brain Pi lifecycle Tools. Helper modules in this directory are library code, not extension factories; listing only the two factory files here prevents Pi's directory discovery from loading them as extensions.",
+  "description": "Explicit extension entry manifest for the Immune-Brain Pi lifecycle Tools. Helper modules in this directory are library code, not extension factories; listing only the three factory files here prevents Pi's directory discovery from loading them as extensions.",
   "pi": {
     "extensions": [
       "./imm-canary-enroll.ts",
-      "./imm-canary-work.ts"
+      "./imm-canary-work.ts",
+      "./imm-unattended-batch.ts"
     ]
   }
 }