immune-brain 5.1.0 → 5.1.2

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

@@ -8,6 +8,8 @@ const PROTOCOL_MARKER = "<!-- immune-brain-tracker:v1 -->";
 const KIND_INITIATIVE_MARKER = "<!-- immune-brain:kind=initiative -->";
 const KIND_TASK_MARKER = "<!-- immune-brain:kind=task -->";
 const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Public scenario identity: an upstream Brainstorm id or a Spec-local id. */
+const SCENARIO_ID_PATTERN = /^(?:BR-SCN|SCN)-[1-9][0-9]{0,8}$/;
 const MAX_GH_OUTPUT = 8 * 1024 * 1024;
 const MAX_DIAGNOSTIC = 512;
 const GH_TIMEOUT_MS = 20_000;
@@ -62,6 +64,23 @@ export interface InitiativeProjection {
 	out_of_scope?: string[];
 }
 
+/**
+ * One user scenario projected onto the Task that first makes it observable.
+ * Public projection only: it never widens TaskIntent scope or authority.
+ */
+export interface InitiativeTaskScenario {
+	id: string;
+	actor: string;
+	given: string;
+	when: string;
+	then: string;
+	mode: "automated" | "manual";
+	/** Canonical acceptance IDs this scenario maps to. Required for automated; optional for manual. */
+	acceptance?: string[];
+	/** Why a deterministic check cannot prove this scenario. Required for manual. */
+	manual_reason?: string;
+}
+
 export interface InitiativePublicationInput {
 	initiative_id: string;
 	goal: string;
@@ -71,6 +90,8 @@ export interface InitiativePublicationInput {
 		intent: string;
 		acceptance: Array<{ id: string; summary: string }>;
 		projection?: TaskProjection;
+		/** Optional. Omitted or empty renders no User scenarios section for this Task. */
+		scenarios?: InitiativeTaskScenario[];
 	}>;
 	/**
 	 * Explicit amendment input: binds the caller's desired pending frontier to
@@ -179,6 +200,15 @@ export type TrackerOperation =
 		goal: string;
 		slices: InitiativeSlice[];
 		projection?: InitiativeProjection;
+		/** Derived Parent listing. Absent or empty renders no User scenarios section. */
+		scenarios?: Array<{
+			slice_id: string;
+			id: string;
+			mode: "automated" | "manual";
+			when: string;
+			then: string;
+			manual_reason?: string;
+		}>;
 	}
 	| {
 		op: "upsert-task";
@@ -191,6 +221,8 @@ export type TrackerOperation =
 		projection?: TaskProjection;
 		/** The canonical TaskIntent content hash this Task was prepared from. */
 		intent_hash?: string;
+		/** Public scenarios owned by this Task. Absent renders no User scenarios section. */
+		scenarios?: InitiativeTaskScenario[];
 	}
 	| {
 		op: "mark-terminal";
@@ -270,7 +302,7 @@ function countLiteral(value: string, needle: string): number {
 	return count;
 }
 
-function marker(name: "repo-id" | "initiative-id" | "task-id" | "slice-id" | "intent-hash", value: string | number): string {
+function marker(name: "repo-id" | "initiative-id" | "task-id" | "slice-id" | "intent-hash" | "scenarios", value: string | number): string {
 	return `<!-- immune-brain:${name}=${value} -->`;
 }
 
@@ -730,8 +762,9 @@ function stripPublishedIntentHash(body: string): string {
 	return body.replace(/<!-- immune-brain:intent-hash=[A-Za-z0-9][A-Za-z0-9._:-]{0,127} -->\n?/g, "");
 }
 
-function ownershipMarkerValue(body: string, name: "initiative-id" | "slice-id" | "task-id"): string | null {
-	const values = [...body.matchAll(new RegExp(`<!-- immune-brain:${name}=([A-Za-z0-9][A-Za-z0-9._-]{0,127}) -->`, "g"))];
+function ownershipMarkerValue(body: string, name: "initiative-id" | "slice-id" | "task-id" | "scenarios"): string | null {
+	const pattern = name === "scenarios" ? "[A-Za-z0-9%_!*'()~.-]+" : "[A-Za-z0-9][A-Za-z0-9._-]{0,127}";
+	const values = [...body.matchAll(new RegExp(`<!-- immune-brain:${name}=(${pattern}) -->`, "g"))];
 	return values.length === 1 ? values[0][1] : null;
 }
 
@@ -953,6 +986,160 @@ function listText(values: string[] | undefined, fallback: string): string {
 	return values?.length ? values.map((value) => `- ${value}`).join("\n") : fallback;
 }
 
+/**
+ * Child section after Acceptance criteria. Empty input returns "" so a Task
+ * without scenarios, and a publication with none at all, stays byte-identical.
+ */
+function childScenarioSection(scenarios: InitiativeTaskScenario[] | undefined): string {
+	if (!scenarios?.length) return "";
+	const items = scenarios.map((scenario) => {
+		const mapped = scenario.acceptance?.length ? scenario.acceptance.map((id) => `\`${id}\``).join(", ") : "none";
+		const visible = `Actor: ${scenario.actor}. Given: ${scenario.given}. When: ${scenario.when}. Then: ${scenario.then}.`;
+		if (scenario.mode === "manual")
+			return `- [ ] \`${scenario.id}\` (manual, ${mapped}): ${visible} Reason: ${scenario.manual_reason}.`;
+		return `- \`${scenario.id}\` (automated, ${mapped}): ${visible}`;
+	});
+	return `\n## User scenarios\n\n${items.join("\n")}\n`;
+}
+
+/**
+ * Parent listing after Testing strategy, derived from the Tasks. One plain
+ * bullet per scenario; no checkboxes. Empty input returns "".
+ */
+function parentScenarioSection(scenarios: Array<{ slice_id: string; id: string; mode: "automated" | "manual"; actor?: string; given?: string; when: string; then: string; manual_reason?: string }> | undefined): string {
+	if (!scenarios?.length) return "";
+	const items = scenarios.map((scenario) => {
+		const prefix = scenario.actor && scenario.given ? `Actor: ${scenario.actor}. Given: ${scenario.given}. ` : "";
+		const reason = scenario.manual_reason ? ` Reason: ${scenario.manual_reason}.` : "";
+		return `- \`${scenario.id}\` (Slice \`${scenario.slice_id}\`, ${scenario.mode}): ${prefix}When: ${scenario.when}. Then: ${scenario.then}.${reason}`;
+	});
+	return `\n## User scenarios\n\n${items.join("\n")}\n`;
+}
+
+
+type HistoricalScenarioListing = InitiativeTaskScenario & { slice_id: string };
+
+/**
+ * Read the Parent listings already published by historical Children. Their
+ * Child bytes stay untouched, but an amendment must keep those listings and
+ * reserve their IDs before it rebuilds the Parent or accepts pending input.
+ */
+function historicalScenarioListings(children: Iterable<{ body?: unknown }>): HistoricalScenarioListing[] | string {
+	const listings: HistoricalScenarioListing[] = [];
+	for (const child of children) {
+		if (typeof child.body !== "string") continue;
+		const sliceId = ownershipMarkerValue(child.body, "slice-id");
+		if (!sliceId) continue;
+		const markerStarts = [...child.body.matchAll(/<!-- immune-brain:scenarios=/g)].length;
+		if (markerStarts > 1) return `historical Slice ${sliceId} has duplicate scenarios markers`;
+		const encoded = ownershipMarkerValue(child.body, "scenarios");
+		if (encoded === null) {
+			if (markerStarts === 0) continue;
+			return `historical Slice ${sliceId} has a malformed scenarios marker`;
+		}
+		const malformed = `historical Slice ${sliceId} has a malformed scenarios marker`;
+		let decoded: unknown;
+		try { decoded = JSON.parse(decodeURIComponent(encoded)); }
+		catch { return malformed; }
+		let scenarios: InitiativeTaskScenario[] | undefined;
+		try { scenarios = normalizeTaskScenarios(decoded, `historical Slice ${sliceId}`, undefined, new Set()); }
+		catch { return malformed; }
+		// The marker is the only source of historical scenarios, so it must hold
+		// exactly what the publish path writes for these values: the same
+		// validator, re-encoded byte for byte. Anything else is an unamendable
+		// Child, and the batch is rejected before any remote write.
+		if (scenarios === undefined || encodeURIComponent(JSON.stringify(scenarios)) !== encoded) return malformed;
+		for (const scenario of scenarios) listings.push({ ...scenario, slice_id: sliceId });
+	}
+	return listings;
+}
+
+function retainHistoricalScenarioIds(children: Iterable<{ body?: unknown }>, seenScenarioIds = new Set<string>()): string | null {
+	const listings = historicalScenarioListings(children);
+	if (typeof listings === "string") return listings;
+	for (const listing of listings) {
+		if (seenScenarioIds.has(listing.id)) return `historical Slice ${listing.slice_id} repeats scenario id ${listing.id}`;
+		seenScenarioIds.add(listing.id);
+	}
+	return null;
+}
+
+/**
+ * Reject the whole batch, before any remote write, when a scenario is malformed
+ * or names an acceptance ID its TaskIntent lacks. Text uses the same public
+ * projection rules as every other projected field. When `acceptanceIds` is
+ * omitted the TaskIntent-bound existence check is skipped, which is what the
+ * historical read-back needs: a published marker already passed it once.
+ */
+function normalizeTaskScenarios(
+	value: unknown,
+	taskId: string,
+	acceptanceIds: Set<string> | undefined,
+	seenScenarioIds: Set<string>,
+): InitiativeTaskScenario[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) throw new Error(`Task ${taskId} scenarios must be an array`);
+	if (value.length === 0) return undefined;
+	return value.map((item, index) => {
+		const name = `Task ${taskId} scenarios[${index}]`;
+		if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error(`${name} must be an object`);
+		const raw = item as Record<string, unknown>;
+		const required = ["id", "actor", "given", "when", "then", "mode"] as const;
+		for (const field of required) {
+			if (raw[field] === undefined) throw new Error(`${name} is missing ${field}`);
+		}
+		const id = typeof raw.id === "string" && SCENARIO_ID_PATTERN.test(raw.id) ? raw.id : null;
+		if (!id) throw new Error(`${name} id must match BR-SCN-<n> or SCN-<n>`);
+		if (seenScenarioIds.has(id)) throw new Error(`Task ${taskId} repeats scenario id ${id}`);
+		seenScenarioIds.add(id);
+		if (raw.mode !== "automated" && raw.mode !== "manual")
+			throw new Error(`${name} mode must be automated or manual`);
+		const acceptance = raw.acceptance === undefined
+			? undefined
+			: normalizedList(raw.acceptance, `${name}.acceptance`, 128)?.map((acceptanceId) => identifier(acceptanceId, `${name}.acceptance`));
+		if (acceptance && new Set(acceptance).size !== acceptance.length)
+			throw new Error(`${name} repeats an acceptance id`);
+		for (const acceptanceId of acceptance ?? []) {
+			if (acceptanceIds && !acceptanceIds.has(acceptanceId))
+				throw new Error(`Task ${taskId} scenario ${id} names unknown acceptance id ${acceptanceId}`);
+		}
+		if (raw.mode === "automated" && !acceptance?.length)
+			throw new Error(`Task ${taskId} scenario ${id} is automated with no acceptance id`);
+		if (raw.mode === "manual" && raw.manual_reason === undefined)
+			throw new Error(`Task ${taskId} scenario ${id} is manual without manual_reason`);
+		const scenario: InitiativeTaskScenario = {
+			id,
+			actor: projectionText(raw.actor, `${name}.actor`, 500),
+			given: projectionText(raw.given, `${name}.given`, 500),
+			when: projectionText(raw.when, `${name}.when`, 500),
+			then: projectionText(raw.then, `${name}.then`, 500),
+			mode: raw.mode,
+			...(acceptance ? { acceptance } : {}),
+			...(raw.manual_reason === undefined ? {} : { manual_reason: projectionText(raw.manual_reason, `${name}.manual_reason`, 500) }),
+		};
+		// The historical read-back re-applies these rules to the stored values, so
+		// each one must survive its own projection a second time. Escaping can grow
+		// a value past its bound and a restricted-context acceptance ID passes the
+		// pending path; either would make a published Child unamendable.
+		const roundTrip: Array<[string, string]> = [
+			["actor", scenario.actor],
+			["given", scenario.given],
+			["when", scenario.when],
+			["then", scenario.then],
+			...(scenario.manual_reason === undefined ? [] : [["manual_reason", scenario.manual_reason] as [string, string]]),
+		];
+		for (const [label, value] of roundTrip) {
+			if (projectionText(value, `${name}.${label}`, 500) !== value)
+				throw new Error(`${name}.${label} fails the public-projection round-trip`);
+		}
+		for (const acceptanceId of acceptance ?? []) {
+			if (projectionText(acceptanceId, `${name}.acceptance`, 128) !== acceptanceId || identifier(acceptanceId, `${name}.acceptance`) !== acceptanceId)
+				throw new Error(`${name}.acceptance fails the public-projection round-trip`);
+		}
+		return scenario;
+	});
+}
+
 function bodyLimitFailure(operation: TrackerOperation["op"], body: string, reserve = 0): GithubTrackerResult | null {
 	return Buffer.byteLength(body, "utf8") + reserve <= GITHUB_ISSUE_BODY_LIMIT
 		? null
@@ -973,7 +1160,7 @@ function createInitiativeBody(
 		KIND_INITIATIVE_MARKER,
 		marker("repo-id", repository.id),
 		marker("initiative-id", operation.initiative_id),
-	].join("\n")}\n\n${provenance}## How to use this Issue\n\n- Edit planning prose and Slice ordering directly after creation.\n- Keep each Slice marker attached to exactly one stable Slice entry.\n- The tracker never rewrites this Parent after creation; the tracker closes it as completed once every Slice Child is completed, and never closes it otherwise.\n\n## Problem\n\n${publicText(projection.problem ?? "The Initiative addresses the bounded delivery described below.", "projection.problem")}\n\n## Result\n\n${publicText(projection.result ?? operation.goal, "projection.result")}\n\n## Initiative design\n\n${publicText(projection.design ?? "Each Child preserves the shared Initiative decisions and boundaries recorded here.", "projection.design")}\n\n## Decisions\n\n${listText(projection.decisions, "- No additional Initiative decisions recorded.")}\n\n## Testing strategy\n\n${publicText(projection.testing_strategy ?? "Each Child closes from its focused acceptance verification.", "projection.testing_strategy")}\n\n## Out of scope\n\n${listText(projection.out_of_scope, "- Unrelated work outside this Initiative.")}\n\n## Slices\n\n${operation.slices.length + historicalSlices.length === 0 ? "No Slices recorded yet." : [...historicalSlices, ...operation.slices.map((slice) => `- [ ] ${marker("slice-id", slice.id)} **${slice.id}**: ${slice.result ?? slice.goal}${slice.blocked_by?.length ? ` (blocked by: ${slice.blocked_by.join(", ")})` : ""}`)].join("\n")}\n\n${ISSUE_FOOTER}\n`;
+	].join("\n")}\n\n${provenance}## How to use this Issue\n\n- Edit planning prose and Slice ordering directly after creation.\n- Keep each Slice marker attached to exactly one stable Slice entry.\n- The tracker never rewrites this Parent after creation; the tracker closes it as completed once every Slice Child is completed, and never closes it otherwise.\n\n## Problem\n\n${publicText(projection.problem ?? "The Initiative addresses the bounded delivery described below.", "projection.problem")}\n\n## Result\n\n${publicText(projection.result ?? operation.goal, "projection.result")}\n\n## Initiative design\n\n${publicText(projection.design ?? "Each Child preserves the shared Initiative decisions and boundaries recorded here.", "projection.design")}\n\n## Decisions\n\n${listText(projection.decisions, "- No additional Initiative decisions recorded.")}\n\n## Testing strategy\n\n${publicText(projection.testing_strategy ?? "Each Child closes from its focused acceptance verification.", "projection.testing_strategy")}\n${parentScenarioSection(operation.scenarios)}\n## Out of scope\n\n${listText(projection.out_of_scope, "- Unrelated work outside this Initiative.")}\n\n## Slices\n\n${operation.slices.length + historicalSlices.length === 0 ? "No Slices recorded yet." : [...historicalSlices, ...operation.slices.map((slice) => `- [ ] ${marker("slice-id", slice.id)} **${slice.id}**: ${slice.result ?? slice.goal}${slice.blocked_by?.length ? ` (blocked by: ${slice.blocked_by.join(", ")})` : ""}`)].join("\n")}\n\n${ISSUE_FOOTER}\n`;
 }
 
 async function createInitiative(
@@ -1056,7 +1243,8 @@ function childBody(
 		// idempotent replay can compare against what was actually published
 		// instead of against whatever bytes it happens to read this time.
 		...(operation.intent_hash ? [marker("intent-hash", operation.intent_hash)] : []),
-	].join("\n")}\n\n## Parent\n\n| Initiative | \`${operation.initiative_id}\` |\n| Parent Issue | [#${parent.number}](${parent.url}) |\n| Slice | \`${operation.slice_id}\` |\n| Risk | \`${operation.risk}\` |\n\n## Current behavior\n\n${publicText(projection.current_behavior ?? "The current behavior is defined by the repository's existing contract.", "projection.current_behavior")}\n\n## Desired behavior\n\n${publicText(projection.desired_behavior ?? projection.result ?? operation.goal, "projection.desired_behavior")}\n\n## Key interfaces\n\n${listText(projection.key_interfaces, "- Canonical TaskIntent acceptance and Kernel lifecycle remain authoritative.")}\n\n## Acceptance criteria\n\n${acceptance}\n\n## Verification\n\n${publicText(projection.verification ?? "Run the focused acceptance verification declared by the TaskIntent.", "projection.verification")}\n\n## Blocked by\n\n${projection.blocked_by?.length ? projection.blocked_by.map((id) => `- \`${identifier(id, "blocked_by task_id")}\``).join("\n") : "None"}\n\n## Out of scope\n\n${listText(projection.out_of_scope, "- Scope not declared by the validated TaskIntent.")}\n\n## Agent handoff\n\n${publicText(projection.agent_handoff ?? "Implement only the bounded TaskIntent result and run the focused checks. Do not widen scope or treat GitHub as authorization.", "projection.agent_handoff")}\n\n${ISSUE_FOOTER}\n`;
+		...(operation.scenarios?.length ? [marker("scenarios", encodeURIComponent(JSON.stringify(operation.scenarios)))] : []),
+	].join("\n")}\n\n## Parent\n\n| Initiative | \`${operation.initiative_id}\` |\n| Parent Issue | [#${parent.number}](${parent.url}) |\n| Slice | \`${operation.slice_id}\` |\n| Risk | \`${operation.risk}\` |\n\n## Current behavior\n\n${publicText(projection.current_behavior ?? "The current behavior is defined by the repository's existing contract.", "projection.current_behavior")}\n\n## Desired behavior\n\n${publicText(projection.desired_behavior ?? projection.result ?? operation.goal, "projection.desired_behavior")}\n\n## Key interfaces\n\n${listText(projection.key_interfaces, "- Canonical TaskIntent acceptance and Kernel lifecycle remain authoritative.")}\n\n## Acceptance criteria\n\n${acceptance}\n${childScenarioSection(operation.scenarios)}\n## Verification\n\n${publicText(projection.verification ?? "Run the focused acceptance verification declared by the TaskIntent.", "projection.verification")}\n\n## Blocked by\n\n${projection.blocked_by?.length ? projection.blocked_by.map((id) => `- \`${identifier(id, "blocked_by task_id")}\``).join("\n") : "None"}\n\n## Out of scope\n\n${listText(projection.out_of_scope, "- Scope not declared by the validated TaskIntent.")}\n\n## Agent handoff\n\n${publicText(projection.agent_handoff ?? "Implement only the bounded TaskIntent result and run the focused checks. Do not widen scope or treat GitHub as authorization.", "projection.agent_handoff")}\n\n${ISSUE_FOOTER}\n`;
 }
 
 /** Derived approved-final content and baseline-derived historical evidence for an amendment. */
