immune-brain 4.1.0 → 4.2.0

package/README.md

@@ -198,29 +198,55 @@ The three repair/maintenance skills are host-native: they never create a managed
 
 ## Lifecycle
 
+```mermaid
+flowchart TD
+    subgraph Planning ["1. Planning Phase"]
+        B["imm-brainstorm<br/>Clarify Requirements & Constraints"] --> P["imm-planner<br/>Author Spec & TaskIntent"]
+        P --> TI["TaskIntent (.intent.json)<br/>• goal / scope_hint<br/>• risk tier<br/>• acceptance descriptors"]
+    end
+
+    subgraph Enrollment ["2. Enrollment Gate"]
+        TI --> EG{"Native User Gate<br/>Host Modal Confirmation"}
+        EG -->|Confirm| KS[(".imm/state/kernel.sqlite<br/>Atomic TaskRecord<br/>Exclusive Workspace Claim")]
+    end
+
+    subgraph Loop ["3. Execution & Assurance Loop (imm-loop)"]
+        KS --> EX["Executor Role<br/>Edit code strictly inside scope_hint"]
+        EX --> FRZ["advance_assurance<br/>Artifacts frozen (active:frozen)"]
+        FRZ --> QA["Deterministic QA Engine<br/>Run acceptance verification commands<br/>Generate QA Attestation"]
+        
+        QA -->|Fail| RW1["Rework / Fix"]
+        RW1 --> EX
+        
+        QA -->|Pass| RK{"Risk Tier?"}
+        RK -->|routine| ST["Settlement"]
+        RK -->|material / critical| RV["Review Role<br/>Structured verdict (Pass / Rework)"]
+        
+        RV -->|Rework| RW2["Rework"]
+        RW2 --> EX
+        RV -->|Pass| ST
+    end
+
+    subgraph Settlement ["4. Settlement & Learnings"]
+        ST --> CLS["Atomic Closure<br/>• Lifecycle: done<br/>• Audit evidence in .imm/audit/<br/>• Release Workspace Claim"]
+        CLS -.-> CP["Compounder Role<br/>Extract Learnings to docs/solutions/"]
+    end
 ```
