immune-brain 3.6.4 → 3.6.5

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

@@ -163,18 +163,23 @@ After approval, author, stage, and validate every TaskIntent in the decompositio
 with `valid: true` and `enrollment_ready: true`. Resolve `../bin/imm-tracker` from this packaged contract; do not assume a bare command is on `PATH`. Submit the entire approved set once through
 `imm-tracker publish-initiative --stdin --json`. Its input contains the confirmed
 Initiative slug and goal, Parent projection, and every Child's `slice_id`,
-canonical TaskIntent path, and public projection. The Parent projection requires
+canonical TaskIntent path, bounded public `acceptance` summaries, and public
+projection. The Parent projection requires
 `problem`, `result`, and `design`, and may include `decisions`,
 `testing_strategy`, and `out_of_scope`. `design` records Initiative-level
 invariants, Slice boundaries and ordering, shared interfaces or state flow, and
 material compatibility decisions. Every Parent Slice must correspond to one
 published Child; future checklist-only Slices are not allowed in the batch.
 
-Each Child projection may contain `result`, `current_behavior`,
+Each Child must provide public `acceptance` entries with `id` and a 1-500
+character `summary`. Their IDs must match every canonical TaskIntent acceptance
+ID exactly once. Canonical assertion prose is authority evidence and must never
+be copied into public GitHub projection. Each Child projection may contain
+`result`, `current_behavior`,
 `desired_behavior`, `key_interfaces`, `verification`, `blocked_by` Task IDs,
 `out_of_scope`, and `agent_handoff`. The tracker rereads every canonical
-TaskIntent for identity, risk, and acceptance; projection fields never widen
-TaskIntent scope or authority. It validates the complete dependency graph before
+TaskIntent for identity, risk, and acceptance IDs; projection fields and public
+summaries never widen TaskIntent scope or authority. It validates the complete dependency graph before
 remote writes, creates the Parent once, creates all Children, attaches every
 Child as a native Sub-issue, creates native `blocked_by` relations, and rereads
 the complete topology. The Child Agent Brief includes a direct Parent Issue link.

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

