immune-brain 4.2.0 → 4.4.0

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

@@ -506,7 +506,7 @@ a State Ledger. Keep historical Plan validation strictly read-only.
 
 ## Verification
 
-- Validate every candidate through `imm-kernel intent validate <path> --json` after authoring and staging. Require `valid: true` and `enrollment_ready: true` before Enrollment.
+- Validate every candidate through `imm-kernel intent validate <path> --json` after authoring and staging. Require `valid: true` and `enrollment_ready: true` before Enrollment. When `git_base_initialization_required: true`, report that the existing native Enrollment confirmation includes an empty root commit; leave initialization to the Host. An invalid `git_base` blocks Enrollment and requires Git repair.
 - For complex work, verify Spec design metadata, document language, reference closure, concrete descriptor paths, and complete Brainstorm traceability before handoff. Simple TaskIntent-only work verifies those properties on the Intent.
 - Enrollment validates descriptor structure only. Deterministic QA owns descriptor execution after implementation; planning does not run the acceptance suite.
 - Managed execution handoff is Git-tracked TaskIntent author/validate plus current-Host native Enrollment. Do not sync a v3 State Ledger or invoke a missing dispatcher.

package/plugins/immune-brain/runtime/assurance/enrollment_git_base.ts

@@ -0,0 +1,83 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { preparePiCanary, readGitHead, revalidatePiCanary, type PiCanaryPreparation, type PiCanaryPrepareInput } from "../kernel/pi_canary_prepare";
+import { withKernelStoreLock } from "../kernel/storage";
+
+export type EnrollmentGitBase = { state: "committed"; head: string } | { state: "unborn"; branch: string };
+
+function git(root: string, args: string[], input?: string, env = process.env): string {
+	return execFileSync("git", args, { cwd: root, encoding: "utf8", input, env, stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+/** Read-only. A missing branch is bootstrap-able; a broken existing ref is not. */
+export function inspectEnrollmentGitBase(root: string): EnrollmentGitBase {
+	if (git(root, ["rev-parse", "--is-inside-work-tree"]) !== "true")
+		throw new Error("Enrollment requires a Git working tree");
+	try { return { state: "committed", head: readGitHead(root) }; } catch { /* Inspect the unborn case below. */ }
+	const branch = git(root, ["symbolic-ref", "--no-recurse", "HEAD"]);
+	if (!branch.startsWith("refs/heads/")) throw new Error("Enrollment HEAD must name a local branch");
+	const ref = spawnSync("git", ["show-ref", "--verify", "--quiet", branch], { cwd: root });
+	const symbolic = spawnSync("git", ["symbolic-ref", "-q", branch], { cwd: root });
+	if (ref.status !== 1 || symbolic.status !== 1)
+		throw new Error("Enrollment Git HEAD is invalid; only an absent branch can be initialized");
+	return { state: "unborn", branch };
+}
+
+export function enrollmentGitBaseNotice(base: EnrollmentGitBase): string | undefined {
+	return base.state === "unborn"
+		? `Git: create an empty initial commit on ${base.branch} before Enrollment; staged files and working tree remain unchanged. This commit remains if later Enrollment fails or is cancelled.`
+		: undefined;
+}
+
+function identityEnv(root: string): NodeJS.ProcessEnv {
+	const configured = (key: string): string => {
+		const result = spawnSync("git", ["config", "--get", key], { cwd: root, encoding: "utf8" });
+		if (result.status !== 0 && result.status !== 1) throw new Error(`Cannot read Git identity: ${key}`);
+		return result.stdout?.trim() ?? "";
+	};
+	const name = configured("user.name") || "Immune-Brain Enrollment";
+	const email = configured("user.email") || "enrollment@immune-brain.local";
+	return { ...process.env,
+		GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME || name, GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL || email,
+		GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME || name, GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL || email,
+	};
+}
+
+/** Called only after native confirmation. Never stages files or writes Git config. */
+export function initializeEnrollmentGitBase(
+	root: string, input: PiCanaryPrepareInput, previous: PiCanaryPreparation,
+	base: EnrollmentGitBase, signal?: AbortSignal,
+): PiCanaryPreparation {
+	const assertUnchanged = () => {
+		signal?.throwIfAborted();
+		if (!revalidatePiCanary(root, input, previous).unchanged
+			|| JSON.stringify(inspectEnrollmentGitBase(root)) !== JSON.stringify(base))
+			throw new Error("Workspace or Git branch changed after confirmation; retry Enrollment");
+	};
+	assertUnchanged();
+	if (base.state === "committed") return previous;
+	return withKernelStoreLock(root, () => {
+		// CAS the captured branch itself, never HEAD: a concurrent symbolic HEAD
+		// switch must not redirect the write to another branch. Recheck HEAD after
+		// the write and report any created base if the workspace changed.
+		let created: string | undefined;
+		try {
+			assertUnchanged();
+			if (!previous.intent || previous.backend_claim.present || previous.task_record_v3?.present || previous.workspace.current_working !== null)
+				throw new Error("Empty Git base initialization requires an unowned workspace and a tracked TaskIntent");
+			const tree = git(root, ["hash-object", "-t", "tree", "-w", "--stdin"], "");
+			const commit = git(root, ["commit-tree", tree, "-m", "chore: initialize empty Enrollment base"], undefined, identityEnv(root));
+			assertUnchanged();
+			git(root, ["update-ref", "--no-deref", base.branch, commit, "0".repeat(commit.length)]);
+			created = commit;
+			const current = preparePiCanary(root, input);
+			const withoutGit = ({ digest, git_base_head, git_error, ...owners }: PiCanaryPreparation) => owners;
+			if (git(root, ["symbolic-ref", "--no-recurse", "HEAD"]) !== base.branch || current.git_base_head !== commit
+				|| JSON.stringify(withoutGit(current)) !== JSON.stringify(withoutGit(previous)))
+				throw new Error("Workspace changed during empty Git base initialization; retry Enrollment");
+			return current;
+		} catch (error) {
+			if (created) throw new Error(`${error instanceof Error ? error.message : String(error)}; empty initial commit ${created} remains`);
+			throw error;
+		}
+	});
+}

package/plugins/immune-brain/runtime/claude/interaction.ts

@@ -74,6 +74,7 @@ export interface NativeConfirmationInput {
 	intentRevision?: number;
 	intentContentHash?: string;
 	bindingDigest?: string;
+	gitBaseNotice?: string;
 	planDigest?: string;
 	batchDetails?: {
 		initiative_slug: string;

package/plugins/immune-brain/runtime/claude/kernel_ports.ts

@@ -39,6 +39,7 @@ import {
 } from "../kernel/enrollment_authority";
 import { enrollCanaryTask, runEnrollmentRehearsal } from "../kernel/enrollment";
 import { reconcileKernelAuthority, repairKernelAuthority } from "../kernel/storage";
+import { inspectEnrollmentGitBase, enrollmentGitBaseNotice, initializeEnrollmentGitBase } from "../assurance/enrollment_git_base";
 import { preparePiCanary, revalidatePiCanary } from "../kernel/pi_canary_prepare";
 import { runDeterministicQa } from "../assurance/qa";
 import { taskDiffIdentity, taskRevisionIdentity } from "../workspace_scope";
@@ -524,6 +525,7 @@ export class ClaudeRuntime {
 		intentRevision?: number;
 		intentContentHash?: string;
 		bindingDigest?: string;
+		gitBaseNotice?: string;
 	} = {}): Promise<{ confirmation_ref: string }> {
 		throwIfCancelled(meta.signal);
 		const probe = probeHost(this.env, process.platform, this.hostVersion);
@@ -557,45 +559,55 @@ export class ClaudeRuntime {
 
 	async enroll(taskId: string, meta: ToolMeta) {
 		const now = new Date().toISOString();
-		const preparation = await preparePiCanary(this.cwd, { task_id: taskId, now });
+		let preparation = await preparePiCanary(this.cwd, { task_id: taskId, now });
 		const intent = await readTaskIntentForRecord(this.cwd, taskId);
+		const gitBase = inspectEnrollmentGitBase(this.cwd);
 		const gate = await this.gate("enroll", { ...meta, taskId }, {
 			risk: intent.intent.risk,
 			intentRevision: preparation.intent?.revision,
 			intentContentHash: preparation.intent?.content_hash,
 			bindingDigest: preparation.digest,
+			gitBaseNotice: enrollmentGitBaseNotice(gitBase),
 		});
 		const { unchanged } = await revalidatePiCanary(this.cwd, { task_id: taskId, now }, preparation);
 		if (!unchanged) throw new NativeAuthorityError("workspace_changed", "workspace changed after native confirmation");
 		if (!preparation.intent) throw new Error("enrollment requires a readable TaskIntent");
 		throwIfCancelled(meta.signal);
-		const nonce = enrollmentNonce();
-		const binding: EnrollmentCapabilityBinding = {
-			task_id: taskId,
-			intent_path: preparation.intent.path,
-			intent_revision: preparation.intent.revision,
-			intent_content_hash: preparation.intent.content_hash,
-			preparation_digest: preparation.digest,
-			actor_id: LITERAL_USER_ACTOR_ID,
-			confirmation_ref: gate.confirmation_ref,
-			expires_at: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
-			nonce,
-		};
-		const capability = this.enrollmentRegistry.issue(binding);
-		const input = {
-			task_id: taskId,
-			intent_path: binding.intent_path,
-			intent_revision: binding.intent_revision,
-			preparation_digest: binding.preparation_digest,
-			capability,
-			capability_binding: binding,
-			now,
-		};
-		const rehearsal = runEnrollmentRehearsal(this.cwd, input, capability, this.enrollmentRegistry);
-		if (!rehearsal.rehearsed || rehearsal.evidence.outcome !== "ready") {
-			throw new Error(`Kernel enrollment rehearsal failed: ${rehearsal.evidence.blockers.join("; ")}`);
+		preparation = initializeEnrollmentGitBase(this.cwd, { task_id: taskId, now }, preparation, gitBase, meta.signal);
+		const gitBaseNote = gitBase.state === "unborn" ? `; empty initial commit ${preparation.git_base_head} remains` : "";
+		try {
+			if (!preparation.intent) throw new Error("Enrollment requires a readable TaskIntent");
+			const nonce = enrollmentNonce();
+			const binding: EnrollmentCapabilityBinding = {
+				task_id: taskId,
+				intent_path: preparation.intent.path,
+				intent_revision: preparation.intent.revision,
+				intent_content_hash: preparation.intent.content_hash,
+				preparation_digest: preparation.digest,
+				actor_id: LITERAL_USER_ACTOR_ID,
+				confirmation_ref: gate.confirmation_ref,
+				expires_at: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
+				nonce,
+			};
+			const capability = this.enrollmentRegistry.issue(binding);
+			const input = {
+				task_id: taskId,
+				intent_path: binding.intent_path,
+				intent_revision: binding.intent_revision,
+				preparation_digest: binding.preparation_digest,
+				capability,
+				capability_binding: binding,
+				now,
+			};
+			const rehearsal = runEnrollmentRehearsal(this.cwd, input, capability, this.enrollmentRegistry);
+			if (!rehearsal.rehearsed || rehearsal.evidence.outcome !== "ready") {
+				throw new Error(`Kernel enrollment rehearsal failed: ${rehearsal.evidence.blockers.join("; ")}`);
+			}
+			return enrollCanaryTask(this.cwd, input, this.enrollmentRegistry);
+		} catch (error) {
+			if (gitBaseNote) throw new Error(`${error instanceof Error ? error.message : String(error)}${gitBaseNote}`);
+			throw error;
 		}
-		return enrollCanaryTask(this.cwd, input, this.enrollmentRegistry);
 	}
 
 	async advance(taskId: string, signal?: AbortSignal) {
@@ -646,6 +658,13 @@ export class ClaudeRuntime {
 		}
 	}
 
+	async reviseIntent(taskId: string, nextIntent: unknown) {
+		return this.executeOrdinary({ cwd: this.cwd }, {
+			taskId,
+			operation: { op: "revise_intent", next_intent: nextIntent, actor_id: "executor" },
+		});
+	}
+
 	/**
 	 * Ordinary Kernel operation, not a privileged one: canary_application builds
 	 * the action without a capability and the Pi Host lists resolve_finding in

package/plugins/immune-brain/runtime/claude/mcp_server.ts

@@ -23,6 +23,7 @@ export const TOOLS = [
 	{ name: "advance_assurance", description: "Advance frozen Assurance through deterministic QA and Review reservation.", privileged: false },
 	{ name: "submit_review", description: "Submit the Parent-mediated Review verdict bound to the correlated receipt.", privileged: false },
 	{ name: "request_authorization", description: "Apply exact literal-user authorization.", privileged: true },
+	{ name: "revise_intent", description: "Apply a compatible TaskIntent revision.", privileged: false },
 	{ name: "approve_breaking_intent_revision", description: "Approve a breaking TaskIntent revision.", privileged: true },
 	{ name: "stop", description: "Stop the active task with literal-user authority.", privileged: true },
 	{ name: "start_unattended_batch", description: "Start an unattended serial batch run for an Initiative after native confirmation.", privileged: true },
@@ -42,7 +43,7 @@ export function listMcpTools() {
 					? { initiative_slug: { type: "string" } }
 					: {
 						task_id: { type: "string" },
-						...(tool.name === "approve_breaking_intent_revision" ? { next_intent: { type: "object" } } : {}),
+						...(tool.name === "approve_breaking_intent_revision" || tool.name === "revise_intent" ? { next_intent: { type: "object" } } : {}),
 						...(tool.name === "stop" ? { reason: { type: "string" } } : {}),
 						...(tool.name === "submit_review" ? { verdict: { type: "object" } } : {}),
 						...(tool.name === "resolve_finding" ? { finding_id: { type: "string" } } : {}),
@@ -57,7 +58,9 @@ export function listMcpTools() {
 						? ["task_id", "finding_id"]
 						: tool.name === "refute_finding"
 							? ["task_id", "finding_id", "attestation_id"]
-							: ["task_id"],
+							: tool.name === "revise_intent"
+								? ["task_id", "next_intent"]
+								: ["task_id"],
 		},
 		annotations: tool.privileged ? privilegedAnnotations() : { readOnlyHint: tool.name === "status" },
 	}));
@@ -162,6 +165,10 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				if (!Object.hasOwn(args, "verdict")) throw new Error("verdict is required");
 				return runtime.submitReview(taskId, args.verdict);
 			}
+			if (name === "revise_intent") {
+				if (!Object.hasOwn(args, "next_intent")) throw new Error("next_intent is required");
+				return runtime.reviseIntent(taskId, args.next_intent);
+			}
 			if (name === "resolve_finding") {
 				// Structural only. Which findings may be resolved, and when, stays
 				// the reducer's decision; duplicating it here would create a second
@@ -378,6 +385,7 @@ export function elicitationParams(input: NativeConfirmationInput) {
 		input.intentRevision !== undefined ? `Intent revision: ${input.intentRevision}` : null,
 		input.intentContentHash ? `Intent hash: ${input.intentContentHash}` : null,
 		input.bindingDigest ? `Binding digest: ${input.bindingDigest}` : null,
+		input.gitBaseNotice,
 	].filter(Boolean);
 	return {
 		mode: "form",

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

@@ -40,6 +40,7 @@ import { projectLegacyAudit } from "../kernel/legacy_audit";
 import { inspectStorageLayout } from "../kernel/storage_paths";
 import { migrateLegacyLayout } from "../kernel/storage_layout_migration";
 import { readBackendClaim } from "../kernel/backend_claim";
+import { inspectEnrollmentGitBase, type EnrollmentGitBase } from "../assurance/enrollment_git_base";
 import { probeKernelStore } from "../kernel";
 
 export interface KernelCommandResult {
@@ -1134,8 +1135,11 @@ function runIntentValidate(args: string[], root: string): KernelExecution {
 		gitTracked = false;
 	}
 
+	let gitBase: EnrollmentGitBase | { state: "invalid"; reason: string };
+	try { gitBase = inspectEnrollmentGitBase(canonicalRoot); }
+	catch (error) { gitBase = { state: "invalid", reason: error instanceof Error ? error.message : String(error) }; }
 	const contentHash = canonicalIntentHash(intent);
-	const enrollmentReady = gitTracked && allEligible;
+	const enrollmentReady = gitTracked && allEligible && gitBase.state !== "invalid";
 	return {
 		result: jsonResult(
 			{
@@ -1148,6 +1152,8 @@ function runIntentValidate(args: string[], root: string): KernelExecution {
 				acceptance_ids: intent.acceptance.map((item) => item.id),
 				verification: verification,
 				git_ownership: gitTracked ? "tracked" : "untracked",
+				git_base: gitBase,
+				git_base_initialization_required: gitBase.state === "unborn",
 				enrollment_ready: enrollmentReady,
 			},
 			0,

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

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

@@ -93,6 +93,8 @@ Privileged effects include:
 
 Routine Managed enrollment uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Explicit Plan-only requests stop with candidate artifacts and do not invoke Enrollment; execution-bearing requests open the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. The routine task proceeds from that single confirmation through enrollment, execution, and QA without a second human stop. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
 
+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.
+
 ## Parallel Read-Only Dispatch
 
 State mutations, step activations, QA decisions, and plan switches remain