-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>/)
-```
+
+### Core Logic: Three Pillars
+
+1. **Two Paths**
+   - **Host-native Path**: Daily conversation, code inspections, and ad-hoc fixes stay 100% native with zero workflow overhead.
+   - **Managed Path**: Explicitly entered via `imm-brainstorm`, `imm-planner`, or `imm-loop`, strictly governed by the Assurance Kernel.
+
+2. **Authority & Contract**
+   - **TaskIntent (`.intent.json`)**: Machine-readable behavioral contract locking `scope_hint` (file boundaries), `risk` tier, and `acceptance` descriptors.
+   - **Native Gate (Enrollment)**: The single human-authority confirmation gate; Kernel atomically acquires exclusive workspace ownership (`.imm/state/kernel.sqlite` CAS) to prevent concurrency conflicts and scope drift.
+
+3. **Deterministic Assurance**
+   - **QA-First**: The Kernel directly runs verification commands and checks exit codes/byte bounds; never relies on conversational claims.
+   - **Risk-Tiered Gates**: `routine` tasks complete upon QA pass; `material` and `critical` tasks require an isolated Review subagent to issue a structured verdict.
+   - **Unattended Batch**: Serial execution driven by GitHub Issues and bound by `plan_digest`, where each child independently completes its own Enrollment → QA → Review → Commit cycle.
 
 Key invariants:
 

package/README.zh-CN.md

@@ -198,29 +198,55 @@ Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，
 
 ## 生命周期
 
+```mermaid
+flowchart TD
+    subgraph Planning ["1. 规划阶段"]
+        B["imm-brainstorm<br/>需求澄清/约束"] --> P["imm-planner<br/>编写 Spec & TaskIntent"]
+        P --> TI["TaskIntent (.intent.json)<br/>• goal / scope_hint<br/>• risk tier<br/>• acceptance descriptors"]
+    end
+
+    subgraph Enrollment ["2. 准入登记"]
+        TI --> EG{"Native User Gate<br/>当前 Host 弹窗确认"}
+        EG -->|确认| KS[(".imm/state/kernel.sqlite<br/>原子生成 TaskRecord<br/>独占 Workspace Claim")]
+    end
+
+    subgraph Loop ["3. 执行与验证循环 (imm-loop)"]
+        KS --> EX["Executor 角色<br/>在 scope_hint 范围内修改代码"]
+        EX --> FRZ["advance_assurance<br/>制品冻结 (active:frozen)"]
+        FRZ --> QA["确定性 QA 引擎<br/>原子运行 acceptance 校验命令<br/>生成 QA Attestation"]
+        
+        QA -->|失败| RW1["Rework 返工修正"]
+        RW1 --> EX
+        
+        QA -->|通过| RK{"Risk 等级?"}
+        RK -->|routine| ST["Settlement 结算"]
+        RK -->|material / critical| RV["Review 审查角色<br/>结构化裁决 (Pass / Rework)"]
+        
+        RV -->|Rework| RW2["Rework 驳回"]
+        RW2 --> EX
+        RV -->|Pass| ST
+    end
+
+    subgraph Settlement ["4. 结算与沉淀"]
+        ST --> CLS["原子结项<br/>• Lifecycle: done<br/>• 写入审计日志 .imm/audit/<br/>• 释放 Workspace Claim"]
+        CLS -.-> CP["Compounder 角色<br/>提取经验至 docs/solutions/"]
+    end
 ```
-普通请求：日常编程 / 问答（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>/）
-```
+
+### 核心逻辑三要素
+
+1. **双轨制 (Two Paths)**
+   - **Host-native Path**：日常对话、代码检视、单点修改，不触碰 Kernel 权限，零流程开销。
+   - **Managed Path**：由 `imm-brainstorm` / `imm-planner` / `imm-loop` 显式驱动，全程受 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 产出结构化裁决。
+   - **批处理 (Unattended Batch)**：基于 GitHub Issue / `plan_digest` 串行推进，每个子任务独立走完 Enrollment → QA → Review → Commit 闭环。
 
 核心不变量：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "4.1.0",
+  "version": "4.2.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.1.0",
+  "version": "4.2.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-work.ts

@@ -588,11 +588,12 @@ export default function (
 			}
 			const projection = await projectAssuranceState(ctx.cwd, taskId);
 			if (projection.error) {
+				const nextAction = recoveryActionForAssuranceFailure(projection.error) ?? "inspect authority state";
 				const details = {
 					state: "blocked",
 					operation: action.op,
 					result: projection.error,
-					next_action: "inspect authority state",
+					next_action: nextAction,
 				};
 				presentTaskRailResult(ctx, taskId, details);
 				return failCanaryTool(taskId, action.op, "blocked", "projection_unavailable", projection.error, details.next_action);
@@ -1536,7 +1537,7 @@ async function buildAssuranceSnapshot(
 			})
 		: null;
 	const taskSnapshot = !reviewBundle && !reviewManifest
-		? captureGitTaskSnapshot(root, intent.scope_hint)
+		? captureGitTaskSnapshot(root, intent.scope_hint, taskId)
 		: null;
 	const dirtyFiles = reviewManifest
 		? Object.keys(reviewManifest.changed_paths)
@@ -1760,6 +1761,10 @@ async function enrichAssuranceResult(
 }
 
 function nextActionForAssuranceResult(result: Record<string, unknown>, taskState: AssuranceTaskState): string {
+	const recovery = recoveryActionForAssuranceFailure(
+		"error" in taskState ? taskState.error : result.reason,
+	);
+	if (recovery) return recovery;
 	if ("error" in taskState) return "inspect authority state";
 	if (result.state === "review_preparation_failed") return "repair Review preparation, then retry advance_assurance; QA is already committed";
 	if (result.code === "verdict_invalid") return "fix the verdict payload and resubmit submit_review; the Review reservation remains active; do not re-dispatch the reviewer";
@@ -1779,6 +1784,17 @@ function nextActionForAssuranceResult(result: Record<string, unknown>, taskState
 	}
 }
 
