immune-brain 4.1.0 → 4.3.0

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

@@ -55,7 +55,12 @@ Continue while the current projection has a valid action:
 1. For active artifacts, implement only the enrolled acceptance within the
    `scope_hint` envelope in the current conversation. New helpers or tests
    inside an approved directory or glob do not require a revision. Run focused
-   checks. Executor checks are diagnostic evidence, not a QA or Review approval.
+   checks. Before `advance_assurance`, inspect ownership and stage only the exact
+   task-owned paths needed for delivery. Do not hand routine task-owned staging
+   to the user. If a file mixes pre-existing user changes with task changes and
+   the task-owned hunks cannot be isolated reliably, stop with that ownership
+   conflict instead of staging the whole file. Staging grants no commit or push
+   authority. Executor checks are diagnostic evidence, not a QA or Review approval.
 2. Call `advance_assurance` in the foreground and consume its direct terminal
    result. The Kernel freezes the artifacts itself before QA: it binds Git
    content identity in place without relocating source paths. A simple task has

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

@@ -76,7 +76,8 @@ Then route deterministically:
   coordination, except a Loop-requested revision follows Enrolled Intent Revision
   below to prepare a non-authoritative proposal for that same owner;
 - an active or otherwise nonterminal v3 Plan remains on its existing v3 route;
-- no routing policy preserves the legacy v3 Planner behavior;
+- no routing policy on an otherwise unowned workspace triggers automatic policy
+  activation below before producing any planning artifact;
 - a valid `kernel_task_intent` retirement policy produces one TaskIntent draft
   through the current Host's explicit `imm-planner`;
 - an invalid, unreadable, untracked, or tracked-deleted policy rejects new
@@ -107,6 +108,46 @@ workspace claim, and final authority preconditions without executing acceptance
 descriptors. A routine task proceeds from that single confirmation through
 enrollment, execution and QA without a second human stop.
 
+**Automatic policy activation**
+
+Explicit `imm-planner` entry includes local routing setup, including for plan-only
+requests. When the routing projection reports `policy_status: legacy_v3` and
+`ownership: absent`, and neither Kernel nor nonterminal v3 ownership exists,
+perform these steps without a separate enablement question:
+
+1. Create `docs/plans/` if needed. Require real directories without symlink
+   components; create `docs/plans/managed-task-routing-policy.json` exclusively
+   (fail if it already exists), using exactly the JSON below with two-space
+   indentation, the shown field order, and one trailing newline.
+2. Run `git add -- docs/plans/managed-task-routing-policy.json` only for the file
+   created in this activation. Preserve all other worktree and index changes;
+   do not commit, force-add an ignored file, or alter Git configuration.
+3. Re-run `imm-plan --routing-status --json` through the resolved wrapper.
+   Continue canonical TaskIntent authoring only when `policy_status: active`,
+   `route: kernel_task_intent`, and `ownership: tracked_clean` all hold. Report
+   automatic activation briefly and continue planning in the same turn.
+
+```json
+{
+  "contract": "immune_brain/managed_task_routing_policy/v1",
+  "revision": 1,
+  "new_task_route": "kernel_task_intent",
+  "v3_new_plan_sync": "retired",
+  "legacy_v3_mode": "drain_read_only",
+  "terminal_import": "disabled"
+}
+```
+
+An already active policy needs no write or staging. An existing invalid,
+untracked, unreadable, tracked-deleted, or divergent policy is not an activation
+candidate: preserve it and report `routing_policy_invalid`. If creation,
+staging, or verification fails, report the concrete blocker and retain any
+created file; stop before authoring, without overwriting existing bytes or
+falling back to v3. A repository/user prohibition on policy setup or staging
+blocks only this dependent planning step. Activation grants no execution
+authority; the native Enrollment gate remains required. Read-only routing
+queries and the canonical author command retain their existing runtime behavior.
+
 ## Candidate Authoring
 
 Read this section before creating new candidate artifacts, after request routing
