immune-brain 5.1.1 → 5.2.0

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/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/plugin_version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/plugin_versioning.ts from the root package.json.
-export const PLUGIN_VERSION = "5.1.1" as const;
+export const PLUGIN_VERSION = "5.2.0" as const;

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

@@ -26,6 +26,11 @@ material task-local maintenance risks. Pure naming, length, complexity
 thresholds, formatting, and design preference are not findings and must not
 cause style-only rework.
 
+Test-suite growth is advisory, never blocking: note a delivered test that
+duplicates an existing assertion, asserts only private implementation, or
+leaves a test protecting behavior the change retired. Weakened or missing
+tests for an acceptance remain blocking under the rules above.
+
 When a finding repeats an acceptance id or anchor that already produced rework in
 this task, do not file it as a fresh single-trigger defect. Name the invariant
 class it belongs to and state in `evidence.trigger` why the previously accepted
@@ -34,6 +39,13 @@ about the fix's scope, not a new bug. A trigger the accepted contract explicitly
 excludes is reported as an advisory note against that boundary, never as blocking
 rework.
 
+A defect that lies inside the TaskIntent goal and `scope_hint` is a blocking
+finding even when no acceptance assertion names its exact case word for word:
+cite the acceptance whose principle it violates as `acceptance_id` and
+`violated.ref`. Ask for the fix and a test that pins the case, never for the case
+to be written into the acceptance text; a missing literal clause is not itself a
+finding and does not call for an Intent revision.
+
 ## Invariant and Evidence Coverage
 
 Judge whether the change actually closes the invariant its acceptance names,
@@ -53,6 +65,14 @@ seam, or a seam silently replaced by a different one, is a finding carrying
 named, its absence is not a finding: candidates written before this rule carries
 no defect for lacking one.
 
+When the Spec referenced by an acceptance maps an `automated` user scenario to
+it, check that the delivered tests at that acceptance's agreed seam assert the
+scenario's `Then`: a scenario whose observable result is asserted nowhere is a
+finding carrying `violated.kind` of `acceptance` with `ref` the acceptance id.
+A `manual` scenario, and an acceptance with no mapped scenario, produce no such
+finding. This adds no finding kind and no verdict branch: it is the same
+`acceptance` finding the seam rule above already defines.
+
 Before pass, enumerate the immutable change set and read each complete per-file
 diff, including deletions. Page bounded reads until every hunk is visible; a
 truncated aggregate output or summary is incomplete coverage. Trace changed

package/plugins/immune-brain/runtime/prompts/executor.md

@@ -54,6 +54,13 @@ Record missing evidence as blocked and repair it before handoff. The Loop owns
 verdict submission, finding disposition and the second-rework generalize-or-refute
 rule.
 
+A finding whose defect lies inside the TaskIntent goal and `scope_hint` is
+ordinary rework even when no acceptance names its exact case: fix the code and
+add the test that pins the case. Do not propose an Intent revision for it, and
+never append a single input case to an acceptance assertion to close a finding;
+acceptance states principles, tests enumerate cases. Route to `imm-planner` only
+when the goal, the scope, or a user-visible commitment must change.
+
 ## Code Quality Guard
 
 Before handoff, check the implementation for real implementation rather than
@@ -61,6 +68,14 @@ 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.
+
+Keep the test suite lean. Each added test pins one acceptance invariant or
+finding case at its public seam; do not mirror private calls, mock order or
+internal return values that a public assertion already covers. Before adding a
+test, search existing tests for the same behavior and extend or parameterize
+them instead of duplicating setup. When the change retires or replaces a
+behavior, update or delete the tests that protected it within scope and name
+the retired behavior or continuing owner in Delivery Evidence.
 Treat naming, function length, parameter count, nesting, and abstraction taste
 as contextual signals, never as automatic failure thresholds.