@@ -1094,6 +1282,26 @@ function approvedAmendmentContent(
 			blocked_by: operation.projection?.blocked_by,
 		})),
 	}) as Extract<TrackerOperation, { op: "create-initiative" }>;
+	const historicalScenarios = historicalScenarioListings([...amendment.historical.values()].map((binding) => ({ body: binding.body })));
+	if (typeof historicalScenarios === "string") return historicalScenarios;
+	parent.scenarios = [
+		...historicalScenarios.map((scenario) => ({
+			slice_id: scenario.slice_id,
+			id: scenario.id,
+			mode: scenario.mode,
+			when: scenario.when,
+			then: scenario.then,
+			...(typeof scenario.manual_reason === "string" ? { manual_reason: scenario.manual_reason } : {}),
+		})),
+		...prepared.order.flatMap((operation) =>
+			(operation.scenarios ?? []).map((scenario) => ({
+				slice_id: operation.slice_id,
+				id: scenario.id,
+				mode: scenario.mode,
+				when: scenario.when,
+				then: scenario.then,
+			}))),
+	];
 	const historicalSliceIds: Set<string> = new Set();
 	for (const child of amendment.historical.values()) {
 		const sliceId = ownershipMarkerValue(child.body, "slice-id");
@@ -1120,7 +1328,7 @@ function approvedAmendmentContent(
 	void sourceStub;
 	// The approved final Parent body fixes the Slices checklist, so every Child
 	// title is numbered from the Initiative order rather than from this batch.
-	const parentBody = createInitiativeBody(sourceStub.repository, parent, historicalSlices);
+	const parentBody = createInitiativeBody(sourceStub.repository, { ...parent, scenarios: parent.scenarios }, historicalSlices);
 	const oversizedParent = bodyLimitFailure("create-initiative", parentBody);
 	if (oversizedParent) return `${oversizedParent.status}: ${oversizedParent.message}`;
 	const pendingContent = new Map<string, { title: string; body: string }>();
@@ -1587,6 +1795,7 @@ function validateOperation(operation: TrackerOperation): TrackerOperation {
 				id: identifier(item.id, `acceptance[${index}].id`),
 				summary: projectionText(item.summary, `acceptance[${index}].summary`, 500),
 			})),
