immune-brain 5.2.0 → 5.5.1

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

@@ -0,0 +1,248 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { projectTaskStatus } from "../assurance/coordinator";
+import { readTaskIntent } from "../kernel/intent";
+import { readAuditTaskPair, readSecureProjectFile, readSettledTaskEvidence, revisionForContent } from "../kernel/storage";
+import { auditRunRecordPath, auditRunTerminalProofPath } from "../kernel/storage_paths";
+import { captureGitTaskRevisionSnapshot, pathMatchesScope } from "../workspace_scope";
+import { readParentConsolidationReceipt } from "./batch_state";
+import { parseFinalVerification } from "./batch_final_verification";
+
+export interface DeliveryRun { task_id: string; run_id: string }
+export interface DeliveryConsolidation extends DeliveryRun { source_runs: DeliveryRun[] }
+export const consolidationSchema = {
+	type: "object", additionalProperties: false, required: ["task_id", "run_id", "source_runs"],
+	properties: {
+		task_id: { type: "string" }, run_id: { type: "string" },
+		source_runs: { type: "array", minItems: 1, maxItems: 16, items: {
+			type: "object", additionalProperties: false, required: ["task_id", "run_id"],
+			properties: { task_id: { type: "string" }, run_id: { type: "string" } },
+		} },
+	},
+} as const;
+
+function object(value: unknown, keys: string[]): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value) ||
+		Object.keys(value).sort().join() !== [...keys].sort().join()) throw new Error("invalid delivery_consolidation shape");
+	return value as Record<string, unknown>;
+}
+function run(value: unknown): DeliveryRun {
+	const raw = object(value, ["task_id", "run_id"]);
+	if (typeof raw.task_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(raw.task_id) ||
+		typeof raw.run_id !== "string" || !/^run-[A-Za-z0-9][A-Za-z0-9._-]{0,123}$/.test(raw.run_id))
+		throw new Error("invalid consolidation task/run identity");
+	return { task_id: raw.task_id, run_id: raw.run_id };
+}
+export function parseDeliveryConsolidation(value: unknown): DeliveryConsolidation | undefined {
+	if (value === undefined) return undefined;
+	const raw = object(value, ["task_id", "run_id", "source_runs"]);
+	const final = run({ task_id: raw.task_id, run_id: raw.run_id });
+	if (!Array.isArray(raw.source_runs) || !raw.source_runs.length || raw.source_runs.length > 16)
+		throw new Error("consolidation requires 1–16 source runs");
+	const sources = raw.source_runs.map(run).sort((a, b) => a.task_id.localeCompare(b.task_id));
+	if (new Set([final.task_id, ...sources.map(source => source.task_id)]).size !== sources.length + 1)
+		throw new Error("duplicate/self consolidation selection");
+	return { ...final, source_runs: sources };
+}
+export function consolidationDigest(value: unknown): string {
+	return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function git(root: string, argv: string[]): string {
+	const result = spawnSync("git", ["-C", root, ...argv], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+	if (result.status !== 0) throw new Error(`consolidation Git inspection failed: ${argv[0]}`);
+	return result.stdout;
+}
+export interface ConsolidationEnvelope {
+	initiative_slug: string;
+	plan_digest: string;
+	selection: DeliveryConsolidation;
+	parent_tasks: Array<{ task_id: string; intent_hash: string }>;
+	branch: string;
+	head: string;
+	final_commands: string[];
+	/** All source approvals are historical; only the final run approves the composed bytes. */
+	runs: Array<{ task_id: string; run_id: string; record_hash: string; proof_hash: string;
+		intent_hash: string; review_revision: unknown }>;
+	delivery_diff_hash: string;
+	manifest: Array<{ path: string; mode: string | null; oid: string | null }>;
+}
+export interface ConsolidationReceipt {
+	contract: "assurance_kernel/parent_delivery_consolidation/v1";
+	envelope: ConsolidationEnvelope;
+	digest: string;
+	commit: string | null;
+}
+
+export function parseConsolidationReceipt(value: unknown): ConsolidationReceipt {
+	const raw = object(value, ["contract", "envelope", "digest", "commit"]);
+	if (raw.contract !== "assurance_kernel/parent_delivery_consolidation/v1" ||
+		(typeof raw.commit !== "string" && raw.commit !== null) ||
+		(typeof raw.commit === "string" && !/^[a-f0-9]{40,64}$/.test(raw.commit))) throw new Error("invalid consolidation receipt");
+	const e = object(raw.envelope, ["initiative_slug", "plan_digest", "selection", "parent_tasks", "branch", "head",
+		"final_commands", "runs", "delivery_diff_hash", "manifest"]);
+	const selection = parseDeliveryConsolidation(e.selection)!;
+	if (JSON.stringify(selection) !== JSON.stringify(e.selection) || typeof e.initiative_slug !== "string" ||
+		!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(e.initiative_slug) || typeof e.branch !== "string" || !e.branch ||
+		typeof e.head !== "string" || !/^[a-f0-9]{40,64}$/.test(e.head) ||
+		!Array.isArray(e.parent_tasks) || !e.parent_tasks.length || !Array.isArray(e.runs) ||
+		!Array.isArray(e.manifest) || !e.manifest.length || !Array.isArray(e.final_commands) ||
+		e.final_commands.some(c => typeof c !== "string") || typeof raw.digest !== "string" ||
+		raw.digest !== consolidationDigest(e)) throw new Error("consolidation receipt digest/shape mismatch");
+	const hash = (value: unknown) => typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
+	if (!hash(e.plan_digest) || !hash(e.delivery_diff_hash) || !parseFinalVerification(e.final_commands)?.length)
+		throw new Error("invalid consolidation proof/commands");
+	const expectedRuns = [selection, ...selection.source_runs].map(({ task_id, run_id }) => ({ task_id, run_id }));
+	if (e.runs.length !== expectedRuns.length) throw new Error("consolidation run contributions missing");
+	for (let index = 0; index < e.runs.length; index++) {
+		const binding = object(e.runs[index], ["task_id", "run_id", "record_hash", "proof_hash", "intent_hash", "review_revision"]);
+		if (JSON.stringify(run({ task_id: binding.task_id, run_id: binding.run_id })) !== JSON.stringify(expectedRuns[index]) ||
+			!hash(binding.record_hash) || !hash(binding.proof_hash) || !hash(binding.intent_hash))
+			throw new Error("consolidation run contribution binding mismatch");
+	}
+	const parentIds = e.parent_tasks.map(value => {
+		const task = object(value, ["task_id", "intent_hash"]);
+		if (typeof task.task_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(task.task_id) || !hash(task.intent_hash))
+			throw new Error("invalid consolidation Parent binding");
+		return task.task_id;
+	});
+	if (new Set(parentIds).size !== parentIds.length) throw new Error("duplicate consolidation Parent contribution");
+	const paths = e.manifest.map(value => {
+		const entry = object(value, ["path", "mode", "oid"]);
+		if (typeof entry.path !== "string" || !entry.path || entry.path.startsWith("/") || entry.path.includes("\\") ||
+			entry.path.split("/").some(part => !part || part === "." || part === "..") ||
+			(entry.mode !== "100644" && entry.mode !== "100755" && entry.mode !== null) ||
+			(entry.oid !== null && (typeof entry.oid !== "string" || !/^[a-f0-9]{40,64}$/.test(entry.oid))) ||
+			((entry.mode === null) !== (entry.oid === null))) throw new Error("invalid consolidation file identity");
+		return entry.path;
+	});
+	if (new Set(paths).size !== paths.length || JSON.stringify(paths) !== JSON.stringify([...paths].sort()))
+		throw new Error("consolidation manifest is not canonical");
+	return raw as unknown as ConsolidationReceipt;
+}
+
+async function runEvidence(root: string, identity: DeliveryRun) {
+	const settled = readSettledTaskEvidence(root, identity.task_id);
+	if (!settled || settled.runId !== identity.run_id || settled.proof.terminal_lifecycle !== "done")
+		throw new Error(`consolidation requires the exact settled done run: ${identity.task_id}`);
+	const record = settled.record;
+	if (record.contract !== "assurance_kernel/task_record/v4") throw new Error("consolidation requires v4 immutable Git delivery records");
+	const pair = readAuditTaskPair(root, identity.task_id, identity.run_id);
+	if (!pair || JSON.stringify(pair.record) !== JSON.stringify(settled.record) || JSON.stringify(pair.proof) !== JSON.stringify(settled.proof))
+		throw new Error(`consolidation source audit mismatch: ${identity.task_id}`);
+	const current = readTaskIntent(root, identity.task_id, settled.record.intent_ref.path);
+	if (current.content_hash !== settled.record.intent_ref.content_hash) throw new Error("consolidation Intent changed");
+	const status = await projectTaskStatus(root, identity.task_id);
+	if (status.error || status.projection.run_id !== identity.run_id || !status.projection.completion_ready)
+		throw new Error(`consolidation run has no completion proof: ${identity.task_id}`);
+	const review = [...record.attestations].reverse().find(a => a.kind === "review")?.review_revision ?? null;
+	if (review) {
+		if (git(root, ["rev-parse", `${review.review_commit}^{tree}`]).trim() !== review.review_tree ||
+			git(root, ["rev-parse", `${review.review_commit}^@`]).trim() !== review.base_head)
+			throw new Error("consolidation immutable Review revision mismatch");
+	}
+	return { settled: { ...settled, record }, binding: { task_id: identity.task_id, run_id: identity.run_id,
+		record_hash: revisionForContent(readSecureProjectFile(root, auditRunRecordPath(identity.task_id, identity.run_id))),
+		proof_hash: revisionForContent(readSecureProjectFile(root, auditRunTerminalProofPath(identity.task_id, identity.run_id))),
+		intent_hash: current.content_hash, review_revision: review } };
+}
+
+/** Read-only preparation: no index, association, receipt, or Git ref writes before the native gate. */
+export async function prepareDeliveryConsolidation(root: string, initiativeSlug: string, planDigest: string,
+	parentTaskIds: string[], selection: DeliveryConsolidation, commands: string[]): Promise<ConsolidationEnvelope> {
+	selection = parseDeliveryConsolidation(selection)!;
+	const all = [selection, ...selection.source_runs];
+	if (!selection.source_runs.some(source => parentTaskIds.includes(source.task_id)))
+		throw new Error("consolidation must select an original Parent contribution");
+	const sources = [];
+	for (const identity of all) sources.push(await runEvidence(root, identity));
+	const final = sources[0]!.settled.record;
+	if (final.intent_snapshot.risk === "routine" || !sources[0]!.binding.review_revision || !final.git_base_head)
+		throw new Error("final consolidation requires fresh QA and independent material/critical Review");
+	const snapshot = captureGitTaskRevisionSnapshot(root, final.intent_snapshot.scope_hint, final.git_base_head, selection.task_id);
+	const diffHash = consolidationDigest(snapshot);
+	if (!final.attestations.some(a => a.kind === "qa" && a.diff_hash === diffHash && a.task_revision === final.intent_snapshot.revision &&
+		a.intent_content_hash === final.intent_ref.content_hash && a.acceptance_results.length === final.intent_snapshot.acceptance.length &&
+		a.acceptance_results.every(r => r.status === "passed")) ||
+		!final.attestations.some(a => a.kind === "review" && a.diff_hash === diffHash && a.review_revision &&
+			a.task_revision === final.intent_snapshot.revision && a.intent_content_hash === final.intent_ref.content_hash))
+		throw new Error("final composed bytes do not match fresh QA/Review");
+	const finalScope = final.intent_snapshot.scope_hint;
+	for (const source of sources.slice(1)) {
+		const record = source.settled.record;
+		if (!record.git_base_head) throw new Error("source run has no Git delivery base");
+		const review = source.binding.review_revision;
+		if (!review) throw new Error("source run has no immutable Review delivery");
+		for (const path of git(root, ["diff", "--name-only", "--no-renames", "-z", record.git_base_head, review.review_commit]).split("\0").filter(Boolean))
+			if (!finalScope.some(scope => pathMatchesScope(path, scope))) throw new Error(`source contribution is not covered by final Review scope: ${path}`);
+	}
+	const auditPaths = new Set(all.flatMap(identity => [auditRunRecordPath(identity.task_id, identity.run_id), auditRunTerminalProofPath(identity.task_id, identity.run_id)]));
+	const dirty = [...new Set([...git(root, ["diff", "--name-only", "--no-renames", "-z", "HEAD"]).split("\0"),
+		...git(root, ["ls-files", "--others", "--exclude-standard", "-z"]).split("\0")].filter(Boolean))].sort();
+	const unstaged = git(root, ["diff", "--name-only", "-z"]).split("\0").filter(Boolean);
+	if (unstaged.some(path => !auditPaths.has(path))) throw new Error("consolidation has unstaged delivery drift");
+	const manifest = dirty.map(path => {
+		if (!finalScope.some(scope => pathMatchesScope(path, scope)) && !auditPaths.has(path)) throw new Error(`dirty_outside_scope: ${path}`);
+		if (!existsSync(join(root, path))) return { path, mode: null, oid: null };
+		const stat = lstatSync(join(root, path));
+		if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("consolidation only accepts regular delivery files");
+		const oid = git(root, ["hash-object", "--", path]).trim();
+		const staged = git(root, ["ls-files", "--stage", "--", path]);
+		const mode = staged ? staged.split(" ")[0]! : stat.mode & 0o111 ? "100755" : "100644";
+		return { path, mode, oid };
+	});
+	const parentTasks = parentTaskIds.map(task_id => ({ task_id, intent_hash: readTaskIntent(root, task_id).content_hash }));
+	return { initiative_slug: initiativeSlug, plan_digest: planDigest, selection, parent_tasks: parentTasks,
+		branch: git(root, ["symbolic-ref", "--short", "HEAD"]).trim(), head: git(root, ["rev-parse", "HEAD"]).trim(),
+		final_commands: commands, runs: sources.map(source => source.binding), delivery_diff_hash: diffHash, manifest };
+}
+
+/** Verify committed content against the accepted manifest, not against a historical source bundle. */
+export async function verifyConsolidatedCommit(root: string, receipt: ConsolidationReceipt): Promise<void> {
+	parseConsolidationReceipt(receipt);
+	const { envelope: e, commit } = receipt;
+	if (!commit) throw new Error("consolidation commit receipt is pending");
+	// Recovery must preserve the whole checkout, not just the reviewed scope snapshot.
+	if (git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]).length)
+		throw new Error("consolidation recovery requires a clean workspace");
+	if (git(root, ["ls-files", "-v", "-z"]).split("\0").some(entry => entry && !entry.startsWith("H ")))
+		throw new Error("consolidation recovery rejects hidden index flags");
+	const message = git(root, ["show", "-s", "--format=%B", commit]);
+	if (!message.startsWith(`imm(${e.selection.task_id}): `) ||
+		!message.split("\n").includes(`Immune-Brain-Task: ${e.selection.task_id}`))
+		throw new Error("consolidation commit lacks the selected final task identity");
+	if (git(root, ["rev-parse", `${commit}^@`]).trim() !== e.head ||
+		git(root, ["symbolic-ref", "--short", "HEAD"]).trim() !== e.branch ||
+		spawnSync("git", ["-C", root, "merge-base", "--is-ancestor", commit, "HEAD"], { stdio: "ignore" }).status !== 0)
+		throw new Error("consolidation commit lineage mismatch");
+	const paths = git(root, ["diff-tree", "--no-commit-id", "--no-renames", "--name-only", "-r", "-z", e.head, commit]).split("\0").filter(Boolean).sort();
+	if (JSON.stringify(paths) !== JSON.stringify(e.manifest.map(entry => entry.path))) throw new Error("consolidation commit manifest differs");
+	for (const entry of e.manifest) {
+		const tree = git(root, ["ls-tree", "-z", commit, "--", entry.path]);
+		const identity = tree ? tree.split("\t")[0]!.split(" ") : null;
+		if ((identity?.[0] ?? null) !== entry.mode || (identity?.[2] ?? null) !== entry.oid)
+			throw new Error("consolidation committed bytes/mode mismatch");
+	}
+	for (const identity of e.runs) {
+		const current = (await runEvidence(root, identity)).binding;
+		if (JSON.stringify(current) !== JSON.stringify(identity)) throw new Error("consolidation source proof changed");
+		for (const path of [auditRunRecordPath(identity.task_id, identity.run_id), auditRunTerminalProofPath(identity.task_id, identity.run_id)])
+			if (git(root, ["show", `${commit}:${path}`]) !== readSecureProjectFile(root, path)) throw new Error("committed source audit mismatch");
+	}
+	for (const parent of e.parent_tasks)
+		if (readTaskIntent(root, parent.task_id).content_hash !== parent.intent_hash) throw new Error("consolidated Parent Intent changed");
+	const final = readSettledTaskEvidence(root, e.selection.task_id)!.record;
+	if (final.contract !== "assurance_kernel/task_record/v4") throw new Error("final consolidation record changed contract");
+	const live = captureGitTaskRevisionSnapshot(root, final.intent_snapshot.scope_hint, final.git_base_head, e.selection.task_id);
+	if (consolidationDigest(live) !== e.delivery_diff_hash) throw new Error("consolidated delivery changed after commit");
+}
+
+export async function observeConsolidatedDeliveries(root: string, slug: string, requiredIds: readonly string[]) {
+	const receipt = readParentConsolidationReceipt(root, slug);
+	if (!receipt || !receipt.commit) return null;
+	if (JSON.stringify(receipt.envelope.parent_tasks.map(task => task.task_id).sort()) !== JSON.stringify([...requiredIds].sort()))
+		throw new Error("consolidation Parent contribution set changed");
+	await verifyConsolidatedCommit(root, receipt);
+	return receipt;
+}

