immune-brain 3.5.0 → 3.6.0

package/README.md

@@ -139,7 +139,7 @@ Key invariants:
 
 ## Configuration
 
-Immune-Brain has **no separate config file**. Preferences live in `AGENTS.md` (repo root or `~/.pi/agent/AGENTS.md`):
+Immune-Brain has **no separate config file**. Preferences live in your host's agent instruction file at the repo root — `AGENTS.md` (Pi) or `CLAUDE.md` (Claude Code):
 
 ```md
 ## Immune-Brain Preferences
@@ -150,10 +150,10 @@ Immune-Brain has **no separate config file**. Preferences live in `AGENTS.md` (r
 | Preference | Options | Default | Notes |
 |---|---|---|---|
 | Reply language | any natural language | repo `AGENTS.md` | Machine contracts / paths stay literal |
-| Initiative carrier | `local` / `github` | `github` | Only matters when a proposal splits across multiple TaskIntents |
+| Initiative carrier | `local` / `github` | none — Planner asks | Only matters when a proposal splits across multiple TaskIntents |
 | Advisory subagents | allowed / solo | allowed | Respects Pi host policy + explicit user instruction |
 
-Precedence: **current message > repo `AGENTS.md` > `~/.pi/agent/AGENTS.md` > skill default**.
+Precedence: **current message > repo agent instruction file > user-level agent instruction file > ask**. Skills read these files directly, so a preference works even when the host does not auto-load that file.
 
 See [`docs/reference/immune-brain-config.md`](docs/reference/immune-brain-config.md) for details.
 

package/README.zh-CN.md

@@ -139,7 +139,7 @@ Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，
 
 ## 配置
 
-Immune-Brain **没有独立配置文件**，偏好设置写在 `AGENTS.md`（仓库根目录或 `~/.pi/agent/AGENTS.md`）：
+Immune-Brain **没有独立配置文件**，偏好设置写在仓库根目录下当前 Host 的 agent 指令文件里——`AGENTS.md`（Pi）或 `CLAUDE.md`（Claude Code）：
 
 ```md
 ## Immune-Brain Preferences
@@ -150,10 +150,10 @@ Immune-Brain **没有独立配置文件**，偏好设置写在 `AGENTS.md`（仓
 | 偏好 | 选项 | 默认 | 说明 |
 |---|---|---|---|
 | 回复语言 | 任意自然语言 | 仓库 `AGENTS.md` | 机器契约/路径/标识符保持原文 |
-| Initiative 载体 | `local` / `github` | `github` | 仅当提案拆分为多个 TaskIntent 时生效 |
+| Initiative 载体 | `local` / `github` | 无默认，Planner 询问 | 仅当提案拆分为多个 TaskIntent 时生效 |
 | Advisory subagent | 允许 / 单人 | 允许 | 受 Pi host 策略与用户显式指令约束 |
 
-优先级：**当前消息 > 仓库 `AGENTS.md` > `~/.pi/agent/AGENTS.md` > Skill 默认值**。
+优先级：**当前消息 > 仓库 agent 指令文件 > 用户级 agent 指令文件 > 询问**。Skill 会直接读取这些文件，因此即使 Host 不自动加载该文件，偏好依然生效。
 
 详见 [`docs/reference/immune-brain-config.md`](docs/reference/immune-brain-config.md)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "3.5.0",
+  "version": "3.6.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": "3.5.0",
+  "version": "3.6.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