+function recoveryActionForAssuranceFailure(reason: unknown): string | null {
+	if (typeof reason !== "string") return null;
+	if (reason.includes("task scope contains unstaged or untracked changes:"))
+		return "stage only the listed task-owned paths, then retry the blocked operation";
+	if (reason.includes("QA resolution failed ("))
+		return "repair the verification command or delivery environment, then retry advance_assurance";
+	if (reason.includes("task delivery contains paths outside the authorization envelope:"))
+		return "reconcile the listed paths: unstage unrelated paths or revise TaskIntent scope for task-owned paths, then retry advance_assurance";
+	return null;
+}
+
 function toolResult(text: string, details?: Record<string, unknown>) {
 	return { content: [{ type: "text" as const, text }], details };
 }

package/plugins/immune-brain/dist/BASELINE.md

@@ -6,7 +6,9 @@
   from `dist/`; nested modes, examples, recovery, and references load on demand.
 - Ask only when missing information would change the goal, scope, observable behavior, compatibility, risk acceptance, a protected effect, or a fact only the user can supply. Resolve repository facts and delegated technical choices with bounded evidence instead of asking.
 - Keep edits inside the user-requested Direct scope or the enrolled TaskIntent acceptance and `scope_hint`.
-- Stage only explicit task-owned paths. Never use `git add .` or `git add -A` in a dirty worktree.
+- Stage only explicit task-owned paths. This staging authority does not grant
+  commit, push, broad staging, or authority over pre-existing user changes.
+  Never use `git add .` or `git add -A` in a dirty worktree.
 - Do not create, switch, or delete Git worktrees; operate only in the Host launch directory.
 - Record reproducible evidence before reporting closure.
 - Required verification must pass before reporting completion; disclosing a gap is not a substitute. Autonomously diagnose, repair, and rerun failing conventional local checks within the authorized scope; never delete, skip, or weaken a valid check to manufacture a pass. If a required check remains failing or cannot run, report the work as incomplete with the concrete blocker.
@@ -46,7 +48,9 @@ routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
    Managed owner remains authoritative; the user resumes it with `imm-loop`.
 2. **Start explicitly**: the selected Immune-Brain Skill owns its planning or
    coordination work. It creates only requested artifacts and their required
-   parent directories; it does not install project-wide contract files.
+   parent directories. Explicit Planner entry also owns absent routing-policy
+   activation under Planner's Kernel TaskIntent Routing section;
+   it does not otherwise install project-wide contract files.
 3. **Preserve authority**: Planner output is a candidate for later literal-user
    Enrollment, and Fast-Track preserves TaskIntent scope, Enrollment, QA,
    Review, authorization, and completion boundaries.

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.1.0";
+var PLUGIN_VERSION = "4.2.0";
 
 // plugins/immune-brain/runtime/claude/interaction.ts
 import { createHash, randomUUID } from "node:crypto";

package/plugins/immune-brain/dist/imm-loop.md

@@ -55,7 +55,12 @@ Continue while the current projection has a valid action:
 1. For active artifacts, implement only the enrolled acceptance within the
    `scope_hint` envelope in the current conversation. New helpers or tests
    inside an approved directory or glob do not require a revision. Run focused
-   checks. Executor checks are diagnostic evidence, not a QA or Review approval.
+   checks. Before `advance_assurance`, inspect ownership and stage only the exact
+   task-owned paths needed for delivery. Do not hand routine task-owned staging
+   to the user. If a file mixes pre-existing user changes with task changes and
+   the task-owned hunks cannot be isolated reliably, stop with that ownership
+   conflict instead of staging the whole file. Staging grants no commit or push
+   authority. Executor checks are diagnostic evidence, not a QA or Review approval.
 2. Call `advance_assurance` in the foreground and consume its direct terminal
    result. The Kernel freezes the artifacts itself before QA: it binds Git
    content identity in place without relocating source paths. A simple task has

