immune-brain 3.6.9 → 4.0.0

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

@@ -1,11 +1,9 @@
 /**
- * Plan parsing, normalization, signatures, and validation.
+ * Plan parsing, normalization, and validation.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, relative, sep } from "node:path";
-import { createHash } from "node:crypto";
 import process from "node:process";
-import { stableStringify } from "./canonical_json";
 
 // ── errors ───────────────────────────────────────────────────────────
 
@@ -48,18 +46,18 @@ const ROADMAP_SLICE_REQUIRED_FIELDS: Array<[key: string, label: string]> = [
 
 // ── plan parsing helpers ─────────────────────────────────────────────
 
-export function hasPlaceholder(value: string): boolean {
+function hasPlaceholder(value: string): boolean {
 	const text = value || "";
 	return Boolean(
 		PLACEHOLDER_RE.test(text) || text.includes("<") || text.includes(">"),
 	);
 }
 
-export function isActionStepResult(value: string): boolean {
+function isActionStepResult(value: string): boolean {
 	return ACTION_RESULT_RE.test((value || "").trim());
 }
 
-export function parseDependsOn(rawValue: string): number[] {
+function parseDependsOn(rawValue: string): number[] {
 	const value = rawValue.trim();
 	if (value.toLowerCase() === "none") return [];
 	const deps: number[] = [];
@@ -81,7 +79,7 @@ export function parseDependsOn(rawValue: string): number[] {
 	return deps;
 }
 
-export function parseStepScope(rawValue: string): string[] {
+function parseStepScope(rawValue: string): string[] {
 	const codeSpans = [...rawValue.matchAll(/`([^`\n]+)`/g)].map((match) =>
 		match[1].trim(),
 	);
@@ -110,7 +108,7 @@ export function parseStepScope(rawValue: string): string[] {
 	return paths;
 }
 
-export function parseBrainstormManifestItems(rawValue: string): string[] {
+function parseBrainstormManifestItems(rawValue: string): string[] {
 	return rawValue
 		? rawValue
 				.split(/[;,]/)
@@ -119,7 +117,7 @@ export function parseBrainstormManifestItems(rawValue: string): string[] {
 		: [];
 }
 
-export function parseBrainstormTraceRow(
+function parseBrainstormTraceRow(
 	stripped: string,
 ): Record<string, string> | null {
 	if (!stripped.startsWith("|") || !stripped.endsWith("|")) return null;
@@ -137,7 +135,7 @@ export function parseBrainstormTraceRow(
 	return { item, status, target, reason };
 }
 
-export function parseDiscoveryCache(
+function parseDiscoveryCache(
 	rawValue: string,
 ): Array<{ path: string; reason: string }> {
 	const value = (rawValue || "").trim();
@@ -157,7 +155,7 @@ export function parseDiscoveryCache(
 	return entries;
 }
 
-export function validateParallelProbeShape(
+function validateParallelProbeShape(
 	probe: Record<string, unknown>,
 ): Record<string, unknown> {
 	if (typeof probe !== "object" || probe === null) {
@@ -179,7 +177,7 @@ export function validateParallelProbeShape(
 	return probe;
 }
 
-export function parseParallelProbeEntry(
+function parseParallelProbeEntry(
 	rawEntry: string,
 ): Record<string, unknown> {
 	const probe: Record<string, unknown> = {};
@@ -205,7 +203,7 @@ export function parseParallelProbeEntry(
 	return validateParallelProbeShape(probe);
 }
 
-export function parseParallelProbes(
+function parseParallelProbes(
 	rawValue: string,
 ): Array<Record<string, unknown>> {
 	const value = (rawValue || "").trim();
@@ -237,7 +235,7 @@ function parseSpecReference(rawValue: string): string {
 	return (rawValue || "").trim().replace(/^`|`$/g, "");
 }
 
-export interface ParsedSpecDesign {
+interface ParsedSpecDesign {
 	path: string;
 	exists: boolean;
 	design_risk: string | null;
@@ -340,7 +338,7 @@ function parseReferencedSpec(
 
 // ── plan parsing ─────────────────────────────────────────────────────
 
-export interface ParsedStep {
+interface ParsedStep {
 	number: number;
 	result: string | null;
 	verification: string | null;
@@ -353,7 +351,7 @@ export interface ParsedStep {
 	agent_hint: string | null;
 }
 
-export interface ParsedRoadmapPhase {
+interface ParsedRoadmapPhase {
 	title: string;
 	acceptance_criteria_present: boolean;
 	acceptance_criteria: string[];
@@ -361,14 +359,14 @@ export interface ParsedRoadmapPhase {
 	promotion_criteria: string[];
 }
 
-export interface PlanValidationWarning {
+interface PlanValidationWarning {
 	code: string;
 	message: string;
 	phase?: string;
 	field?: string;
 }
 
-export interface ParsedPlan {
+interface ParsedPlan {
 	path: string;
 	summary: string | null;
 	task: Record<string, string>;
@@ -378,7 +376,7 @@ export interface ParsedPlan {
 	steps: ParsedStep[];
 }
 
-export function parsePlan(path: string): ParsedPlan {
+function parsePlan(path: string): ParsedPlan {
 	const lines = readFileSync(path, "utf-8").split("\n");
 	let summary: string | null = null;
 	const steps: ParsedStep[] = [];
@@ -533,9 +531,7 @@ export function parsePlan(path: string): ParsedPlan {
 	};
 }
 
-// ── plan signature ───────────────────────────────────────────────────
-
-export interface NormalizedStep {
+interface NormalizedStep {
 	number: number;
 	step_id: string;
 	result: string;
@@ -548,17 +544,16 @@ export interface NormalizedStep {
 	test_scenarios?: string[] | null;
 }
 
-export interface NormalizedPlan {
+interface NormalizedPlan {
 	plan_path: string;
 	summary: string;
 	task: Record<string, string>;
 	steps: NormalizedStep[];
 }
 
-export type WorkflowProfile = "standard" | "strict";
-export type CompounderPolicy = "optional" | "required";
+type WorkflowProfile = "standard" | "strict";
 
-export function workflowProfileForTask(
+function workflowProfileForTask(
 	task: Record<string, string> | null | undefined,
 ): WorkflowProfile {
 	return task?.workflow_profile?.trim().toLowerCase() === "standard"
@@ -566,40 +561,7 @@ export function workflowProfileForTask(
 		: "strict";
 }
 
-export function compounderPolicyForTask(
-	task: Record<string, string> | null | undefined,
-): CompounderPolicy {
-	if (task?.compounder?.trim().toLowerCase() === "optional") return "optional";
-	return "required";
-}
-
-export function buildSignaturePayload(normalizedPlan: NormalizedPlan): string {
-	// Keep cross-runtime parity: the legacy Plan signature predates Scope.
-	const payload = {
-		summary: normalizedPlan.summary,
-		task: normalizedPlan.task,
-		steps: normalizedPlan.steps.map((step) => ({
-			number: step.number,
-			step_id: step.step_id,
-			result: step.result,
-			verification: step.verification,
-			test_scenarios: step.test_scenarios,
-			discovery_cache: step.discovery_cache,
-			parallel_probes: step.parallel_probes,
-			depends_on: step.depends_on,
-			agent_hint: step.agent_hint,
-		})),
-	};
-	return stableStringify(payload);
-}
-
-export function buildPlanSignature(normalizedPlan: NormalizedPlan): string {
-	return createHash("sha256")
-		.update(buildSignaturePayload(normalizedPlan))
-		.digest("hex");
-}
-
-export function normalizePlan(
+function normalizePlan(
 	plan: ParsedPlan,
 	projectRoot?: string,
 ): NormalizedPlan {
@@ -623,7 +585,7 @@ export function normalizePlan(
 	};
 }
 
-export function normalizePlanPath(
+function normalizePlanPath(
 	planPath: string,
 	projectRoot?: string,
 ): string {
@@ -845,7 +807,7 @@ function validatePlanContract(task: Record<string, string>): string[] {
 	return errors;
 }
 
-export function validatePlan(plan: ParsedPlan): {
+function validatePlan(plan: ParsedPlan): {
 	errors: string[];
 	warnings: PlanValidationWarning[];
 } {
@@ -954,7 +916,7 @@ export function validatePlan(plan: ParsedPlan): {
 	return { errors, warnings };
 }
 
-export interface OriginCoverageProjection {
+interface OriginCoverageProjection {
 	applicable: boolean;
 	declared_items: number;
 	mapped_items: number;
@@ -964,7 +926,7 @@ export interface OriginCoverageProjection {
 	complete: boolean;
 }
 
-export interface PlanValidationProjection extends NormalizedPlan {
+interface PlanValidationProjection extends NormalizedPlan {
 	warnings: PlanValidationWarning[];
 	origin_coverage: OriginCoverageProjection;
 }
@@ -975,7 +937,7 @@ const REASON_REQUIRED_STATUSES = new Set([
 	"deferred",
 ]);
 
-export function deriveOriginCoverage(
+function deriveOriginCoverage(
 	plan: ParsedPlan,
 ): OriginCoverageProjection {
 	const declared = [

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

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "3.6.9" as const;
+export const PLUGIN_VERSION = "4.0.0" as const;

package/plugins/immune-brain/runtime/prompts/code-review.md

@@ -38,6 +38,8 @@ boundary name). Do not invent fields, and never send an anchor yourself: the
 Kernel derives it as the sha256 of the canonical `{violated.kind,
 violated.ref, caller_chain}`, so an identical claim keeps one stable identity
 across review rounds while a different call chain is a different claim. A
-passing review has no findings. If the
+passing review carries no blocking findings; non-blocking notes may ride along as
+`kind: "advisory"` findings, and every finding, advisory included, needs the
+same machine-checkable evidence. If the
 checkpoint is `awaiting_user_successor_decision`, stop without dispatch; only
 a literal user may invoke `--approve-successor`.

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

@@ -1,10 +1,10 @@
 # Internal role: executor
 
 You are the Immune-Brain Executor role inside Loop. Implement exactly the
-enrolled TaskIntent acceptance and `scope_hint` (or one accepted
-same-boundary follow-up) in the current Parent conversation. Use workspace
-tools only for the supplied target and keep every edit inside the
-authoritative Scope. Do not discover or load a Pi Skill.
+enrolled TaskIntent acceptance and `scope_hint` envelope (or one accepted
+same-boundary follow-up) in the current Parent conversation. New helpers or
+tests inside an approved directory or glob do not require a revision. Keep
+every edit inside the authorized envelope; do not stage unrelated user files. Do not discover or load a Pi Skill.
 
 Before handoff, run the permitted diagnostic checks and return commands and
 outcomes to the Parent as structured diagnostic evidence. The read-only Loop

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

@@ -0,0 +1,58 @@
+// Staging a TaskIntent sidecar is one operation on both Hosts: capture the
+// sidecar bytes together with its Git index entry, and restore both. Claude used
+// to stop at `git update-index`; Pi re-read the bytes and the index and failed
+// closed on any mismatch. The stricter branch is now the only one, so a restore
+// that silently left either side inconsistent cannot pass as success.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface StagedIntentSnapshot {
+	/** Repository-relative path of the staged sidecar. */
+	path: string;
+	bytes: Buffer;
+	index_state: Buffer;
+}
+
+/** Capture the sidecar bytes and the exact index entry the restore must reproduce. */
+export function captureStagedIntent(root: string, relativePath: string): StagedIntentSnapshot {
+	return {
+		path: relativePath,
+		bytes: readFileSync(join(root, relativePath)),
+		index_state: execFileSync("git", ["ls-files", "--stage", "-z", "--", relativePath], {
+			cwd: root,
+			stdio: ["ignore", "pipe", "pipe"],
+		}),
+	};
+}
+
+/**
+ * Restore the sidecar and its index entry, then verify both. A restore that
+ * leaves either the bytes or the index different from the snapshot throws.
+ */
+export function restoreStagedIntent(root: string, snapshot: StagedIntentSnapshot): void {
+	writeFileSync(join(root, snapshot.path), snapshot.bytes);
+	execFileSync("git", ["update-index", "--force-remove", "--", snapshot.path], {
+		cwd: root,
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	if (snapshot.index_state.length > 0) {
+		execFileSync("git", ["update-index", "-z", "--index-info"], {
+			cwd: root,
+			input: snapshot.index_state,
+			stdio: ["pipe", "ignore", "pipe"],
+		});
+	}
+	const restoredBytes = readFileSync(join(root, snapshot.path));
+	if (!restoredBytes.equals(snapshot.bytes)) {
+		throw new Error("failed to restore prior intent bytes");
+	}
+	const restoredIndex = execFileSync("git", ["ls-files", "--stage", "-z", "--", snapshot.path], {
+		cwd: root,
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	if (!restoredIndex.equals(snapshot.index_state)) {
+		throw new Error("failed to restore prior intent git index entry");
+	}
+}

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

@@ -3,7 +3,7 @@
 // Invariant: The runtime never creates, switches, or deletes a Git worktree,
 // never pushes a ref, and never opens or updates a pull request.
 import { spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
 	constants,
 	closeSync,
@@ -11,15 +11,15 @@ import {
 	lstatSync,
 	mkdirSync,
 	openSync,
-	readFileSync,
 	realpathSync,
 	renameSync,
 	rmSync,
 	writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { readAuditTaskPair, readSecureProjectFile } from "../kernel/storage";
-import { pathMatchesScope } from "../workspace_scope";
+import { localRunId, readAuditTaskPair, readSecureProjectFile } from "../kernel/storage";
+import { captureGitTaskRevisionSnapshot, pathMatchesScope } from "../workspace_scope";
+import { expectedBatchHead, findExistingActiveBatch, findSettledBatchRecord } from "./batch_preflight";
 
 export type BatchGitPreflightRejectReason =
 	| "batch_branch_exists"
@@ -66,7 +66,8 @@ const DEFAULT_GIT_ENV = {
 
 /**
  * Preflight before any child is enrolled: requires clean working tree,
- * committed HEAD, and absence of refs/heads/imm/<initiative-slug>.
+ * committed HEAD, and an absent batch branch or the current branch of a settled
+ * run whose commit lineage is preserved.
  * Verifies root is the top-level repository root (Finding 5).
  * Explicitly passes --untracked-files=all so repo config cannot bypass dirty check (Finding 2).
  * Disables Git hooks during checkout (Finding 2).
@@ -163,6 +164,17 @@ export function runBatchGitPreflight(input: {
 		{ stdio: ["ignore", "ignore", "ignore"] },
 	);
 	if (branchCheck.status === 0) {
+		const settled = findSettledBatchRecord(root, initiativeSlug);
+		const currentBranch = spawnSync("git", ["-C", root, "symbolic-ref", "--short", "HEAD"], { encoding: "utf8" });
+		// Reuse only this initiative's current, settled branch. Never move or reset
+		// a ref; the new authorization binds the current HEAD, including newly
+		// committed candidate intents, and the old run's evidence stays intact.
+		if (
+			findExistingActiveBatch(root, initiativeSlug) === null &&
+			settled?.branch === branch && currentBranch.status === 0 && currentBranch.stdout.trim() === branch &&
+			headResult.stdout.trim() === baseHead &&
+			spawnSync("git", ["-C", root, "merge-base", "--is-ancestor", expectedBatchHead(settled), baseHead]).status === 0
+		) return { ok: true, branch };
 		return {
 			ok: false,
 			reason: "batch_branch_exists",
@@ -442,7 +454,11 @@ export async function commitBatchChild(input: {
 	const { root, taskId, batchId, expectedHead, branch: expectedBranch } = input;
 
 	// 1. Verify Kernel reports that child done via immutable terminal audit pair (Finding 2)
-	const auditPair = readAuditTaskPair(root, taskId);
+	// The committed local run owns this task's evidence: another worktree's run
+	// directory for the same task is not this batch's audit pair. Settlement
+	// clears the active run, so the lookup includes terminal runs.
+	const localRun = localRunId(root, taskId);
+	const auditPair = readAuditTaskPair(root, taskId, localRun ?? undefined);
 	if (!auditPair) {
 		throw new Error(`cannot commit child ${taskId}: task is not settled done (audit pair missing)`);
 	}
@@ -532,6 +548,19 @@ export async function commitBatchChild(input: {
 		spawnSync("git", ["-C", root, "reset", "--quiet"], { stdio: ["ignore", "ignore", "ignore"] });
 		throw new Error("dirty_outside_scope");
 	}
+	const record = auditPair.record as {
+		contract?: string;
+		git_base_head?: string;
+		attestations?: Array<{ kind: string; diff_hash: string }>;
+	};
+	const qa = [...(record.attestations ?? [])].reverse().find((item) => item.kind === "qa");
+	if (record.contract === "assurance_kernel/task_record/v4" && qa?.diff_hash) {
+		if (!record.git_base_head) throw new Error("batch commit requires a TaskRecord v4 git_base_head");
+		const captured = captureGitTaskRevisionSnapshot(root, scopeHint, record.git_base_head, taskId);
+		const digest = `sha256:${createHash("sha256").update(JSON.stringify(captured)).digest("hex")}`;
+		if (digest !== qa.diff_hash)
+			throw new Error("batch commit drifted from the reviewed delivery identity");
+	}
 
 	// 6. Commit with structured message, Immune-Brain-Batch trailer, and all hooks disabled (Finding 1)
 	const goalFirstLine = goal.trim().split(/\r?\n/)[0]?.trim() || taskId;
@@ -730,7 +759,8 @@ export async function lookupBatchCommit(input: {
 		}
 
 		// Verify terminal audit exists and is settled done
-		const auditPair = readAuditTaskPair(root, taskId);
+		const adoptedRun = localRunId(root, taskId);
+		const auditPair = readAuditTaskPair(root, taskId, adoptedRun ?? undefined);
 		if (!auditPair) {
 			throw new Error(`batch_head_lineage_broken: adopted commit lacks terminal audit pair for ${taskId}`);
 		}

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

@@ -7,10 +7,12 @@ import {
 	TaskIntentObservationError,
 } from "../kernel/intent";
 import { readTaskRecordRaw } from "../kernel/storage";
+import { inspectSpecBinding, type SpecBindingInspection } from "../kernel/spec_binding";
 import type {
 	BatchPlan,
 	BatchPlanBudget,
 	BatchPlanChild,
+	BatchPlanChildReason,
 	BatchPlanDigestChild,
 	InitiativeObservationReader,
 	ProjectBatchPlanInput,
@@ -20,6 +22,21 @@ const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const DEFAULT_DEADLINE_MS = 8 * 60 * 60 * 1_000;
 const DEFAULT_QA_FAILURE_LIMIT = 2;
 
+/**
+ * Enrollment refuses a child whose scope_hint cannot name its bound Spec pair,
+ * so the plan excludes the same children here, before a confirmation offers
+ * them and before an Executor writes their implementation. The reason carries a
+ * stable code plus every path the intent must add. Advisory only: this mints,
+ * alters, and consumes no authority.
+ */
+function specBindingReason(inspection: Extract<SpecBindingInspection, { ok: false }>): BatchPlanChildReason {
+	// One shared branch renders the concrete paths of every refusal that carries
+	// them — a `binding_missing` whose declared halves never paired included.
+	// `binding_incomplete` always carries paths, so it has no entry of its own.
+	if (inspection.missing.length > 0) return `spec_binding_incomplete: ${inspection.missing.join(", ")}`;
+	return inspection.code === "binding_ambiguous" ? "spec_binding_ambiguous" : "spec_binding_missing";
+}
+
 function compareIds(left: string, right: string): number {
 	return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -153,10 +170,33 @@ export async function projectBatchPlan(
 		const intentPath = `docs/plans/${task.task_id}.intent.json`;
 		try {
 			const read = observeTaskIntent(root, task.task_id, intentPath);
+			if (read.intent.risk === "critical") {
+				children.push({
+					...child,
+					status: "needs_human",
+					reason: "critical",
+					intent_path: read.intent_ref.path,
+					intent_revision: read.intent_ref.revision,
+					intent_content_hash: read.content_hash,
+				});
+				continue;
+			}
+			const binding = inspectSpecBinding(read.intent);
+			if (!binding.ok) {
+				children.push({
+					...child,
+					status: "needs_human",
+					reason: specBindingReason(binding),
+					intent_path: read.intent_ref.path,
+					intent_revision: read.intent_ref.revision,
+					intent_content_hash: read.content_hash,
+				});
+				continue;
+			}
 			children.push({
 				...child,
-				status: read.intent.risk === "critical" ? "needs_human" : "enrollable",
-				reason: read.intent.risk === "critical" ? "critical" : null,
+				status: "enrollable",
+				reason: null,
 				intent_path: read.intent_ref.path,
 				intent_revision: read.intent_ref.revision,
 				intent_content_hash: read.content_hash,