immune-brain 2.8.2 → 3.0.1

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

@@ -1,15 +1,35 @@
 # Internal role: code-review
 
-You are the Immune-Brain read-only code review role inside Loop. Review only
-the bounded change surface and the evidence supplied by the Parent. Classify
-findings, state observable verification criteria, and preserve the current
-review gate identity. Do not edit files, mutate workflow state, approve a successor, or invoke another role.
-
-The stable Review Gate is `imm-code-review`. Return exactly one JSON object
-with the fields required by the Loop review contract: `contract`, `role`,
-`task_id`, `snapshot_digest`, `decision` (`pass` or `rework`), and for
-`pass` include `approval` (`kind`, `authority_role`, `summary`), for `rework`
-include `findings` (`id`, `kind`, `acceptance_id`, `summary`). Do not invent
-fields. A passing review has no findings. If the checkpoint is
-`awaiting_user_successor_decision`, stop without dispatch; only a literal user
-may invoke `--approve-successor`.
+You are the Immune-Brain read-only code review role inside Loop. Review the
+immutable Git revision and bounded evidence supplied by the Parent. For
+`assurance_kernel/review_manifest/v5`, read the metadata manifest first, verify
+`base_head`, `review_commit`, its single parent, `review_tree`, and
+`manifest_digest`, then inspect source only with read-only Git commands such as
+`git diff <base_head> <review_commit>` and `git show <review_commit>:<path>`.
+Never read live worktree bytes as evidence, enumerate neighborhood files, or
+infer task ownership from unchanged paths. Read an unchanged path only when an
+acceptance assertion, changed caller, or same state machine directly requires
+it, and cite the path and reason in the finding. The manifest is metadata only;
+source content must not be copied into the review envelope.
+
+Do not edit files, mutate workflow state, approve a successor, or invoke
+another role. The stable Review Gate is `imm-code-review`.
+
+## Code Quality Guard
+
+Apply the Code Quality Guard reference to the immutable revision: reject
+fabricated success, unknown-error suppression, missing external-boundary
+validation, invented imports/APIs, weakened tests, unauthorized behavior
+changes, and speculative production paths when the diff creates a concrete
+risk. Report only evidence-based correctness, security, regression, or
+material task-local maintenance risks. Pure naming, length, complexity
+thresholds, formatting, and design preference are not findings and must not
+cause style-only rework.
+
+Return exactly one JSON object with the fields required by the Loop review
+contract: `contract`, `role`, `task_id`, `snapshot_digest`, `decision` (`pass`
+or `rework`), and for `pass` include `approval` (`kind`, `authority_role`,
+`summary`), for `rework` include `findings` (`id`, `kind`, `acceptance_id`,
+`summary`). Do not invent fields. A passing review has no findings. 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

@@ -11,3 +11,17 @@ action. Preserve failed and blocked attempts. Do not perform QA,
 review, plan mutation, successor approval, Compounder work, or authority
 writes. If the requested change needs scope expansion, stop and return an
 `imm-planner` route with the concrete missing scope and verification reason.
+
+## Code Quality Guard
+
+Before handoff, check the implementation for real implementation rather than
+mock or hard-coded success, swallowed unexpected errors, missing validation at
+external trust boundaries, invented dependencies or APIs, unauthorized
+observable behavior changes, and production paths without a current caller.
+Do not weaken tests or hide an incomplete result to make Verification pass.
+Treat naming, function length, parameter count, nesting, and abstraction taste
+as contextual signals, never as automatic failure thresholds.
+
+Fix in-scope integrity defects before Verification. If fixing one requires
+behavior, scope, or authority beyond the active Step, stop and route the
+concrete reason to `imm-planner`.

package/plugins/immune-brain/runtime/prompts/pr-fix.md

@@ -60,6 +60,15 @@ shard on failure; on second failure, fall back to solo repair.
 Re-run project checks and PR-related conflict checks. Compare local HEAD
 against PR head expectation before push.
 
