immune-brain 4.3.0 → 4.4.0

package/README.md

@@ -116,6 +116,7 @@ Immune-Brain provides two clean modes: **Host-native** for daily coding, and **M
 | 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 |
+| Cross-host workflow (Claude plan + Pi code) | Run `/imm-planner` in Claude Code, switch to Pi and run `/imm-loop` | → Staged Spec & TaskIntent are shared on disk; Pi confirms via native TUI and executes loop |
 | 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 |
@@ -125,6 +126,40 @@ Immune-Brain provides two clean modes: **Host-native** for daily coding, and **M
 > - **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.
 
+### Cross-Host Workflow: Plan in Claude Code, Build in Pi
+
+Immune-Brain is architected to be completely session-neutral. All task contracts, specifications, and assurance evidence live on disk in Git-tracked files (`docs/plans/`, `docs/specs/`) and `.imm/`. Pi and Claude Code share the exact same deterministic Kernel authority and state machine.
+
+This enables a best-of-both-worlds workflow: **leverage Claude Code's deep reasoning and large context window for requirement analysis and Spec planning, then switch to Pi for fast, focused foreground coding and execution loops**.
+
+```text
+┌───────────────────────────────────┐    Git-Tracked Artifacts on Disk   ┌───────────────────────────────────┐
+│            Claude Code            │ ─────────────────────────────────> │                Pi                 │
+│  1. /imm-brainstorm (Clarify)     │        docs/specs/*.spec.md        │  1. /imm-loop (Native TUI Modal)  │
+│  2. /imm-planner    (Spec/Intent) │       docs/plans/*.intent.json     │  2. Executor (Code) + QA Engine   │
+└───────────────────────────────────┘                                    └───────────────────────────────────┘
+```
+
+#### Recommended Workflow
+
+1. **Phase 1: Spec Authoring & Planning in Claude Code**
+   - **Clarify requirements (optional)**: If the problem is fuzzy or has unknown boundaries, run `/imm-brainstorm` in Claude Code to frame goals, constraints, and architecture risks.
+   - **Author the plan and spec**: Run `/imm-planner "Plan <feature>"`. Planner generates:
+     - Living Spec (`docs/specs/<name>.spec.md`): records the technical design and architectural trade-offs.
+     - `TaskIntent` (`docs/plans/<task-id>.intent.json`): strictly locks down the editable file boundary (`scope_hint`), risk tier (`routine` / `material` / `critical`), and deterministic test verification commands (`acceptance`).
+   - **Stage in Git**: Stage the generated artifacts (`git add docs/`). You can stop before Enrollment without executing.
+2. **Phase 2: Code Implementation & Execution in Pi**
+   - **Launch Pi**: Open Pi in the same repository workspace.
+   - **Enroll & run**: Enter `/imm-loop`. Pi discovers the staged `TaskIntent` and opens its native TUI modal confirmation for Enrollment.
+   - **Automated loop**:
+     - **Executor** writes implementation code strictly inside `scope_hint`.
+     - **Deterministic QA engine** directly runs acceptance commands against exit codes.
+     - For `material` or `critical` tasks, Pi foreground Reviewer audits changes.
+     - Upon pass, Kernel atomically settles terminal audit records in `.imm/audit/<task-id>/` and releases the workspace claim.
+3. **Why Cross-Host Switching Works Seamlessly**
+   - **Session-neutral state**: All contracts and authority records live in the repository and local SQLite CAS, completely independent of any individual AI chat session.
+   - **Bidirectional resumption**: Interrupted tasks can be resumed at any point in either Pi or Claude Code with `/imm-loop`.
+
 ---
 
 ## The 7 Skills
@@ -328,6 +363,8 @@ 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 switch between hosts (e.g. plan in Claude Code, code in Pi)?** Yes. Immune-Brain's contracts and state live entirely on disk in the repository, decoupled from conversation sessions. You can leverage Claude Code for deep architectural thinking and Spec planning, then switch to Pi to run `imm-loop` for code execution and deterministic QA. Interrupted tasks can be resumed in either host at any time.
+
 **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.
 
 ---

package/README.zh-CN.md

