immune-brain 4.1.0 → 4.3.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.3.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.3.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

@@ -26,6 +26,9 @@ import {
 	withKernelStoreLock,
 	inspectStorageLayout,
 	migrateLegacyLayout,
+	inspectEnrollmentGitBase,
+	enrollmentGitBaseNotice,
+	initializeEnrollmentGitBase,
 } from "./runtime-stub";
 import {
 	presentTaskRail,
@@ -292,6 +295,7 @@ async function executeForegroundEnrollment(
 	pi: Pick<ExtensionAPI, "events">,
 ): Promise<EnrollmentTerminal> {
 	let stage = "preparing";
+	let gitBaseNote = "";
 	const progress = (nextStage: string, summary: string) => {
 		stage = nextStage;
 		const update = updateResult(action, taskId, nextStage, summary);
@@ -303,7 +307,7 @@ async function executeForegroundEnrollment(
 		taskId,
 		"cancelled",
 		stage,
-		`Foreground enrollment cancelled during ${stage}; zero authority writes were requested`,
+		`Foreground enrollment cancelled during ${stage}; zero authority writes were requested${gitBaseNote}`,
 		"retry by invoking the launcher again",
 	);
 
@@ -437,7 +441,7 @@ async function executeForegroundEnrollment(
 				`task ${taskId} is terminal in this worktree`,
 				"inspect authority state; do not retry enrollment",
 			);
-		const preparation = await preparePiCanary(root, { task_id: taskId, now });
+		let preparation = await preparePiCanary(root, { task_id: taskId, now });
 		signal.throwIfAborted();
 		if (!preparation.intent)
 			return terminal(action, taskId, "blocked", stage, "A Git-tracked TaskIntent is required for Kernel enrollment", "author and stage the canonical TaskIntent");
@@ -468,6 +472,8 @@ async function executeForegroundEnrollment(
 			return terminal(action, taskId, "blocked", stage, `Enrollment is ineligible: ${reasons}`, "resolve the eligibility blockers");
 		}
 
+		const gitBase = await inspectEnrollmentGitBase(root);
+		const gitNotice = await enrollmentGitBaseNotice(gitBase);
 		const acceptanceDetails = taskIntent.intent.acceptance.length === 0
 			? "(none)"
 			: taskIntent.intent.acceptance
@@ -483,6 +489,7 @@ async function executeForegroundEnrollment(
 				`Risk: ${taskIntent.intent.risk}`,
 				`Scope: ${taskIntent.intent.scope_hint.length > 0 ? taskIntent.intent.scope_hint.join(", ") : "(none)"}`,
 				`Acceptance: ${taskIntent.intent.acceptance.length} descriptor(s)`,
+				...(gitNotice ? [gitNotice] : []),
 			].join("\n");
 			const confirmationDetails = [
 				`Acceptance descriptors:`,
@@ -536,6 +543,11 @@ async function executeForegroundEnrollment(
 			return terminal(action, taskId, "blocked", stage, "Workspace changed after confirmation; enrollment aborted before authority", "restore the intended snapshot and rerun enrollment");
 		signal.throwIfAborted();
 
+		preparation = await initializeEnrollmentGitBase(root, { task_id: taskId, now }, preparation, gitBase, signal);
+		if (gitBase.state === "unborn") gitBaseNote = `; empty initial commit ${preparation.git_base_head} remains`;
+		if (!preparation.intent) throw new Error("Enrollment requires a readable TaskIntent");
+		signal.throwIfAborted();
+
 		const nonce = randomUUID();
 		const binding = {
 			task_id: taskId,
@@ -562,7 +574,7 @@ async function executeForegroundEnrollment(
 		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("; ")}`, "resolve the final-lock preconditions and retry");
+			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();
 
@@ -579,11 +591,13 @@ async function executeForegroundEnrollment(
 				"continue with imm-loop",
 			);
 		} catch (error) {
-			return classifyCommitFailure(root, action, taskId, now, error);
+			const failure = await classifyCommitFailure(root, action, taskId, now, error);
+			failure.summary += gitBaseNote;
+			return failure;
 		}
 	} catch (error) {
 		if (signal.aborted) return cancelled();
-		return terminal(action, taskId, "failed", stage, `Foreground enrollment failed during ${stage}: ${errorMessage(error)}`, "correct the reported failure and retry");
+		return terminal(action, taskId, "failed", stage, `Foreground enrollment failed during ${stage}: ${errorMessage(error)}${gitBaseNote}`, "correct the reported failure and retry");
 	}
 }
 

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/.pi-extension/runtime-stub.ts

@@ -43,18 +43,8 @@ export interface PiCanaryPrepareInput {
 	task_id: string;
 	now: string;
 }
-export interface PiCanaryPreparation {
-	contract: "assurance_kernel/pi_canary_preparation/v1";
-	task_id: string;
-	generated_at: string;
-	root_state_path: string;
-	intent: { path: string; revision: number; content_hash: string } | null;
-	backend_claim: { present: boolean; task_id: string | null; lifecycle_status: string | null };
-	task_tombstone: { present: boolean; terminal_lifecycle: string | null };
-	task_record_v3: { present: boolean; lifecycle: string | null; artifact_state: string | null } | null;
-	workspace: { current_working: string | null };
-	digest: string;
-}
+export type PiCanaryPreparation = import("../runtime/kernel/pi_canary_prepare").PiCanaryPreparation;
+export type EnrollmentGitBase = import("../runtime/assurance/enrollment_git_base").EnrollmentGitBase;
 export interface EnrollCanaryInput {
 	task_id: string;
 	intent_path: string;
@@ -242,6 +232,18 @@ export async function createEnrollmentAuthorityRegistry(): Promise<EnrollmentAut
 	const mod = await import(/* @vite-ignore */ kernelPath("enrollment_authority"));
 	return mod.createEnrollmentAuthorityRegistry();
 }
+export async function inspectEnrollmentGitBase(root: string): Promise<EnrollmentGitBase> {
+	const mod = await import(/* @vite-ignore */ runtimePath("assurance/enrollment_git_base"));
+	return mod.inspectEnrollmentGitBase(root);
+}
+export async function enrollmentGitBaseNotice(base: EnrollmentGitBase): Promise<string | undefined> {
+	const mod = await import(/* @vite-ignore */ runtimePath("assurance/enrollment_git_base"));
+	return mod.enrollmentGitBaseNotice(base);
+}
+export async function initializeEnrollmentGitBase(root: string, input: PiCanaryPrepareInput, previous: PiCanaryPreparation, base: EnrollmentGitBase, signal?: AbortSignal): Promise<PiCanaryPreparation> {
+	const mod = await import(/* @vite-ignore */ runtimePath("assurance/enrollment_git_base"));
+	return mod.initializeEnrollmentGitBase(root, input, previous, base, signal);
+}
 export async function preparePiCanary(
 	root: string,
 	input: PiCanaryPrepareInput,

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.
@@ -89,6 +93,8 @@ Privileged effects include:
 
 Routine Managed enrollment uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Explicit Plan-only requests stop with candidate artifacts and do not invoke Enrollment; execution-bearing requests open the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. The routine task proceeds from that single confirmation through enrollment, execution, and QA without a second human stop. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
 
+For an unborn symbolic Git HEAD, the same Enrollment confirmation discloses an empty root commit. After approval, the Host creates that commit without staging project content or changing the index/worktree, then revalidates ownership and rehearses Enrollment against the new base. Git identity uses existing environment/config values with an explicit automation fallback, never config writes. Decline or pre-initialization cancellation leaves HEAD unborn; if later Enrollment fails or is cancelled, report the remaining commit. Invalid Git refs are errors, not initialization candidates.
+
 ## Parallel Read-Only Dispatch
 
 State mutations, step activations, QA decisions, and plan switches remain