immune-brain 4.6.0 → 5.1.0

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

@@ -15,8 +15,10 @@ import {
 	VerificationAbortedError,
 } from "./verification";
 import { createInvocationRegistry, type InvocationState, type InvocationToken } from "./invocations";
-import type { ReviewBundle, ReviewManifestV5, ReviewRevision } from "./review_evidence";
-import { buildRoleDelegationPacket } from "../role_prompt_bridge";
+import type { ReviewBundle, ReviewManifestV5 } from "./review_evidence";
+import { createVerdictAuthority, type VerdictAuthority } from "./verdict_authority";
+import type { ConfirmationReferenceSource } from "./host_port";
+import { buildRoleDelegationPacket, STATIC_REVIEW_RULES } from "../role_prompt_bridge";
 import type { AssuranceProjectionResult } from "../kernel/assurance_projection";
 import type { TaskIntentIdentityToken } from "../kernel/intent_token_registry";
 import type { AssuranceHostPort, HostReviewReservation } from "./host_port";
@@ -346,7 +348,7 @@ export type AssuranceSubmitReviewResult = AssuranceRecoveryFields & (
 	| { state: "review_preparation_failed"; operation: "review"; operation_id: string; reason: string }
 	| { state: "completed" }
 	| { state: "settlement_unknown"; operation: "qa" | "review"; operation_id: string; reason: string }
-	| { state: "blocked"; reason: string; code?: "verdict_invalid" });
+	| { state: "blocked"; reason: string; code?: "verdict_invalid"; recovery_action?: string });
 
 export type ActiveAssuranceState =
 	| { state: "running"; operation: "qa"; operation_id: string; deadline_seconds: number }