@@ -116,6 +116,7 @@ Immune-Brain 提供两种清晰的工作模式：日常轻量编码走 **Host-na
 | 计划已确认，准备执行与验证 | `/imm-loop` | → Executor 在范围内实现 → 确定性 QA 验收 → 隔离 Review 审查 → 任务结算 |
 | 会话中断或需恢复未完成任务 | `/imm-loop` | → 从磁盘状态（`.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 闭环 |
 | PR 被评论 / CI 挂了 | 对该 PR 使用 `/imm-pr-fix` | → 独立修复：在当前 PR 内针对性修复，不创建新 managed 任务 |
 | 文档过时需要清理 | `/imm-doc-prune` | → 只读审计过时文档，仅删除经哈希审批的条目 |
 | Agent 指令文件膨胀 | `/imm-agent-doc-maintain` | → 将 tracked `AGENTS.md` / `CLAUDE.md` 压到最小必要上下文 |
@@ -125,6 +126,40 @@ Immune-Brain 提供两种清晰的工作模式：日常轻量编码走 **Host-na
 > - **普通输入保持 Host-native**：自然语言提问绝不自动绑架流程或发起 Enrollment。你完全自主决定何时开启严格工程保障。
 > - **Managed 工作流显式启动**：需要澄清用 `imm-brainstorm`，制定计划用 `imm-planner`，执行与恢复用 `imm-loop`。
 
+### 跨 Host 协作：Claude Code 规划 + Pi 编码执行
+
+Immune-Brain 的核心状态与契约完全去会话化（Session-neutral），所有规划与审计证据均落盘在 Git 仓库（`docs/plans/`、`docs/specs/`）与 `.imm/` 中。Pi 与 Claude Code 共享完全一致的确定性 Kernel 核心与状态机。
+
+你可以自由组合两个宿主的优势：**利用 Claude Code 的深度推理与长上下文能力进行需求澄清、Spec 撰写与任务规划，切换到 Pi 中进行极速的前台编码、确定性 QA 验收与审查闭环**。
+
+```text
+┌───────────────────────────────────┐    Git 追踪制品（落盘共享）    ┌───────────────────────────────────┐
+│         Claude Code 终端          │ ───────────────────────────> │              Pi 终端              │
+│  1. /imm-brainstorm (澄清与约束)    │     docs/specs/*.spec.md     │  1. /imm-loop (原生 TUI 弹窗准入)   │
+│  2. /imm-planner    (编写计划/规格) │    docs/plans/*.intent.json  │  2. Executor 编码 + QA 自动化验收   │
+└───────────────────────────────────┘                              └───────────────────────────────────┘
+```
+
+#### 推荐协作步骤
+
+1. **在 Claude Code 中制定 Spec 与任务规划**
+   - **需求澄清（可选）**：若需求复杂或边界模糊，先在 Claude Code 中运行 `/imm-brainstorm`，梳理目标、约束与架构风险。
+   - **编写计划与规格**：运行 `/imm-planner "规划 <需求名称>"`。Planner 会生成：
+     - Living Spec（`docs/specs/<name>.spec.md`）：记录设计方案、架构决策与模块边界。
+     - `TaskIntent`（`docs/plans/<task-id>.intent.json`）：严格锁定可修改的文件范围（`scope_hint`）、风险等级（`routine` / `material` / `critical`）以及可执行的自动化验收命令（`acceptance`）。
+   - **暂存至 Git**：规划完成后停在 Enrollment 之前，将生成的 Spec 和 TaskIntent 加入 Git 暂存（`git add docs/`）。
+2. **切换到 Pi 中进行代码编写与闭环执行**
+   - **启动 Pi**：在同一个项目工作区中打开 Pi。
+   - **确认准入并执行**：运行 `/imm-loop`。Pi 会自动检测到暂存的 `TaskIntent`，并在 Pi 原生 TUI 弹窗中提示 Enrollment 确认。
+   - **自动执行与验收**：
+     - Executor 角色严格在 `scope_hint` 限定的文件内编写代码。
+     - Kernel 自动运行 acceptance 命令进行确定性 QA 验收，不依赖口头汇报。
+     - 若为 `material` 或 `critical` 任务，自动调度前台 Reviewer 审查。
+     - 验证全部通过后，Kernel 原子落盘证据至 `.imm/audit/<task-id>/` 并释放工作区锁定。
+3. **为什么可以无缝切换？**
+   - **状态落盘，解耦会话**：所有任务契约（TaskIntent）、设计规格（Spec）和执行状态（`.imm/state/kernel.sqlite`）均持久化在磁盘上，不绑定任何特定 AI 会话的上下文。
+   - **双向断点恢复**：无论在哪个 Host 暂停或关闭会话，随时可以在 Pi 或 Claude Code 中重新输入 `/imm-loop` 无缝恢复，Kernel projection 确保进度与证据不丢失。
+
 ---
 
 ## 7 个 Skills
@@ -328,6 +363,8 @@ docs/specs/                           # Living specs（原地更新）
 
 **能不能整个 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` 双向恢复。
+
 **支持哪些 AI 编程工具？** Pi 与 Claude Code 是支持的宿主（Claude Code 最低版本为 `2.1.236`）。两者共享同一套确定性 Kernel 核心、质量保障机制与工具链。
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "4.3.0",
+  "version": "4.4.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.3.0",
+  "version": "4.4.0",
   "description": "Immune-Brain Claude Code Host: native Enrollment, QA, Review, and Kernel settlement.",
   "author": {
     "name": "Immune-Brain Team"

package/plugins/immune-brain/dist/claude/mcp-server.mjs

@@ -39,7 +39,7 @@ function probeHost(env = process.env, platform = process.platform, hostVersion)
 }
 
 // plugins/immune-brain/runtime/plugin_version.ts
-var PLUGIN_VERSION = "4.3.0";
+var PLUGIN_VERSION = "4.4.0";
 
 // plugins/immune-brain/runtime/claude/interaction.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -12564,6 +12564,12 @@ class ClaudeRuntime {
       return { ...result, tracker: TRACKER_PROJECTION_FAILURE };
     }
   }
+  async reviseIntent(taskId, nextIntent) {
+    return this.executeOrdinary({ cwd: this.cwd }, {
+      taskId,
+      operation: { op: "revise_intent", next_intent: nextIntent, actor_id: "executor" }
+    });
+  }
   async resolveFinding(taskId, findingId) {
     return this.executeOrdinary({ cwd: this.cwd }, {
       taskId,
@@ -13072,6 +13078,7 @@ var TOOLS = [
   { name: "advance_assurance", description: "Advance frozen Assurance through deterministic QA and Review reservation.", privileged: false },
   { name: "submit_review", description: "Submit the Parent-mediated Review verdict bound to the correlated receipt.", privileged: false },
   { name: "request_authorization", description: "Apply exact literal-user authorization.", privileged: true },
+  { name: "revise_intent", description: "Apply a compatible TaskIntent revision.", privileged: false },
   { name: "approve_breaking_intent_revision", description: "Approve a breaking TaskIntent revision.", privileged: true },
   { name: "stop", description: "Stop the active task with literal-user authority.", privileged: true },
   { name: "start_unattended_batch", description: "Start an unattended serial batch run for an Initiative after native confirmation.", privileged: true },
@@ -13088,14 +13095,14 @@ function listMcpTools() {
       properties: {
         ...tool.name === "start_unattended_batch" ? { initiative_slug: { type: "string" } } : {
           task_id: { type: "string" },
-          ...tool.name === "approve_breaking_intent_revision" ? { next_intent: { type: "object" } } : {},
+          ...tool.name === "approve_breaking_intent_revision" || tool.name === "revise_intent" ? { next_intent: { type: "object" } } : {},
           ...tool.name === "stop" ? { reason: { type: "string" } } : {},
           ...tool.name === "submit_review" ? { verdict: { type: "object" } } : {},
           ...tool.name === "resolve_finding" ? { finding_id: { type: "string" } } : {},
           ...tool.name === "refute_finding" ? { finding_id: { type: "string" }, attestation_id: { type: "string" } } : {}
         }
       },
-      required: tool.name === "start_unattended_batch" ? ["initiative_slug"] : tool.name === "submit_review" ? ["task_id", "verdict"] : tool.name === "resolve_finding" ? ["task_id", "finding_id"] : tool.name === "refute_finding" ? ["task_id", "finding_id", "attestation_id"] : ["task_id"]
+      required: tool.name === "start_unattended_batch" ? ["initiative_slug"] : tool.name === "submit_review" ? ["task_id", "verdict"] : tool.name === "resolve_finding" ? ["task_id", "finding_id"] : tool.name === "refute_finding" ? ["task_id", "finding_id", "attestation_id"] : tool.name === "revise_intent" ? ["task_id", "next_intent"] : ["task_id"]
     },
     annotations: tool.privileged ? privilegedAnnotations() : { readOnlyHint: tool.name === "status" }
   }));
@@ -13189,6 +13196,11 @@ function createMcpRuntime(options = {}) {
           throw new Error("verdict is required");
         return runtime.submitReview(taskId, args.verdict);
       }
+      if (name === "revise_intent") {
+        if (!Object.hasOwn(args, "next_intent"))
+          throw new Error("next_intent is required");
+        return runtime.reviseIntent(taskId, args.next_intent);
+      }
       if (name === "resolve_finding") {
         if (typeof args.finding_id !== "string" || !args.finding_id)
           throw new Error("finding_id is required");

package/plugins/immune-brain/runtime/claude/kernel_ports.ts

@@ -658,6 +658,13 @@ export class ClaudeRuntime {
 		}
 	}
 
+	async reviseIntent(taskId: string, nextIntent: unknown) {
+		return this.executeOrdinary({ cwd: this.cwd }, {
+			taskId,
+			operation: { op: "revise_intent", next_intent: nextIntent, actor_id: "executor" },
+		});
+	}
+
 	/**
 	 * Ordinary Kernel operation, not a privileged one: canary_application builds
 	 * the action without a capability and the Pi Host lists resolve_finding in

package/plugins/immune-brain/runtime/claude/mcp_server.ts

@@ -23,6 +23,7 @@ export const TOOLS = [
 	{ name: "advance_assurance", description: "Advance frozen Assurance through deterministic QA and Review reservation.", privileged: false },
 	{ name: "submit_review", description: "Submit the Parent-mediated Review verdict bound to the correlated receipt.", privileged: false },
 	{ name: "request_authorization", description: "Apply exact literal-user authorization.", privileged: true },
+	{ name: "revise_intent", description: "Apply a compatible TaskIntent revision.", privileged: false },
 	{ name: "approve_breaking_intent_revision", description: "Approve a breaking TaskIntent revision.", privileged: true },
 	{ name: "stop", description: "Stop the active task with literal-user authority.", privileged: true },
 	{ name: "start_unattended_batch", description: "Start an unattended serial batch run for an Initiative after native confirmation.", privileged: true },
@@ -42,7 +43,7 @@ export function listMcpTools() {
 					? { initiative_slug: { type: "string" } }
 					: {
 						task_id: { type: "string" },
-						...(tool.name === "approve_breaking_intent_revision" ? { next_intent: { type: "object" } } : {}),
+						...(tool.name === "approve_breaking_intent_revision" || tool.name === "revise_intent" ? { next_intent: { type: "object" } } : {}),
 						...(tool.name === "stop" ? { reason: { type: "string" } } : {}),
 						...(tool.name === "submit_review" ? { verdict: { type: "object" } } : {}),
 						...(tool.name === "resolve_finding" ? { finding_id: { type: "string" } } : {}),
@@ -57,7 +58,9 @@ export function listMcpTools() {
 						? ["task_id", "finding_id"]
 						: tool.name === "refute_finding"
 							? ["task_id", "finding_id", "attestation_id"]
-							: ["task_id"],
+							: tool.name === "revise_intent"
+								? ["task_id", "next_intent"]
+								: ["task_id"],
 		},
 		annotations: tool.privileged ? privilegedAnnotations() : { readOnlyHint: tool.name === "status" },
 	}));
@@ -162,6 +165,10 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				if (!Object.hasOwn(args, "verdict")) throw new Error("verdict is required");
 				return runtime.submitReview(taskId, args.verdict);
 			}
+			if (name === "revise_intent") {
+				if (!Object.hasOwn(args, "next_intent")) throw new Error("next_intent is required");
+				return runtime.reviseIntent(taskId, args.next_intent);
+			}
 			if (name === "resolve_finding") {
 				// Structural only. Which findings may be resolved, and when, stays
 				// the reducer's decision; duplicating it here would create a second

package/plugins/immune-brain/runtime/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "4.3.0" as const;
+export const PLUGIN_VERSION = "4.4.0" as const;