immune-brain 3.6.5 → 3.6.7

package/plugins/immune-brain/runtime/unattended/batch_state.ts

@@ -0,0 +1,360 @@
+// Batch run state persistence for unattended Initiative batch runs.
+// State lives at .imm/state/batches/<batch_id>.json, written only under the
+// kernel store lock, and is Git-ignored with the rest of .imm/state/.
+import { existsSync, mkdirSync, openSync, closeSync, writeFileSync, renameSync, lstatSync, constants, rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { readSecureProjectFile, withKernelStoreLock } from "../kernel/storage";
+import type { BatchPlanChild } from "./types";
+
+export type BatchRunState =
+	| "prepared"
+	| "running"
+	| "needs_human"
+	| "completed"
+	| "budget_stopped"
+	| "failed"
+	| "rejected";
+
+export type BatchChildRunState =
+	| "pending"
+	| "enrolled"
+	| "settled"
+	| "committed"
+	| "needs_human"
+	| "skipped_blocked";
+
+export interface BatchChildRun {
+	task_id: string;
+	slice_id: string;
+	blocked_by: string[];
+	state: BatchChildRunState;
+	/** Terminal reason for needs_human / skipped_blocked / failed children. */
+	reason: string | null;
+	/** Commit created after the Kernel reported this child done. */
+	commit: string | null;
+}
+
+export interface BatchRunStateRecord {
+	contract: "assurance_kernel/batch_run_state/v1";
+	batch_id: string;
+	initiative_slug: string;
+	plan_digest: string;
+	base_head: string;
+	/** Dedicated batch branch, e.g. imm/<initiative-slug>. */
+	branch?: string;
+	/** Timestamp of the literal-user batch confirmation. */
+	confirmation_time: string;
+	/** Authorization expiry from the batch capability binding. */
+	authorization_expires_at: string;
+	budget: {
+		max_children: number;
+		deadline_at: string;
+		qa_failure_limit: number;
+	};
+	batch_state: BatchRunState;
+	children: BatchChildRun[];
+	/** Consecutive deterministic-QA failures across children in this run. */
+	consecutive_qa_failures: number;
+	/** Commit heads produced by this batch, in child order. */
+	commits: string[];
+	created_at: string;
+	updated_at: string;
+}
+
+const BATCH_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+const CHILD_RUN_STATES: ReadonlySet<string> = new Set([
+	"pending",
+	"enrolled",
+	"settled",
+	"committed",
+	"needs_human",
+	"skipped_blocked",
+]);
+
+const BATCH_RUN_STATES: ReadonlySet<string> = new Set([
+	"prepared",
+	"running",
+	"needs_human",
+	"completed",
+	"budget_stopped",
+	"failed",
+	"rejected",
+]);
+
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function isCanonicalTimestamp(value: unknown): value is string {
+	if (typeof value !== "string" || !ISO_TIMESTAMP_PATTERN.test(value)) return false;
+	const milliseconds = Date.parse(value);
+	return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value;
+}
+
+function validateBatchId(batchId: string): void {
+	if (typeof batchId !== "string" || !BATCH_ID_PATTERN.test(batchId))
+		throw new Error("batch id is not a safe file identity");
+}
+
+function statePath(batchId: string): string {
+	validateBatchId(batchId);
+	return join(".imm", "state", "batches", `${batchId}.json`);
+}
+
+function canonicalBytes(record: BatchRunStateRecord): string {
+	return `${JSON.stringify(record, null, 2)}\n`;
+}
+
+function validateRecordShape(value: unknown, batchId: string): asserts value is BatchRunStateRecord {
+	if (typeof value !== "object" || value === null)
+		throw new Error(`batch run state ${batchId} is not an object`);
+	const record = value as Record<string, unknown>;
+	if (record.contract !== "assurance_kernel/batch_run_state/v1")
+		throw new Error(`batch run state ${batchId} has an unknown contract`);
+	if (record.batch_id !== batchId)
+		throw new Error(`batch run state ${batchId} carries batch_id ${String(record.batch_id)}`);
+	if (typeof record.plan_digest !== "string" || !record.plan_digest)
+		throw new Error(`batch run state ${batchId} has an invalid plan_digest`);
+	if (typeof record.base_head !== "string" || !record.base_head)
+		throw new Error(`batch run state ${batchId} has an invalid base_head`);
+	if (record.branch !== undefined && (typeof record.branch !== "string" || !record.branch))
+		throw new Error(`batch run state ${batchId} has an invalid branch`);
+	if (!isCanonicalTimestamp(record.confirmation_time))
+		throw new Error(`batch run state ${batchId} has an invalid confirmation_time`);
+	if (!isCanonicalTimestamp(record.authorization_expires_at))
+		throw new Error(`batch run state ${batchId} has an invalid authorization_expires_at`);
+	if (!isCanonicalTimestamp(record.created_at) || !isCanonicalTimestamp(record.updated_at))
+		throw new Error(`batch run state ${batchId} has invalid state timestamps`);
+	if (!Array.isArray(record.children) || record.children.length === 0)
+		throw new Error(`batch run state ${batchId} has no children`);
+	if (!BATCH_RUN_STATES.has(String(record.batch_state)))
+		throw new Error(`batch run state ${batchId} has an invalid batch_state`);
+	if (
+		typeof record.consecutive_qa_failures !== "number" ||
+		!Number.isInteger(record.consecutive_qa_failures) ||
+		record.consecutive_qa_failures < 0
+	)
+		throw new Error(`batch run state ${batchId} has an invalid consecutive_qa_failures`);
+	const budget = record.budget as Record<string, unknown>;
+	if (
+		typeof record.budget !== "object" ||
+		record.budget === null ||
+		typeof budget.max_children !== "number" ||
+		!Number.isInteger(budget.max_children) ||
+		budget.max_children <= 0 ||
+		!isCanonicalTimestamp(budget.deadline_at) ||
+		typeof budget.qa_failure_limit !== "number" ||
+		!Number.isInteger(budget.qa_failure_limit) ||
+		budget.qa_failure_limit <= 0
+	)
+		throw new Error(`batch run state ${batchId} has an invalid budget`);
+	if (!Array.isArray(record.commits) || record.commits.some((c) => typeof c !== "string"))
+		throw new Error(`batch run state ${batchId} has an invalid commits list`);
+	const seenTaskIds = new Set<string>();
+	for (const child of record.children) {
+		if (
+			typeof child !== "object" ||
+			child === null ||
+			typeof child.task_id !== "string" ||
+			!child.task_id ||
+			typeof child.slice_id !== "string" ||
+			!child.slice_id
+		)
+			throw new Error(`batch run state ${batchId} has an invalid child entry`);
+		if (!CHILD_RUN_STATES.has(String(child.state)))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid state`);
+		if (!Array.isArray(child.blocked_by) || child.blocked_by.some((b: unknown) => typeof b !== "string"))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid blocked_by`);
+		if (
+			(child.reason !== null && typeof child.reason !== "string") ||
+			(child.commit !== null && typeof child.commit !== "string")
+		)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has invalid terminal fields`);
+		// State invariants: commit/reason pair coherently with the state.
+		if (child.state === "committed" && child.commit === null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} is committed without a commit`);
+		if (child.state !== "committed" && child.commit !== null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has a commit but is not committed`);
+		if (
+			(child.state === "needs_human" || child.state === "skipped_blocked") &&
+			child.reason === null
+		)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} needs a terminal reason`);
+		if (seenTaskIds.has(child.task_id))
+			throw new Error(`batch run state ${batchId} has a duplicate child ${child.task_id}`);
+		seenTaskIds.add(child.task_id);
+	}
+	// A committed child must appear in the commits list (review-1).
+	for (const child of record.children) {
+		if (child.state === "committed" && child.commit !== null && !record.commits.includes(child.commit))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} commit is missing from commits`);
+	}
+	if (
+		(record.batch_state === "budget_stopped" ||
+			record.batch_state === "failed" ||
+			record.batch_state === "rejected") &&
+		record.children.some((child) => child.state === "enrolled" || child.state === "settled")
+	)
+		throw new Error(`batch run state ${batchId} is ${String(record.batch_state)} but a child is still mid-flight`);
+	if (
+		record.batch_state === "completed" &&
+		record.children.some((child) => child.state !== "committed")
+	)
+		throw new Error(`batch run state ${batchId} is completed but a child is not committed`);
+}
+
+export function prepareBatchRunState(input: {
+	batch_id: string;
+	initiative_slug: string;
+	children: BatchPlanChild[];
+	plan_digest: string;
+	base_head: string;
+	branch?: string;
+	confirmation_time: string;
+	authorization_expires_at: string;
+	budget: { max_children: number; deadline_at: string; qa_failure_limit: number };
+	now: string;
+}): BatchRunStateRecord {
+	validateBatchId(input.batch_id);
+	const prepared: BatchRunStateRecord = {
+		contract: "assurance_kernel/batch_run_state/v1",
+		batch_id: input.batch_id,
+		initiative_slug: input.initiative_slug,
+		plan_digest: input.plan_digest,
+		base_head: input.base_head,
+		branch: input.branch ?? `imm/${input.initiative_slug}`,
+		confirmation_time: input.confirmation_time,
+		authorization_expires_at: input.authorization_expires_at,
+		budget: input.budget,
+		batch_state: "prepared",
+		children: input.children.map((child) => ({
+			task_id: child.task_id,
+			slice_id: child.slice_id,
+			blocked_by: [...child.blocked_by],
+			state: "pending",
+			reason: null,
+			commit: null,
+		})),
+		consecutive_qa_failures: 0,
+		commits: [],
+		created_at: input.now,
+		updated_at: input.now,
+	};
+	return prepared;
+}
+
+export function readBatchRunState(root: string, batchId: string): BatchRunStateRecord | null {
+	const path = statePath(batchId);
+	if (!existsSync(join(root, path))) return null;
+	const parsed: unknown = JSON.parse(readSecureProjectFile(root, path));
+	validateRecordShape(parsed, batchId);
+	return parsed;
+}
+
+function ensureSecureDirectory(root: string, relative: string): string {
+	// review-4: create the directory with lstat verification so a pre-existing
+	// symlink cannot redirect state writes outside the project; mirrors the
+	// kernel storage boundary.
+	const target = join(root, relative);
+	const parent = dirname(target);
+	if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+	if (existsSync(target)) {
+		const stats = lstatSync(target);
+		if (!stats.isDirectory()) throw new Error(`${relative} exists but is not a directory`);
+	} else {
+		mkdirSync(target);
+	}
+	return target;
+}
+
+function writeFileAtomically(root: string, relative: string, bytes: string): void {
+	// review-4: no-symlink atomic write; lstat each created directory and the
+	// target so writes cannot be redirected by a pre-existing symlink.
+	const target = join(root, relative);
+	const targetDir = dirname(target);
+	const stats = lstatSync(targetDir);
+	if (!stats.isDirectory()) throw new Error(`${dirname(relative)} is not a directory`);
+	const tempPath = `${target}.${randomUUID()}.tmp`;	let fd: number | null = null;
+	try {
+		fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+		writeFileSync(fd, bytes, "utf8");
+		closeSync(fd);
+		fd = null;
+		renameSync(tempPath, target);
+	} finally {
+		if (fd !== null) closeSync(fd);
+		if (existsSync(tempPath)) { try { rmSync(tempPath); } catch { /* temp already moved */ } }
+	}
+}
+
+export function writeBatchRunState(
+	root: string,
+	record: BatchRunStateRecord,
+): BatchRunStateRecord {
+	const path = statePath(record.batch_id);
+	validateRecordShape(record, record.batch_id);
+	return withKernelStoreLock(root, () => {
+		const existing = existsSync(join(root, path)) ? readSecureProjectFile(root, path) : null;
+		if (existing !== null && existing === canonicalBytes(record)) return record;
+		const stored: BatchRunStateRecord = {
+			...record,
+			updated_at: new Date().toISOString(),
+		};
+		// review-4: secure directory + atomic no-symlink write.
+		ensureSecureDirectory(root, join(".imm", "state", "batches"));
+		writeFileAtomically(root, path, canonicalBytes(stored));
+		return stored;
+	});
+}
+
+export interface BatchRunReport {
+	contract: "assurance_kernel/batch_run_report/v1";
+	batch_id: string;
+	initiative_slug: string;
+	batch_state: BatchRunState;
+	children: BatchChildRun[];
+	commits: string[];
+	reason: string | null;
+	/** The single next action for the operator. */
+	next_action: string;
+	created_at: string;
+}
+
+function reportPath(batchId: string): string {
+	validateBatchId(batchId);
+	return join(".imm", "state", "batches", `${batchId}.report.json`);
+}
+
+/** Persist one current stop report per batch. Terminal reports are immutable;
+ * a resumable needs_human report may be replaced by the later stop reached
+ * after a fresh literal-user confirmation. */
+export function writeBatchRunReport(root: string, report: BatchRunReport): BatchRunReport {
+	const relative = reportPath(report.batch_id);
+	return withKernelStoreLock(root, () => {
+		const path = join(root, relative);
+		if (existsSync(path)) {
+			const original: unknown = JSON.parse(readSecureProjectFile(root, relative));
+			if (
+				typeof original !== "object" ||
+				original === null ||
+				(original as BatchRunReport).contract !== "assurance_kernel/batch_run_report/v1"
+			)
+				throw new Error(`batch run report ${report.batch_id} has an unknown contract`);
+			const prior = original as BatchRunReport;
+			if (canonicalReportBytes(prior) === canonicalReportBytes(report)) return prior;
+			if (prior.batch_state !== "needs_human") return prior;
+		}
+		ensureSecureDirectory(root, join(".imm", "state", "batches"));
+		writeFileAtomically(root, relative, canonicalReportBytes(report));
+		return report;
+	});
+}
+
+function canonicalReportBytes(report: BatchRunReport): string {
+	return `${JSON.stringify(report, null, 2)}\n`;
+}
+
+/** All terminal batch states; needs_human is a park, not terminal. */
+export function isTerminalBatchState(state: BatchRunState): boolean {
+	return state === "completed" || state === "budget_stopped" || state === "failed" || state === "rejected";
+}

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

@@ -0,0 +1,60 @@
+import type { GithubInitiativeObservation } from "../github_issue_tracker";
+
+export interface BatchPlanBudget {
+	max_children: number;
+	deadline_at: string;
+	qa_failure_limit: number;
+}
+
+export interface BatchPlanBudgetInput {
+	max_children?: number;
+	deadline_at?: string;
+	qa_failure_limit?: number;
+}
+
+export interface BatchPlanDigestChild {
+	task_id: string;
+	intent_path: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	blocked_by: string[];
+}
+
+export type BatchPlanChildStatus =
+	| "enrollable"
+	| "already_settled"
+	| "already_owned"
+	| "needs_human"
+	| "blocked";
+
+export interface BatchPlanChild {
+	task_id: string;
+	slice_id: string;
+	blocked_by: string[];
+	status: BatchPlanChildStatus;
+	reason: "critical" | "invalid_intent" | "dependency_unavailable" | null;
+	intent_path: string | null;
+	intent_revision: number | null;
+	intent_content_hash: string | null;
+}
+
+export interface BatchPlan {
+	contract: "assurance_kernel/batch_plan/v1";
+	initiative_slug: string;
+	confirmation_time: string;
+	tracker_observation: GithubInitiativeObservation;
+	children: BatchPlanChild[];
+	enrollable: BatchPlanDigestChild[];
+	plan_digest: string;
+	budget: BatchPlanBudget;
+}
+
+export interface ProjectBatchPlanInput {
+	confirmation_time: string;
+	budget?: BatchPlanBudgetInput;
+}
+
+export type InitiativeObservationReader = (
+	root: string,
+	initiativeSlug: string,
+) => Promise<GithubInitiativeObservation>;

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.