@@ -26,8 +26,6 @@ import {
 	canonicalDescriptorBytes,
 	resolveBunRunner,
 	assertRunnerCompatible,
-	runFixedVerification,
-	VerificationAbortedError,
 	findingsDigest,
 	type FrozenRunner,
 	type VerificationDescriptor,
@@ -43,7 +41,7 @@ import {
 	type ReviewRevision,
 } from "./pi-canary-review-bundle";
 import type { InvocationToken } from "./pi-canary-invocations";
-import { qaFindingId } from "./pi-canary-qa-findings";
+import { runDeterministicQa } from "../runtime/assurance/qa";
 import {
 	reservedAgentParams,
 	type ReservedAgentParams,
@@ -1268,97 +1266,6 @@ async function reconcileReviewRevisionRefs(root: string): Promise<{ removed: str
 	return reconcileReviewRefs(root, live);
 }
 
-export interface QaVerificationProgressInput {
-	index: number;
-	total: number;
-	acceptance_id: string;
-	phase: "running" | "passed" | "failed";
-	elapsed_ms: number;
-}
-
-export function boundedVerificationFailureDetail(stdout: string, stderr: string): string {
-	const output = (stderr || stdout).trim();
-	const limit = 500;
-	if (output.length <= limit) return output;
-	const marker = "\n... output omitted ...\n";
-	const available = limit - marker.length;
-	const headLength = Math.floor(available / 3);
-	const tailLength = available - headLength;
-	return `${output.slice(0, headLength)}${marker}${output.slice(-tailLength)}`;
-}
-
-export async function runDeterministicQa(
-	snapshot: SnapshotDescriptor,
-	descriptors: Map<string, VerificationDescriptor>,
-	runner: FrozenRunner,
-	options: {
-		signal?: AbortSignal;
-		onProgress?: (progress: QaVerificationProgressInput) => void;
-		runVerification?: typeof runFixedVerification;
-	} = {},
-): Promise<AssuranceVerdict> {
-	if (snapshot.role !== "qa") throw new Error("deterministic QA requires qa role");
-	if (options.signal?.aborted) throw new VerificationAbortedError();
-	const findings: NonNullable<AssuranceVerdict["findings"]> = [];
-	const runVerification = options.runVerification ?? runFixedVerification;
-	for (const [offset, item] of snapshot.acceptance.entries()) {
-		if (options.signal?.aborted) throw new VerificationAbortedError();
-		const descriptor = descriptors.get(item.id);
-		if (!descriptor) throw new Error(`verification descriptor missing for ${item.id}`);
-		const startedAt = Date.now();
-		options.onProgress?.({
-			index: offset + 1,
-			total: snapshot.acceptance.length,
-			acceptance_id: item.id,
-			phase: "running",
-			elapsed_ms: 0,
-		});
-		const result = await runVerification(snapshot.root, descriptor, runner, {
-			signal: options.signal,
-		});
-		const failed = result.exit_code !== 0 || result.timed_out;
-		options.onProgress?.({
-			index: offset + 1,
-			total: snapshot.acceptance.length,
-			acceptance_id: item.id,
-			phase: failed ? "failed" : "passed",
-			elapsed_ms: Date.now() - startedAt,
-		});
-		if (failed) {
-			const detail = boundedVerificationFailureDetail(result.stdout, result.stderr);
-			findings.push({
-				id: qaFindingId(item.id, snapshotDigest(snapshot)),
-				kind: "blocking",
-				acceptance_id: item.id,
-				summary: `verification failed (exit ${result.exit_code}${result.timed_out ? ", timed out" : ""}) stdout=${result.stdout.length}B stderr=${result.stderr.length}B${detail ? `: ${detail}` : ""}`,
-				findings_digest: "",
-			});
-		}
-	}
-	if (findings.length > 0) {
-		return {
-			contract: "assurance_kernel/assurance_verdict/v2",
-			role: "qa",
-			task_id: snapshot.task_id,
-			snapshot_digest: snapshotDigest(snapshot),
-			decision: "rework",
-			findings,
-		};
-	}
-	return {
-		contract: "assurance_kernel/assurance_verdict/v2",
-		role: "qa",
-		task_id: snapshot.task_id,
-		snapshot_digest: snapshotDigest(snapshot),
-		decision: "pass",
-		approval: {
-			kind: "qa",
-			authority_role: "qa",
-			summary: `all ${snapshot.acceptance.length} fixed verification descriptor(s) passed`,
-		},
-	};
-}
-
 async function applyAssuranceVerdict(
 	ctx: ExtensionContext,
 	snapshot: SnapshotDescriptor,
@@ -1795,7 +1702,7 @@ async function enrichAssuranceResult(
 
 function nextActionForAssuranceResult(result: Record<string, unknown>, taskState: AssuranceTaskState): string {
 	if ("error" in taskState) return "inspect authority state";
-	if (result.state === "review_preparation_failed") return "retry advance_assurance";
+	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";
 	if (taskState.lifecycle === "done" || taskState.lifecycle === "stopped") return "none";
 	switch (result.state) {
@@ -1806,7 +1713,7 @@ function nextActionForAssuranceResult(result: Record<string, unknown>, taskState
 		case "stopped": return "none";
 		case "rework": return "repair findings, then advance assurance";
 		case "cancelled": return "retry the interrupted foreground operation";
-		case "settlement_unknown": return "inspect authority state";
+		case "settlement_unknown": return "advance_assurance to reconcile Kernel state; do not replay the uncertain write";
 		case "blocked":
 		case "failed":
 		default: return taskState.next_obligation;

package/plugins/immune-brain/.pi-extension/pi-canary-interaction.ts

@@ -43,6 +43,7 @@ export interface TaskRailView {
 	next: string;
 	/** Assurance phase label derived from the normalized Rail state. */
 	phase?: string;
+	recovery?: string;
 	/** Latest per-descriptor QA fact; rendered only while present. */
 	acceptance_progress?: TaskRailAcceptanceProgress;
 }
@@ -209,7 +210,7 @@ export function presentTaskRailResult(
 	const lifecycle = string(taskState?.lifecycle) ?? string(details.lifecycle) ?? string(details.stage);
 	const operation = string(details.operation);
 	const rawState = string(details.state);
-	const result = string(details.result) ?? string(details.reason) ?? operation ?? rawState ?? "Task state updated";
+	const result = string(details.result) ?? string(details.reason) ?? string(details.summary) ?? operation ?? rawState ?? "Task state updated";
 	const next = string(details.next_action) ?? "Follow the projected Obligation";
 	const current = details.current;
 	const total = details.total;
@@ -231,6 +232,7 @@ export function presentTaskRailResult(
 		result,
 		next,
 		phase: string(details.stage),
+		recovery: recoveryHint(details),
 		acceptance_progress: hasAcceptanceProgress
 			? {
 					current,
@@ -336,14 +338,17 @@ export function renderStructuredResult(
 	const taskState = record(details.task_state);
 	const lifecycle = string(taskState?.lifecycle) ?? string(details.lifecycle) ?? string(details.stage);
 	const state = string(details.state) ?? "unknown";
-	const summary = string(details.result) ?? string(details.reason) ?? string(details.operation) ?? state;
+	const summary = string(details.result) ?? string(details.reason) ?? string(details.summary) ?? string(details.operation) ?? state;
 	const next = string(details.next_action) ?? "No action reported";
 	const terminal = lifecycle === "done" || lifecycle === "stopped";
+	const blocked = railState({ state }) === "Blocked";
 	const lines = [
-		`${theme.fg("muted", "State:")} ${theme.fg(state === "blocked" || state === "failed" ? "warning" : "accent", lifecycle ?? state)}`,
-		`${theme.fg("muted", "Result:")} ${theme.fg(state === "blocked" || state === "failed" ? "warning" : "dim", summary)}`,
+		`${theme.fg("muted", "State:")} ${theme.fg(blocked ? "warning" : "accent", blocked ? "Blocked" : lifecycle ?? state)}`,
+		`${theme.fg("muted", "Result:")} ${theme.fg(blocked ? "warning" : "dim", summary)}`,
 		`${theme.fg("muted", "Next:")} ${theme.fg("dim", next)}`,
 	];
+	const recovery = recoveryHint(details);
+	if (recovery) lines.push(`${theme.fg("muted", "Recovery:")} ${theme.fg("dim", recovery)}`);
 	if (terminal && taskState) lines.push(...renderFinalLines(taskState, theme));
 	return new Text(lines.join("\n"), 0, 0);
 }
@@ -396,6 +401,7 @@ function renderTaskRail(view: TaskRailView, width = 120, theme?: Theme): string[
 	if (view.phase) {
 		lines.push(`${label("Phase:")} ${body(bounded(view.phase, availableContentWidth))}`);
 	}
+	if (view.recovery) lines.push(`${label("Recovery:")} ${body(bounded(view.recovery, availableContentWidth))}`);
 	if (view.acceptance_progress) {
 		const progress = view.acceptance_progress;
 		const symbol = progress.state === "passed" ? "✓" : progress.state === "failed" ? "✗" : "●";
@@ -441,8 +447,17 @@ export function renderTaskOverview(view: TaskOverviewView, width = 120, theme?:
 	return lines;
 }
 
+function recoveryHint(details: Record<string, unknown>): string | undefined {
+	if (details.code === "verdict_invalid") return "Correct Review payload; reservation retained";
+	if (details.state === "review_preparation_failed") return "Repair Review preparation; QA already committed";
+	if (details.state === "settlement_unknown") return "Reconcile Kernel state; do not replay writes";
+	if (details.state === "authority_conflict") return "Resolve authority conflict before resuming";
+	if (details.state === "rework") return "Repair blocking findings; retain unrelated fresh evidence";
+	return undefined;
+}
+
 function railState(input: { lifecycle?: string; obligation?: string; operation?: string; state?: string; stage?: string }): TaskRailState {
-	if (input.state === "blocked" || input.state === "failed" || input.state === "settlement_unknown") return "Blocked";
+	if (["blocked", "failed", "settlement_unknown", "review_preparation_failed", "authority_conflict", "rework"].includes(input.state ?? "")) return "Blocked";
 	if (input.lifecycle === "done") return "Completed";
 	if (input.lifecycle === "stopped") return "Stopped";
 	if (input.state === "awaiting_user" || input.operation === "request_authorization") return "Approval required";

package/plugins/immune-brain/.pi-extension/pi-canary-native-review.ts

@@ -9,7 +9,7 @@ export interface ReservedAgentParams {
 	thinking: "";
 	inherit_context: false;
 	isolated: true;
-	isolation: "worktree";
+	isolation: "off";
 	run_in_background: false;
 	max_turns: number;
 	resume: "";
@@ -50,7 +50,7 @@ export function reservedAgentParams(input: {
 		thinking: "",
 		inherit_context: false,
 		isolated: true,
-		isolation: "worktree",
+		isolation: "off",
 		run_in_background: false,
 		max_turns: input.max_turns ?? 16,
 		resume: "",

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

@@ -42,7 +42,7 @@ function probeHost(env = process.env, platform = process.platform, hostVersion)
 }
 
 // plugins/immune-brain/runtime/plugin_version.ts
-var PLUGIN_VERSION = "3.5.0";
+var PLUGIN_VERSION = "3.6.0";
 
 // plugins/immune-brain/runtime/claude/interaction.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -1275,8 +1275,6 @@ class AssuranceCoordinator {
       this.rejectedReviewOperations.delete(taskId);
     }
     const refreshed = this.active(taskId);
-    if (refreshed?.state === "settlement_unknown")
-      return refreshed;
     if (refreshed?.state === "running")
       return { state: "blocked", reason: `assurance operation ${refreshed.operation_id} is already running` };
     const operationId = randomUUID2();
@@ -1308,18 +1306,30 @@ class AssuranceCoordinator {
       progress(phase, `Preparing deterministic QA for ${taskId}`);
       await this.ports.advanceBeforeProjection?.();
       ensureOperationLive();
-      let projection = await this.ports.projectTask(ctx.cwd, taskId);
+      let projection;
+      try {
+        projection = await this.ports.projectTask(ctx.cwd, taskId);
+      } catch (error) {
+        if (!(error instanceof Error) || !("code" in error) || !["EINTR", "EAGAIN"].includes(String(error.code)))
+          throw error;
+        ensureOperationLive();
+        progress("retrying_projection", "Retrying the initial authority read once; no writes replayed", { retry_attempt: 1 });
+        ensureOperationLive();
+        projection = await this.ports.projectTask(ctx.cwd, taskId);
+      }
       ensureOperationLive();
       if (projection.error)
         return { state: "blocked", reason: projection.error };
-      if (projection.projection.lifecycle === "done")
-        return { state: "completed" };
-      if (projection.projection.lifecycle === "stopped")
-        return { state: "stopped" };
+      if (projection.projection.lifecycle === "done" || projection.projection.lifecycle === "stopped") {
+        this.unknownOperations.delete(taskId);
+        return { state: projection.projection.lifecycle === "done" ? "completed" : "stopped" };
+      }
       if (!projection.claim)
         return { state: "blocked", reason: "no active backend claim" };
       if (projection.claim.task_id !== taskId)
         return { state: "blocked", reason: `backend claim belongs to ${projection.claim.task_id}, not ${taskId}` };
+      if (projection.projection.lifecycle === "active")
+        this.unknownOperations.delete(taskId);
       const parked = await this.ports.readTaskRecord(ctx.cwd, taskId);
       ensureOperationLive();
       if (parked.record?.findings.some((finding) => finding.kind === "replan_required" && finding.status === "open"))
@@ -1533,10 +1543,8 @@ class AssuranceCoordinator {
   }
   async submitReview(taskId, ctx, verdictInput) {
     const unknown = this.unknownOperations.get(taskId);
-    if (unknown) {
-      this.unknownOperations.delete(taskId);
+    if (unknown)
       return { state: "settlement_unknown", operation: unknown.operation, operation_id: unknown.operationId, reason: unknown.reason };
-    }
     const rejected = this.rejectedReviewOperations.get(taskId);
     if (rejected)
       return { state: "blocked", reason: rejected.reason };
@@ -2663,11 +2671,16 @@ var INTENT_SIDECAR_RELATIVE_PREFIX = "docs/plans/";
 var RISK_FLOOR_SCOPE_PREFIXES = [
   "plugins/immune-brain/runtime/kernel",
   "plugins/immune-brain/runtime/authority_commit_receipts.ts",
+  "plugins/immune-brain/runtime/assurance",
+  "plugins/immune-brain/runtime/claude/interaction.ts",
+  "plugins/immune-brain/runtime/claude/capability.ts",
+  "plugins/immune-brain/runtime/claude/review_host.ts",
+  "plugins/immune-brain/runtime/claude/kernel_ports.ts",
+  "plugins/immune-brain/runtime/claude/mcp_server.ts",
   "plugins/immune-brain/.pi-extension"
 ];
 var CHANGED_PATH_RISK_FLOOR_PREFIXES = [
-  "plugins/immune-brain/runtime/kernel",
-  "plugins/immune-brain/.pi-extension",
+  ...RISK_FLOOR_SCOPE_PREFIXES,
   "docs/specs",
   "docs/plans"
 ];
@@ -6378,6 +6391,75 @@ function attemptRef(snapshotDigest2) {
   return `${digest8}-${randomUUID4().slice(0, 6)}`;
 }
 
+// plugins/immune-brain/runtime/assurance/qa.ts
+async function runDeterministicQa(snapshot, descriptors, runner, options = {}) {
+  if (snapshot.role !== "qa")
+    throw new Error("deterministic QA requires qa role");
+  if (options.signal?.aborted)
+    throw new VerificationAbortedError;
+  const findings = [];
+  const runVerification = options.runVerification ?? runFixedVerification;
+  for (const [offset, item] of snapshot.acceptance.entries()) {
+    if (options.signal?.aborted)
+      throw new VerificationAbortedError;
+    const descriptor = descriptors.get(item.id);
+    if (!descriptor)
+      throw new Error(`verification descriptor missing for ${item.id}`);
+    const startedAt = Date.now();
+    options.onProgress?.({
+      index: offset + 1,
+      total: snapshot.acceptance.length,
+      acceptance_id: item.id,
+      phase: "running",
+      elapsed_ms: 0
+    });
+    const result = await runVerification(snapshot.root, descriptor, runner, {
+      signal: options.signal
+    });
+    if (options.signal?.aborted)
+      throw new VerificationAbortedError;
+    const failed = result.exit_code !== 0 || result.timed_out;
+    options.onProgress?.({
+      index: offset + 1,
+      total: snapshot.acceptance.length,
+      acceptance_id: item.id,
+      phase: failed ? "failed" : "passed",
+      elapsed_ms: Date.now() - startedAt
+    });
+    if (failed) {
+      findings.push({
+        id: qaFindingId(item.id, snapshotDigest(snapshot)),
+        kind: "blocking",
+        acceptance_id: item.id,
+        summary: `verification failed (exit ${result.exit_code}${result.timed_out ? ", timed out" : ""}) stdout=${Buffer.byteLength(result.stdout)}B stderr=${Buffer.byteLength(result.stderr)}B`,
+        findings_digest: ""
+      });
+    }
+  }
+  if (findings.length > 0) {
+    return {
+      contract: "assurance_kernel/assurance_verdict/v2",
+      role: "qa",
+      task_id: snapshot.task_id,
+      snapshot_digest: snapshotDigest(snapshot),
+      decision: "rework",
+      findings
+    };
+  }
+  return {
+    contract: "assurance_kernel/assurance_verdict/v2",
+    role: "qa",
+    task_id: snapshot.task_id,
+    snapshot_digest: snapshotDigest(snapshot),
+    decision: "pass",
+    approval: {
+      kind: "qa",
+      authority_role: "qa",
+      summary: `all ${snapshot.acceptance.length} fixed verification descriptor(s) passed`
+    }
+  };
+}
+
 // plugins/immune-brain/runtime/claude/kernel_ports.ts
 function diffSnapshotOf(root, record) {
   if (record.contract === "assurance_kernel/task_record/v4") {
@@ -6442,45 +6524,6 @@ function assertProjectionBinding(before, after, allowDiffChange = false) {
     throw new Error("Task changed after native confirmation; authority aborted before capability issuance");
   }
 }
-async function runDeterministicQa(snapshot, descriptors, runner, options = {}) {
-  if (snapshot.role !== "qa")
-    throw new Error("deterministic QA requires qa role");
-  if (options.signal?.aborted)
-    throw new VerificationAbortedError;
-  const findings = [];
-  for (const [offset, item] of snapshot.acceptance.entries()) {
-    if (options.signal?.aborted)
-      throw new VerificationAbortedError;
-    const descriptor = descriptors.get(item.id);
-    if (!descriptor)
-      throw new Error(`verification descriptor missing for ${item.id}`);
-    const startedAt = Date.now();
-    options.onProgress?.({ index: offset + 1, total: snapshot.acceptance.length, acceptance_id: item.id, phase: "running", elapsed_ms: 0 });
-    const result = await runFixedVerification(snapshot.root, descriptor, runner, { signal: options.signal });
-    const failed = result.exit_code !== 0 || result.timed_out;
-    options.onProgress?.({ index: offset + 1, total: snapshot.acceptance.length, acceptance_id: item.id, phase: failed ? "failed" : "passed", elapsed_ms: Date.now() - startedAt });
-    if (failed) {
-      findings.push({
-        id: qaFindingId(item.id, snapshotDigest(snapshot)),
-        kind: "blocking",
-        acceptance_id: item.id,
-        summary: `verification failed (exit ${result.exit_code}${result.timed_out ? ", timed out" : ""})`,
-        findings_digest: ""
-      });
-    }
-  }
-  if (findings.length > 0) {
-    return { contract: "assurance_kernel/assurance_verdict/v2", role: "qa", task_id: snapshot.task_id, snapshot_digest: snapshotDigest(snapshot), decision: "rework", findings };
-  }
-  return {
-    contract: "assurance_kernel/assurance_verdict/v2",
-    role: "qa",
-    task_id: snapshot.task_id,
-    snapshot_digest: snapshotDigest(snapshot),
-    decision: "pass",
-    approval: { kind: "qa", authority_role: "qa", summary: `all ${snapshot.acceptance.length} fixed verification descriptor(s) passed` }
-  };
-}
 function qaOutcomes(record) {
   return Object.fromEntries(record.attestations.filter((item) => item.kind === "qa").flatMap((item) => item.acceptance_results).map((result) => [result.acceptance_id, { status: result.status, summary: result.summary }]));
 }

package/plugins/immune-brain/dist/docs/reference/immune-brain-config.md

@@ -1,25 +1,34 @@
-# Immune-Brain Pi Preferences
+# Immune-Brain Host Preferences
 
 Pi and Claude Code are supported code-agent hosts. Immune-Brain does not load an
 agent-local TOML file or Immune-Brain-specific environment overrides. User and
-project preferences belong in Pi-injected `AGENTS.md` instructions.
+project preferences belong in the Host's agent instruction files.
 
 ## Precedence
 
 Planner preferences resolve in this order:
 
 1. a literal instruction in the current request;
-2. the repository root `AGENTS.md`;
-3. `~/.pi/agent/AGENTS.md`; or
-4. the Skill's documented default or an explicit user question.
+2. the repository root agent instruction file, whichever the repository tracks:
+   `AGENTS.md` or `CLAUDE.md`;
+3. the Host's user-level agent instruction file; or
+4. an explicit user question.
 
-Invalid values are reported rather than guessed.
+Hosts differ in which files they auto-load: Pi injects `AGENTS.md`, while Claude
+Code auto-loads `CLAUDE.md` and does not read `~/.pi/agent/AGENTS.md` at all. A
+Skill therefore reads sources 2 and 3 directly instead of assuming the Host
+placed them in context, and reports which sources it checked.
+
+Invalid values are reported rather than guessed. A preference with no documented
+default resolves to a user question, never to a silently chosen value.
 
 ## Initiative Carrier
 
 The Initiative carrier preference applies only to proposals split across
 multiple TaskIntents. Ordinary TaskIntents remain tracked by Kernel
-TaskRecords. Set one of these fixed directives in `AGENTS.md`:
+TaskRecords. There is no built-in carrier default; when no directive is found,
+Planner asks. Set one of these fixed directives in the repository root
+`AGENTS.md` or `CLAUDE.md`:
 
 ```md
 ## Immune-Brain Preferences
@@ -33,7 +42,7 @@ TaskRecords. Set one of these fixed directives in `AGENTS.md`:
 - Initiative carrier default: github
 ```
 
-A repository directive overrides the global directive. A configured `github`
+A repository directive overrides the user-level directive. A configured `github`
 default is standing opt-in for GitHub projection, but the literal user still
 confirms the Initiative name, immutable slug, complete Parent/Child decomposition,
 granularity, and dependencies before the first remote mutation. Planner reports