@@ -133,6 +174,12 @@ file creation; then it validates the created artifact with
 continue through Kernel `revise_intent` authority and are not a Planner
 overwrite path.
 
+After authoring, inspect ownership and stage only the exact Planner-produced
+Spec and TaskIntent paths before validation and handoff. Do not hand routine
+Planner-owned staging to the user. This grants no commit, push, broad staging,
+or authority over pre-existing user changes; a mixed-change ownership conflict
+stops only the affected handoff.
+
 Before authoring a TaskIntent that adds a field or verdict branch to a state
 machine, enumerate every consumer of that value and of the version gates around
 it: the producing side, each branch or switch that reads it, and any migration or
@@ -263,7 +310,12 @@ script or host tool through its literal `command`; do not infer a language,
 package manager, or runner. Add `environment.prepare` only when the check needs
 explicit setup, and declare only the generated directories it needs in
 `environment.writable_paths`. Never hide package installation inside an
-acceptance command. Prefer the highest existing observable behavioral test seam
+acceptance command. For every descriptor, identify whether its executable is
+provided by the QA host or by tracked delivery content, where every dependency
+comes from in the disposable delivery, what explicit setup is required, and
+which declared writable paths that setup or check creates. A dependency found
+only in the Planner's live worktree, including an absolute local `node_modules`
+path, is not delivery provenance. Prefer the highest existing observable behavioral test seam
 and the fewest sufficient seams; never use the full test suite, a build, network
 access, or redundant heavyweight checks as acceptance. Cite relevant test prior
 art and explain how the selected seam catches the intended regression. This is
@@ -271,7 +323,9 @@ a planning heuristic: it must not weaken acceptance-specific focused
 verification descriptors or add a mandatory user confirmation. Use the smallest
 `timeout_ms` and `max_output_bytes` that cover deterministic post-implementation
 QA. A v1 descriptor is historical-only and requires explicit Intent revision
-before execution.
+before execution. Report `valid` and `enrollment_ready` only as structural and
+Enrollment readiness; only a completed deterministic QA result proves that a
+descriptor executed and passed.
 
 ## Core Responsibilities
 
@@ -410,7 +464,7 @@ optional advisory dispatch fails, continue inline and record the reason.
 
 ## Boundary
 
-- **Allowed**: Write a TaskIntent. Add a Spec only for complex work. Initiative planning carriers and necessary domain vocabulary.
+- **Allowed**: Write a TaskIntent. Add a Spec only for complex work. Activate an absent routing policy under Kernel TaskIntent Routing. Initiative planning carriers and necessary domain vocabulary.
 - **Blocked**: Implementation edits, direct Kernel-store writes, enrolled intent overwrites, and QA/Review decisions.
 - **Workflow guard**: Execution continues through native Enrollment and explicit `imm-loop`. Planner owns design and decomposition, not execution authority.
 
@@ -452,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) {

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

@@ -378,6 +378,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.1.0" as const;
+export const PLUGIN_VERSION = "4.3.0" as const;

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

@@ -6,7 +6,9 @@
   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.
+- Stage only explicit task-owned paths. This staging authority does not grant
+  commit, push, broad staging, or authority over pre-existing user changes.
+  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.
 - 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.
@@ -46,7 +48,9 @@ routing. A new Managed workflow starts only from explicit `imm-brainstorm`,
    Managed owner remains authoritative; the user resumes it with `imm-loop`.
 2. **Start explicitly**: the selected Immune-Brain Skill owns its planning or
    coordination work. It creates only requested artifacts and their required
-   parent directories; it does not install project-wide contract files.
+   parent directories. Explicit Planner entry also owns absent routing-policy
+   activation under Planner's Kernel TaskIntent Routing section;
+   it does not otherwise install project-wide contract files.
 3. **Preserve authority**: Planner output is a candidate for later literal-user
    Enrollment, and Fast-Track preserves TaskIntent scope, Enrollment, QA,
    Review, authorization, and completion boundaries.
@@ -89,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