package/plugins/immune-brain/dist/imm-planner.md

@@ -76,7 +76,8 @@ Then route deterministically:
   coordination, except a Loop-requested revision follows Enrolled Intent Revision
   below to prepare a non-authoritative proposal for that same owner;
 - an active or otherwise nonterminal v3 Plan remains on its existing v3 route;
-- no routing policy preserves the legacy v3 Planner behavior;
+- no routing policy on an otherwise unowned workspace triggers automatic policy
+  activation below before producing any planning artifact;
 - a valid `kernel_task_intent` retirement policy produces one TaskIntent draft
   through the current Host's explicit `imm-planner`;
 - an invalid, unreadable, untracked, or tracked-deleted policy rejects new
@@ -107,6 +108,46 @@ workspace claim, and final authority preconditions without executing acceptance
 descriptors. A routine task proceeds from that single confirmation through
 enrollment, execution and QA without a second human stop.
 
+**Automatic policy activation**
+
+Explicit `imm-planner` entry includes local routing setup, including for plan-only
+requests. When the routing projection reports `policy_status: legacy_v3` and
+`ownership: absent`, and neither Kernel nor nonterminal v3 ownership exists,
+perform these steps without a separate enablement question:
+
+1. Create `docs/plans/` if needed. Require real directories without symlink
+   components; create `docs/plans/managed-task-routing-policy.json` exclusively
+   (fail if it already exists), using exactly the JSON below with two-space
+   indentation, the shown field order, and one trailing newline.
+2. Run `git add -- docs/plans/managed-task-routing-policy.json` only for the file
+   created in this activation. Preserve all other worktree and index changes;
+   do not commit, force-add an ignored file, or alter Git configuration.
+3. Re-run `imm-plan --routing-status --json` through the resolved wrapper.
+   Continue canonical TaskIntent authoring only when `policy_status: active`,
+   `route: kernel_task_intent`, and `ownership: tracked_clean` all hold. Report
+   automatic activation briefly and continue planning in the same turn.
+
+```json
+{
+  "contract": "immune_brain/managed_task_routing_policy/v1",
+  "revision": 1,
+  "new_task_route": "kernel_task_intent",
+  "v3_new_plan_sync": "retired",
+  "legacy_v3_mode": "drain_read_only",
+  "terminal_import": "disabled"
+}
+```
+
+An already active policy needs no write or staging. An existing invalid,
+untracked, unreadable, tracked-deleted, or divergent policy is not an activation
+candidate: preserve it and report `routing_policy_invalid`. If creation,
+staging, or verification fails, report the concrete blocker and retain any
+created file; stop before authoring, without overwriting existing bytes or
+falling back to v3. A repository/user prohibition on policy setup or staging
+blocks only this dependent planning step. Activation grants no execution
+authority; the native Enrollment gate remains required. Read-only routing
+queries and the canonical author command retain their existing runtime behavior.
+
 ## Candidate Authoring
 
 Read this section before creating new candidate artifacts, after request routing
@@ -133,6 +174,12 @@ file creation; then it validates the created artifact with
 continue through Kernel `revise_intent` authority and are not a Planner
 overwrite path.
 
+After authoring, inspect ownership and stage only the exact Planner-produced
+Spec and TaskIntent paths before validation and handoff. Do not hand routine
+Planner-owned staging to the user. This grants no commit, push, broad staging,
+or authority over pre-existing user changes; a mixed-change ownership conflict
+stops only the affected handoff.
+
 Before authoring a TaskIntent that adds a field or verdict branch to a state
 machine, enumerate every consumer of that value and of the version gates around
 it: the producing side, each branch or switch that reads it, and any migration or
@@ -263,7 +310,12 @@ script or host tool through its literal `command`; do not infer a language,
 package manager, or runner. Add `environment.prepare` only when the check needs
 explicit setup, and declare only the generated directories it needs in
 `environment.writable_paths`. Never hide package installation inside an