+## Code Quality Guard
+
+Apply the same integrity boundary while repairing a blocker. Do not clear CI or
+review feedback by swallowing unexpected errors, fabricating success, or using
+a repair that would weaken tests, invent an unavailable API or dependency,
+change unrelated behavior, or widen the PR beyond the named blocker. Preserve
+the PR's observable intent. If the correct repair needs new scope or a product
+decision, stop and report it to the Parent.
+
 ## Boundary
 
 Work only inside the supplied Plan, `plan_id`, changed-file boundary, review

package/plugins/immune-brain/runtime/prompts/test-fixer.md

@@ -1,3 +1,10 @@
 # Internal role: test-fixer
 
 You are the Immune-Brain bounded test-repair role inside Loop. Edit only the delegated test files listed in `focus_delta.specific_changes` for the active target. Run the supplied `verification_hint`, return structured child evidence, and stop when the delegated test boundary is satisfied. Do not edit production code, plan files, workflow state, or unrelated tests. Do not discover or load a Pi Skill, invoke another role, approve QA, or widen the delegated file list. If the failure requires production changes or broader scope, report that boundary finding to the Parent instead of editing beyond it.
+
+## Code Quality Guard
+
+Preserve test intent while repairing tests. Do not delete or loosen assertions,
+reduce coverage, replace target behavior with a mock, or change expected
+behavior solely to make the test pass. A production defect is a boundary
+finding for the Parent, not permission to edit production code.

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

@@ -5,6 +5,7 @@
  * retirement. It exposes:
  *   - `imm-kernel` intent author/validate (host-neutral TaskIntent drafts)
  *   - `imm-kernel status --json` (read-only v3 legacy shadow status)
+ *   - `imm-kernel inspect --json` (read-only Inspect Projection)
  *   - `imm-kernel audit --legacy` (explicit read-only legacy audit)
  *   - `imm-plan --routing-status --json` (strict Git-owned route projection)
  *   - `imm-plan <plan-path> [--json]` (read-only Plan validation)