package/plugins/immune-brain/runtime/workspace_scope.ts

@@ -62,9 +62,15 @@ function enrollmentBaselinePath(root: string): string {
 	return join(root, ".imm/state/enrollment-baseline.json");
 }
 
-export function writeEnrollmentBaseline(root: string): void {
+/**
+ * Records the dirt that predates the task. `claimedPaths` are the in-scope
+ * paths the confirmed Enrollment gate listed: they are left out, so later
+ * snapshots treat them as task work instead of withholding them.
+ */
+export function writeEnrollmentBaseline(root: string, claimedPaths: readonly string[] = []): void {
 	const snapshot = captureGitWorkspaceSnapshot(root);
 	if (!snapshot) return;
+	for (const path of claimedPaths) delete snapshot.dirty_files[path];
 	const path = enrollmentBaselinePath(root);
 	mkdirSync(dirname(path), { recursive: true });
 	writeFileSync(path, `${JSON.stringify(snapshot)}\n`);
@@ -220,13 +226,14 @@ export function setGitTaskSnapshotTestHook(hook: () => void): () => void {
 	};
 }
 
-function gitBytes(root: string, args: string[]): Buffer {
+function gitBytes(root: string, args: string[], env?: NodeJS.ProcessEnv): Buffer {
 	const diff = args[0] === "diff";
 	const command = diff ? ["diff", "--exit-code", ...args.slice(1)] : args;
 	const result = spawnSync("git", ["--no-optional-locks", "-c", "diff.autoRefreshIndex=false", "-C", root, ...command], {
 		encoding: null,
 		stdio: ["ignore", "pipe", "pipe"],
 		maxBuffer: 8 * 1024 * 1024,
+		...(env ? { env } : {}),
 	});
 	if ((result.status !== 0 && !(diff && result.status === 1)) || !Buffer.isBuffer(result.stdout)) {
 		throw new Error(`Git task snapshot command failed: git ${args.join(" ")}`);
@@ -282,7 +289,7 @@ function decodeIndexFlaggedPaths(bytes: Buffer, label: string): Array<{ path: st
 		const record = bytes.subarray(start, index);
 		if (record.length < 3 || record[1] !== 0x20) throw new Error(`${label} contains a malformed entry`);
 		const tag = String.fromCharCode(record[0]);
-		if (tag === "h" || tag === "S") {
+		if (tag === "h" || tag === "S" || tag === "s") {
 			flagged.push({
 				path: decodeCanonicalGitPath(record.subarray(2), label),
 				flag: tag === "h" ? "assume-unchanged" : "skip-worktree",
@@ -394,9 +401,10 @@ function taskPathMatchesScope(path: string, scope: string[]): boolean {
 
 /**
  * A staged in-scope path that still equals the Enrollment baseline predates the
- * task. Dropping it silently let QA attest workspace bytes that the Review
- * revision did not carry, so it is a hard stop instead: reverting and reapplying
- * yields the same bytes, and only a fresh Enrollment from a clean scope recovers.
+ * task and was not listed by the confirmed Enrollment gate. Dropping it silently
+ * let QA attest workspace bytes that the Review revision did not carry, so it is
+ * a hard stop instead: reverting and reapplying yields the same bytes, and only
+ * a fresh Enrollment that lists the path, or starts from a clean scope, recovers.
  * The task's own planning sidecar is exempt, as it is in dirtyScopePaths:
  * Enrollment requires it tracked, so it is routinely staged in the baseline.
  */
@@ -411,14 +419,15 @@ function assertNoPreEnrollmentScopeChanges(root: string, scopedStagedPaths: read
 		.sort(comparePaths);
 	if (withheld.length > 0)
 		throw new Error(
-			`task scope contains staged changes that predate Enrollment and cannot become task work: ${withheld.join(", ")}; stop the task and re-enroll from a clean scope`,
+			`task scope contains staged changes that predate Enrollment and cannot become task work: ${withheld.join(", ")}; stop the task and enroll again so the Enrollment gate lists them, or from a clean scope`,
 		);
 }
 
 /**
  * In-scope paths that are already staged, modified or untracked relative to
- * HEAD. Enrollment refuses these: the baseline would record them as user dirt
- * and they could never be delivered by the task.
+ * HEAD. The Enrollment gate lists them; the ones it listed are claimed as task
+ * work, and any other one refuses Enrollment, because the baseline would record
+ * it as user dirt and the task could never deliver it.
  */
 export function dirtyScopePaths(projectRoot: string, scopeHint: unknown, taskId?: string): string[] {
 	const root = realpathSync(resolve(projectRoot));
@@ -430,7 +439,7 @@ export function dirtyScopePaths(projectRoot: string, scopeHint: unknown, taskId?
 	);
 }
 
-function taskSnapshotOnce(root: string, scope: string[], taskId?: string): GitTaskSnapshot {
+function taskSnapshotOnce(root: string, scope: string[], taskId?: string, tolerated?: string[]): GitTaskSnapshot {
 	const repositoryRoot = git(root, ["rev-parse", "--show-toplevel"])?.trim();
 	const head = git(root, ["rev-parse", "--verify", "HEAD^{commit}"])?.trim();
 	if (!repositoryRoot || !head || !GIT_OBJECT_ID.test(head))
@@ -462,8 +471,10 @@ function taskSnapshotOnce(root: string, scope: string[], taskId?: string): GitTa
 	const uncommittedInScope = [...new Set([...unstagedPaths, ...untrackedPaths])]
 		.filter((path) => taskPathMatchesScope(path, scope))
 		.sort(comparePaths);
-	if (uncommittedInScope.length > 0)
-		throw new Error(`task scope contains unstaged or untracked changes: ${uncommittedInScope.join(", ")}`);
+	if (uncommittedInScope.length > 0) {
+		if (!tolerated) throw new Error(`task scope contains unstaged or untracked changes: ${uncommittedInScope.join(", ")}`);
+		tolerated.splice(0, tolerated.length, ...uncommittedInScope);
+	}
 
 	const taskPaths = [...new Set(stagedPaths)]
 		.filter((path) => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope))
@@ -495,6 +506,7 @@ export function captureGitTaskSnapshot(
 	projectRoot: string,
 	scopeHint: unknown,
 	taskId?: string,
+	tolerated?: string[],
 ): GitTaskSnapshot {
 	const requestedRoot = resolve(projectRoot);
 	const requestedStat = lstatSync(requestedRoot);
@@ -502,9 +514,9 @@ export function captureGitTaskSnapshot(
 		throw new Error("task snapshot root must be a real directory");
 	const root = realpathSync(requestedRoot);
 	const scope = assertCanonicalTaskScope(scopeHint);
-	const before = taskSnapshotOnce(root, scope, taskId);
+	const before = taskSnapshotOnce(root, scope, taskId, tolerated);
 	gitTaskSnapshotTestHook?.();
-	const after = taskSnapshotOnce(root, scope, taskId);
+	const after = taskSnapshotOnce(root, scope, taskId, tolerated);
 	if (JSON.stringify(after) !== JSON.stringify(before))
 		throw new Error("Git task snapshot changed while being captured");
 	return before;
@@ -561,6 +573,7 @@ function taskRevisionSnapshotOnce(
 	scope: string[],
 	baseHead: string,
 	taskId?: string,
+	tolerated?: string[],
 ): GitTaskRevisionSnapshot {
 	const repositoryRoot = git(root, ["rev-parse", "--show-toplevel"])?.trim();
 	const head = git(root, ["rev-parse", "--verify", "HEAD^{commit}"])?.trim();
@@ -606,8 +619,10 @@ function taskRevisionSnapshotOnce(
 		"Git task revision paths",
 	);
 	const drift = [...new Set([...scopedUnstagedPaths, ...scopedUntrackedPaths])].sort(comparePaths);
-	if (drift.length > 0)
-		throw new Error(`task scope contains unstaged or untracked changes: ${drift.join(", ")}`);
+	if (drift.length > 0) {
+		if (!tolerated) throw new Error(`task scope contains unstaged or untracked changes: ${drift.join(", ")}`);
+		tolerated.splice(0, tolerated.length, ...drift);
+	}
 
 	const changed = [...new Set(scopedStagedPaths)].sort(comparePaths);
 	const changedPaths: Record<string, GitTaskIndexEntry> = {};
@@ -640,6 +655,7 @@ export function captureGitTaskRevisionSnapshot(
 	scopeHint: unknown,
 	baseHead: unknown,
 	taskId?: string,
+	tolerated?: string[],
 ): GitTaskRevisionSnapshot {
 	const requestedRoot = resolve(projectRoot);
 	const requestedStat = lstatSync(requestedRoot);
@@ -650,9 +666,9 @@ export function captureGitTaskRevisionSnapshot(
 		throw new Error("task revision base must be a Git commit id");
 	const scope = assertCanonicalTaskScope(scopeHint);
 	const normalizedBase = baseHead.toLowerCase();
-	const before = taskRevisionSnapshotOnce(root, scope, normalizedBase, taskId);
+	const before = taskRevisionSnapshotOnce(root, scope, normalizedBase, taskId, tolerated);
 	gitTaskSnapshotTestHook?.();
-	const after = taskRevisionSnapshotOnce(root, scope, normalizedBase, taskId);
+	const after = taskRevisionSnapshotOnce(root, scope, normalizedBase, taskId, tolerated);
 	if (JSON.stringify(after) !== JSON.stringify(before))
 		throw new Error("Git task revision changed while being captured");
 	return before;
@@ -705,6 +721,36 @@ export function taskDeliveryIdentity(
 	return taskDiffIdentity(projectRoot, record.intent_snapshot.scope_hint, record.task_id);
 }
 
+/**
+ * The delivery identity for a read-only status projection. Unstaged or
+ * untracked in-scope paths do not refuse it: the identity is the staged one and
+ * the paths are returned for a warning. Nothing may be frozen from this value;
+ * every snapshot that is frozen goes through `taskDeliveryIdentity`, which
+ * still refuses those paths.
+ */
+export function taskStatusIdentity(
+	projectRoot: string,
+	record: TaskDeliveryRecord,
+): GitTaskDiffIdentity & { unstaged_scope_paths: string[] } {
+	const unstaged: string[] = [];
+	const scope = record.intent_snapshot.scope_hint;
+	if (record.contract === "assurance_kernel/task_record/v4") {
+		if (!record.git_base_head) throw new Error("TaskRecord v4 is missing git_base_head");
+		const snapshot = captureGitTaskRevisionSnapshot(projectRoot, scope, record.git_base_head, record.task_id, unstaged);
+		return {
+			diff_hash: hashTaskSnapshot(snapshot),
+			changed_paths: Object.keys(snapshot.changed_paths).sort(comparePaths),
+			unstaged_scope_paths: unstaged,
+		};
+	}
+	const snapshot = captureGitTaskSnapshot(projectRoot, scope, record.task_id, unstaged);
+	return {
+		diff_hash: hashTaskSnapshot(snapshot),
+		changed_paths: Object.keys(snapshot.staged_files).sort(comparePaths),
+		unstaged_scope_paths: unstaged,
+	};
+}
+
 /** The same v4 identity for an immutable delivered commit, without touching the index. */
 export function taskCommitRevisionIdentity(projectRoot: string, scopeHint: unknown, baseHead: string, commit: string): GitTaskDiffIdentity {
 	const requested = resolve(projectRoot);
@@ -989,3 +1035,65 @@ export function assertChangedFilesWithinScope(
 		);
 	}
 }
+
+function gitBlobId(body: Buffer, length: number): string {
+	const hash = createHash(length === 64 ? "sha256" : "sha1");
+	hash.update(`blob ${body.length}\0`);
+	hash.update(body);
+	return hash.digest("hex");
+}
+
+/**
+ * In-scope tracked paths whose working-directory content differs from `tree`.
+ * Bytes are compared directly, never through the index stat cache, so a file a
+ * command rewrote with identical content is not a difference. Paths outside the
+ * scope are the user's environment and are not read.
+ */
+// A hosting process that carries one of these would compare another repository
+// or index instead of the task's working directory.
+const GIT_REPOSITORY_BINDINGS = [
+	"GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY",
+	"GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE", "GIT_PREFIX",
+];
+
+export function inScopeTrackedDrift(projectRoot: string, tree: string, scopeHint: unknown): string[] {
+	const root = resolve(projectRoot);
+	const env = { ...process.env };
+	for (const name of GIT_REPOSITORY_BINDINGS) delete env[name];
+	if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(tree)) throw new Error("frozen tree has invalid identity");
+	const scope = Array.isArray(scopeHint) ? scopeHint.filter((entry): entry is string => typeof entry === "string") : [];
+	const inScope = (path: string) => !isNonDeliveryPath(path) && taskPathMatchesScope(path, scope);
+	const expected = new Map<string, { mode: string; oid: string }>();
+	for (const entry of gitBytes(root, ["ls-tree", "-r", "-z", tree], env).toString("utf8").split("\0")) {
+		const tab = entry.indexOf("\t");
+		if (tab < 0) continue;
+		const [mode, , oid] = entry.slice(0, tab).split(" ");
+		const path = entry.slice(tab + 1);
+		if (mode && oid && inScope(path)) expected.set(path, { mode, oid });
+	}
+	const tracked = splitNull(gitBytes(root, ["ls-files", "-z"], env).toString("utf8")).filter(inScope);
+	const regular: string[] = [];
+	const drift = new Set<string>();
+	for (const path of new Set([...expected.keys(), ...tracked])) {
+		const want = expected.get(path);
+		let stat;
+		try { stat = lstatSync(join(root, path)); } catch { stat = null; }
+		if (!want || !stat) { if (want || stat) drift.add(path); continue; }
+		// A submodule is pinned by the index, not by working-directory bytes.
+		if (want.mode === "160000") continue;
+		if (stat.isSymbolicLink()) {
+			if (want.mode !== "120000" || gitBlobId(Buffer.from(readlinkSync(join(root, path))), want.oid.length) !== want.oid) drift.add(path);
+		} else if (!stat.isFile() || want.mode === "120000" || (want.mode === "100755") !== ((stat.mode & 0o100) !== 0)) drift.add(path);
+		else regular.push(path);
+	}
+	if (regular.length) {
+		// `--stdin-paths` applies the same clean filters as `git add` would.
+		const hashed = spawnSync("git", ["--no-optional-locks", "-C", root, "hash-object", "--stdin-paths"], {
+			input: `${regular.join("\n")}\n`, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], maxBuffer: 8 * 1024 * 1024, env,
+		});
+		const ids = hashed.status === 0 ? hashed.stdout.split("\n").filter(Boolean) : [];
+		if (ids.length !== regular.length) throw new Error("Git task snapshot command failed: git hash-object");
+		regular.forEach((path, index) => { if (ids[index] !== expected.get(path)!.oid) drift.add(path); });
+	}
+	return [...drift].sort(comparePaths);
+}

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

@@ -15,6 +15,12 @@
   their own existing grant. An explicit approval already covering the same
   operation, target, and impact — including a valid batch capability — stays
   usable without another gate.
+- A precondition commit is the one commit the runtime makes without a separate
+  grant. When an `imm-run` precondition would fail only because paths are
+  uncommitted, the runtime commits that precondition's committable set, an
+  explicit path list, silently and continues. It runs Git hooks normally and
+  grants no push, publication, history rewrite, or commit of any other path. A
+  model never makes this commit itself and never asks the user to make it.
 - Before a new outbound effect, check the project's existing research channel and
 data scope. A public article, a mock, a documentation example, or a local
 read-only database gives no authority to call an arbitrary provider or send new
@@ -55,11 +61,19 @@ framing does not load that execution guidance.
 
 Ordinary host input stays host-native and does not run natural-language Managed
 routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
-`imm-planner`, or `imm-run` Skill entry.
+`imm-planner`, or `imm-run` Skill entry. For `imm-planner` and `imm-brainstorm`
+the user's request for that planning or clarification, by slash command or in
+natural language, is such an entry; a request that asks for neither stays
+host-native. `imm-run` starts only from a literal-user entry. A model-entered
+Planner or Brainstorm leaves the session's run entry unchanged.
 
 1. **Continue an existing Managed owner explicitly**: an active Assurance
    projection, TaskIntent, TaskRecord, reviewer `follow_up`, or other nonterminal
    Managed owner remains authoritative; the user resumes it with `imm-run`.
+   Once that entry binds this session, ordinary status questions and in-scope
+   clarification retain automatic response continuation. Explicit cancel, planning
+   entry or session replacement releases the binding; Host continuation metadata
+   remains non-authoritative.
 2. **Start explicitly**: the selected Immune-Brain Skill owns its planning or
    coordination work. It creates only requested artifacts and their required
    parent directories. Explicit Planner entry also owns absent routing-policy
@@ -112,6 +126,8 @@ Routine Managed enrollment is the first step of an explicit `imm-run` entry and
 
 For an unborn symbolic Git HEAD, the same Enrollment confirmation discloses an empty root commit. After approval, the Host creates that commit without staging project content or changing the index/worktree, then revalidates ownership and rehearses Enrollment against the new base. Git identity uses existing environment/config values with an explicit automation fallback, never config writes. Decline or pre-initialization cancellation leaves HEAD unborn; if later Enrollment fails or is cancelled, report the remaining commit. Invalid Git refs are errors, not initialization candidates.
 
+Before Enrollment prepares its binding, the Host commits the Enrollment committable set when an untracked TaskIntent would otherwise fail it. The set is the task's own TaskIntent and the Spec its binding names. In-scope changes that already exist are not committed: the Enrollment gate lists them and only the listed paths become task work on confirmation, so a dirty scope is never claimed without that list being shown. The commit is silent, needs no separate confirmation, and the native confirmation binds the HEAD that results. When no precondition fails, no commit is made. Dirty paths outside the set are left as they are and do not block Enrollment. With an unborn HEAD the empty root commit comes first and this commit follows it. A commit Git refuses fails Enrollment with Git's message and is never retried with hooks bypassed; if Enrollment is declined, cancelled or fails afterwards, report the remaining commit.
+
 ## Parallel Read-Only Dispatch
 
 State mutations, step activations, QA decisions, and plan switches remain

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

@@ -1,13 +1,14 @@
 ---
 name: imm-brainstorm
-description: Use when the user explicitly requests Immune-Brain requirement clarification.
+description: Use when the user asks to clarify or explore requirements before Immune-Brain planning.
 ---
 
 # Immune-Brain: Brainstorm
 
 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.
+canonical contract index, not a whole-document read. Starts on the user's request
+to clarify or explore requirements, by slash command or in natural language;
+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

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

@@ -1,12 +1,13 @@
 ---
 name: imm-planner
-description: Use when the user explicitly requests Immune-Brain Spec and TaskIntent planning.
+description: Use when the user asks for an Immune-Brain Spec, Plan, or TaskIntent for a repository change.
 ---
 
 # Immune-Brain: Planner
 
 Use [`../../dist/imm-planner.md`](../../dist/imm-planner.md) as the canonical contract
-index, not a whole-document read. Explicit entry only: ordinary host requests stay
+index, not a whole-document read. Starts on the user's request for a Spec, Plan
+or TaskIntent, by slash command or in natural language; other host requests stay
 host-native.
 
 Mandatory constraints before any action: Planner writes a TaskIntent, and a Spec
@@ -42,6 +43,11 @@ own routes instead of these stages.
 - retirement design: [Retirement Completion Contract](../../dist/imm-planner.md#retirement-completion-contract)
 - optional research dispatch: [Research Dispatch](../../dist/imm-planner.md#research-dispatch)
 
+A Spec with external input declares its threat model and supported environment,
+acceptance enumerates concrete negative cases rather than absolute
+any-malformed-input clauses, and descriptors name focused test files, never whole
+suites.
+
 Every request stops after candidate TaskIntent validation, plus Spec validation when the work is complex; Plan-only requests stop there too. The Planner
 never invokes the current Host's native Enrollment gate, even when the request also asks for
 execution: report the candidate and name a literal-user `imm-run` entry as the

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

@@ -7,12 +7,16 @@ description: Use when the user explicitly requests execution or resumption of an
 
 Use [`../../dist/imm-run.md`](../../dist/imm-run.md) as the canonical contract
 index, not a whole-document read, in the current host conversation. Explicit entry only:
-ordinary host input never resumes a Managed owner implicitly.
+ordinary host input never creates a Managed execution binding. Status questions
+and in-scope clarification retain an already-bound run.
 
 Mandatory constraints before any action: verify the active backend claim,
 TaskIntent, and TaskRecord via `imm_kernel_canary` `status` first; invalid or
-contradictory projections fail closed. With no active claim, the first step
-is the native Enrollment gate for the validated candidate, invoked once. Resume only from those authority facts:
+contradictory projections fail closed. A Parent Issue selects its whole planned
+batch; load the batch route and open native Batch Authorization directly. A Child
+Issue selects only its TaskIntent, verifies predecessor settlement and integration,
+then opens single-task Enrollment. With no active claim, a standalone validated
+candidate opens native Enrollment once. Resume only from those authority facts:
 a compaction heading, HANDOFF summary, or Issue state is prose, never authority.
 All Managed authority gates use the
 current Host's native interaction. A failed gate stays fail-closed and
@@ -25,11 +29,11 @@ references load only under their own condition. Never read the whole contract
 or all references as an entry prerequisite.
 
 - common: [Shared Guards](../../dist/BASELINE.md#shared-guards), [Workflow Activation](../../dist/BASELINE.md#workflow-activation), [Host Confirmation Boundary](../../dist/BASELINE.md#host-confirmation-boundary), [Kernel Canary Routing and Authority](../../dist/imm-run.md#kernel-canary-routing-and-authority)
-- unattended batch run, or any question about whether `imm-run` starts one: [Unattended Batch Opt-In](../../dist/imm-run.md#unattended-batch-opt-in)
-- parallel batch (`max_parallel`, `lane_offers`, Lane admission or integration): [Parallel Batch Opt-In](../../dist/imm-run.md#parallel-batch-opt-in)
-- a lane-mode report carries an `executor` handoff, or a Lane's Executor Host session has ended: [Lane Executor Supervision](../../dist/imm-run.md#lane-executor-supervision)
-- that Parent runs inside Herdr (`HERDR_ENV=1`): [Herdr Lane Tabs](../../dist/imm-run.md#herdr-lane-tabs)
-- a lane-mode batch is about to start, to resolve the repository's parallelism, Executor Host, model and effort: [Lane Preferences](../../dist/imm-run.md#lane-preferences)
+- Parent Issue, unattended batch run, or any question about whether `imm-run` starts one: [Unattended Batch Opt-In](../../dist/imm-run-batch.md#unattended-batch-opt-in)
+- parallel batch (`max_parallel`, `lane_offers`, Lane admission or integration): [Parallel Batch Opt-In](../../dist/imm-run-batch.md#parallel-batch-opt-in)
+- a lane-mode report carries an `executor` handoff, or a Lane's Executor Host session has ended: [Lane Executor Supervision](../../dist/imm-run-batch.md#lane-executor-supervision)
+- that Parent runs inside Herdr (`HERDR_ENV=1`): [Herdr Lane Tabs](../../dist/imm-run-batch.md#herdr-lane-tabs)
+- a lane-mode batch is about to start, to resolve the repository's parallelism, Executor Host, model and effort: [Lane Preferences](../../dist/imm-run-batch.md#lane-preferences)
 - steady execution: [Verification and Local Recovery](../../dist/BASELINE.md#verification-and-local-recovery), [Execution Loop](../../dist/imm-run.md#execution-loop), [Observable Output](../../dist/imm-run.md#observable-output)
 - rework, scope expansion, breaking revision, user decision, stop, interruption or unknown state before any action: [Decisions and Recovery](../../dist/imm-run.md#decisions-and-recovery), [Failure Output](../../dist/imm-run.md#failure-output); re-read `status`, then the pending obligation. Rework submits the verdict before editing, and an uncertain interruption resumes from exact task/run authority facts rather than a summary.
 - review or post-settlement learning: [Review and Learning](../../dist/imm-run.md#review-and-learning)