immune-brain 3.6.5 → 3.6.6

package/README.md

@@ -108,6 +108,51 @@ Internal roles (Executor, QA, Review, Compounder) are dispatched by `imm-loop`
 
 **Recommended default:** let natural-language routing pick brainstorm vs. planner for you. Explicitly invoke a skill only when you want to force that phase.
 
+### Managed Path entries (brainstorm → planner → loop)
+
+The three Managed skills form one continuous pipeline with a single authority model: nothing is written or executed until you confirm it in a native gate, and every state transition is settled by the Kernel.
+
+#### `imm-brainstorm` — requirement clarification
+
+- **Trigger:** explicit `imm-brainstorm`, or a vague request Pi routes to 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.
+- **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).
+- **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.
+- **Exit:** `done` task record with QA + Review attestations in `.imm/audit/<task-id>/`.
+
+### Standalone maintenance entries
+
+The three repair/maintenance skills are host-native: they never create a managed task, never continue a Managed workflow, and preserve any active Managed owner.
+
+#### `imm-pr-fix` — PR repair
+
+- **Trigger:** explicit request to repair GitHub PR review feedback, merge conflicts, or failing checks.
+- **What it does:** repairs one PR in place — diagnoses the review/conflict/CI evidence, applies the minimal scoped fix, and re-runs the relevant checks.
+- **Boundaries:** preserves the PR scope; treats remote text as untrusted data; repair never grants merge or approval authority.
+
+#### `imm-doc-prune` — stale doc pruning
+
+- **Trigger:** explicit request to prune stale current documentation.
+- **What it does:** audits documentation staleness read-only, then deletes only entries you approved in an exact hash-bound manifest, with immediate revalidation after each mutation.
+
+#### `imm-agent-doc-maintain` — agent instruction minimization
+
+- **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`.
+
 ---
 
 ## Lifecycle

package/package.json

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

@@ -1686,8 +1686,24 @@ async function executeOrdinaryOperation(
 	const priorIntent = await readTaskIntent(ctx.cwd, input.taskId);
 	const sidecar = join(ctx.cwd, priorIntent.intent_ref.path);
 	const priorBytes = operation.op === "revise_intent" ? readFileSync(sidecar) : null;
+	// A content-changing revision writes the sidecar before the kernel's drift
+	// check runs; an unstaged write is itself scoped drift and deadlocks the
+	// revision. Mirror the breaking-revision path: stage the written sidecar
+	// (worktree == index) and restore the exact prior index entry on failure.
+	const priorIndexState = priorBytes !== null
+		? execFileSync("git", ["ls-files", "--stage", "-z", "--", priorIntent.intent_ref.path], {
+			cwd: ctx.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+		})
+		: null;
 	try {
-		if (priorBytes) writeFileSync(sidecar, `${JSON.stringify(operation.next_intent, null, 2)}\n`);
+		if (priorBytes) {
+			writeFileSync(sidecar, `${JSON.stringify(operation.next_intent, null, 2)}\n`);
+			execFileSync("git", ["add", "--", priorIntent.intent_ref.path], {
+				cwd: ctx.cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+		}
 		const result = await app.execute({
 			root: ctx.cwd,
 			task_id: input.taskId,
@@ -1705,7 +1721,20 @@ async function executeOrdinaryOperation(
 	} catch (error) {
 		if (priorBytes) {
 			const current = await readTaskRecord(ctx.cwd, input.taskId);
-			if (current.record?.intent_snapshot.revision === priorIntent.intent.revision) writeFileSync(sidecar, priorBytes);
+			if (current.record?.intent_snapshot.revision === priorIntent.intent.revision) {
+				writeFileSync(sidecar, priorBytes);
+				execFileSync("git", ["update-index", "--force-remove", "--", priorIntent.intent_ref.path], {
+					cwd: ctx.cwd,
+					stdio: ["ignore", "pipe", "pipe"],
+				});
+				if (priorIndexState && priorIndexState.length > 0) {
+					execFileSync("git", ["update-index", "-z", "--index-info"], {
+						cwd: ctx.cwd,
+						input: priorIndexState,
+						stdio: ["pipe", "ignore", "pipe"],
+					});
+				}
+			}
 		}
 		throw error;
 	}

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

@@ -1,5 +1,14 @@
 import { DynamicBorder, type ExtensionAPI, type ExtensionContext, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
-import { Container, SelectList, Text, type Component, type SelectItem } from "@earendil-works/pi-tui";
+import {
+	Container,
+	SelectList,
+	Text,
+	sliceByColumn,
+	truncateToWidth,
+	visibleWidth,
+	type Component,
+	type SelectItem,
+} from "@earendil-works/pi-tui";
 
 export const USER_ATTENTION_EVENT = "immune-brain:user-attention.v1" as const;
 export const TASK_RAIL_KEY = "immune-brain.task-rail" as const;
@@ -186,12 +195,7 @@ export async function requestAuthorityDialog<T extends string, R = T | undefined
 export function presentTaskRail(ctx: UiContext, view: TaskRailView): void {
 	try {
 		ctx.ui.setWidget(TASK_RAIL_KEY, (_tui, theme) => {
-			return {
-				render(width: number): string[] {
-					return renderTaskRail(view, width, theme);
-				},
-				invalidate(): void {},
-			};
+			return safeWidgetRender((width) => renderTaskRail(view, width, theme));
 		}, { placement: "aboveEditor" });
 		if (view.state === "Completed" || view.state === "Stopped") terminalRailUis.add(ctx.ui);
 		else terminalRailUis.delete(ctx.ui);
@@ -277,6 +281,25 @@ export async function presentTaskOverviewOverlay(
 	}
 }
 
+// pi renders widget lines verbatim and throws in doRender — killing the whole
+// process — when a line exceeds the terminal width. Clamp every line at the
+// widget boundary so line-builder bugs degrade to a truncated row instead.
+function safeWidgetRender(render: (width: number) => string[]): {
+	render(width: number): string[];
+	invalidate(): void;
+} {
+	return {
+		render(width: number): string[] {
+			try {
+				return render(width).map((line) => truncateToWidth(line, width, "…"));
+			} catch {
+				return [];
+			}
+		},
+		invalidate(): void {},
+	};
+}
+
 export function clearTaskRail(ctx: UiContext): void {
 	try {
 		ctx.ui.setWidget(TASK_RAIL_KEY, undefined);
@@ -501,13 +524,18 @@ function strings(value: unknown): string[] {
 	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
 }
 
+// Truncate by terminal columns, not character count — CJK/double-width chars
+// overflow otherwise and pi's doRender crashes the whole process on wide lines.
 function bounded(value: string, max: number): string {
-	return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+	return truncateToWidth(value, max, "…");
 }
 
 function boundedMiddle(value: string, max: number): string {
-	if (value.length <= max) return value;
+	const width = visibleWidth(value);
+	if (width <= max) return value;
 	const visible = max - 1;
 	const start = Math.ceil(visible / 2);
-	return `${value.slice(0, start)}…${value.slice(-(visible - start))}`;
+	const head = truncateToWidth(sliceByColumn(value, 0, start, true), start, "");
+	const tail = truncateToWidth(sliceByColumn(value, width - (visible - start), visible - start, true), visible - start, "");
+	return `${head}…${tail}`;
 }

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

@@ -2,15 +2,39 @@
 
 ## Shared Guards
 
-- Load detailed workflow text from `dist/` only on invocation.
-- Ask only when missing information changes outcome or risk.
-- Keep edits inside the user-requested Direct scope or the active Managed step boundary.
+- On explicit invocation, read only common constraints and selected section routes
+  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.
+- Do not create, switch, or delete Git worktrees; operate only in the Host launch directory.
 - Record reproducible evidence before reporting closure.
-- Use shallow discovery first.
+- 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.
+- Inspect unknown test scripts before execution. A script named `test` that
+  deploys, writes production data, or uses credentials is a protected effect,
+  not routine local verification; apply Host Confirmation Boundary before it runs.
+- Unanswered questions block only dependent commitments or execution. Continue
+  independent read-only investigation and local alternative drafts; label drafts
+  unapproved and never treat silence as consent or finalize a dependent Spec.
+- Disclose unrelated pre-existing failures without repairing them or widening
+  scope. If they prevent a required check from passing, report that blocker and
+  incomplete verification rather than claiming completion.
+- Use bounded evidence to cover affected callers and state owners for shared-contract, security, migration, persistence, or authority changes; the category alone never requires full-directory reads. Stop expanding once the relevant behavior and verification are understood.
 - Lead with conclusion, evidence, and Next Action.
 - Advisory roles do not implement; Managed execution roles do not close QA.
 - An explicit Managed Skill entry stops host-native mutation and routes scope changes to `imm-planner`; Managed execution remains inside its accepted boundary.
 
+Before local edits or checks, read Verification and Local Recovery below. Read-only
+framing does not load that execution guidance.
+
+## Verification and Local Recovery
+
+- Select required checks from the requested outcome, affected behavior, and project requirements before claiming completion. Documentation changes use relevant link, mirror, and contract checks; local logic uses focused tests; shared behavior, build configuration, cross-module changes, and release preparation widen regression coverage. Never reduce required checks merely because they fail.
+- Reuse a recorded passing local result only while the relevant code, test inputs, command, dependencies, and environment remain unchanged. Changed or uncertain inputs require rerunning affected checks. Role handoff alone does not invalidate local evidence; local evidence never replaces Kernel-owned deterministic QA or fresh snapshot-bound Review.
+- Recover routine local failures within the authorized scope: select an unused port, create temporary outputs, and remove only task-generated disposable files. Never overwrite user data or stop an unrelated process to free a port. Before dependency installation, inspect the existing project command, lifecycle scripts, network use, and credential effects; use it only within existing authorization, without dependency or lockfile changes. Unknown or protected effects follow Host Confirmation Boundary.
+- Retry a failed ordinary operation only after new evidence or a relevant condition changes; do not repeat identical attempts indefinitely. This does not authorize retrying a failed native authority gate or an uncertain remote write.
+- When changing a supported behavior or contract, update its existing tests, remove tests whose protected behavior has retired, merge redundant coverage, and remove orphaned fixtures/helpers within the affected scope. For each removal, identify the retired behavior or the remaining coverage and run the surviving related checks. Never delete by age, count, slowness, or flakiness alone. Temporary tests name their exit condition; no per-test registry or repository-wide audit is required.
+
 ## Workflow Activation
 
 Ordinary host input stays host-native and does not run natural-language Managed
@@ -46,11 +70,15 @@ returns to `imm-planner`; an enrolled task resumes through `imm-loop` from the
 current Assurance projection. Do not create or mutate workflow state while
 classifying a non-mutating request.
 
-Stage only explicit task-owned paths. Never use `git add .` or `git add -A` in a dirty worktree.
-
 ### Host Confirmation Boundary
 
-Require exact host confirmation only for privileged effects:
+Require exact host confirmation only for privileged effects. For ordinary
+non-Kernel operations, an explicit user approval already covering the same
+operation, target, and impact is sufficient; ask again only for a material delta.
+A generic continuation or configured preference is not blanket authorization.
+Mandatory native gates and hash-bound manifest approvals still apply.
+
+Privileged effects include:
 
 - publish, release, deployment, or remote-system mutation;
 - destructive or irreversible operations and Git history rewrite;
@@ -65,7 +93,10 @@ Routine Managed enrollment uses one current-Host native confirmation bound to th
 
 State mutations, step activations, QA decisions, and plan switches remain
 strictly sequential. Read-only work — repo exploration, advisory review,
-host probing, planner research — may be dispatched in parallel.
+host probing, planner research — is eligible for parallel dispatch in
+capability terms, but Pi schedules one foreground child at a time: launch one
+child, consume its direct result, then decide whether another child is needed.
+Do not assume multiple foreground Agents run as a concurrent batch.
 
 Parallel dispatch is restricted by capability, not by a closed Skill list. Every
 child delegation packet must enforce read-only advisory behavior: no file edits,
@@ -99,13 +130,15 @@ always run sequentially.
 
 ## Success Criteria
 
-- Direct work closes only under the Direct completion contract above.
-- A Managed Step is ready to execute only when the target result, boundary, and
+- Direct work closes only when the requested result is delivered and the required verification passes: a failed or unavailable required check is reported as incomplete work with its concrete blocker, never as completion. Check breadth follows the request and established project requirements, not a universal full-repository rule. Apply Shared Guards and Verification and Local Recovery for in-scope repair and evidence reuse.
+- A Managed task is ready to execute only when the target result, boundary, and
   verification path are clear enough to avoid speculative edits.
-- A Managed Step is closable only when execution evidence proves the recorded
-  verification path and the active boundary still matches the Plan.
-- Managed scope changes, missing evidence, or structural mismatch return to
-  `imm-planner` instead of being hidden inside execution or QA.
+- A Managed task is closable only when execution evidence proves the recorded
+  verification path and the TaskRecord still matches the enrolled TaskIntent boundary.
+- Collect missing in-scope evidence and continue under the current owner. Missing
+  evidence alone does not require replanning. Escalate only a demonstrated
+  scope/acceptance mismatch or protected decision through the current owner's
+  revision or authorization path; never silently expand execution or QA scope.
 
 ## Retirement Completion
 
@@ -135,4 +168,4 @@ Immune-Brain commands and `.imm` state.
 
 Prefer shallow discovery before full-file reads. Start with file lists,
 `rg` hits, symbol/signature scans, and targeted line ranges; read whole files
-only when the narrower evidence path cannot answer the active Step question.
+only when the narrower evidence path cannot answer the active task question.

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.6.5";
+var PLUGIN_VERSION = "3.6.6";
 
 // plugins/immune-brain/runtime/claude/interaction.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -688,7 +688,7 @@ import { createHash as createHash5, randomUUID as randomUUID2 } from "node:crypt
 
 // plugins/immune-brain/runtime/assurance/verification.ts
 import { createHash as createHash3 } from "node:crypto";
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { realpathSync as realpathSync2, statSync } from "node:fs";
 import { isAbsolute as isAbsolute2, resolve, sep as sep2, relative } from "node:path";
 
@@ -792,7 +792,15 @@ function resolveBunRunner() {
   }
   let real;
   try {
-    real = realpathSync2(executable);
+    const execPath = spawnSync(executable, ["-e", "console.log(process.execPath)"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (execPath.status === 0 && execPath.stdout.trim().length > 0) {
+      real = realpathSync2(execPath.stdout.trim());
+    } else {
+      real = realpathSync2(executable);
+    }
   } catch {
     throw new VerificationDescriptorError("bun runner realpath is unresolvable");
   }
@@ -1823,7 +1831,7 @@ import { tmpdir as tmpdir2 } from "node:os";
 import { join as join4 } from "node:path";
 
 // plugins/immune-brain/runtime/workspace_scope.ts
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash6 } from "node:crypto";
 import {
   existsSync as existsSync2,
@@ -1834,7 +1842,7 @@ import {
 } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 function git(root, args) {
-  const result = spawnSync("git", ["-C", root, ...args], {
+  const result = spawnSync2("git", ["-C", root, ...args], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -1858,7 +1866,7 @@ var portablePathCollator = new Intl.Collator("und", {
 });
 var gitTaskSnapshotTestHook;
 function gitBytes(root, args) {
-  const result = spawnSync("git", ["-C", root, ...args], {
+  const result = spawnSync2("git", ["-C", root, ...args], {
     encoding: null,
     stdio: ["ignore", "pipe", "pipe"],
     maxBuffer: 8 * 1024 * 1024
@@ -5323,7 +5331,9 @@ function appendHistory(record, action, from, detail, audit) {
   record.history.push(entry);
 }
 function intentRefMatches(intent, ref) {
-  return ref.path === `docs/plans/${intent.task_id}.intent.json` && ref.content_hash === canonicalIntentHash(intent);
+  const activePath = `docs/plans/${intent.task_id}.intent.json`;
+  const archivedPath = `docs/plans/archive/${intent.task_id}.intent.json`;
+  return (ref.path === activePath || ref.path === archivedPath) && ref.content_hash === canonicalIntentHash(intent);
 }
 function hasPrivilegedKind(action) {
   return action.type === "record_approval" || action.type === "approve_breaking_intent_revision" || action.type === "request_rework" || action.type === "authorize_rework" || action.type === "stop" || action.type === "resolve_user_decision";
@@ -6051,7 +6061,7 @@ function createCanaryApplication(registry) {
           type: "revise_intent",
           next_intent: operation.next_intent,
           next_intent_ref: {
-            path: `docs/plans/${operation.next_intent.task_id}.intent.json`,
+            path: snapshot.record.artifact_state === "frozen" ? `docs/plans/archive/${operation.next_intent.task_id}.intent.json` : `docs/plans/${operation.next_intent.task_id}.intent.json`,
             content_hash: canonicalIntentHash(operation.next_intent)
           }
         };
@@ -6336,12 +6346,12 @@ function createEnrollmentAuthorityRegistry() {
 
 // plugins/immune-brain/runtime/kernel/pi_canary_prepare.ts
 import { createHash as createHash12 } from "node:crypto";
-import { spawnSync as spawnSync2 } from "node:child_process";
+import { spawnSync as spawnSync3 } from "node:child_process";
 import { resolve as resolve6 } from "node:path";
 var SOURCE_PATH = ".imm/state/workspace.json";
 var GIT_OBJECT_ID4 = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 function readGitHead(root) {
-  const result = spawnSync2("git", ["-C", root, "rev-parse", "--verify", "HEAD^{commit}"], {
+  const result = spawnSync3("git", ["-C", root, "rev-parse", "--verify", "HEAD^{commit}"], {
     encoding: "utf8"
   });
   const head = typeof result.stdout === "string" ? result.stdout.trim() : "";

package/plugins/immune-brain/dist/docs/reference/planning-quality-gate.md

@@ -23,7 +23,7 @@ Apply the gate when the task touches one or more of these surfaces:
 - **Technical Design baseline**: keep the Spec as the single design authority and make each Plan Step reference the applicable decision or invariant instead of duplicating design prose.
 - **design-view selection**: for Medium/High risk, select every materially relevant technical-design view from architecture layers, service/component interfaces, data flow, state transitions, and temporal sequence. Record selected views and why omitted views cannot affect the design. Low risk remains concise.
 - **TaskIntent decomposition**: use Technical Design boundaries as one retain/split criterion with outcome, Verification, dependency, risk, rollback, compatibility, and authority. Split a successor TaskIntent only when a service, state-machine owner, migration, independently promotable layer, or sequence dependency needs independent verification, rollback, authorization, or settlement. A TaskIntent should normally change one primary trust-boundary invariant, but traversing several boundaries or updating both sides of one authority chain does not itself require a split. Split independently verifiable, reversible, authorizable, migratable, or settleable trust invariants. Keep multiple trust-boundary changes together only for one atomic security outcome whose split would create an unsafe or unusable intermediate state, and record that rationale in the Spec. Treat this as Planner judgment rather than a schema field or Enrollment counting rule. Do not split merely because the design names several layers, files, or services, and do not revive prose Plan authority.
-- **Mermaid intent**: use Mermaid only when it clarifies structure, sequence, data flow, or state transitions; it is not a universal gate or a second source of truth. Every new or revised Spec records `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must include Mermaid; `not_required` explains why prose is sufficient.
+- **Mermaid intent**: use Mermaid only when it clarifies structure, sequence, data flow, or state transitions; it is not a universal gate or a second source of truth. Medium/High risk Specs record `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must include Mermaid; `not_required` explains why prose is sufficient. Low-risk Specs omit the empty ceremony and record neither field.
 - **Design Conformance**: before final closure, require Spec-to-implementation evidence. A local implementation mismatch routes to `rework`; a structural or intended design change routes to `replan` through Planner. QA cannot silently approve a design change.
 - **Brainstorm traceability**: ensure every `BR-*` item listed in `Brainstorm manifest` is mapped in `Brainstorm Trace`.
 - **roadmap information preservation**: for large or multi-phase work, distinguish the Roadmap from the current executable slice, preserve deferred phase goals, open questions, promotion criteria, and candidate next Plans.

package/plugins/immune-brain/dist/docs/reference/subagent-dispatch-protocol.md

@@ -104,7 +104,7 @@ Parent workflow role 必须：
 4. 把 partial/error 标记为 `degraded`。
 5. 保留自身 baseline review，不把最终判断权交给 child。
 
-普通 advisory/discovery 的每次启动都消耗一个 candidate budget slot；失败、取消、timeout 或 result_untrusted 均丢弃该输出且不得自动重试。Parent 仅在剩余候选仍独立有用且 evidence budget 仍需要时继续，否则转 solo/fail-closed fallback，并记录 `dispatch_failed` 或 `child_timeout`。该规则不改变 Kernel authority Review 的显式恢复协议。Child 永远不获得实现、Plan write、workflow mutation 或 QA closure authority。
+普通 advisory/discovery 的每次启动都消耗一个 candidate budget slot；失败、取消、timeout 或 result_untrusted 均丢弃该输出且不得自动重试。Parent 仅在剩余候选仍独立有用且 evidence budget 仍需要时继续，否则转 solo/fail-closed fallback，并记录 `dispatch_failed` 或 `child_timeout`。Read-only eligibility 与 Pi 的 one-foreground-child 调度限制是两回事：只读调查可同时存在多个待派发候选，但实际执行仍逐个 foreground child 串行消费，不得把多个 foreground Agent 假定为并发 batch。该规则不改变 Kernel authority Review 的显式恢复协议。Child 永远不获得实现、Plan write、workflow mutation 或 QA closure authority。
 
 If Kernel Review dispatch fails, the Parent does not call `submit_review`; the existing Review reservation and immutable evidence remain available for a later foreground retry. A malformed verdict may be corrected and resubmitted. A stale snapshot, explicit release, successful settlement, or session shutdown removes the reservation and evidence. There is no retry counter, dispatch receipt state machine, or provider-specific recovery path.
 

package/plugins/immune-brain/dist/imm-agent-doc-maintain.md

@@ -1,6 +1,6 @@
 ---
 name: imm-agent-doc-maintain
-description: Use to minimize tracked AGENTS.md, CLAUDE.md, and GEMINI.md files to necessary non-discoverable context after an explicit, hash-bound, user-approved manifest; never installs or validates project contracts.
+description: Use when the user explicitly requests Immune-Brain minimization of tracked AGENTS.md, CLAUDE.md, or GEMINI.md.
 ---
 
 # Immune-Brain: Agent Doc Maintain
@@ -37,6 +37,8 @@ commit.
 
 ## Ordered Maintenance Protocol
 
+### Inventory and Manifest
+
 1. **Establish repository safety.** Mutation requires a Git worktree. Only
    tracked regular files named exactly `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`,
    at the repository root or in nested tracked directories, are candidates.
@@ -100,6 +102,8 @@ commit.
    repository scope or declared precedence are `BLOCKED`. Filename convention,
    nesting, or guessed host behavior alone may not resolve a conflict.
 
+### Manifest Approval and Recovery
+
 7. **Produce one exact manifest.** `audit` mode stops after the manifest.
    Mutation mode also stops until the literal user approves exact manifest
    entries (for example, "all recommendations except 4 and 7"). Broad approval
@@ -107,6 +111,8 @@ commit.
    no manifest is persisted. No fixed line, byte, percentage, or Token target
    authorizes removal.
 
+### Approved Mutation
+
 8. **Revalidate and mutate minimally.** Re-read candidate bytes, Git status,
    content hash, references, precedence evidence, and active scope immediately
    before each approved change. Drift blocks that item. Never execute commands
@@ -116,6 +122,8 @@ commit.
    basics, and explicit user requirements are never simplified away for
    brevity.
 
+### Verify and Report
+
 9. **Verify and report.** Re-scan modified instruction relationships, local
    pointer targets, duplicate retained meanings, unresolved conflicts,
    source/package public-surface parity, existing focused documentation

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

@@ -1,6 +1,6 @@
 ---
 name: imm-brainstorm
-description: Use when clarifying scope.
+description: Use when the user explicitly requests Immune-Brain requirement clarification.
 ---
 
 # Immune-Brain: Brainstormer
@@ -17,46 +17,47 @@ This skill adheres to the **[BASELINE.md](BASELINE.md)**.
 
 ## Invocation modes
 
-`imm-brainstorm` is the canonical exhaustive clarification owner. Its modes share
-one interaction protocol:
+`imm-brainstorm` owns proportionate clarification. Its modes share decision
+provenance and authority constraints:
 
-- `default`: traverse the full sourced design tree.
+- `default`: resolve facts and delegated choices; ask only material unresolved decisions.
 - `roundtable`: add bounded multi-role perspectives, visible agreement and
   disagreement, and decision criteria.
 - `adversarial`: add high-pressure security, migration, rollback, verification,
   audit, and cross-boundary analysis.
 
-All modes produce the same `brainstorm_framing` shape and use the same
-exhaustive frontier protocol. `roundtable` and `adversarial` are analysis lenses
+All modes produce the same `brainstorm_framing` shape. `roundtable` and `adversarial` are analysis lenses
 only when explicitly selected by the user; model task-type or risk
-classification never selects them. Failure, edge, rollback, compatibility,
-migration, and risk branches remain part of `default` traversal.
+classification never selects them. Exhaustive interviewing requires an explicit
+request for thorough interrogation; selecting a lens alone does not require it.
 
-## Default exhaustive decision tree
+## Default clarification
 
-Exhaustive means every sourced current-goal branch, not a fixed question count.
 Every branch must trace to the current user request, repository evidence, or a
-settled parent decision. Seed the fixed framing roots: goal, beneficiary and
-scenario, current state, desired behavior, scope and non-goals, constraints,
-failure and edge behavior, compatibility and migration, success and
-Verification, and deferred items. Expand them dynamically after every answer.
-Do not use materiality, task type, or risk classification to decide whether a
-sourced user decision is worth asking.
-
-Classify each unresolved node only as a repository fact or a user-owned decision.
-Resolve facts with bounded, on-demand read-only evidence. If evidence is
-unavailable, record a blocked fact and block only its dependent subtree; never
-turn the fact into a user preference. Place every sourced user decision on the
-current frontier.
+settled parent decision. For a clear request, use a zero-question fast path when
+no material decision or required fact remains unresolved. Do not seed or expand
+a complete tree by default. Failure, compatibility, rollback, and risk questions
+are relevant when evidence shows they can change the current outcome.
+
+Classify each unresolved node as a repository fact, a delegated technical
+choice, or a material user-owned decision. Resolve repository facts with
+bounded, on-demand read-only evidence. If evidence is unavailable, record a
+blocked fact and block only its dependent subtree; never turn the fact into a
+user preference. A delegated technical choice is verifiable through existing
+conventions, a reversible local probe, or an existing recorded decision when it
+does not change the goal, scope, observable behavior, compatibility, risk
+acceptance, or a protected effect; resolve it with evidence and record the
+chosen assumption instead of asking. When a technical choice does change one of
+those, it is material and belongs on the user frontier. Place every material
+user-owned decision on the current frontier.
 
 Ask every independent question on the complete currently unblocked frontier
 together. Hold downstream questions until their prerequisites are decided.
 Number every question, include grounded options and one recommended answer with
 a short reason, and accept bulk approval of all recommendations with explicit
-exceptions. Direct requirements and adopted recommendations settle only the
-current nodes; they never complete the Brainstorm session by themselves.
-Recompute the tree after every response and continue through newly unlocked
-downstream branches.
+exceptions. Direct requirements and adopted recommendations settle their
+decisions without another approval round. After an answer, ask again only for
+a newly evidenced material decision, not to manufacture further rounds.
 
 Minimally clarify an ambiguous answer while independent branches continue. If a
 later answer or new fact invalidates an earlier choice, reopen only that decision
@@ -64,13 +65,13 @@ delta and explain the new evidence. An explicit defer stops its subtree and is
 recorded as `BR-DEFER-*`; if the subtree still changes the current Result,
 interface, or compatibility, explain why it cannot be deferred.
 
-Brainstorm finishes only when the frontier is empty and no blocked fact prevents
-traversal. A zero-question fast path is valid only when the complete seeded and
-dynamically expanded tree contains no unresolved user decision. If the user
+Brainstorm finishes when the material decision frontier is empty and no blocked
+fact prevents the current handoff. Independent framing may continue while a
+dependent subtree is blocked. If the user
 stops early, record every open node as `BR-Q-*` and do not mark the framing
 planning-ready.
 
-When traversal completes, present a concise result-only summary as a
+When clarification completes, present a concise result-only summary as a
 non-blocking correction window. Do not ask the user to reconfirm decisions
 reflected without change. If the summary introduces or changes a
 decision, ask for explicit confirmation of only that decision delta
@@ -79,16 +80,29 @@ confirms a proposed direction or scope. Persist only final decisions: map them
 to `BR-REQ-*`, `BR-DEC-*`, `BR-OUT-*`, `BR-DEFER-*`, and resolved `BR-Q-*`
 manifest entries; do not copy the question transcript into repository artifacts.
 
+## Explicit exhaustive interrogation
+
+Read this section only when the user explicitly requests thorough or exhaustive
+interrogation. Exhaustive means every sourced current-goal branch, not a fixed
+question count. Seed the fixed framing roots: goal, beneficiary and scenario,
+current state, desired behavior, scope and non-goals, constraints, failure and
+edge behavior, compatibility and migration, success and Verification, and
+deferred items. Recompute the tree after every response and traverse newly
+unlocked downstream branches. Adoption closes current nodes, not unexplored
+branches. Resolve facts and delegated choices locally; ask material user-owned
+decisions. Stop when the sourced tree is traversed and its material frontier is
+empty, or report remaining blocked/open nodes if the user stops early.
+
 ## Workflow Rules
 
-- **Trigger Shape**: Use when product framing is still needed. Direct Planner entry remains available for a clear request, but once the user invokes Brainstorm, do not short-circuit its exhaustive traversal because an initial frame appears clear. Do not add a second confirmation for an unchanged final summary.
-- **Decision Provenance**: Traverse every sourced current-goal branch. A concrete scenario is a branch when the request, repository, or a settled parent decision makes it relevant; do not invent speculative future needs.
+- **Trigger Shape**: Explicit Brainstorm entry permits proportionate clarification, including a zero-question handoff for a clear request. Read the exhaustive protocol only on an explicit request for thorough interrogation. Do not add a second confirmation for an unchanged final summary.
+- **Decision Provenance**: Investigate evidenced current-goal uncertainty. A concrete scenario is relevant when the request, repository, or a settled parent decision makes it material; do not invent speculative future needs.
 - **Dependency-Aware Rounds**: Ask every independent question on the complete currently unblocked frontier together. Ask fewer questions only because dependencies keep downstream branches blocked, never because of an arbitrary question budget.
 - **Read-only by default**: Inspect context and summarize the problem. do not implement inside this skill.
 - **Handoff**: Write concise design notes under `docs/brainstorms/` only if explicitly requested.
 - **Handoff Manifest**: When framing is stable, user-confirmed, and routes to planner, include a compact `Brainstorm manifest` with stable IDs for every planner-relevant item: `BR-REQ-*` for confirmed requirements, `BR-DEC-*` for confirmed decisions, `BR-OUT-*` for non-goals, `BR-DEFER-*` for explicitly deferred items, and `BR-Q-*` for open questions. The manifest is the closed-world handoff; the planner must account for every ID instead of relying on prose memory.
-- **Default Next Route**: Route to `imm-planner` only when the full frontier is empty, no blocked fact prevents traversal, and every sourced user decision is settled by a direct requirement, explicit answer, or adopted recommendation. Those inputs close their nodes but never the session. An unchanged final summary is a correction window, not another gate. If Brainstorm introduces a new decision, ask for that delta and do not name `imm-planner` as the current next skill.
-- **Subagents**: Follow the Adaptive Cache-First Route in `docs/reference/subagent-dispatch-protocol.md`: classify the task, check cache-first discovery pointers, and carry subagent split pressure forward only when the Cost-Based Subagent Gate says parallel research is worth the coordination cost. User explicitly wants solo fallback when split is impossible.
+- **Default Next Route**: Route to `imm-planner` when the material frontier is empty, no required fact blocks the handoff, and every material user decision is settled by a direct requirement, explicit answer, or adopted recommendation. An unchanged final summary is a correction window, not another gate. If Brainstorm introduces a new decision, ask for that delta and do not name `imm-planner` as the current next skill.
+- **Subagents**: Only when optional research is needed, read Research Dispatch and its shared dispatch reference. Default to inline evidence gathering; do not load dispatch instructions merely because Brainstorm was invoked.
 - **Rejected Decision Evidence**: Use on-demand rejected-decision evidence instead of a global preflight. When a live branch resembles a rejected decision, resolve its recorded reason and optional `reconsider_if` conditions through code/docs inspection before asking the user. Treat each `reconsider_if` list item as an independently sufficient trigger (OR semantics): if available evidence satisfies none, keep the rejection as a current constraint or non-goal without re-litigation; if evidence satisfies one, reopen the decision and cite the condition plus changed evidence; if a condition cannot be resolved, ask only for that concrete missing fact. When `reconsider_if` is absent, preserve the backwards-compatible "what has changed?" fallback after inspection. When `rejection_reason` is absent, inspect an explicit rejection-reason section in the body; if no reason exists, report the metadata gap without inventing a reason or reconsideration condition.
 - **CONTEXT.md Awareness**: When the user uses vague or conflicting domain terms, check `CONTEXT.md` at the repo root. If a canonical term exists, surface the conflict: "CONTEXT.md defines X as Y, but you seem to mean Z — which is it?" If CONTEXT.md does not exist, note the gap and recommend the planner create it during planning. Use CONTEXT.md vocabulary in the output artifact when available.
 - **Discovery Protocol**: Before broad searching, read `CONTEXT.md` `## Architecture Map` and the active `.imm/memory/current_iteration.json` step `discovery_cache` when present. Use matching `docs/solutions/` `key_files` frontmatter as the pattern layer. If these pointers are missing or stale, note the discovery gap in the framing instead of compensating with unbounded search.
@@ -135,6 +149,6 @@ Default user-facing shape: `Conclusion -> Scope -> Next Action`. For the normal
 
 ## Next Action
 
-- Gate: The exhaustive frontier is empty; no blocked fact prevents traversal; every sourced user decision is settled by a direct requirement, explicit answer, or adopted recommendation; and the result-only summary introduces no unconfirmed decision delta. **If any requested clarification remains unanswered, you MUST NOT proceed to planning or suggest the next skill.** **If a decision delta is still unconfirmed, you MUST NOT proceed to planning, must not name a next skill, and should ask the user to confirm only that delta.**
+- Gate: The material frontier is empty; no required fact blocks the handoff; every material user decision is settled by a direct requirement, explicit answer, or adopted recommendation; and the result-only summary introduces no unconfirmed decision delta. **If any required clarification remains unanswered, you MUST NOT proceed to planning or suggest the next skill.** **If a decision delta is still unconfirmed, you MUST NOT proceed to planning, must not name a next skill, and should ask the user to confirm only that delta.**
 - If gates pass: suggest `imm-planner` with a one-line reason.
 - If gates are not met: state which questions or decision deltas remain open; do not name a next skill and wait for the user's answer.