@@ -355,51 +357,17 @@ export type ActiveAssuranceState =
 
 export interface AssuranceCoordinatorPorts {
 	host: AssuranceHostPort;
+	confirmationReference: ConfirmationReferenceSource;
+	onReworkApplied?: (ctx: HostContext, taskId: string, findingsCount: number) => void;
 	projectTask(root: string, taskId: string): Promise<AssuranceProjectionResult>;
 	readTaskRecord(root: string, taskId: string): Promise<TaskRecordRead>;
 	readTaskIntent(root: string, taskId: string): Promise<TaskIntentRead>;
-	buildAssurance(
-		root: string,
-		taskId: string,
-		role: AssuranceRole,
-		projection: AssuranceProjectionResult,
-	): Promise<{
-		snapshot: SnapshotDescriptor;
-		descriptors: Map<string, VerificationDescriptor>;
-		reviewBundle: ReviewBundle | null;
-		reviewManifest?: ReviewManifestV5 | null;
-	}>;
-	/**
-	 * Publish and prove the deterministic task-scoped revision before QA runs, so
-	 * a preparation failure can never consume or fake a settled QA attestation.
-	 * Returns null for records still on the legacy v3 bundle path.
-	 */
-	ensureReviewRevision?(
-		root: string,
-		taskId: string,
-		projection: AssuranceProjectionResult,
-	): Promise<ReviewRevision | null>;
 	runQa(
 		snapshot: SnapshotDescriptor,
 		descriptors: Map<string, VerificationDescriptor>,
 		options: { signal?: AbortSignal; onProgress?: (progress: QaVerificationProgress) => void },
 	): Promise<AssuranceVerdict>;
 	writeReviewEvidence(input: { snapshot: SnapshotDescriptor; evidence: ReviewBundle | ReviewManifestV5 }): { path: string; remove(): void };
-	applyVerdict(
-		ctx: HostContext,
-		input: {
-			taskId: string;
-			snapshot: SnapshotDescriptor;
-			verdict: AssuranceVerdict;
-			invocation: InvocationToken;
-			actorId: string;
-			hooks?: {
-				beforeCommit?: () => Promise<void>;
-				onCommit?: () => void;
-				afterCommit?: () => Promise<void>;
-			};
-		},
-	): Promise<void>;
 	applyOrdinaryOperation(ctx: HostContext, input: { taskId: string; operation: { op: string; actor_id: string } }): Promise<unknown>;
 	advanceBeforeProjection?: () => Promise<void>;
 	qaBeforeProjection?: () => Promise<void>;
@@ -478,19 +446,19 @@ export function snapshotDigest(snapshot: SnapshotDescriptor): string {
 	return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
 }
 
-export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: string): string {
+/**
+ * The per-dispatch Review facts: which evidence to read, which revision it pins,
+ * what the acceptances assert, and the exact verdict shapes.
+ *
+ * This is the whole prompt for a Host whose reviewer definition already carries
+ * the role contract and `STATIC_REVIEW_RULES` — the Claude Host. A Host whose
+ * dispatched agent carries no instructions (Pi) gets `buildReviewPrompt`, which
+ * prepends both.
+ */
+export function buildReviewSnapshotPrompt(snapshot: SnapshotDescriptor, evidencePath?: string): string {
 	if (snapshot.role !== "review") throw new Error("native review prompt requires review role");
 	const acceptance = snapshot.acceptance.map((item) => `- ${item.id}: ${item.assertion}`).join("\n");
 	const digest = snapshotDigest(snapshot);
-	const rolePacket = buildRoleDelegationPacket({
-		role: "code-review",
-		context: {
-			task_id: snapshot.task_id,
-			review_gate: "imm-code-review",
-			changed_files_signature: snapshot.diff_hash,
-			snapshot_digest: digest,
-		},
-	});
 	const revision = snapshot.review_revision;
 	const evidenceContract = revision
 		? [
@@ -506,25 +474,44 @@ export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: s
 				`The user-selected worktree may contain staged task changes that are absent from the isolated reviewer worktree. Review authority is bound only to the bundle dirty_files current_content bytes and committed HEAD provenance. Analyze code exclusively from those bundle bytes; repository file reads are permitted only for the provenance git commands above. A symbol present in current_content but absent from HEAD is the task change, not an absence.`,
 			];
 	return [
-		rolePacket.prompt,
 		...evidenceContract,
-		`Do not edit files, create files, run mutating commands, or change Git state. Focus on correctness, regressions, security, and missing tests.`,
-		`Execution outcomes for every acceptance were verified deterministically by the Kernel QA layer before this review and are embedded in this bundle under outcomes (the immutable evidence file, acceptance_id -> {status, summary}); do not re-execute descriptors and do not treat the absence of local test runs as a finding. Your review covers evidence provenance, code correctness, regressions, security, and missing tests against the embedded assertions and code.`,
 		`Snapshot digest: ${digest}`,
 		`TaskRecord revision: ${snapshot.record_revision}`,
 		revision
 			? `Intent revision ${snapshot.intent_revision} (hash ${snapshot.intent_content_hash}), diff ${snapshot.diff_hash}, review revision ${revision.review_commit} (base ${revision.base_head}, tree ${revision.review_tree}, manifest ${revision.manifest_digest}), state ${snapshot.lifecycle}:${snapshot.artifact_state}.`
 			: `Intent revision ${snapshot.intent_revision} (hash ${snapshot.intent_content_hash}), diff ${snapshot.diff_hash}, review bundle ${snapshot.review_bundle_digest}, state ${snapshot.lifecycle}:${snapshot.artifact_state}.`,
 		"Acceptance assertions:", acceptance,
-		"Reserve the final turn for exactly one strict JSON verdict. Reply with ONLY that object, without markdown fences or commentary.",
-		`Every rework finding must carry machine-checkable provenance: evidence.trigger (the concrete inputs or state that reach the defect), a non-empty evidence.caller_chain (ordered repository paths or symbols), and evidence.violated {kind: "acceptance"|"security_boundary", ref}. The anchor is derived from that evidence; a finding without it is rejected and the correction must be resubmitted.`,
-		`PASS shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>"}}`,
-		`A pass verdict may carry non-blocking notes as findings, but every one of them must set kind "advisory"; a blocking finding is a rework verdict and must omit approval: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>"},"findings":[{"id":"review-1","kind":"advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
+		`PASS shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>","inspected_paths":["<every changed path of the reviewed change set>"]}}`,
+		`A pass verdict may carry non-blocking notes as findings, but every one of them must set kind "advisory"; a blocking finding is a rework verdict and must omit approval: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"pass","approval":{"kind":"review","authority_role":"reviewer","summary":"<one line>","inspected_paths":["<every changed path of the reviewed change set>"]},"findings":[{"id":"review-1","kind":"advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
 		`REWORK shape: {"contract":"assurance_kernel/assurance_verdict/v2","role":"review","task_id":"${snapshot.task_id}","snapshot_digest":"${digest}","decision":"rework","findings":[{"id":"review-1","kind":"blocking|advisory","acceptance_id":"<id|null>","summary":"<one line>","evidence":{"trigger":"<concrete inputs or state>","caller_chain":["<path-or-symbol>"],"violated":{"kind":"acceptance|security_boundary","ref":"<acceptance id or boundary>"}}}]}`,
 		`REWORK verdicts must omit the approval field entirely; do not emit "approval": null.`,
 	].join("\n");
 }
 
+/**
+ * The complete Review prompt: the internal role contract, the static review
+ * rules, and the per-dispatch facts. Dispatched by a Host whose agent carries no
+ * instructions of its own.
+ */
+export function buildReviewPrompt(snapshot: SnapshotDescriptor, evidencePath?: string): string {
+	if (snapshot.role !== "review") throw new Error("native review prompt requires review role");
+	const digest = snapshotDigest(snapshot);
+	const rolePacket = buildRoleDelegationPacket({
+		role: "code-review",
+		context: {
+			task_id: snapshot.task_id,
+			review_gate: "imm-code-review",
+			changed_files_signature: snapshot.diff_hash,
+			snapshot_digest: digest,
+		},
+	});
+	return [
+		rolePacket.prompt,
+		...STATIC_REVIEW_RULES,
+		buildReviewSnapshotPrompt(snapshot, evidencePath),
+	].join("\n");
+}
+
 function parseVerdictEvidence(value: unknown, index: number): FindingEvidence {
 	if (!value || typeof value !== "object" || Array.isArray(value))
 		throw new Error(`finding ${index} evidence is required`);
@@ -593,7 +580,28 @@ export function parseAssuranceVerdict(input: unknown, snapshot: SnapshotDescript
 		const expectedKind = snapshot.role === "qa" ? "qa" : "review";
 		const expectedRole = snapshot.role === "qa" ? "qa" : "reviewer";
 		if (!approval || approval.kind !== expectedKind || approval.authority_role !== expectedRole || typeof approval.summary !== "string" || !approval.summary.trim()) throw new Error("pass verdict approval is invalid");
-		const unknownApproval = Object.keys(approval).find((key) => !["kind", "authority_role", "summary"].includes(key));
+		// A Review pass must claim the paths it inspected: BR-DEC-3 converts silent
+		// partial coverage into an explicit false statement. The list is checked
+		// here against the reviewed change set and removed before settlement, so
+		// the Kernel approval and TaskRecord never see it. QA verdicts treat the
+		// field as unknown, exactly as before.
+		if (snapshot.role === "review") {
+			const required = snapshot.dirty_files;
+			const listed = approval.inspected_paths;
+			if (listed === undefined) throw new Error(`review pass verdict approval.inspected_paths is required; it must list every reviewed changed path${required.length ? `: ${required.join(", ")}` : " (none for this change set)"}`);
+			if (!Array.isArray(listed) || listed.some((entry) => typeof entry !== "string" || !entry.trim())) throw new Error("review pass verdict approval.inspected_paths must be an array of repository-relative path strings");
+			const seen = new Set<string>();
+			for (const entry of listed as string[]) {
+				if (seen.has(entry)) throw new Error(`review pass verdict approval.inspected_paths lists a duplicate path: ${entry}`);
+				seen.add(entry);
+			}
+			const foreign = (listed as string[]).filter((entry) => !required.includes(entry));
+			if (foreign.length) throw new Error(`review pass verdict approval.inspected_paths lists a path outside the reviewed change set: ${foreign.join(", ")}`);
+			const missing = required.filter((entry) => !seen.has(entry));
+			if (missing.length) throw new Error(`review pass verdict approval.inspected_paths omits reviewed changed paths: ${missing.join(", ")}`);
+		}
+		const allowedApproval = snapshot.role === "review" ? ["kind", "authority_role", "summary", "inspected_paths"] : ["kind", "authority_role", "summary"];
+		const unknownApproval = Object.keys(approval).find((key) => !allowedApproval.includes(key));
 		if (unknownApproval) throw new Error(`pass verdict approval has unknown field: ${unknownApproval}`);
 		const passFindings = raw.findings === undefined ? [] : parseVerdictFindings(raw.findings as unknown[], snapshot);
 		if (passFindings.some((finding) => finding.kind !== "advisory")) throw new Error("pass verdict findings must all be advisory");
@@ -726,7 +734,14 @@ export class AssuranceCoordinator {
 	private sessionActive = true;
 	private sessionGeneration = 0;
 
-	constructor(private readonly ports: AssuranceCoordinatorPorts) {}
+	readonly authority: VerdictAuthority;
+	constructor(private readonly ports: AssuranceCoordinatorPorts, authorityOverrides: Partial<VerdictAuthority> = {}) {
+		this.authority = { ...createVerdictAuthority({
+			confirmationReference: ports.confirmationReference,
+			commitInvocation: token => this.commitInvocation(token),
+			onReworkApplied: ports.onReworkApplied,
+		}), ...authorityOverrides };
+	}
 
 	onSessionStart(): void {
 		this.sessionActive = true;
@@ -973,9 +988,9 @@ export class AssuranceCoordinator {
 				progress("preparing_review_revision", "Proving the immutable Review revision before QA");
 				try {
 					if (parked.record?.contract === "assurance_kernel/task_record/v4") {
-						if (!this.ports.ensureReviewRevision)
+						if (!this.authority.ensureReviewRevision)
 							throw new Error("v4 Review revision preparation is unavailable");
-						await this.ports.ensureReviewRevision(ctx.cwd, taskId, projection);
+						await this.authority.ensureReviewRevision(ctx.cwd, taskId, projection);
 					}
 				} catch (error) {
 					return { state: "blocked", reason: `review revision preparation failed: ${boundedAssuranceError(error)}` };
@@ -989,7 +1004,7 @@ export class AssuranceCoordinator {
 				progress("capturing_snapshot", "Capturing the immutable QA snapshot");
 				await this.ports.qaBeforeProjection?.();
 				ensureOperationLive();
-				const assurance = await this.ports.buildAssurance(ctx.cwd, taskId, "qa", projection);
+				const assurance = await this.authority.buildAssurance(ctx.cwd, taskId, "qa", projection);
 				ensureOperationLive();
 				// Preparation counts against the same ceiling as the checks, so the
 				// aggregate clock starts before the first prepared group runs. A host
@@ -1027,7 +1042,7 @@ export class AssuranceCoordinator {
 				try {
 					progress("settling_qa", "Settling deterministic QA through the Kernel revision boundary");
 					authorityBoundaryStarted = true;
-					await this.ports.applyVerdict(ctx, {
+					await this.authority.applyVerdict(ctx, {
 						taskId,
 						snapshot: assurance.snapshot,
 						verdict: qaVerdict,
@@ -1090,10 +1105,10 @@ export class AssuranceCoordinator {
 			authorityBoundaryStarted = false;
 			if (aborted()) return this.reviewPreparationFailed(taskId, operationId, "host cancellation after QA authority settlement");
 			progress("preparing_review", "Preparing the reserved foreground Review evidence");
-			let review: Awaited<ReturnType<AssuranceCoordinatorPorts["buildAssurance"]>>;
+			let review: Awaited<ReturnType<VerdictAuthority["buildAssurance"]>>;
 			let evidence: { path: string; remove(): void };
 			try {
-				review = await this.ports.buildAssurance(ctx.cwd, taskId, "review", fresh);
+				review = await this.authority.buildAssurance(ctx.cwd, taskId, "review", fresh);
 				const payload = review.reviewManifest ?? review.reviewBundle;
 				if (!payload) throw new Error("review evidence is missing after QA settlement");
 				evidence = this.ports.writeReviewEvidence({ snapshot: review.snapshot, evidence: payload });
@@ -1116,6 +1131,7 @@ export class AssuranceCoordinator {
 					taskId,
 					operationId,
 					prompt: buildReviewPrompt(review.snapshot, evidence.path),
+					snapshotPrompt: buildReviewSnapshotPrompt(review.snapshot, evidence.path),
 					evidencePath: evidence.path,
 					maxTurns: reviewTurnBudget(workload),
 				});
@@ -1202,9 +1218,9 @@ export class AssuranceCoordinator {
 		}
 		if (reservation.snapshot.review_revision) {
 			try {
-				if (!this.ports.ensureReviewRevision)
+				if (!this.authority.ensureReviewRevision)
 					throw new Error("v4 Review revision verification is unavailable");
-				const revision = await this.ports.ensureReviewRevision(ctx.cwd, taskId, fresh);
+				const revision = await this.authority.ensureReviewRevision(ctx.cwd, taskId, fresh);
 				if (!revision || revision.base_head !== reservation.snapshot.review_revision.base_head || revision.review_commit !== reservation.snapshot.review_revision.review_commit || revision.review_tree !== reservation.snapshot.review_revision.review_tree || revision.manifest_digest !== reservation.snapshot.review_revision.manifest_digest)
 					throw new Error("Review revision changed before submission");
 			} catch (error) {
@@ -1220,7 +1236,7 @@ export class AssuranceCoordinator {
 		const invocation = this.openInvocation(taskId);
 		this.releaseReviewReservation(taskId, reservation);
 		try {
-			await this.ports.applyVerdict(ctx, {
+			await this.authority.applyVerdict(ctx, {
 				taskId,
 				snapshot: reservation.snapshot,
 				verdict,

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

@@ -1,7 +1,27 @@
+import type { SnapshotDescriptor } from "./coordinator";
+
+export type ConfirmationReferenceSource = (input: {
+	snapshot: SnapshotDescriptor;
+	actorId: string;
+	now: string;
+}) => string;
+
 export interface ReviewRequest {
 	taskId: string;
 	operationId: string;
+	/**
+	 * The complete Review prompt: internal role contract, static review rules and
+	 * the per-dispatch facts. Dispatched by a Host whose reviewer agent carries no
+	 * instructions of its own.
+	 */
 	prompt: string;
+	/**
+	 * The per-dispatch facts alone, a strict suffix of `prompt`. A Host whose
+	 * reviewer definition already carries the role contract and the static rules
+	 * dispatches only this, so the static instructions stay generated from one
+	 * source instead of being sent twice.
+	 */
+	snapshotPrompt: string;
 	evidencePath: string;
 	maxTurns: number;
 }

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

@@ -8,14 +8,14 @@ import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import { qaFindingId } from "./qa_findings";
 import { captureGitTaskRevisionSnapshot } from "../workspace_scope";
-import { readTaskRecord } from "../kernel/storage";
+import { readTaskRecordRaw } from "../kernel/storage";
 
 function deliveryTreeForSnapshot(
 	snapshot: SnapshotDescriptor,
 	writeTree: typeof writeDeliveryTree,
 ): string {
 	if (snapshot.review_revision?.review_tree) return snapshot.review_revision.review_tree;
-	const record = readTaskRecord(snapshot.root, snapshot.task_id).record;
+	const record = readTaskRecordRaw(snapshot.root, snapshot.task_id).record;
 	if (!record || record.contract !== "assurance_kernel/task_record/v4" || !record.git_base_head)
 		throw new Error("QA delivery requires a TaskRecord v4 git_base_head");
 	const captured = captureGitTaskRevisionSnapshot(