@@ -183,6 +184,7 @@ async function runKernelCli(args: string[], root: string): Promise<{
 	const sub = args[0] ?? "";
 	if (sub === "intent") return runKernelCommand(args, root);
 	if (sub === "status" && args.includes("--json")) return runKernelCommand(args, root);
+	if (sub === "inspect" && args.includes("--json")) return runKernelCommand(args, root);
 	if (sub === "audit") {
 		// Explicit read-only legacy audit: bounded, no symlink, deterministic
 		// redacted projection. Never writes journal or workflow state.
@@ -204,7 +206,7 @@ async function runKernelCli(args: string[], root: string): Promise<{
 	}
 	return {
 		stdout: "",
-		stderr: "invalid_kernel_command: imm-kernel supports intent author|validate, status --json, and audit --legacy only\n",
+		stderr: "invalid_kernel_command: imm-kernel supports intent author|validate, status --json, inspect --json, and audit --legacy only\n",
 		returncode: 2,
 	};
 }
@@ -236,12 +238,13 @@ async function main(argv: string[]): Promise<number> {
 						{
 							name: "imm-kernel",
 							description:
-								"v4-only Kernel surface: intent author/validate, status, and explicit legacy audit.",
+								"v4-only Kernel surface: intent author/validate, status, inspect, and explicit legacy audit.",
 							json_output: true,
 							examples: [
 								"imm-kernel intent author docs/plans/<task-id>.intent.json --stdin --json",
 								"imm-kernel intent validate docs/plans/<task-id>.intent.json --json",
 								"imm-kernel status --json",
+								"imm-kernel inspect --json",
 								"imm-kernel audit --legacy",
 							],
 						},

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

@@ -126,7 +126,7 @@ export interface GitTaskSnapshot {
 	staged_files: Record<string, GitTaskIndexEntry>;
 }
 
-const GIT_OBJECT_ID = /^[a-f0-9]{40,64}$/;
+const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const TASK_GIT_MODES = new Set(["100644", "100755", "120000"] as const);
 const fatalUtf8 = new TextDecoder("utf-8", { fatal: true });
 const portablePathCollator = new Intl.Collator("und", {
@@ -195,6 +195,34 @@ function decodeNullPaths(bytes: Buffer, label: string): string[] {
 	return paths;
 }
 
+function decodeIndexFlaggedPaths(bytes: Buffer, label: string): Array<{ path: string; flag: "assume-unchanged" | "skip-worktree" }> {
+	if (bytes.length === 0) return [];
+	if (bytes[bytes.length - 1] !== 0) throw new Error(`${label} is not NUL-terminated`);
+	const flagged: Array<{ path: string; flag: "assume-unchanged" | "skip-worktree" }> = [];
+	let start = 0;
+	for (let index = 0; index < bytes.length; index += 1) {
+		if (bytes[index] !== 0) continue;
+		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") {
+			flagged.push({
+				path: decodeCanonicalGitPath(record.subarray(2), label),
+				flag: tag === "h" ? "assume-unchanged" : "skip-worktree",
+			});
+		}
+		start = index + 1;
+	}
+	return flagged;
+}
+
+function assertNoScopedIndexFlags(root: string, scope: string[], label: string): void {
+	const flagged = decodeIndexFlaggedPaths(gitBytes(root, ["ls-files", "-v", "-z", "--"]), "Git index flags")
+		.filter(({ path }) => taskPathMatchesScope(path, scope));
+	if (flagged.length > 0)
+		throw new Error(`${label} contains unsupported index flags: ${flagged.map(({ path, flag }) => `${path} (${flag})`).join(", ")}`);
+}
+
 function assertNoCaseFoldCollisions(paths: string[], label: string): void {
 	const prefixes: string[] = [];
 	for (const path of paths) {
@@ -300,6 +328,7 @@ function taskSnapshotOnce(root: string, scope: string[]): GitTaskSnapshot {
 		throw new Error("task snapshot does not support sparse checkout or sparse index");
 	if (gitBytes(root, ["ls-files", "--unmerged", "-z"]).length > 0)
 		throw new Error("task snapshot does not support unmerged index entries");
+	assertNoScopedIndexFlags(root, scope, "task snapshot");
 
 	const stagedPaths = decodeNullPaths(
 		gitBytes(root, ["diff", "--cached", "--no-renames", "--name-only", "-z", head, "--"]),
@@ -363,11 +392,168 @@ export function captureGitTaskSnapshot(
 	return before;
 }
 
-export function taskDiffHash(projectRoot: string, scopeHint: unknown): string {
+export interface GitTaskDiffIdentity {
+	diff_hash: string;
+	changed_paths: string[];
+}
+
+function hashTaskSnapshot(snapshot: object): string {
+	return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
+}
+
+export function taskDiffIdentity(
+	projectRoot: string,
+	scopeHint: unknown,
+): GitTaskDiffIdentity {
 	const snapshot = captureGitTaskSnapshot(projectRoot, scopeHint);
-	return `sha256:${createHash("sha256")
-		.update(JSON.stringify(snapshot))
-		.digest("hex")}`;
+	return {
+		diff_hash: hashTaskSnapshot(snapshot),
+		changed_paths: Object.keys(snapshot.staged_files).sort(comparePaths),
+	};
+}
+
+export function taskDiffHash(projectRoot: string, scopeHint: unknown): string {
+	return taskDiffIdentity(projectRoot, scopeHint).diff_hash;
+}
+
+function gitRequired(root: string, args: string[], failure: string): string {
+	const output = git(root, args);
+	if (output === null) throw new Error(failure);
+	return output.trim();
+}
+
+/**
+ * The v4 scoped revision snapshot: the exact delta between the Enrollment base
+ * commit and the current index, restricted to the TaskIntent mutation envelope.
+ * It deliberately omits the current HEAD so an out-of-scope commit never
+ * invalidates task identity, and it never reads unchanged scope matches.
+ */
+export interface GitTaskRevisionSnapshot {
+	kind: "git-task-revision-v1";
+	repository_root: string;
+	base_head: string;
+	base_tree: string;
+	scope: string[];
+	changed_paths: Record<string, GitTaskIndexEntry>;
+}
+
+function taskRevisionSnapshotOnce(
+	root: string,
+	scope: string[],
+	baseHead: string,
+): GitTaskRevisionSnapshot {
+	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))
+		throw new Error("cannot derive a task revision outside a committed Git workspace");
+	if (realpathSync(resolve(repositoryRoot)) !== root)
+		throw new Error("task revision repository root does not match the project root");
+	if (gitRequired(root, ["cat-file", "-t", baseHead], `task revision base is unreadable: ${baseHead}`) !== "commit")
+		throw new Error(`task revision base is not a commit: ${baseHead}`);
+	if (git(root, ["merge-base", "--is-ancestor", baseHead, head]) === null)
+		throw new Error(
+			`task revision base ${baseHead} is no longer an ancestor of HEAD; rewrite the task history or re-enroll`,
+		);
+	const baseTree = gitRequired(root, ["rev-parse", `${baseHead}^{tree}`], "task revision base tree is unreadable");
+	if (!GIT_OBJECT_ID.test(baseTree)) throw new Error("task revision base tree has invalid identity");
+	const sparseCheckout = git(root, ["config", "--bool", "core.sparseCheckout"])?.trim();
+	const sparseIndex = git(root, ["config", "--bool", "index.sparse"])?.trim();
+	if (sparseCheckout === "true" || sparseIndex === "true")
+		throw new Error("task revision does not support sparse checkout or sparse index");
+	if (gitBytes(root, ["ls-files", "--unmerged", "-z"]).length > 0)
+		throw new Error("task revision does not support unmerged index entries");
+	assertNoScopedIndexFlags(root, scope, "task revision");
+
+	const stagedPaths = decodeNullPaths(
+		gitBytes(root, ["diff", "--cached", "--no-renames", "--name-only", "-z", baseHead, "--"]),
+		"task revision paths",
+	);
+	const unstagedPaths = decodeNullPaths(
+		gitBytes(root, ["diff", "--no-renames", "--name-only", "-z", "--"]),
+		"unstaged task revision paths",
+	);
+	const untrackedPaths = decodeNullPaths(
+		gitBytes(root, ["ls-files", "--others", "--exclude-standard", "-z", "--"]),
+		"untracked task revision paths",
+	);
+	const scopedStagedPaths = stagedPaths.filter((path) => taskPathMatchesScope(path, scope));
+	const scopedUnstagedPaths = unstagedPaths.filter((path) => taskPathMatchesScope(path, scope));
+	const scopedUntrackedPaths = untrackedPaths.filter((path) => taskPathMatchesScope(path, scope));
+	assertNoCaseFoldCollisions(
+		[...scopedStagedPaths, ...scopedUnstagedPaths, ...scopedUntrackedPaths],
+		"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(", ")}`);
+
+	const changed = [...new Set(scopedStagedPaths)].sort(comparePaths);
+	const changedPaths: Record<string, GitTaskIndexEntry> = {};
+	for (const path of changed) {
+		const current = indexEntry(root, path);
+		const base = headEntry(root, baseHead, path);
+		if (!current && !base) throw new Error(`task revision path has no index or base identity: ${path}`);
+		if (current && base && current.oid === base.oid && current.mode === base.mode)
+			throw new Error(`task revision path is not actually changed: ${path}`);
+		changedPaths[path] = {
+			status: !base ? "added" : !current ? "deleted" : "modified",
+			mode: current?.mode ?? null,
+			oid: current?.oid ?? null,
+			base_mode: base?.mode ?? null,
+			base_oid: base?.oid ?? null,
+		};
+	}
+	return {
+		kind: "git-task-revision-v1",
+		repository_root: root,
+		base_head: baseHead,
+		base_tree: baseTree,
+		scope,
+		changed_paths: changedPaths,
+	};
+}
+
+export function captureGitTaskRevisionSnapshot(
+	projectRoot: string,
+	scopeHint: unknown,
+	baseHead: unknown,
+): GitTaskRevisionSnapshot {
+	const requestedRoot = resolve(projectRoot);
+	const requestedStat = lstatSync(requestedRoot);
+	if (requestedStat.isSymbolicLink() || !requestedStat.isDirectory())
+		throw new Error("task revision root must be a real directory");
+	const root = realpathSync(requestedRoot);
+	if (typeof baseHead !== "string" || !GIT_OBJECT_ID.test(baseHead.toLowerCase()))
+		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);
+	gitTaskSnapshotTestHook?.();
+	const after = taskRevisionSnapshotOnce(root, scope, normalizedBase);
+	if (JSON.stringify(after) !== JSON.stringify(before))
+		throw new Error("Git task revision changed while being captured");
+	return before;
+}
+
+export function taskRevisionIdentity(
+	projectRoot: string,
+	scopeHint: unknown,
+	baseHead: string,
+): GitTaskDiffIdentity {
+	const snapshot = captureGitTaskRevisionSnapshot(projectRoot, scopeHint, baseHead);
+	return {
+		diff_hash: hashTaskSnapshot(snapshot),
+		changed_paths: Object.keys(snapshot.changed_paths).sort(comparePaths),
+	};
+}
+
+/** The single v4 freshness identity shared by QA, Review, authorization, and completion. */
+export function taskRevisionDiffHash(
+	projectRoot: string,
+	scopeHint: unknown,
+	baseHead: string,
+): string {
+	return taskRevisionIdentity(projectRoot, scopeHint, baseHead).diff_hash;
 }
 
 function isGitWorkspaceSnapshot(value: unknown): value is GitWorkspaceSnapshot {

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

@@ -17,8 +17,7 @@ a reusable Learning; routine work without that evidence returns `next: none`
 and creates no Learning. Do not discover or load a Pi Skill for these roles. The Managed Path public entries remain `imm-brainstorm`, `imm-planner`, and `imm-loop`; standalone `imm-pr-fix` and `imm-doc-prune` are host-native and are never dispatched as the Loop role.
 Subagent Dispatch Protocol](../../dist/docs/reference/subagent-dispatch-protocol.md#authorization-authority).
 All internal Agent dispatch envelopes use `run_in_background: false` and
-return `tool_call`, `tool_result`, and `tool_execution_end` evidence to the
-Parent before any workflow mutation.
+return a direct result to the Parent before any workflow mutation.
 
 At `terminal_plan_complete`, stop with no next skill, authority, or action. At `awaiting_user_successor_decision`, stop with `recommended_authority: user`. This boundary follows the explicit internal Compounder handoff and runtime terminal settlement; it must not dispatch Planner, Compounder, transition, or a new Pi session/subagent. Only a literal user may approve a successor through the native authority gate; the internal runtime token is `--approve-successor`, never a public Skill or user-facing entry.
 
@@ -39,8 +38,8 @@ asking the user for chat pre-confirmation; the native host interaction is the
 single authority decision. Do not invoke the removed `imm-canary-work` Skill as
 a separate entry point. Invalid or contradictory projections fail closed. After
 implementation and focused verification, freeze the artifacts and call
-`advance_assurance`. If it returns `review_ready`, invoke the exact reserved
-foreground Agent and call `submit_review`; `request_authorization` remains the
+`advance_assurance`. If it returns `review_ready`, invoke the foreground
+reviewer and pass its structured verdict to `submit_review`; `request_authorization` remains the
 critical-risk user authorization boundary. Every QA/Review operation stays
 foreground and returns its next projected obligation directly to the Parent. The host performs any opted-in GitHub Issue projection only after the
 corresponding authority mutation: only a fresh claimless `done`/`stopped`

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

@@ -46,6 +46,8 @@ For Medium and High Design Risk, select every materially relevant technical-desi
 
 Use the selected design boundaries as one TaskIntent decomposition dimension alongside outcome, Verification, dependency, risk, rollback, compatibility, and authority. Keep one TaskIntent when the selected views describe one coherent executable slice with shared acceptance, risk treatment, rollback, and authority. Split a successor TaskIntent only when a service, state-machine owner, migration, independently promotable layer, or sequence dependency needs independent verification, rollback, authorization, or settlement. Do not split merely because the design names several layers, files, or services.
 
+Treat trust-boundary changes as the same kind of decomposition evidence. A TaskIntent should normally change one primary trust-boundary invariant; merely traversing several boundaries or updating both sides of one end-to-end authority chain does not require a split. Split separate trust invariants when they can be independently verified, rolled back, authorized, migrated, or settled. Keep multiple trust-boundary changes together only when they form one atomic security outcome and splitting would create an unsafe or unusable intermediate state; record that reason in the Spec. This is Planner judgment, not a TaskIntent schema field or an Enrollment counting rule.
+
 ## Reference Closure Preflight
 
 Before authoring a TaskIntent, trace each expected behavior from its public or