@gajae-code/coding-agent 0.11.0 → 0.11.2

package/src/gjc-runtime/ultragoal-guard.ts

@@ -1,7 +1,11 @@
 import * as fs from "node:fs/promises";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import { resolveGjcSessionForRead, SessionResolutionError } from "./session-resolution";
-import { validateDeferredMemberReceiptFresh, validateReceiptFreshBase } from "./ultragoal-receipt-freshness";
+import {
+	validateDeferredMemberReceiptFresh,
+	validateReceiptFreshBase,
+	validateSupersededFinalAggregateReceipt,
+} from "./ultragoal-receipt-freshness";
 import {
 	getUltragoalPaths,
 	getUltragoalRunCompletionState,
@@ -49,10 +53,18 @@ export interface UltragoalAskBlockDiagnostic {
 export interface CurrentGoalLike {
 	objective: string;
 	status?: string;
+	provenance?: { source: "ultragoal"; runId: string; goalId: string } | { source: "user" };
 }
 
-function objectiveMatches(currentObjective: string, plan: UltragoalPlan): boolean {
-	const normalized = currentObjective.trim();
+function objectiveMatches(currentGoal: CurrentGoalLike, plan: UltragoalPlan, sessionId?: string | null): boolean {
+	const provenance = currentGoal.provenance;
+	if (provenance?.source === "ultragoal") {
+		return (
+			provenance.runId === sessionId &&
+			(provenance.goalId === "aggregate" || plan.goals.some(goal => goal.id === provenance.goalId))
+		);
+	}
+	const normalized = currentGoal.objective.trim();
 	if (!normalized) return false;
 	if (normalized === plan.gjcObjective || normalized === DEFAULT_ULTRAGOAL_OBJECTIVE) return true;
 	if (plan.gjcObjectiveAliases?.some(alias => alias === normalized)) return true;
@@ -156,8 +168,33 @@ function requiredGoals(plan: UltragoalPlan): UltragoalGoal[] {
 	return plan.goals.filter(goal => goal.status !== "superseded");
 }
 
+/**
+ * Select the goal whose final-aggregate receipt should represent the run.
+ * Prefer a receipt that still validates fresh; several goals can hold
+ * final-aggregate receipts once plan growth (e.g. `steer add_subgoal`) stales
+ * an earlier one and a later checkpoint re-mints. Fall back to the newest
+ * holder (array-last) purely for diagnostics when none validates.
+ */
+function findFinalAggregateReceiptGoal(
+	plan: UltragoalPlan,
+	ledger: readonly UltragoalLedgerEvent[],
+): UltragoalGoal | null {
+	const candidates = [...requiredGoals(plan)]
+		.reverse()
+		.filter(goal => goal.completionVerification?.receiptKind === "final-aggregate");
+	if (candidates.length === 0) return null;
+	return (
+		candidates.find(
+			goal =>
+				validateCompletionReceipt({ plan, ledger, goal, receiptKind: "final-aggregate" }).state ===
+				"active_verified_complete",
+		) ?? candidates[0]!
+	);
+}
+
 function findReceiptGoal(
 	plan: UltragoalPlan,
+	ledger: readonly UltragoalLedgerEvent[],
 	currentObjective: string,
 ): { goal: UltragoalGoal; receiptKind: UltragoalReceiptKind } | null {
 	if (
@@ -165,9 +202,7 @@ function findReceiptGoal(
 		currentObjective === DEFAULT_ULTRAGOAL_OBJECTIVE ||
 		plan.gjcObjectiveAliases?.some(alias => alias === currentObjective)
 	) {
-		const finalGoal = [...requiredGoals(plan)]
-			.reverse()
-			.find(goal => goal.completionVerification?.receiptKind === "final-aggregate");
+		const finalGoal = findFinalAggregateReceiptGoal(plan, ledger);
 		return finalGoal ? { goal: finalGoal, receiptKind: "final-aggregate" } : null;
 	}
 	const storyGoal = plan.goals.find(goal => goal.objective === currentObjective);
@@ -300,6 +335,28 @@ export function validateCompletionReceipt(input: {
 					goalId: input.goal.id,
 				};
 			}
+			if (
+				priorGoal.completionVerification.validationBatch?.role !== "deferred-member" &&
+				priorGoal.completionVerification.receiptKind === "final-aggregate"
+			) {
+				// A prior goal may hold the run's previous final-aggregate receipt
+				// when plan growth staled it and a later checkpoint re-minted the
+				// aggregate receipt. Accept it as historical evidence for its own
+				// goal instead of demanding an impossible per-goal receipt.
+				const supersededDiagnostic = validateSupersededFinalAggregateReceipt({
+					ledger: input.ledger,
+					goal: priorGoal,
+					receipt: priorGoal.completionVerification,
+				});
+				if (supersededDiagnostic) {
+					return {
+						state: supersededDiagnostic.state,
+						message: `Ultragoal final receipt requires valid historical evidence for ${priorGoal.id}: ${supersededDiagnostic.message}`,
+						goalId: input.goal.id,
+					};
+				}
+				continue;
+			}
 			const priorDiagnostic =
 				priorGoal.completionVerification.validationBatch?.role === "deferred-member"
 					? validateDeferredMemberReceiptFresh({
@@ -341,6 +398,8 @@ export async function readUltragoalVerificationState(input: {
 	currentGoal?: CurrentGoalLike | null;
 	sessionId?: string | null;
 }): Promise<UltragoalGuardDiagnostic> {
+	const currentGoal = input.currentGoal;
+
 	const currentObjective = input.currentGoal?.objective?.trim() ?? "";
 	if (!currentObjective) return { state: "inactive", message: "No current goal objective is active." };
 	let plan: UltragoalPlan | null;
@@ -366,7 +425,7 @@ export async function readUltragoalVerificationState(input: {
 		}
 		return { state: "inactive", message: "No Ultragoal plan exists." };
 	}
-	if (!objectiveMatches(currentObjective, plan))
+	if (!currentGoal || !objectiveMatches(currentGoal, plan, input.sessionId))
 		return { state: "unrelated_goal", message: "Current goal is not an active Ultragoal objective." };
 	if (plan.goals.some(goal => goal.status === "review_blocked")) {
 		return {
@@ -381,7 +440,21 @@ export async function readUltragoalVerificationState(input: {
 			message: "Ultragoal has blocked or failed goals; record blockers or rerun verification.",
 		};
 	}
-	const receiptTarget = findReceiptGoal(plan, currentObjective);
+	const provenance = currentGoal.provenance;
+
+	const receiptTarget =
+		provenance?.source === "ultragoal"
+			? provenance.goalId === "aggregate" || plan.gjcGoalMode === "aggregate"
+				? (() => {
+						const goal = findFinalAggregateReceiptGoal(plan, ledger);
+						return goal ? { goal, receiptKind: "final-aggregate" as const } : null;
+					})()
+				: (() => {
+						const goal = plan.goals.find(item => item.id === provenance.goalId);
+						return goal ? { goal, receiptKind: "per-goal" as const } : null;
+					})()
+			: findReceiptGoal(plan, ledger, currentObjective);
+
 	if (!receiptTarget) {
 		// When earlier required goals are already complete but later ones remain, name the
 		// specific blocking goals (a final-aggregate receipt cannot exist yet anyway). Only
@@ -623,9 +696,7 @@ export async function isUltragoalAskBlocked(
 		});
 	}
 
-	const finalReceiptGoal = [...requiredGoals(plan)]
-		.reverse()
-		.find(goal => goal.completionVerification?.receiptKind === "final-aggregate");
+	const finalReceiptGoal = findFinalAggregateReceiptGoal(plan, ledger);
 	if (!finalReceiptGoal) {
 		return activeAskDiagnostic({
 			reason: "Ultragoal aggregate completion is missing a final aggregate receipt.",
@@ -886,7 +957,7 @@ export async function assertUltragoalDropAllowed(input: {
 	if (!input.currentGoal) return;
 	if (input.currentGoal.status !== "active") return;
 	// Unrelated active goal: not this aggregate run.
-	if (!objectiveMatches(input.currentGoal.objective, plan)) return;
+	if (!objectiveMatches(input.currentGoal, plan, sessionId)) return;
 	// All required stories complete: a legitimate reset, not a give-up.
 	if (getUltragoalRunCompletionState(plan).allComplete) return;
 	const nudge = await consumeUltragoalNudge({

package/src/gjc-runtime/ultragoal-pipeline.ts

@@ -0,0 +1,306 @@
+import * as crypto from "node:crypto";
+import {
+	appendLedger,
+	collectPipelineBlockerFootprints,
+	currentUltragoalSessionId,
+	getUltragoalPaths,
+	handleIdsFromValue,
+	hashPipelineMetadata,
+	isSubstantiveEvidence,
+	type JsonObject,
+	nonEmptyString,
+	openPipelineOverlap,
+	pipelinePeer,
+	readUltragoalLedger,
+	readUltragoalPlan,
+	requireCoveredHandles,
+	requireFreshPipelineMetadata,
+	requireJsonObjectOrArrayValue,
+	requireJsonObjectValue,
+	requireNonEmptyPipelineTargets,
+	resultHandleIds,
+	stringArray,
+	targetsAreDisjoint,
+	targetsOverlap,
+	type UltragoalGoal,
+	type UltragoalLedgerEvent,
+	type UltragoalPipelineLedgerEventName,
+	type UltragoalPipelineOverlapReceipt,
+	type UltragoalPipelineOverlapState,
+	type UltragoalPlan,
+	validateValidationBatchPipelineExclusion,
+	writePlan,
+} from "./ultragoal-runtime";
+
+export function requirePipelineStartable(plan: UltragoalPlan, prior: UltragoalGoal, next: UltragoalGoal): void {
+	if (plan.gjcGoalMode !== "aggregate")
+		throw new Error("pipeline overlap is supported only for aggregate ultragoal mode");
+	if (openPipelineOverlap(plan))
+		throw new Error("Cannot start pipeline overlap because another overlap is already open");
+	if (prior.status !== "active")
+		throw new Error(`Prior goal ${prior.id} must be active before pipeline overlap starts`);
+	if (next.status !== "pending" && next.status !== "failed")
+		throw new Error(`Next goal ${next.id} must be pending or retryable failed`);
+	validateValidationBatchPipelineExclusion(prior);
+	validateValidationBatchPipelineExclusion(next);
+	if (prior.validationBatch || next.validationBatch)
+		throw new Error("pipeline overlap cannot start for validation batch goals");
+	const priorMetadata = requireFreshPipelineMetadata(prior);
+	const nextMetadata = requireFreshPipelineMetadata(next);
+	if (!priorMetadata.eligible || !nextMetadata.eligible)
+		throw new Error("pipeline overlap requires eligible original-plan metadata on both goals");
+	if (!priorMetadata.independentOf.includes(next.id) || !nextMetadata.independentOf.includes(prior.id)) {
+		throw new Error("pipeline overlap requires symmetric original independence");
+	}
+	if (!targetsAreDisjoint(priorMetadata.targets, nextMetadata.targets))
+		throw new Error("pipeline overlap requires disjoint files and surfaces");
+}
+
+function pipelineEventRefs(prior: UltragoalGoal, next: UltragoalGoal): JsonObject {
+	return {
+		priorMetadataHash: prior.pipelineMetadata?.metadataHash,
+		nextMetadataHash: next.pipelineMetadata?.metadataHash,
+		priorTargets: prior.pipelineMetadata?.targets,
+		nextTargets: next.pipelineMetadata?.targets,
+	};
+}
+
+function pipelineReceipt(
+	cwd: string,
+	event: string,
+	overlapId: string,
+	prior: UltragoalGoal,
+	next: UltragoalGoal,
+): UltragoalPipelineOverlapReceipt {
+	const paths = getUltragoalPaths(cwd, currentUltragoalSessionId(cwd));
+	return {
+		ok: true,
+		event,
+		overlap_id: overlapId,
+		prior_goal_id: prior.id,
+		next_goal_id: next.id,
+		status: next.pipelineMetadata?.overlap,
+		next_goal_status: next.status,
+		goals_path: paths.goalsPath,
+		ledger_path: paths.ledgerPath,
+	};
+}
+
+export async function startUltragoalPipelineOverlap(input: {
+	cwd: string;
+	priorGoalId: string;
+	nextGoalId: string;
+	reviewHandles: JsonObject | JsonObject[];
+	qaHandles: JsonObject | JsonObject[];
+	implementationHandle: JsonObject;
+}): Promise<UltragoalPipelineOverlapReceipt> {
+	const plan = await readUltragoalPlan(input.cwd);
+	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
+	const prior = plan.goals.find(goal => goal.id === input.priorGoalId);
+	const next = plan.goals.find(goal => goal.id === input.nextGoalId);
+	if (!prior || !next) throw new Error("start-pipeline-overlap requires existing prior and next goal ids");
+	const reviewHandles = requireJsonObjectOrArrayValue(input.reviewHandles, "review handles");
+	const qaHandles = requireJsonObjectOrArrayValue(input.qaHandles, "QA handles");
+	requireJsonObjectValue(input.implementationHandle, "implementation handle");
+	requirePipelineStartable(plan, prior, next);
+	const now = new Date().toISOString();
+	const overlapId = `pipeline-${crypto.randomUUID()}`;
+	const priorMetadata = requireFreshPipelineMetadata(prior);
+	const nextMetadata = requireFreshPipelineMetadata(next);
+	const priorOpenMetadata = {
+		...priorMetadata,
+		overlap: "open" as const,
+		overlapId,
+		priorGoalId: prior.id,
+		nextGoalId: next.id,
+	};
+	const nextOpenMetadata = {
+		...nextMetadata,
+		overlap: "open" as const,
+		overlapId,
+		priorGoalId: prior.id,
+		nextGoalId: next.id,
+	};
+	prior.pipelineMetadata = { ...priorOpenMetadata, metadataHash: hashPipelineMetadata(priorOpenMetadata) };
+	next.pipelineMetadata = { ...nextOpenMetadata, metadataHash: hashPipelineMetadata(nextOpenMetadata) };
+	prior.updatedAt = now;
+	next.updatedAt = now;
+	next.status = "active";
+	next.startedAt = next.startedAt ?? now;
+	plan.updatedAt = now;
+	await writePlan(input.cwd, plan);
+	const refs = pipelineEventRefs(prior, next);
+	const expectedReviewHandleIds = handleIdsFromValue(reviewHandles, "review");
+	const expectedQaHandleIds = handleIdsFromValue(qaHandles, "QA");
+	await appendLedger(input.cwd, {
+		event: "pipeline_overlap_started",
+		eventId: crypto.randomUUID(),
+		timestamp: now,
+		schemaVersion: 1,
+		overlapId,
+		priorGoalId: prior.id,
+		nextGoalId: next.id,
+		reviewHandles,
+		reviewHandleIds: expectedReviewHandleIds,
+		qaHandles,
+		qaHandleIds: expectedQaHandleIds,
+		implementationHandle: input.implementationHandle,
+		...refs,
+	});
+	await appendLedger(input.cwd, { event: "goal_started", goalId: next.id, pipelineOverlapId: overlapId });
+	return pipelineReceipt(input.cwd, "pipeline_overlap_started", overlapId, prior, next);
+}
+
+function resultStatus(value: JsonObject, fieldName: string): string {
+	const status = nonEmptyString(value.status) ?? nonEmptyString(value.verdict) ?? nonEmptyString(value.result);
+	if (!status) throw new Error(`${fieldName} requires status, verdict, or result`);
+	return status.toLowerCase();
+}
+
+function requireCleanPipelineResult(result: JsonObject, expectedHandleIds: readonly string[], fieldName: string): void {
+	const status = resultStatus(result, fieldName);
+	if (!["passed", "pass", "approved", "clear"].includes(status)) throw new Error(`${fieldName} did not pass`);
+	const evidence = nonEmptyString(result.evidence);
+	if (!evidence || !isSubstantiveEvidence(evidence)) throw new Error(`${fieldName} requires substantive evidence`);
+	requireCoveredHandles(expectedHandleIds, resultHandleIds(result, fieldName), fieldName);
+	if (collectPipelineBlockerFootprints(result, fieldName).length > 0)
+		throw new Error(`${fieldName} cannot clean-join with blockers`);
+}
+
+function pipelineStartEventHandleIds(
+	ledger: UltragoalLedgerEvent[],
+	overlapId: string,
+): { review: string[]; qa: string[] } {
+	const event = ledger.find(row => row.event === "pipeline_overlap_started" && row.overlapId === overlapId) as
+		| JsonObject
+		| undefined;
+	if (!event) throw new Error(`No pipeline_overlap_started event found for ${overlapId}`);
+	const review =
+		stringArray(event.reviewHandleIds) ??
+		handleIdsFromValue(requireJsonObjectOrArrayValue(event.reviewHandles, "review handles"), "review");
+	const qa =
+		stringArray(event.qaHandleIds) ??
+		handleIdsFromValue(requireJsonObjectOrArrayValue(event.qaHandles, "QA handles"), "QA");
+	return { review, qa };
+}
+
+export async function joinUltragoalPipelineOverlap(input: {
+	cwd: string;
+	overlapId: string;
+	reviewResult: JsonObject;
+	qaResult: JsonObject;
+}): Promise<UltragoalPipelineOverlapReceipt> {
+	const plan = await readUltragoalPlan(input.cwd);
+	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
+	const overlap = openPipelineOverlap(plan);
+	if (!overlap || overlap.overlapId !== input.overlapId)
+		throw new Error(`No open pipeline overlap found for ${input.overlapId}`);
+	const { prior, next, overlapId } = overlap;
+	const nextMetadata = requireFreshPipelineMetadata(next);
+	const ledger = await readUltragoalLedger(input.cwd);
+	const expectedHandles = pipelineStartEventHandleIds(ledger, overlapId);
+	const reviewBlockers = collectPipelineBlockerFootprints(input.reviewResult, "review result");
+	const qaBlockers = collectPipelineBlockerFootprints(input.qaResult, "QA result");
+	const blockerFootprints = [...reviewBlockers, ...qaBlockers];
+	let state: UltragoalPipelineOverlapState;
+	let event: UltragoalPipelineLedgerEventName;
+	if (blockerFootprints.length === 0) {
+		try {
+			requireCleanPipelineResult(input.reviewResult, expectedHandles.review, "review result");
+			requireCleanPipelineResult(input.qaResult, expectedHandles.qa, "QA result");
+			state = "joined_clean";
+			event = "pipeline_overlap_joined";
+		} catch {
+			state = "quarantine_required";
+			event = "pipeline_overlap_quarantined";
+		}
+	} else if (blockerFootprints.every(footprint => !targetsOverlap(footprint, nextMetadata.targets))) {
+		state = "blocked_disjoint_continue";
+		event = "pipeline_overlap_joined";
+	} else {
+		state = "quarantine_required";
+		event = "pipeline_overlap_quarantined";
+	}
+	const now = new Date().toISOString();
+	for (const goal of [prior, next]) {
+		const metadata = requireFreshPipelineMetadata(goal);
+		const joinedMetadata = { ...metadata, overlap: state, blockerFootprints };
+		goal.pipelineMetadata = { ...joinedMetadata, metadataHash: hashPipelineMetadata(joinedMetadata) };
+		goal.updatedAt = now;
+	}
+	if (state === "quarantine_required") next.status = "blocked";
+	plan.updatedAt = now;
+	await writePlan(input.cwd, plan);
+	await appendLedger(input.cwd, {
+		event,
+		eventId: crypto.randomUUID(),
+		timestamp: now,
+		schemaVersion: 1,
+		overlapId,
+		priorGoalId: prior.id,
+		nextGoalId: next.id,
+		status: state,
+		reviewResult: input.reviewResult,
+		qaResult: input.qaResult,
+		blockerFootprints,
+		...pipelineEventRefs(prior, next),
+	});
+	return pipelineReceipt(input.cwd, event, overlapId, prior, next);
+}
+
+export async function rebaselineUltragoalPipelineOverlap(input: {
+	cwd: string;
+	overlapId: string;
+	goalId: string;
+	evidence: string;
+	targetState: JsonObject;
+}): Promise<UltragoalPipelineOverlapReceipt> {
+	const plan = await readUltragoalPlan(input.cwd);
+	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
+	const goal = plan.goals.find(item => item.id === input.goalId);
+	if (!goal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
+	const evidence = input.evidence.trim();
+	if (!isSubstantiveEvidence(evidence)) throw new Error("rebaseline-pipeline-overlap requires substantive evidence");
+	const targetState = requireNonEmptyPipelineTargets(input.targetState, "target state");
+	const metadata = requireFreshPipelineMetadata(goal);
+	if (metadata.overlap !== "quarantine_required" || metadata.overlapId !== input.overlapId) {
+		throw new Error(`Goal ${goal.id} is not quarantined for overlap ${input.overlapId}`);
+	}
+	for (const footprint of metadata.blockerFootprints ?? []) {
+		if (targetsOverlap(footprint, targetState))
+			throw new Error("rebaseline-pipeline-overlap target state overlaps unresolved blocker footprints");
+	}
+	const now = new Date().toISOString();
+	const rebaselinedMetadata = { ...metadata, overlap: "rebaseline_complete" as const, targets: targetState };
+	goal.pipelineMetadata = { ...rebaselinedMetadata, metadataHash: hashPipelineMetadata(rebaselinedMetadata) };
+	goal.status = "active";
+	goal.evidence = evidence;
+	goal.updatedAt = now;
+	plan.updatedAt = now;
+	await writePlan(input.cwd, plan);
+	const peer = pipelinePeer(plan, metadata);
+	await appendLedger(input.cwd, {
+		event: "pipeline_overlap_rebaselined",
+		eventId: crypto.randomUUID(),
+		timestamp: now,
+		schemaVersion: 1,
+		overlapId: input.overlapId,
+		priorGoalId: metadata.priorGoalId ?? peer?.id ?? "",
+		nextGoalId: metadata.nextGoalId ?? goal.id,
+		goalId: goal.id,
+		evidence,
+		targetState,
+		metadataHash: goal.pipelineMetadata.metadataHash,
+	});
+	const paths = getUltragoalPaths(input.cwd, currentUltragoalSessionId(input.cwd));
+	return {
+		ok: true,
+		event: "pipeline_overlap_rebaselined",
+		overlap_id: input.overlapId,
+		prior_goal_id: metadata.priorGoalId ?? peer?.id ?? "",
+		goal_id: goal.id,
+		status: goal.pipelineMetadata.overlap,
+		goals_path: paths.goalsPath,
+		ledger_path: paths.ledgerPath,
+	};
+}

package/src/gjc-runtime/ultragoal-receipt-freshness.ts

@@ -244,6 +244,93 @@ export function validateReceiptFreshBase(input: {
 	return null;
 }
 
+/**
+ * Validate a receipt whose plan-generation freshness was legitimately staled
+ * by later plan growth as a historical attestation for its own goal:
+ * internally consistent, anchored to a ledger checkpoint event that carries a
+ * byte-identical receipt, quality gate untampered, and the goal row untouched
+ * since verification. Plan-generation freshness against the CURRENT plan is
+ * intentionally not required; that is exactly what later plan growth
+ * invalidates by design. Returns null when the receipt stands as valid
+ * historical evidence.
+ */
+function validateLedgerAnchoredHistoricalReceipt(input: {
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receipt: UltragoalCompletionVerification;
+	label: string;
+}): UltragoalReceiptFreshnessDiagnostic | null {
+	if (
+		input.receipt.schemaVersion !== 1 ||
+		input.receipt.goalId !== input.goal.id ||
+		!input.receipt.planGeneration ||
+		!input.receipt.checkpointLedgerEventId ||
+		hashStructuredValue(input.receipt.basis) !== input.receipt.planGeneration
+	) {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} ${input.label} is malformed.`,
+			goalId: input.goal.id,
+		};
+	}
+	const event = findLedgerReceiptEvent(input.ledger, input.receipt);
+	if (!event)
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} ${input.label} ledger event is missing.`,
+			goalId: input.goal.id,
+		};
+	// Bind the goals.json receipt to the FULL receipt recorded on the ledger
+	// event. Field-selective matching would accept a coordinated edit of the
+	// goals-row basis/generation paired with only the event generation.
+	const eventReceipt = event.completionVerification as UltragoalCompletionVerification | undefined;
+	if (!eventReceipt || hashStructuredValue(eventReceipt) !== hashStructuredValue(input.receipt))
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} ${input.label} does not match its ledger event receipt.`,
+			goalId: input.goal.id,
+		};
+	if (hashStructuredValue(event.qualityGateJson) !== input.receipt.qualityGateHash)
+		return {
+			state: "active_dirty_quality_gate",
+			message: `Ultragoal ${input.goal.id} ${input.label} quality-gate hash does not match ledger.`,
+			goalId: input.goal.id,
+		};
+	if (input.goal.updatedAt !== input.receipt.verifiedAt)
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} changed after its ${input.label} was verified.`,
+			goalId: input.goal.id,
+		};
+	return null;
+}
+
+/**
+ * Validate a final-aggregate receipt that was legitimately superseded — its
+ * aggregate claim staled by later plan growth (e.g. `steer add_subgoal`
+ * appending goals after a terminal run) — as historical evidence for its own
+ * goal. Returns null when the receipt stands.
+ */
+export function validateSupersededFinalAggregateReceipt(input: {
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receipt: UltragoalCompletionVerification;
+}): UltragoalReceiptFreshnessDiagnostic | null {
+	if (input.receipt.receiptKind !== "final-aggregate") {
+		return {
+			state: "active_stale_receipt",
+			message: `Ultragoal ${input.goal.id} superseded final-aggregate receipt is malformed.`,
+			goalId: input.goal.id,
+		};
+	}
+	return validateLedgerAnchoredHistoricalReceipt({
+		ledger: input.ledger,
+		goal: input.goal,
+		receipt: input.receipt,
+		label: "superseded final-aggregate receipt",
+	});
+}
+
 export function findFreshBatchCloseReceipt(input: {
 	plan: UltragoalPlan;
 	ledger: readonly UltragoalLedgerEvent[];
@@ -267,7 +354,21 @@ export function findFreshBatchCloseReceipt(input: {
 		receipt: finalReceipt,
 		receiptKind: finalReceipt.receiptKind,
 	});
-	return diagnostic ? null : finalReceipt;
+	if (!diagnostic) return finalReceipt;
+	// A batch close staled only by later plan growth (e.g. `steer add_subgoal`
+	// after the batch completed) still proves the batch was validly closed:
+	// the member receipts are freshness-checked separately, the close is
+	// anchored to its ledger event, and the final goal's row is untouched.
+	// Without this, completing a goal appended after a closed batch can never
+	// validate, because the old close can never be fresh against the grown
+	// plan and identical-evidence replays of fresh receipts are no-ops.
+	const historicalDiagnostic = validateLedgerAnchoredHistoricalReceipt({
+		ledger: input.ledger,
+		goal: finalGoal,
+		receipt: finalReceipt,
+		label: "superseded batch-close receipt",
+	});
+	return historicalDiagnostic ? null : finalReceipt;
 }
 
 export function validateDeferredMemberReceiptFresh(input: {