@@ -436,6 +436,7 @@ export class AssuranceCoordinator {
 	sessionGenerationValue(): number { return this.sessionGeneration; }
 
 	async advance(taskId: string, ctx: HostContext, signal?: AbortSignal, onUpdate?: (update: ForegroundToolUpdate) => void): Promise<AssuranceAdvanceResult> {
+		if (this.isInvocationOpen(taskId)) return { state: "blocked", reason: "an authority invocation is already open" };
 		const active = this.active(taskId);
 		if (active?.state === "review_ready") {
 			const reservation = this.reviewReservations.get(taskId);
@@ -819,6 +820,17 @@ export class AssuranceCoordinator {
 		return { state: "blocked", reason: `Kernel requires ${settled.projection.next_obligation} after Review` };
 	}
 
+	isReviewVerdictValid(taskId: string, verdictInput: unknown): boolean {
+		const reservation = this.reviewReservations.get(taskId);
+		if (!reservation) return false;
+		try {
+			parseAssuranceVerdict(verdictInput, reservation.snapshot);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
 	abandonReview(taskId: string, reason: string): AssuranceSubmitReviewResult {
 		const reservation = this.reviewReservations.get(taskId);
 		if (!reservation) return { state: "blocked", reason };
@@ -833,6 +845,12 @@ export class AssuranceCoordinator {
 		return { state: "review_ready", operation: "review", operation_id: reservation.operationId, snapshot_digest: snapshotDigest(reservation.snapshot), review_bundle_digest: reservation.snapshot.review_bundle_digest ?? "", agent_params: reservation.hostReservation.dispatch };
 	}
 
+	releaseStoppedReview(taskId: string): void {
+		const reservation = this.reviewReservations.get(taskId);
+		if (reservation) this.releaseReviewReservation(taskId, reservation);
+		this.rejectedReviewOperations.delete(taskId);
+	}
+
 	private releaseReviewReservation(taskId: string, reservation: ReviewReservation, rejectionReason?: string): void {
 		if (this.reviewReservations.get(taskId) !== reservation) return;
 		this.reviewReservations.delete(taskId);

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

@@ -119,13 +119,16 @@ export async function submitClaudeReview(
 		if (observed.release) return coordinator.abandonReview(taskId, observed.reason);
 		return { state: "blocked", reason: observed.reason };
 	}
-	const parentJson = extractVerdictJson(verdictInput);
-	const receiptJson = extractVerdictJson(observed.receipt.result);
-	if (parentJson && receiptJson && verdictFingerprint(parentJson) !== verdictFingerprint(receiptJson)) {
-		return { state: "blocked", reason: "parent verdict does not match reviewer receipt" };
+	const parentValid = coordinator.isReviewVerdictValid(taskId, verdictInput);
+	if (!parentValid) return coordinator.submitReview(taskId, ctx, verdictInput);
+	const receiptValid = coordinator.isReviewVerdictValid(taskId, observed.receipt.result);
+	if (!receiptValid) {
+		return coordinator.abandonReview(taskId, "reviewer receipt is not a valid verdict");
 	}
-	if (parentJson && !receiptJson) {
-		return { state: "blocked", reason: "reviewer receipt is not a valid verdict" };
+	const parentJson = extractVerdictJson(verdictInput)!;
+	const receiptJson = extractVerdictJson(observed.receipt.result)!;
+	if (verdictFingerprint(parentJson) !== verdictFingerprint(receiptJson)) {
+		return { state: "blocked", reason: "parent verdict does not match reviewer receipt" };
 	}
 	return coordinator.submitReview(taskId, ctx, verdictInput);
 }
@@ -525,6 +528,19 @@ export class ClaudeRuntime {
 		return submitClaudeReview(this.host, this.coordinator, { cwd: this.cwd }, taskId, verdictInput);
 	}
 
+	/**
+	 * Ordinary Kernel operation, not a privileged one: canary_application builds
+	 * the action without a capability and the Pi Host lists resolve_finding in
+	 * its ordinary KERNEL_OPERATIONS. The reducer owns every precondition, so
+	 * this port reads no findings and tests no kind.
+	 */
+	async resolveFinding(taskId: string, findingId: string) {
+		return this.executeOrdinary({ cwd: this.cwd }, {
+			taskId,
+			operation: { op: "resolve_finding", finding_id: findingId, actor_id: "executor" },
+		});
+	}
+
 	async authorize(taskId: string, operation: string, meta: ToolMeta, extra: Record<string, unknown> = {}) {
 		if (operation === "repair_authority_state") {
 			const authority = reconcileKernelAuthority(this.cwd, taskId);
@@ -534,7 +550,7 @@ export class ClaudeRuntime {
 			return repairKernelAuthority(this.cwd, taskId, authority.revision);
 		}
 		if (!isPrivilegedOperation(operation) && operation !== "request_authorization") throw new Error(`unsupported privileged operation ${operation}`);
-		let op: PrivilegedOperation | "request_authorization" | "resolve_user_decision" = operation;
+		let op: PrivilegedOperation | "request_authorization" | "resolve_user_decision" | "authorize_rework" = operation;
 		let decisionOp: { finding_id: string; resolution: string } | undefined;
 		const projection = await this.status(taskId);
 		if (projection.error || !projection.claim) throw new Error(projection.error ?? "no active backend claim");
@@ -551,6 +567,8 @@ export class ClaudeRuntime {
 				if (open.length !== 1) throw new Error(`resolve-user-decision requires exactly one open user decision; found ${open.length}`);
 				op = "resolve_user_decision";
 				decisionOp = { finding_id: open[0].id, resolution: `resume after literal-user decision: ${open[0].summary}` };
+			} else if (readiness.state === "authorize_rework") {
+				op = "authorize_rework";
 			} else {
 				throw new Error(readiness.blocked ?? "no unique host-derived authorization operation");
 			}
@@ -668,7 +686,11 @@ export class ClaudeRuntime {
 				diffProvider: diffSnapshotOf,
 				now,
 			});
-			if (op === "stop" || op === "approve_breaking_intent_revision") stagePlanningArtifactTransition(this.cwd, result.record);
+			if (
+				op === "stop" ||
+				op === "authorize_rework" ||
+				op === "approve_breaking_intent_revision"
+			) stagePlanningArtifactTransition(this.cwd, result.record);
 			return result;
 		} catch (error) {
 			if (sidecar && priorBytes && priorIndexState) {
@@ -773,7 +795,7 @@ export class ClaudeRuntime {
 		}));
 	}
 
-	private async executeOrdinary(ctx: HostContext, input: { taskId: string; operation: { op: string; actor_id: string; next_intent?: unknown } }) {
+	private async executeOrdinary(ctx: HostContext, input: { taskId: string; operation: { op: string; actor_id: string; next_intent?: unknown; finding_id?: string } }) {
 		const { app } = await this.authority();
 		const operation = input.operation.op === "revise_intent"
 			? { ...input.operation, next_intent: await parseTaskIntentV1(input.operation.next_intent) }

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

@@ -26,6 +26,7 @@ export const TOOLS = [
 	{ name: "approve_breaking_intent_revision", description: "Approve a breaking TaskIntent revision.", privileged: true },
 	{ name: "stop", description: "Stop the active task with literal-user authority.", privileged: true },
 	{ name: "repair_authority_state", description: "Repair a proven recoverable stale backend claim.", privileged: false },
+	{ name: "resolve_finding", description: "Resolve one open blocking or advisory finding whose cause is fixed and verified.", privileged: false },
 ] as const;
 
 export function listMcpTools() {
@@ -39,8 +40,13 @@ export function listMcpTools() {
 				...(tool.name === "approve_breaking_intent_revision" ? { next_intent: { type: "object" } } : {}),
 				...(tool.name === "stop" ? { reason: { type: "string" } } : {}),
 				...(tool.name === "submit_review" ? { verdict: { type: "object" } } : {}),
+				...(tool.name === "resolve_finding" ? { finding_id: { type: "string" } } : {}),
 			},
-			required: tool.name === "submit_review" ? ["task_id", "verdict"] : ["task_id"],
+			required: tool.name === "submit_review"
+				? ["task_id", "verdict"]
+				: tool.name === "resolve_finding"
+					? ["task_id", "finding_id"]
+					: ["task_id"],
 		},
 		annotations: tool.privileged ? privilegedAnnotations() : { readOnlyHint: tool.name === "status" },
 	}));
@@ -119,6 +125,13 @@ export function createMcpRuntime(options: McpRuntimeOptions = {}) {
 				if (!Object.hasOwn(args, "verdict")) throw new Error("verdict is required");
 				return runtime.submitReview(taskId, args.verdict);
 			}
+			if (name === "resolve_finding") {
+				// Structural only. Which findings may be resolved, and when, stays
+				// the reducer's decision; duplicating it here would create a second
+				// authority that could drift from the Kernel.
+				if (typeof args.finding_id !== "string" || !args.finding_id) throw new Error("finding_id is required");
+				return runtime.resolveFinding(taskId, args.finding_id);
+			}
 			if (name === "request_authorization" || name === "approve_breaking_intent_revision" || name === "stop" || name === "repair_authority_state") {
 				return runtime.authorize(taskId, name, toolMeta, args);
 			}

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

@@ -248,19 +248,6 @@ function runInspect(root: string): KernelExecution {
 				),
 			};
 		}
-		let declared: TaskRisk;
-		let intent: TaskIntentV1;
-		try {
-			const raw = JSON.parse(
-				readSecureProjectFile(root, `docs/plans/${claim.task_id}.intent.json`),
-			) as { risk?: unknown };
-			if (raw.risk !== "routine" && raw.risk !== "material" && raw.risk !== "critical")
-				throw new Error(`intent.risk is unreadable for ${claim.task_id}`);
-			declared = raw.risk;
-			intent = parseTaskIntentV1(raw);
-		} catch (error) {
-			return sourceFailure("inspect", error);
-		}
 		let recordRead: ReturnType<typeof readTaskRecordRaw>;
 		try {
 			recordRead = readTaskRecordRaw(root, claim.task_id);
@@ -285,6 +272,21 @@ function runInspect(root: string): KernelExecution {
 			};
 		}
 		const record = recordRead.record;
+		let declared: TaskRisk;
+		let intent: TaskIntentV1;
+		try {
+			const raw = JSON.parse(
+				readSecureProjectFile(root, record.intent_ref.path),
+			) as { risk?: unknown };
+			if (raw.risk !== "routine" && raw.risk !== "material" && raw.risk !== "critical")
+				throw new Error(`intent.risk is unreadable for ${claim.task_id}`);
+			declared = raw.risk;
+			intent = parseTaskIntentV1(raw);
+			if (canonicalIntentHash(intent) !== record.intent_ref.content_hash)
+				throw new Error("TaskIntent sidecar does not match TaskRecord content hash");
+		} catch (error) {
+			return sourceFailure("inspect", error);
+		}
 		const workspaceState = readWorkspaceStateRaw(root);
 		let identity;
 		try {

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

@@ -57,6 +57,7 @@ export interface InitiativePublicationInput {
 	tasks: Array<{
 		slice_id: string;
 		intent: string;
+		acceptance: Array<{ id: string; summary: string }>;
 		projection?: TaskProjection;
 	}>;
 }
@@ -85,6 +86,18 @@ export interface GithubInitiativePublicationResult {
 	message: string;
 }
 
+export interface GithubInitiativeObservation {
+	contract: "immune_brain/github_initiative_observation/v1";
+	initiative_id: string;
+	issue_number: number;
+	tasks: Array<{
+		task_id: string;
+		slice_id: string;
+		issue_number: number;
+		blocked_by: string[];
+	}>;
+}
+
 export interface TaskProjection {
 	result?: string;
 	current_behavior?: string;
@@ -552,6 +565,63 @@ async function readBlockedByIds(
 	}
 }
 
+export async function observeGithubInitiative(
+	root: string,
+	initiativeId: string,
+	gh: GhTransport = createGhTransport(),
+): Promise<GithubInitiativeObservation> {
+	const id = identifier(initiativeId, "initiative_id");
+	const source = await snapshot(resolve(root), gh, "create-initiative");
+	if ("contract" in source) throw new Error(source.message);
+	const parent = initiativeLookup(source.issues, source.repository.id, id);
+	if (parent.kind === "missing") throw new Error(`Initiative ${id} is not published`);
+	if (parent.kind === "ambiguous") throw new Error(parent.message);
+	const subIssueNumbers = await readSubIssueNumbers(root, gh, "create-initiative", source.repository, parent.issue.number);
+	if (!Array.isArray(subIssueNumbers)) throw new Error(subIssueNumbers.message);
+	if (new Set(subIssueNumbers).size !== subIssueNumbers.length)
+		throw new Error(`Initiative ${id} has duplicate native Sub-issue relations`);
+	const tasks = subIssueNumbers.map((issueNumber) => {
+		const matches = source.issues.filter((issue) => issue.number === issueNumber);
+		if (matches.length !== 1) throw new Error(`Initiative ${id} references an unreadable Sub-issue #${issueNumber}`);
+		const issue = matches[0];
+		const taskId = ownershipMarkerValue(issue.body, "task-id");
+		const sliceId = ownershipMarkerValue(issue.body, "slice-id");
+		if (!taskId || !sliceId || ownershipMarkerValue(issue.body, "initiative-id") !== id)
+			throw new Error(`Sub-issue #${issueNumber} has invalid Initiative ownership markers`);
+		const owned = ownedTaskLookup(source.issues, source.repository.id, taskId, id, sliceId);
+		if (owned.kind !== "found" || owned.issue.number !== issueNumber)
+			throw new Error(owned.kind === "ambiguous" ? owned.message : `Sub-issue #${issueNumber} has invalid Task ownership`);
+		return { task_id: taskId, slice_id: sliceId, issue_number: issueNumber, issue_id: issue.id };
+	});
+	if (new Set(tasks.map((task) => task.task_id)).size !== tasks.length)
+		throw new Error(`Initiative ${id} has duplicate Task identities`);
+	if (new Set(tasks.map((task) => task.slice_id)).size !== tasks.length)
+		throw new Error(`Initiative ${id} has duplicate Slice identities`);
+	const taskByIssueId = new Map(tasks.map((task) => [task.issue_id, task.task_id]));
+	const observed: GithubInitiativeObservation["tasks"] = [];
+	for (const task of tasks.sort((left, right) => left.task_id < right.task_id ? -1 : left.task_id > right.task_id ? 1 : 0)) {
+		const blockerIds = await readBlockedByIds(root, gh, "create-initiative", source.repository, task.issue_number);
+		if (!Array.isArray(blockerIds)) throw new Error(blockerIds.message);
+		const blockedBy = blockerIds.map((blockerId) => {
+			const blocker = taskByIssueId.get(blockerId);
+			if (!blocker) throw new Error(`Task ${task.task_id} depends on an Issue outside Initiative ${id}`);
+			return blocker;
+		}).sort();
+		observed.push({
+			task_id: task.task_id,
+			slice_id: task.slice_id,
+			issue_number: task.issue_number,
+			blocked_by: blockedBy,
+		});
+	}
+	return {
+		contract: "immune_brain/github_initiative_observation/v1",
+		initiative_id: id,
+		issue_number: parent.issue.number,
+		tasks: observed,
+	};
+}
+
 async function confirmBlockedBy(
 	root: string,
 	gh: GhTransport,
@@ -1070,7 +1140,7 @@ function preflightPublication(root: string, input: InitiativePublicationInput):
 	const publications = input.tasks.map((task, index) => {
 		if (!task || typeof task !== "object" || Array.isArray(task)) throw new Error(`tasks[${index}] must be an object`);
 		if (typeof task.intent !== "string") throw new Error(`tasks[${index}].intent must be a string`);
-		return taskPublication(root, input.initiative_id, task.slice_id, task.intent, task.projection);
+		return taskPublication(root, input.initiative_id, task.slice_id, task.intent, task.acceptance, task.projection);
 	});
 	const operations = publications.map((publication) => publication.operation);
 	const taskIds = new Set<string>();
@@ -1264,7 +1334,14 @@ function isSuccessfulTrackerStatus(status: TrackerStatus): boolean {
 	return status === "created" || status === "updated" || status === "already_current";
 }
 
-function taskPublication(root: string, initiativeId: string, sliceId: string, intentPath: string, projection?: TaskProjection): PreparedPublicationTask {
+function taskPublication(
+	root: string,
+	initiativeId: string,
+	sliceId: string,
+	intentPath: string,
+	acceptance: unknown,
+	projection?: TaskProjection,
+): PreparedPublicationTask {
 	const absoluteRoot = resolve(root);
 	const absolutePath = resolve(absoluteRoot, intentPath);
 	const rel = relative(absoluteRoot, absolutePath);
@@ -1275,6 +1352,20 @@ function taskPublication(root: string, initiativeId: string, sliceId: string, in
 	const read = readTaskIntent(absoluteRoot, taskId);
 	if (read.intent_ref.path !== rel) throw new Error("TaskIntent path must match its canonical sidecar path");
 	const intent = read.intent;
+	if (!Array.isArray(acceptance)) throw new Error(`Task ${taskId} requires public acceptance summaries`);
+	const expectedIds = new Set(intent.acceptance.map((item) => item.id));
+	const publicById = new Map<string, { id: string; summary: string }>();
+	acceptance.forEach((item, index) => {
+		if (!item || typeof item !== "object" || Array.isArray(item))
+			throw new Error(`Task ${taskId} acceptance[${index}] must be an object`);
+		const raw = item as Record<string, unknown>;
+		const id = identifier(raw.id, `Task ${taskId} acceptance[${index}].id`);
+		if (!expectedIds.has(id)) throw new Error(`Task ${taskId} has unknown public acceptance id: ${id}`);
+		if (publicById.has(id)) throw new Error(`Task ${taskId} has duplicate public acceptance id: ${id}`);
+		publicById.set(id, { id, summary: projectionText(raw.summary, `Task ${taskId} acceptance[${index}].summary`, 500) });
+	});
+	const missingIds = [...expectedIds].filter((id) => !publicById.has(id));
+	if (missingIds.length) throw new Error(`Task ${taskId} is missing public acceptance ids: ${missingIds.join(", ")}`);
 	return {
 		operation: validateOperation({
 			op: "upsert-task",
@@ -1283,7 +1374,7 @@ function taskPublication(root: string, initiativeId: string, sliceId: string, in
 			slice_id: sliceId,
 			goal: intent.goal,
 			risk: intent.risk,
-			acceptance: intent.acceptance.map((item) => ({ id: item.id, summary: item.assertion })),
+			acceptance: intent.acceptance.map((item) => publicById.get(item.id)!),
 			projection,
 		}) as Extract<TrackerOperation, { op: "upsert-task" }>,
 		intent_path: read.intent_ref.path,

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

@@ -160,6 +160,7 @@ export function applyTaskAction(
 			action.type === "record_approval" ||
 			action.type === "approve_breaking_intent_revision" ||
 			action.type === "request_rework" ||
+			action.type === "authorize_rework" ||
 			action.type === "stop" ||
 			action.type === "resolve_user_decision";
 

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

@@ -25,9 +25,10 @@ export interface AssuranceAuthorizationReadiness {
 	/**
 	 * Kernel-decidable authorization readiness:
 	 * - "resolve_user_decision": exactly one open unresolved-user-decision finding;
+	 * - "authorize_rework": an open replan boundary can be overridden by the user;
 	 * - "none": nothing uniquely decidable from Kernel facts.
 	 */
-	state: "resolve_user_decision" | "none";
+	state: "resolve_user_decision" | "authorize_rework" | "none";
 	/** Non-null only when Kernel facts prove the authorization is blocked. */
 	blocked: string | null;
 }
@@ -75,6 +76,8 @@ export function deriveAssuranceAuthorization(input: {
 			state: "none",
 			blocked: `resolve-user-decision requires exactly one open user decision; found ${input.open_user_decision_count}`,
 		};
+	if (input.next_obligation === "revise_intent")
+		return { state: "authorize_rework", blocked: null };
 	return { state: "none", blocked: null };
 }