immune-brain 2.8.3 → 3.0.2

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

@@ -4,6 +4,8 @@ import {
 	TASK_PHASES,
 	TASK_RECORD_CONTRACT_V2,
 	TASK_RECORD_CONTRACT_V3,
+	TASK_RECORD_CONTRACT_V4,
+	REVIEW_REVISION_IDENTITY_CONTRACT,
 	type ApprovalAuthorityRole,
 	type ApprovalKind,
 	type EvidenceStatus,
@@ -19,11 +21,16 @@ import {
 	type TaskHistoryEntryV2,
 	type TaskHistoryEntryV3,
 	type TaskIntentV1,
+	type ReviewRevisionIdentityV1,
+	type TaskRecord,
 	type TaskRecordV2,
 	type TaskRecordV3,
+	type TaskRecordV4,
 } from "./types";
 import { canonicalIntentHash, parseTaskIntentV1 } from "./intent";
 
+const GIT_OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
 export class KernelValidationError extends Error {
 	readonly code = "kernel_schema_invalid";
 
@@ -320,11 +327,13 @@ function parseApprovalV2(
 	value: unknown,
 	index: number,
 	violations: string[],
+	allowReviewRevision = false,
 ): TaskApprovalV2 {
 	const item = objectAt(value, `record.approvals[${index}]`, violations);
 	rejectUnknown(
 		item,
-		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary"],
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary",
+			...(allowReviewRevision ? ["review_revision"] : [])],
 		`record.approvals[${index}]`,
 		violations,
 	);
@@ -356,18 +365,52 @@ function parseApprovalV2(
 		diff_hash: diffHash,
 		actor_id: stringAt(item.actor_id, `record.approvals[${index}].actor_id`, violations),
 		summary: stringAt(item.summary, `record.approvals[${index}].summary`, violations),
+		...(allowReviewRevision && item.review_revision !== undefined
+			? { review_revision: parseReviewRevisionIdentity(item.review_revision, `record.approvals[${index}].review_revision`, violations) }
+			: {}),
 	};
 }
 
+function parseReviewRevisionIdentity(
+	value: unknown,
+	path: string,
+	violations: string[],
+): ReviewRevisionIdentityV1 {
+	const item = objectAt(value, path, violations);
+	rejectUnknown(item, ["contract", "base_head", "review_commit", "review_tree", "manifest_digest"], path, violations);
+	if (item.contract !== REVIEW_REVISION_IDENTITY_CONTRACT)
+		violations.push(`${path}.contract must equal ${REVIEW_REVISION_IDENTITY_CONTRACT}`);
+	const identity = {
+		contract: REVIEW_REVISION_IDENTITY_CONTRACT,
+		base_head: stringAt(item.base_head, `${path}.base_head`, violations),
+		review_commit: stringAt(item.review_commit, `${path}.review_commit`, violations),
+		review_tree: stringAt(item.review_tree, `${path}.review_tree`, violations),
+		manifest_digest: stringAt(item.manifest_digest, `${path}.manifest_digest`, violations),
+	};
+	for (const field of ["base_head", "review_commit", "review_tree"] as const)
+		if (!GIT_OBJECT_ID.test(identity[field]))
+			violations.push(`${path}.${field} must be a lowercase Git object id`);
+	if (!SHA256_HEX.test(identity.manifest_digest))
+		violations.push(`${path}.manifest_digest must be sha256:<64 hex>`);
+	return identity;
+}
+
 function parseAttestationV3(
 	value: unknown,
 	index: number,
 	acceptanceIds: Set<string>,
 	violations: string[],
+	allowReviewRevision = false,
 ): TaskAttestationV3 {
 	const path = `record.attestations[${index}]`;
 	const item = objectAt(value, path, violations);
-	rejectUnknown(item, ["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results"], path, violations);
+	rejectUnknown(
+		item,
+		["id", "kind", "authority_role", "task_revision", "intent_content_hash", "diff_hash", "actor_id", "summary", "acceptance_results",
+			...(allowReviewRevision ? ["review_revision"] : [])],
+		path,
+		violations,
+	);
 	const kind = enumAt(item.kind, APPROVAL_KINDS, `${path}.kind`, violations);
 	const intentContentHash = stringAt(item.intent_content_hash, `${path}.intent_content_hash`, violations);
 	const diffHash = stringAt(item.diff_hash, `${path}.diff_hash`, violations);
@@ -392,6 +435,13 @@ function parseAttestationV3(
 		if (resultIds.length !== acceptanceIds.size || new Set(resultIds).size !== acceptanceIds.size)
 			violations.push(`${path}.acceptance_results must cover every acceptance exactly once`);
 	}
+	const reviewRevision = item.review_revision === undefined
+		? undefined
+		: parseReviewRevisionIdentity(item.review_revision, `${path}.review_revision`, violations);
+	if (reviewRevision && kind !== "review")
+		violations.push(`${path}.review_revision is only valid on review attestations`);
+	if (allowReviewRevision && kind === "review" && !reviewRevision)
+		violations.push(`${path}.review_revision is required for v4 review attestations`);
 	return {
 		id: stringAt(item.id, `${path}.id`, violations),
 		kind,
@@ -402,6 +452,7 @@ function parseAttestationV3(
 		actor_id: stringAt(item.actor_id, `${path}.actor_id`, violations),
 		summary: stringAt(item.summary, `${path}.summary`, violations),
 		acceptance_results: acceptanceResults,
+		...(reviewRevision ? { review_revision: reviewRevision } : {}),
 	};
 }
 
@@ -528,17 +579,19 @@ export function parseTaskRecordV2(raw: unknown): TaskRecordV2 {
 	};
 }
 
-export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
+function parseTaskRecordAtVersion(raw: unknown, version: 3 | 4): TaskRecordV3 | TaskRecordV4 {
 	const violations: string[] = [];
 	const value = objectAt(raw, "record", violations);
 	rejectUnknown(
 		value,
-		["contract", "task_id", "intent_snapshot", "intent_ref", "lifecycle", "artifact_state", "baseline", "attestations", "findings", "history"],
+		["contract", "task_id", "intent_snapshot", "intent_ref", "lifecycle", "artifact_state", "baseline", "attestations", "findings", "history",
+			...(version === 4 ? ["git_base_head"] : [])],
 		"record",
 		violations,
 	);
-	if (value.contract !== TASK_RECORD_CONTRACT_V3)
-		violations.push(`contract must equal ${TASK_RECORD_CONTRACT_V3}`);
+	const expectedContract = version === 4 ? TASK_RECORD_CONTRACT_V4 : TASK_RECORD_CONTRACT_V3;
+	if (value.contract !== expectedContract)
+		violations.push(`contract must equal ${expectedContract}`);
 
 	let snapshot: TaskIntentV1 | null = null;
 	try {
@@ -570,31 +623,65 @@ export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
 
 	const baseline = stringAt(value.baseline, "record.baseline", violations);
 	if (!SHA256_HEX.test(baseline)) violations.push("record.baseline must be sha256:<64 hex>");
+	let gitBaseHead = "";
+	if (version === 4) {
+		const rawGitBaseHead = stringAt(value.git_base_head, "record.git_base_head", violations);
+		if (rawGitBaseHead !== rawGitBaseHead.toLowerCase())
+			violations.push("record.git_base_head must be lowercase");
+		gitBaseHead = rawGitBaseHead;
+		if (!GIT_OBJECT_ID.test(gitBaseHead))
+			violations.push("record.git_base_head must be a lowercase Git commit id");
+	}
 	const acceptanceIds = new Set(snapshot ? snapshot.acceptance.map((item) => item.id) : []);
-	const attestations = arrayAt(value.attestations, "record.attestations", violations).map((item, index) => parseAttestationV3(item, index, acceptanceIds, violations));
+	const attestations = arrayAt(value.attestations, "record.attestations", violations).map((item, index) => parseAttestationV3(item, index, acceptanceIds, violations, version === 4));
+	if (version === 4) {
+		for (const [index, attestation] of attestations.entries()) {
+			if (attestation.kind === "review" && attestation.review_revision && attestation.review_revision.base_head !== gitBaseHead)
+				violations.push(`record.attestations[${index}].review_revision.base_head must equal record.git_base_head`);
+		}
+	}
 	const findings = arrayAt(value.findings, "record.findings", violations).map((item, index) => parseFinding(item, index, violations));
 	const history = arrayAt(value.history, "record.history", violations).map((item, index) => parseHistoryV3(item, index, violations));
 	uniqueIds(attestations, "record.attestations", violations);
 	uniqueIds(findings, "record.findings", violations);
 	uniqueIds(history, "record.history", violations);
 	if (violations.length > 0) throw new KernelValidationError(violations);
-	return {
-		contract: TASK_RECORD_CONTRACT_V3,
+	const record = {
+		contract: expectedContract,
 		task_id: taskId,
 		intent_snapshot: snapshot as TaskIntentV1,
 		intent_ref: { path: refPath, content_hash: refContentHash },
 		lifecycle: lifecycle as TaskRecordV3["lifecycle"],
 		artifact_state: artifactState as TaskRecordV3["artifact_state"],
 		baseline,
+		...(version === 4 ? { git_base_head: gitBaseHead } : {}),
 		attestations,
 		findings,
 		history,
 	};
+	return record as TaskRecordV3 | TaskRecordV4;
+}
+
+/** Strict v3 drain parser: unknown fields and revision identity stay illegal. */
+export function parseTaskRecordV3(raw: unknown): TaskRecordV3 {
+	return parseTaskRecordAtVersion(raw, 3) as TaskRecordV3;
+}
+
+/** Strict v4 parser: the Enrollment base commit is mandatory. */
+export function parseTaskRecordV4(raw: unknown): TaskRecordV4 {
+	return parseTaskRecordAtVersion(raw, 4) as TaskRecordV4;
+}
+
+/** Version-dispatched parser used by every durable Kernel owner. */
+export function parseTaskRecord(raw: unknown): TaskRecord {
+	const contract = (raw as { contract?: unknown } | null)?.contract;
+	if (contract === TASK_RECORD_CONTRACT_V4) return parseTaskRecordV4(raw);
+	return parseTaskRecordV3(raw);
 }
 
-export function assertKernelInvariantsV3(intentRaw: TaskIntentV1, recordRaw: TaskRecordV3): void {
+export function assertKernelInvariantsV3(intentRaw: TaskIntentV1, recordRaw: TaskRecord): void {
 	const intent = parseTaskIntentV1(intentRaw);
-	const record = parseTaskRecordV3(recordRaw);
+	const record = parseTaskRecord(recordRaw);
 	const violations: string[] = [];
 	if (intent.task_id !== record.task_id) violations.push("intent and record task_id must match");
 	if (intent.revision !== record.intent_snapshot.revision) violations.push("intent revision must match record snapshot");
@@ -752,7 +839,9 @@ export function parseTaskAction(raw: unknown): TaskAction {
 				"action",
 				violations,
 			);
-			const approval = parseApprovalV2(value.approval, 0, violations);
+			const approval = parseApprovalV2(value.approval, 0, violations, true);
+			if (approval.review_revision && approval.kind !== "review")
+				violations.push("action.approval.review_revision is only valid on review approvals");
 			action = {
 				...base,
 				type: base.type,
@@ -871,12 +960,12 @@ export function parseTaskAction(raw: unknown): TaskAction {
 }
 
 export function assertTaskRecordUpdateV3(
-	previousRaw: TaskRecordV3,
-	nextRaw: TaskRecordV3,
+	previousRaw: TaskRecord,
+	nextRaw: TaskRecord,
 	action: TaskAction,
 ): void {
-	const previous = parseTaskRecordV3(previousRaw);
-	const next = parseTaskRecordV3(nextRaw);
+	const previous = parseTaskRecord(previousRaw);
+	const next = parseTaskRecord(nextRaw);
 	const violations: string[] = [];
 
 	if (next.contract !== previous.contract)
@@ -885,6 +974,8 @@ export function assertTaskRecordUpdateV3(
 		violations.push("record task_id must remain immutable");
 	if (next.baseline !== previous.baseline)
 		violations.push("record baseline must remain immutable");
+	if (previous.contract === TASK_RECORD_CONTRACT_V4 && next.contract === TASK_RECORD_CONTRACT_V4 && next.git_base_head !== previous.git_base_head)
+		violations.push("record git_base_head must remain immutable");
 
 	const isIntentAction =
 		action.type === "revise_intent" ||

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

@@ -217,7 +217,7 @@ export function buildLoopAction(input: {
 export interface LoopRoleDispatch {
 	packet: RoleDelegationPacket;
 	call: {
-		subagent_type: "general-purpose";
+		subagent_type: LoopRoleSubagent;
 		description: string;
 		prompt: string;
 		inherit_context: false;
@@ -226,6 +226,21 @@ export interface LoopRoleDispatch {
 	};
 }
 
+/**
+ * Authoritative code review runs on the host's configured `Review` agent so the
+ * user's own model/provider selection applies. Architecture exploration uses
+ * the host `Explore` agent. Every other internal role, and especially the
+ * tool-less planning `advisory-reviewer`, stays on the generic agent and never
+ * inherits review authority.
+ */
+export type LoopRoleSubagent = "Review" | "Explore" | "general-purpose";
+
+export function loopRoleSubagentFor(role: LoopRole): LoopRoleSubagent {
+	if (role === "code-review") return "Review";
+	if (role === "arch-explorer") return "Explore";
+	return "general-purpose";
+}
+
 export function buildLoopRoleDispatch(input: {
 	role: LoopRole;
 	context: RoleDelegationContext;
@@ -235,7 +250,7 @@ export function buildLoopRoleDispatch(input: {
 	return {
 		packet,
 		call: {
-			subagent_type: "general-purpose",
+			subagent_type: loopRoleSubagentFor(input.role),
 			description: input.description ?? `${input.role} internal role`,
 			prompt: packet.prompt,
 			inherit_context: false,

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 {