+			scenarios: operation.scenarios,
 		};
 		taskIssueTitle(normalized);
 		return normalized;
@@ -1727,10 +1936,16 @@ function preflightPublication(root: string, input: InitiativePublicationInput):
 	// projection is stamped with them, so a missing or oversized display name
 	// fails the batch closed with zero remote writes.
 	const initiativeShortName = initiativeDisplayNames(input.projection).shortName;
+	const seenScenarioIds = new Set<string>();
+	if (input.amendment) {
+		const historicalBindings = (input.amendment.historical ?? []).map((child) => (child as { binding?: { body?: unknown } }).binding ?? {});
+		const historicalScenarioError = retainHistoricalScenarioIds(historicalBindings, seenScenarioIds);
+		if (historicalScenarioError) throw new Error(historicalScenarioError);
+	}
 	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.acceptance, task.projection, index + 1, initiativeShortName);
+		return taskPublication(root, input.initiative_id, task.slice_id, task.intent, task.acceptance, task.projection, task.scenarios, index + 1, initiativeShortName, seenScenarioIds);
 	});
 	const historicalIds = new Set<string>();
 	if (input.amendment) {
@@ -1772,6 +1987,15 @@ function preflightPublication(root: string, input: InitiativePublicationInput):
 			blocked_by: operation.projection?.blocked_by,
 		})),
 	}) as Extract<TrackerOperation, { op: "create-initiative" }>;