-acceptance command. Prefer the highest existing observable behavioral test seam
+acceptance command. For every descriptor, identify whether its executable is
+provided by the QA host or by tracked delivery content, where every dependency
+comes from in the disposable delivery, what explicit setup is required, and
+which declared writable paths that setup or check creates. A dependency found
+only in the Planner's live worktree, including an absolute local `node_modules`
+path, is not delivery provenance. Prefer the highest existing observable behavioral test seam
 and the fewest sufficient seams; never use the full test suite, a build, network
 access, or redundant heavyweight checks as acceptance. Cite relevant test prior
 art and explain how the selected seam catches the intended regression. This is
@@ -271,7 +323,9 @@ a planning heuristic: it must not weaken acceptance-specific focused
 verification descriptors or add a mandatory user confirmation. Use the smallest
 `timeout_ms` and `max_output_bytes` that cover deterministic post-implementation
 QA. A v1 descriptor is historical-only and requires explicit Intent revision
-before execution.
+before execution. Report `valid` and `enrollment_ready` only as structural and
+Enrollment readiness; only a completed deterministic QA result proves that a
+descriptor executed and passed.
 
 ## Core Responsibilities
 
@@ -410,7 +464,7 @@ optional advisory dispatch fails, continue inline and record the reason.
 
 ## Boundary
 
-- **Allowed**: Write a TaskIntent. Add a Spec only for complex work. Initiative planning carriers and necessary domain vocabulary.
+- **Allowed**: Write a TaskIntent. Add a Spec only for complex work. Activate an absent routing policy under Kernel TaskIntent Routing. Initiative planning carriers and necessary domain vocabulary.
 - **Blocked**: Implementation edits, direct Kernel-store writes, enrolled intent overwrites, and QA/Review decisions.
 - **Workflow guard**: Execution continues through native Enrollment and explicit `imm-loop`. Planner owns design and decomposition, not execution authority.
 

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.1.0" as const;
+export const PLUGIN_VERSION = "4.2.0" as const;

package/plugins/immune-brain/skills/BASELINE.md

@@ -6,7 +6,9 @@
   from `dist/`; nested modes, examples, recovery, and references load on demand.
 - Ask only when missing information would change the goal, scope, observable behavior, compatibility, risk acceptance, a protected effect, or a fact only the user can supply. Resolve repository facts and delegated technical choices with bounded evidence instead of asking.
 - Keep edits inside the user-requested Direct scope or the enrolled TaskIntent acceptance and `scope_hint`.
-- Stage only explicit task-owned paths. Never use `git add .` or `git add -A` in a dirty worktree.
+- Stage only explicit task-owned paths. This staging authority does not grant
+  commit, push, broad staging, or authority over pre-existing user changes.
+  Never use `git add .` or `git add -A` in a dirty worktree.
 - Do not create, switch, or delete Git worktrees; operate only in the Host launch directory.
 - Record reproducible evidence before reporting closure.
 - Required verification must pass before reporting completion; disclosing a gap is not a substitute. Autonomously diagnose, repair, and rerun failing conventional local checks within the authorized scope; never delete, skip, or weaken a valid check to manufacture a pass. If a required check remains failing or cannot run, report the work as incomplete with the concrete blocker.
@@ -46,7 +48,9 @@ routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
    Managed owner remains authoritative; the user resumes it with `imm-loop`.
 2. **Start explicitly**: the selected Immune-Brain Skill owns its planning or
    coordination work. It creates only requested artifacts and their required
-   parent directories; it does not install project-wide contract files.
+   parent directories. Explicit Planner entry also owns absent routing-policy
+   activation under Planner's Kernel TaskIntent Routing section;
+   it does not otherwise install project-wide contract files.
 3. **Preserve authority**: Planner output is a candidate for later literal-user
    Enrollment, and Fast-Track preserves TaskIntent scope, Enrollment, QA,
    Review, authorization, and completion boundaries.