immune-brain 3.6.4 → 3.6.6

package/plugins/immune-brain/runtime/kernel/intent.ts

@@ -27,6 +27,7 @@ import {
 import {
 	mintToken,
 	type TaskIntentIdentityToken,
+	type TokenIdentity,
 } from "./intent_token_registry";
 
 export const INTENT_MAX_BYTES = 64 * 1024;
@@ -406,6 +407,26 @@ export interface ReadTaskIntentResult {
 	token: TaskIntentIdentityToken;
 }
 
+export interface ObservedTaskIntent {
+	intent: TaskIntentV1;
+	content_hash: string;
+	intent_ref: TaskIntentRefV1;
+}
+
+export class TaskIntentObservationError extends Error {
+	readonly code: "missing" | "invalid";
+
+	constructor(code: "missing" | "invalid", message: string) {
+		super(message);
+		this.name = "TaskIntentObservationError";
+		this.code = code;
+	}
+}
+
+interface TaskIntentReadSource extends ObservedTaskIntent {
+	identity: TokenIdentity;
+}
+
 export function setIntentReaderTestHook(
 	hook: { onBeforeDescriptorRead?: () => void } | null,
 ): void {
@@ -523,11 +544,11 @@ function assertIdentitiesUnchanged(
 	}
 }
 
-export function readTaskIntent(
+function readTaskIntentSource(
 	root: string,
 	taskId: string,
 	requestedPath?: string,
-): ReadTaskIntentResult {
+): TaskIntentReadSource {
 	validateTaskId(taskId);
 
 	const canonicalRoot = resolveCanonicalRoot(root);
@@ -545,7 +566,7 @@ export function readTaskIntent(
 	if (!target.startsWith(canonicalRoot + sep))
 		throw new Error("intent sidecar escapes project root");
 	if (!sidecarPresent(canonicalRoot, sidecarPath))
-		throw new Error(`TaskIntent sidecar is missing at ${sidecarPath}`);
+		throw new TaskIntentObservationError("missing", `TaskIntent sidecar is missing at ${sidecarPath}`);
 
 	const pathIdentities = collectPathIdentities(canonicalRoot, sidecarPath);
 	const fileIdentity = pathIdentities[pathIdentities.length - 1];
@@ -557,13 +578,19 @@ export function readTaskIntent(
 			["ls-files", "--error-unmatch", "--", sidecarPath],
 			{ cwd: canonicalRoot, stdio: ["ignore", "pipe", "pipe"] },
 		);
-	} catch {
-		throw new Error("TaskIntent sidecar is not Git-tracked");
+	} catch (error) {
+		if (
+			typeof error === "object"
+			&& error !== null
+			&& "status" in error
+			&& (error as { status?: unknown }).status === 1
+		) throw new TaskIntentObservationError("invalid", "TaskIntent sidecar is not Git-tracked");
+		throw error;
 	}
 
 	const before = lstatSync(target);
 	if (!before.isFile() || before.size > INTENT_MAX_BYTES)
-		throw new Error("TaskIntent sidecar must be a regular file no larger than 64 KiB");
+		throw new TaskIntentObservationError("invalid", "TaskIntent sidecar must be a regular file no larger than 64 KiB");
 
 	const fd = openSync(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
 	let bytes: Buffer;
@@ -576,7 +603,7 @@ export function readTaskIntent(
 		closeSync(fd);
 	}
 	if (bytes.byteLength > INTENT_MAX_BYTES)
-		throw new Error("TaskIntent sidecar exceeds 64 KiB");
+		throw new TaskIntentObservationError("invalid", "TaskIntent sidecar exceeds 64 KiB");
 
 	// Post-read identity re-verification without a second path read as the
 	// source of bytes.
@@ -594,27 +621,15 @@ export function readTaskIntent(
 	try {
 		intent = parseTaskIntentV1(JSON.parse(bytes.toString("utf8")));
 	} catch (error) {
-		throw new Error(
+		throw new TaskIntentObservationError(
+			"invalid",
 			`TaskIntent sidecar is invalid: ${error instanceof Error ? error.message : String(error)}`,
 		);
 	}
 	if (intent.task_id !== taskId)
-		throw new Error("intent.task_id does not match the sidecar filename task id");
+		throw new TaskIntentObservationError("invalid", "intent.task_id does not match the sidecar filename task id");
 
 	const contentHash = canonicalIntentHash(intent);
-	const token = mintToken({
-		canonical_root: canonicalRoot,
-		sidecar_path: sidecarPath,
-		path_dev: fileIdentity.dev,
-		path_ino: fileIdentity.ino,
-		fd_dev: before.dev,
-		fd_ino: before.ino,
-		fd_size: before.size,
-		fd_mtime_ms: before.mtimeMs,
-		source_bytes_sha256: sourceBytesSha256,
-		intent_content_hash: contentHash,
-	});
-
 	return {
 		intent,
 		content_hash: contentHash,
@@ -623,6 +638,35 @@ export function readTaskIntent(
 			revision: intent.revision,
 			content_hash: contentHash,
 		},
-		token,
+		identity: {
+			canonical_root: canonicalRoot,
+			sidecar_path: sidecarPath,
+			path_dev: fileIdentity.dev,
+			path_ino: fileIdentity.ino,
+			fd_dev: before.dev,
+			fd_ino: before.ino,
+			fd_size: before.size,
+			fd_mtime_ms: before.mtimeMs,
+			source_bytes_sha256: sourceBytesSha256,
+			intent_content_hash: contentHash,
+		},
 	};
 }
+
+export function observeTaskIntent(
+	root: string,
+	taskId: string,
+	requestedPath?: string,
+): ObservedTaskIntent {
+	const { identity: _identity, ...observed } = readTaskIntentSource(root, taskId, requestedPath);
+	return observed;
+}
+
+export function readTaskIntent(
+	root: string,
+	taskId: string,
+	requestedPath?: string,
+): ReadTaskIntentResult {
+	const { identity, ...observed } = readTaskIntentSource(root, taskId, requestedPath);
+	return { ...observed, token: mintToken(identity) };
+}

package/plugins/immune-brain/runtime/kernel/reducer.ts

@@ -167,8 +167,10 @@ function sha256Hex(value: string): string {
 }
 
 function intentRefMatches(intent: TaskIntentV1, ref: TaskIntentRefV3): boolean {
+	const activePath = `docs/plans/${intent.task_id}.intent.json`;
+	const archivedPath = `docs/plans/archive/${intent.task_id}.intent.json`;
 	return (
-		ref.path === `docs/plans/${intent.task_id}.intent.json` &&
+		(ref.path === activePath || ref.path === archivedPath) &&
 		ref.content_hash === canonicalIntentHash(intent)
 	);
 }
@@ -178,6 +180,7 @@ function hasPrivilegedKind(action: TaskAction): boolean {
 		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"
 	);
@@ -449,13 +452,16 @@ export function reduceTask(
 					"request_rework requires review, qa, or user authority",
 				]);
 			const round = reviewRound(record);
-			const reviewAuthorityReworks = record.history.filter(
-				(entry) =>
-					entry.type === "request_rework" &&
-					entry.authority?.authority_kind === "review",
-			).length;
+			const hasPriorBlockingReviewRework = record.findings.some(
+				(finding) =>
+					finding.source === "review" &&
+					finding.kind === "blocking" &&
+					finding.review_round !== null,
+			);
 			const parkForReplan =
-				authorityAudit.authority_kind === "review" && reviewAuthorityReworks >= 1;
+				authorityAudit.authority_kind === "review" &&
+				hasPriorBlockingReviewRework &&
+				action.findings.some((finding) => finding.kind === "blocking");
 			if (!parkForReplan) {
 				record.artifact_state = "active";
 				record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
@@ -470,8 +476,8 @@ export function reduceTask(
 				record.findings.push({
 					...finding,
 					status: "open",
-					source: "review",
-					review_round: round,
+					source: authorityAudit.authority_kind === "review" ? "review" : "execution",
+					review_round: authorityAudit.authority_kind === "review" ? round : null,
 				});
 			}
 			if (
@@ -502,6 +508,28 @@ export function reduceTask(
 			appendHistory(record, action, from, `review_round_${round}`, authorityAudit);
 			break;
 		}
+		case "authorize_rework": {
+			if (record.lifecycle !== "active")
+				throw new KernelInvariantError([
+					`cannot authorize rework while lifecycle is ${record.lifecycle}`,
+				]);
+			if (authorityAudit?.authority_kind !== "user")
+				throw new KernelInvariantError([
+					"authorize_rework requires literal-user authority",
+				]);
+			const open = record.findings.filter(
+				(finding) => finding.kind === "replan_required" && finding.status === "open",
+			);
+			if (open.length === 0)
+				throw new KernelInvariantError([
+					"authorize_rework requires an open replan boundary",
+				]);
+			for (const finding of open) finding.status = "resolved";
+			record.artifact_state = "active";
+			record.intent_ref.path = `docs/plans/${record.task_id}.intent.json`;
+			appendHistory(record, action, from, open.map((finding) => finding.id).join(","), authorityAudit);
+			break;
+		}
 		case "complete": {
 			if (record.lifecycle !== "active" || record.artifact_state !== "frozen")
 				throw new KernelInvariantError([

package/plugins/immune-brain/runtime/kernel/types.ts

@@ -297,6 +297,7 @@ export type TaskAction =
 	| (TaskActionBase & { type: "request_rework"; findings: TaskFinding[] })
 	| (TaskActionBase & { type: "complete" })
 	| (TaskActionBase & { type: "stop"; reason: string })
+	| (TaskActionBase & { type: "authorize_rework" })
 	| (TaskActionBase & { type: "resolve_user_decision"; finding_id: string; resolution: string });
 
 

package/plugins/immune-brain/runtime/kernel/validation.ts

@@ -735,6 +735,7 @@ const ACTION_V2_TYPES = [
 	"request_rework",
 	"complete",
 	"stop",
+	"authorize_rework",
 	"resolve_user_decision",
 ] as const;
 
@@ -897,7 +898,8 @@ export function parseTaskAction(raw: unknown): TaskAction {
 			};
 			break;
 		}
-		case "complete": {
+		case "complete":
+		case "authorize_rework": {
 			rejectUnknown(value, [...ACTION_BASE_FIELDS], "action", violations);
 			action = { ...base, type: base.type };
 			break;
@@ -1002,6 +1004,7 @@ export function assertTaskRecordUpdateV3(
 		if (
 			next.intent_ref.path !== previous.intent_ref.path &&
 			action.type !== "request_rework" &&
+			action.type !== "authorize_rework" &&
 			action.type !== "stop"
 		)
 			violations.push("only artifact transitions may change intent_ref path");
@@ -1023,11 +1026,12 @@ export function assertTaskRecordUpdateV3(
 			? [action.finding_id]
 			: action.type === "resolve_user_decision"
 				? [action.finding_id]
-				: action.type === "approve_breaking_intent_revision"
-					? previous.findings
-						.filter((item) => item.kind === "replan_required" && item.status === "open")
-						.map((item) => item.id)
-					: [];
+			: action.type === "authorize_rework" ||
+				  action.type === "approve_breaking_intent_revision"
+				? previous.findings
+					.filter((item) => item.kind === "replan_required" && item.status === "open")
+					.map((item) => item.id)
+				: [];
 	const reworkFindingIds =
 		action.type === "request_rework"
 			? new Set(action.findings.map((item) => item.id))

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 = "3.6.4" as const;
+export const PLUGIN_VERSION = "3.6.6" as const;

package/plugins/immune-brain/runtime/prompts/executor.md

@@ -1,13 +1,16 @@
 # Internal role: executor
 
-You are the Immune-Brain Executor role inside Loop. Implement exactly one
-active Step, or one accepted same-boundary follow-up, in the current Parent
-conversation. Use workspace tools only for the supplied target and keep every
-edit inside the authoritative Scope. Do not discover or load a Pi Skill.
+You are the Immune-Brain Executor role inside Loop. Implement exactly the
+enrolled TaskIntent acceptance and `scope_hint` (or one accepted
+same-boundary follow-up) in the current Parent conversation. Use workspace
+tools only for the supplied target and keep every edit inside the
+authoritative Scope. Do not discover or load a Pi Skill.
 
-Before handoff, verify the active Result with the supplied Verification
-commands and record structured execution evidence through the Loop runtime
-action. Preserve failed and blocked attempts. Do not perform QA,
+Before handoff, run the permitted diagnostic checks and return commands and
+outcomes to the Parent as structured diagnostic evidence. The read-only Loop
+runtime action only constructs the dispatch envelope; it does not store
+evidence or change task state. Preserve failed and blocked attempts. Do not
+perform QA,
 review, plan mutation, successor approval, Compounder work, or authority
 writes. If the requested change needs scope expansion, stop and return an
 `imm-planner` route with the concrete missing scope and verification reason.
@@ -22,6 +25,11 @@ Do not weaken tests or hide an incomplete result to make Verification pass.
 Treat naming, function length, parameter count, nesting, and abstraction taste
 as contextual signals, never as automatic failure thresholds.
 
-Fix in-scope integrity defects before Verification. If fixing one requires
-behavior, scope, or authority beyond the active Step, stop and route the
-concrete reason to `imm-planner`.
+Fix in-scope integrity defects before Verification. Autonomously diagnose,
+repair, and rerun failing ordinary local checks within the authorized scope;
+do not stop for a repair round that stays inside the TaskIntent boundary. If
+fixing requires
+behavior, scope, or authority beyond the enrolled TaskIntent, stop and route the
+concrete reason to `imm-planner`. An unavailable or still-failing required
+check is an explicit blocker: report it to the Parent; never present failed
+verification as completion.

package/plugins/immune-brain/runtime/prompts/pr-fix.md

@@ -71,8 +71,11 @@ decision, stop and report it to the Parent.
 
 ## Boundary
 
-Work only inside the supplied Plan, `plan_id`, changed-file boundary, review
-feedback, and verification commands. Do not create a second Plan, silently
+Work only inside the supplied repair boundary: the current TaskIntent
+acceptance and `scope_hint` when operating under one, otherwise the legacy
+supplied Plan, `plan_id`, changed-file boundary, review feedback, and
+verification commands from the delegation context. Do not create a second
+Plan or TaskIntent, silently
 widen scope, push to unrelated branches, merge, approve a successor, or invoke
 another role. Do not discover or load a Pi Skill.
 

package/plugins/immune-brain/skills/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/skills/imm-agent-doc-maintain/SKILL.md

@@ -1,11 +1,27 @@
 ---
 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
 
-Load [`../../dist/imm-agent-doc-maintain.md`](../../dist/imm-agent-doc-maintain.md),
-then minimize tracked agent instruction files to necessary non-discoverable
-context. This is a standalone host-native maintenance entry, not a Managed Path
+Use [`../../dist/imm-agent-doc-maintain.md`](../../dist/imm-agent-doc-maintain.md)
+as the canonical contract index, not a whole-document read.
+This is a standalone host-native maintenance entry, not a Managed Path
 continuation and not an `imm-loop` internal-role dispatch.
+
+Mandatory constraints: audit is read-only. Mutation requires exact hash-bound
+manifest approval and immediate revalidation. Preserve active Managed ownership;
+never install project contracts, modify external files, or commit.
+Interruption requires a fresh scan.
+
+Section routes - load a section's instructions only when its branch applies.
+Read each linked heading body up to the next heading; nested sections and
+references load only under their own condition. Never read the whole contract
+or all references as an entry prerequisite.
+
+- common: [Authority Boundary](../../dist/imm-agent-doc-maintain.md#authority-boundary), [Invocation](../../dist/imm-agent-doc-maintain.md#invocation), [Non-goals](../../dist/imm-agent-doc-maintain.md#non-goals)
+- audit or manifest preparation: [Inventory and Manifest](../../dist/imm-agent-doc-maintain.md#inventory-and-manifest), [Manifest Approval and Recovery](../../dist/imm-agent-doc-maintain.md#manifest-approval-and-recovery)
+- approved mutation before any edit: [Mutation Envelope](../../dist/imm-agent-doc-maintain.md#mutation-envelope), [Approved Mutation](../../dist/imm-agent-doc-maintain.md#approved-mutation)
+- completion: [Verify and Report](../../dist/imm-agent-doc-maintain.md#verify-and-report)
+- interruption or changed candidate before resuming: [Manifest Approval and Recovery](../../dist/imm-agent-doc-maintain.md#manifest-approval-and-recovery); start a fresh scan

package/plugins/immune-brain/skills/imm-brainstorm/SKILL.md

@@ -1,70 +1,30 @@
 ---
 name: imm-brainstorm
-description: Use to frame and clarify an ambiguous problem and its open questions before planning; framing only, no implementation or plan writing.
+description: Use when the user explicitly requests Immune-Brain requirement clarification.
 ---
 
 # Immune-Brain: Brainstorm
 
-Load [`../../dist/imm-brainstorm.md`](../../dist/imm-brainstorm.md), then frame the
-task before planning. Do not edit project files. Return goal, constraints,
-unknowns, readiness, and Next Action.
-
-## Default exhaustive decision tree
-
-Exhaustive clarification traverses every current-goal branch grounded in the
-user request, repository evidence, or a settled parent decision. Do not use a
-materiality or task-type judgment to decide whether a sourced user decision is
-worth asking. 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; then expand branches from each answer.
-
-Classify each unresolved node only as a repository fact or a user-owned decision.
-Resolve repository facts with bounded, on-demand read-only evidence. A blocked
-fact blocks only its dependent subtree and remains explicit; never convert it
-into a user preference. Place every sourced user decision on the complete
-currently unblocked frontier. Hold dependent questions until their parents are
-settled, but ask all independent questions together. Number each question,
-include grounded options and a 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.
-Minimally clarify an ambiguous answer. If later evidence invalidates a settled
-choice, reopen only that decision delta. An explicit defer stops its subtree and
-becomes `BR-DEFER-*`, unless it still changes the current Result, interface, or
-compatibility and therefore cannot be deferred.
-
-Brainstorm is complete 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 stops early, emit every open node as `BR-Q-*` and do not mark the frame
-planning-ready. Otherwise present a result-only summary as a non-blocking
-correction window and retain final decisions in the `BR-*` manifest rather than
-copying the question transcript. 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 and block Planner handoff
-until it is answered. Agent judgment alone never confirms a proposed direction
-or scope.
-
-Brainstorm supports `default`, `roundtable`, and `adversarial` modes. All use the
-same exhaustive frontier protocol; `roundtable` and `adversarial` add analysis
-lenses only when explicitly selected by the user. Required failure, rollback,
-compatibility, migration, and risk branches remain part of default traversal.
-Consult ADRs and on-demand rejected-decision evidence only when a live branch
-reaches that topic.
-Architecture mapping is a bounded, read-only `arch-explorer` role selected
-through the internal Loop bridge; it cannot write a Spec, Plan, or workflow
-state. Pi's adapter may consume `brainstorm_ensemble` dispatch JSON to prepare
-advisory Pi subagent envelopes, but envelope construction is not child execution
-and does not transfer framing authority. Pi itself may launch those subagents,
-collect completed child outputs, and feed them to
-`normalizePiBrainstormAgentResults`; runtime does not call any agent, poll
-background work, mutate state, or own final Spec/Plan authority.
-Agreement becomes framing evidence, Disagreement becomes decision criteria or
-`BR-Q-*`, and strong-model blockers become risks or verification requirements.
-
-When framing discusses later execution, describe Enrollment only as the current
-Host's native gate. Never recommend another Host, worktree, or unmanaged
-implementation as a fallback for a failed Managed authority interaction.
+Use [`../../dist/imm-brainstorm.md`](../../dist/imm-brainstorm.md) as the
+canonical contract index, not a whole-document read. Explicit entry only: ordinary host questions do not
+start this workflow.
+
+Mandatory constraints before any action: Brainstorm is read-only — no code,
+test, or runtime edits; no Spec, Plan, or workflow-state writes. All modes
+produce a `brainstorm_framing` result with goal, constraints, unknowns,
+readiness, and Next Action.
+
+Section routes - load a section's instructions only when its branch applies.
+Read each linked heading body up to the next heading; nested sections and
+references load only under their own condition. Never read the whole contract
+or all references as an entry prerequisite.
+
+- common: all modes read [Shared Guards](../../dist/BASELINE.md#shared-guards), [Workflow Activation](../../dist/BASELINE.md#workflow-activation), [Host Confirmation Boundary](../../dist/BASELINE.md#host-confirmation-boundary), [Boundary](../../dist/imm-brainstorm.md#boundary), [Invocation modes](../../dist/imm-brainstorm.md#invocation-modes), [Default clarification](../../dist/imm-brainstorm.md#default-clarification), [Workflow Rules](../../dist/imm-brainstorm.md#workflow-rules), [Output artifact](../../dist/imm-brainstorm.md#output-artifact), [Output style](../../dist/imm-brainstorm.md#output-style), [Next Action](../../dist/imm-brainstorm.md#next-action)
+- explicit thorough interrogation: [Explicit exhaustive interrogation](../../dist/imm-brainstorm.md#explicit-exhaustive-interrogation)
+- optional research, including explicitly selected `roundtable` or `adversarial` advisory: [Research Dispatch](../../dist/imm-brainstorm.md#research-dispatch), [Brainstorm Ensemble Advisory](../../dist/imm-brainstorm.md#brainstorm-ensemble-advisory)
+- requested framing document: [Output Language Policy](../../dist/BASELINE.md#output-language-policy)
+
+When framing discusses later execution, describe Enrollment only as the
+current Host's native gate. A failed Managed authority interaction stays
+fail-closed: report one same-Host recovery action, never another Host,
+worktree, or unmanaged implementation.

package/plugins/immune-brain/skills/imm-doc-prune/SKILL.md

@@ -1,11 +1,26 @@
 ---
 name: imm-doc-prune
-description: Use to prune stale current documentation from a Git repository after an explicit, hash-bound, user-approved manifest; never deletes Managed authority artifacts.
+description: Use when the user explicitly requests Immune-Brain pruning of stale current documentation.
 ---
 
 # Immune-Brain: Doc Prune
 
-Load [`../../dist/imm-doc-prune.md`](../../dist/imm-doc-prune.md), then prune
-stale current documentation from the target Git repository. This is a
+Use [`../../dist/imm-doc-prune.md`](../../dist/imm-doc-prune.md) as the canonical
+contract index, not a whole-document read. This is a
 standalone host-native maintenance entry, not a Managed Path continuation
 and not an `imm-loop` internal-role dispatch.
+
+Mandatory constraints: audit is read-only. Mutation requires exact hash-bound
+manifest approval and immediate revalidation. Preserve active Managed ownership;
+never delete authority artifacts or commit. Interruption requires a fresh scan.
+
+Section routes - load a section's instructions only when its branch applies.
+Read each linked heading body up to the next heading; nested sections and
+references load only under their own condition. Never read the whole contract
+or all references as an entry prerequisite.
+
+- common: [Authority Boundary](../../dist/imm-doc-prune.md#authority-boundary), [Invocation](../../dist/imm-doc-prune.md#invocation), [Authority Artifacts Excluded](../../dist/imm-doc-prune.md#authority-artifacts-excluded)
+- audit or manifest preparation: [Inventory and Manifest](../../dist/imm-doc-prune.md#inventory-and-manifest)
+- approved mutation before any edit: [Mutation Envelope](../../dist/imm-doc-prune.md#mutation-envelope), [Approved Mutation](../../dist/imm-doc-prune.md#approved-mutation)
+- completion: [Verify and Report](../../dist/imm-doc-prune.md#verify-and-report)
+- recovery or deletion recoverability: [Recovery](../../dist/imm-doc-prune.md#recovery)