+	initiative.scenarios = operations.flatMap((operation) =>
+		(operation.scenarios ?? []).map((scenario) => ({
+			slice_id: operation.slice_id,
+			id: scenario.id,
+			mode: scenario.mode,
+			when: scenario.when,
+			then: scenario.then,
+		})),
+	);
 	const intentBindings = new Map(publications.map((publication) => [publication.operation.task_id, {
 		intent_path: publication.intent_path,
 		intent_content_hash: publication.intent_content_hash,
@@ -2874,8 +3098,10 @@ function taskPublication(
 	intentPath: string,
 	acceptance: unknown,
 	projection: TaskProjection | undefined,
+	scenarios: unknown,
 	ordinal: number,
 	initiativeShortName: string,
+	seenScenarioIds: Set<string>,
 ): PreparedPublicationTask {
 	const absoluteRoot = resolve(root);
 	const absolutePath = resolve(absoluteRoot, intentPath);
@@ -2901,6 +3127,7 @@ function taskPublication(
 	});
 	const missingIds = [...expectedIds].filter((id) => !publicById.has(id));
 	if (missingIds.length) throw new Error(`Task ${taskId} is missing public acceptance ids: ${missingIds.join(", ")}`);
+	const normalizedScenarios = normalizeTaskScenarios(scenarios, taskId, expectedIds, seenScenarioIds);
 	// Display names are stamped from the Initiative so every Child title carries
 	// the same short name and its declared Slice position; an explicitly
 	// supplied value must agree, never silently override.
@@ -2924,6 +3151,7 @@ function taskPublication(
 			acceptance: intent.acceptance.map((item) => publicById.get(item.id)!),
 			projection: stampedProjection,
 			intent_hash: read.content_hash,
+			scenarios: normalizedScenarios,
 		}) as Extract<TrackerOperation, { op: "upsert-task" }>,
 		intent_path: read.intent_ref.path,
 		intent_content_hash: read.content_hash,

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

@@ -21,6 +21,7 @@ import {
 	reconcileKernelAuthority,
 } from "./storage";
 import { projectTask, resolveProjectedRisk } from "./completion";
+import { inspectSpecBinding } from "./spec_binding";
 import { taskDeliveryIdentity } from "../workspace_scope";
 import type { AssuranceObligation, TaskIntentV1, TaskRecord, TaskRecordV3 } from "./types";
 import type { TaskRecordV2 } from "./legacy_task_record";
@@ -236,7 +237,9 @@ function projectFromRecord(
 		independence_violations: decision.independence_violations,
 		open_user_decision_count: openUserDecisionCount,
 		completion_ready: decision.complete,
-		authorization: deriveAssuranceAuthorization({
+		authorization: !inspectSpecBinding(intent).ok
+			? { state: "none", blocked: "invalid Spec binding requires a valid breaking intent revision" }
+			: deriveAssuranceAuthorization({
 			next_obligation: decision.next_obligation,
 			open_user_decision_count: openUserDecisionCount,
 		}),

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

@@ -26,7 +26,7 @@ import {
 	type BackendClaim,
 } from "./backend_claim";
 import { canonicalIntentHash } from "./intent";
-import { boundSpecPath, readBoundActiveSpec } from "./spec_binding";
+import { assertValidSpecBinding, boundSpecPath, readBoundActiveSpec } from "./spec_binding";
 import { parseTaskRecord } from "./validation";
 import type { TaskIntentIdentityToken } from "./intent_token_registry";
 import {
@@ -208,6 +208,7 @@ export function createCanaryApplication(
 			const current = readTaskRecordRaw(input.root, input.task_id);
 			if (!current.record)
 				throw new KernelInvariantError([`task ${input.task_id} has no TaskRecord v3`]);
+			assertValidSpecBinding(current.record.intent_snapshot);
 			const workspace = readWorkspaceStateRaw(input.root);
 			if (current.record.artifact_state === "frozen")
 				return { revision: current.revision, record: current.record, workspace };
@@ -318,7 +319,13 @@ export function createCanaryApplication(
 		const diffHash = asTaskDiffSnapshot((input.diffProvider ?? taskDeliveryIdentity)(input.root, snapshot.record)).diff_hash;
 		if (operation.op === "stop" && !("capability" in operation))
 			throw new KernelInvariantError(["stop requires user authority capability"]);
-		const hasBoundSpec = boundSpecPath(snapshot.intent_snapshot) !== undefined;
+		// Only a capability-bound breaking revision may recover an invalid prior
+		// binding. Validate the replacement before any authority write.
+		if (operation.op === "approve_breaking_intent_revision") assertValidSpecBinding(operation.next_intent);
+		else assertValidSpecBinding(snapshot.intent_snapshot);
+		const hasBoundSpec = operation.op === "approve_breaking_intent_revision"
+			? boundSpecPath(operation.next_intent) !== undefined
+			: boundSpecPath(snapshot.intent_snapshot) !== undefined;
 		if (operation.op === "complete" && hasBoundSpec && snapshot.record.artifact_state !== "frozen")
 			throw new KernelInvariantError(["complete requires frozen planning artifacts"]);
 		const artifactTransition =

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

@@ -1,5 +1,5 @@
 import { classifyTaskRisk } from "./intent";
-import { archivePath, boundSpecPath } from "./spec_binding";
+import { archivePath, boundSpecPath, inspectSpecBinding } from "./spec_binding";
 import type {
 	ApprovalKind,
 	CompletionDecision,
@@ -49,6 +49,8 @@ export function resolveProjectedRisk(
 	intent: TaskIntentV1,
 	changedPaths: readonly string[] = [],
 ): TaskIntentV1["risk"] {
+	// Invalid bindings have no trusted planning-path exclusions.
+	if (!inspectSpecBinding(intent).ok) return classifyTaskRisk(changedPaths, intent.risk);
 	const excluded = ownSidecarPaths(intent);
 	return classifyTaskRisk(
 		changedPaths.filter((path) => !excluded.has(path)),
@@ -182,6 +184,27 @@ export function projectTask(
 	currentIntentContentHash: string,
 	changedPaths: readonly string[] = [],
 ): TaskProjectionV3 {
+	if (record.lifecycle === "active" && !inspectSpecBinding(intent).ok) {
+		assertKernelInvariantsV3(intent, record);
+		return {
+			contract: "assurance_kernel/projection/v3",
+			task_id: record.task_id,
+			intent_revision: intent.revision,
+			lifecycle: record.lifecycle,
+			artifact_state: record.artifact_state,
+			blocked: true,
+			next_obligation: "revise_intent",
+			complete: false,
+			fresh_acceptance_ids: [],
+			missing_acceptance_ids: intent.acceptance.map((item) => item.id),
+			stale_attestation_ids: record.attestations.map((item) => item.id),
+			missing_approval_kinds: REQUIRED_ATTESTATIONS[resolveProjectedRisk(intent, changedPaths)],
+			blocking_finding_ids: record.findings.filter((item) => item.kind === "blocking" && item.status !== "resolved").map((item) => item.id),
+			unresolved_user_decision_ids: record.findings.filter((item) => item.kind === "unresolved_user_decision" && item.status === "open").map((item) => item.id),
+			replan_required_ids: record.findings.filter((item) => item.kind === "replan_required" && item.status === "open").map((item) => item.id),
+			independence_violations: [],
+		};
+	}
 	const decision = completionDecision(
 		intent,
 		record,

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

@@ -23,6 +23,7 @@ import {
 	parseTaskRecord,
 } from "./validation";
 import { classifyIntentRevision, canonicalIntentHash } from "./intent";
+import { assertValidSpecBinding } from "./spec_binding";
 
 const RISK_RANK: Record<TaskIntentV1["risk"], number> = {
 	routine: 0,
@@ -431,15 +432,24 @@ export function reduceTask(
 			const reviewRevision = approval.review_revision;
 			if (reviewRevision && approval.kind !== "review")
 				throw new KernelInvariantError(["review_revision is only valid on review approvals"]);
+			if (approval.reviewer_verdict_sha256 && approval.kind !== "review")
+				throw new KernelInvariantError(["reviewer_verdict_sha256 is only valid on review approvals"]);
 			if (approval.kind === "review") {
 				if (!reviewRevision)
 					throw new KernelInvariantError(["v4 review approval requires review_revision"]);
 				if (reviewRevision.base_head !== record.git_base_head)
 					throw new KernelInvariantError(["review_revision.base_head must equal the Enrollment git_base_head"]);
 			}
-			const { review_revision: storedReviewRevision, ...approvalWithoutRevision } = approval;
+				// Re-emit the optional review-only fields in the strict parser's emission
+			// order so a written attestation stays byte-identical to its parse roundtrip.
+			const {
+				review_revision: storedReviewRevision,
+				advisory_findings: storedAdvisoryFindings,
+				reviewer_verdict_sha256: storedReviewerDigest,
+				...approvalWithoutExtras
+			} = approval;
 			record.attestations.push({
-				...approvalWithoutRevision,
+				...approvalWithoutExtras,
 				acceptance_results: approval.kind === "qa"
 					? record.intent_snapshot.acceptance.map((item) => ({
 						acceptance_id: item.id,
@@ -448,12 +458,15 @@ export function reduceTask(
 					}))
 					: [],
 				...(storedReviewRevision ? { review_revision: storedReviewRevision } : {}),
+				...(storedAdvisoryFindings ? { advisory_findings: storedAdvisoryFindings } : {}),
+				...(storedReviewerDigest ? { reviewer_verdict_sha256: storedReviewerDigest } : {}),
 			});
 			appendHistory(record, action, from, approval.id, authorityAudit);
 			break;
 		}
 		case "revise_intent":
 		case "approve_breaking_intent_revision": {
+			assertValidSpecBinding(action.next_intent);
 			if (record.lifecycle !== "active")
 				throw new KernelInvariantError([
 					`cannot revise intent while lifecycle is ${record.lifecycle}`,

package/plugins/immune-brain/runtime/kernel/runtime_contracts.json

@@ -0,0 +1,7 @@
+{
+  "contract": "immune_brain/runtime_contracts/v1",
+  "task_record": "assurance_kernel/task_record/v4",
+  "task_tombstone": "assurance_kernel/task_tombstone/v2",
+  "assurance_projection": "assurance_kernel/assurance_projection/v1",
+  "kernel_store_schema": 1
+}

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

@@ -0,0 +1,75 @@
+// The contract identifiers one runtime reads and writes in a worktree's
+// Authority Store. A lane-mode batch reads every Lane's Kernel state with the
+// coordinator's own runtime, so the coordinator and the runtime a Lane
+// Executor loads must agree on these identifiers; a plugin version number
+// proves nothing (two different builds can carry the same one).
+//
+// `runtime_contracts.json` is the same set as data, shipped next to this
+// module, so a coordinator can read another runtime's identifiers without
+// executing its code. A test keeps the two in step.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TASK_TOMBSTONE_CONTRACT } from "./backend_claim";
+import { KERNEL_STORE_SCHEMA_VERSION } from "./storage_paths";
+import { TASK_RECORD_CONTRACT_V4 } from "./types";
+
+export const RUNTIME_CONTRACTS_MANIFEST = "runtime_contracts.json";
+
+export interface RuntimeContracts {
+	contract: "immune_brain/runtime_contracts/v1";
+	task_record: string;
+	task_tombstone: string;
+	assurance_projection: string;
+	kernel_store_schema: number;
+}
+
+/** The identifiers this running runtime supports. */
+export const RUNTIME_CONTRACTS: RuntimeContracts = {
+	contract: "immune_brain/runtime_contracts/v1",
+	task_record: TASK_RECORD_CONTRACT_V4,
+	task_tombstone: TASK_TOMBSTONE_CONTRACT,
+	assurance_projection: "assurance_kernel/assurance_projection/v1",
+	kernel_store_schema: KERNEL_STORE_SCHEMA_VERSION,
+};
+
+const KEYS = ["task_record", "task_tombstone", "assurance_projection", "kernel_store_schema"] as const;
+
+/** Where this running runtime's code was loaded from, for a refusal that names both sides. */
+export function runningRuntimeSource(): string {
+	try {
+		return dirname(fileURLToPath(import.meta.url));
+	} catch {
+		return "unknown";
+	}
+}
+
+/**
+ * Read another runtime's identifiers from its manifest. `runtimeDir` is either
+ * the `runtime/kernel` directory or a plugin root that contains one. Null when
+ * no manifest exists there; a malformed manifest throws.
+ */
+export function readRuntimeContracts(runtimeDir: string): { contracts: RuntimeContracts; path: string } | null {
+	const candidates = [
+		join(runtimeDir, RUNTIME_CONTRACTS_MANIFEST),
+		join(runtimeDir, "kernel", RUNTIME_CONTRACTS_MANIFEST),
+		join(runtimeDir, "runtime", "kernel", RUNTIME_CONTRACTS_MANIFEST),
+		join(runtimeDir, "plugins", "immune-brain", "runtime", "kernel", RUNTIME_CONTRACTS_MANIFEST),
+	];
+	const path = candidates.find((candidate) => existsSync(candidate));
+	if (!path) return null;
+	const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+	if (raw.contract !== "immune_brain/runtime_contracts/v1")
+		throw new Error(`${path} is not an immune_brain/runtime_contracts/v1 manifest`);
+	for (const key of KEYS) {
+		const value = raw[key];
+		if (key === "kernel_store_schema" ? !Number.isSafeInteger(value) : typeof value !== "string" || !value)
+			throw new Error(`${path} has an invalid ${key}`);
+	}
+	return { contracts: raw as unknown as RuntimeContracts, path: resolve(path) };
+}
+
+/** The identifiers on which two runtimes disagree; empty when they can read each other's state. */
+export function runtimeContractDifferences(a: RuntimeContracts, b: RuntimeContracts): string[] {
+	return KEYS.filter((key) => a[key] !== b[key]).map((key) => `${key}: ${String(a[key])} != ${String(b[key])}`);
+}

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

@@ -57,6 +57,12 @@ export function readBoundActiveSpec(
 	}
 }
 
+/** Validate a candidate before it can replace enrolled authority. */
+export function assertValidSpecBinding(intent: TaskIntentV1): void {
+	const binding = inspectSpecBinding(intent);
+	if (!binding.ok) throw new KernelInvariantError([binding.message]);
+}
+
 export interface BoundSpec {
 	active: string;
 	archive: string;