@gajae-code/coding-agent 0.11.0 → 0.11.1

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,
@@ -156,8 +160,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 +194,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 +327,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({
@@ -381,7 +430,7 @@ export async function readUltragoalVerificationState(input: {
 			message: "Ultragoal has blocked or failed goals; record blockers or rerun verification.",
 		};
 	}
-	const receiptTarget = findReceiptGoal(plan, currentObjective);
+	const receiptTarget = 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 +672,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.",

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: {

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

@@ -573,16 +573,32 @@ async function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string |
 
 function chooseReceiptKind(
 	plan: UltragoalPlan,
+	ledger: readonly UltragoalLedgerEvent[],
 	goal: UltragoalGoal,
 	status: UltragoalGoalStatus,
 ): UltragoalReceiptKind {
 	if (plan.gjcGoalMode === "per-story") return "per-goal";
 	if (status !== "complete") return "per-goal";
+	// A non-final validation-batch member must always carry a per-goal
+	// deferred receipt; only the batch's final goal may close the batch and
+	// (in aggregate mode) carry the final-aggregate receipt. Without this, a
+	// context-stale re-verification replay of a member could mint an invalid
+	// final-aggregate receipt with validationBatch.role "deferred-member".
+	if (goal.validationBatch && goal.validationBatch.finalGoalId !== goal.id) return "per-goal";
 	const requiredGoals = requiredUltragoalGoals(plan);
-	const existingFinalAggregateGoal = requiredGoals.find(
-		item => item.id !== goal.id && item.completionVerification?.receiptKind === "final-aggregate",
-	);
-	if (existingFinalAggregateGoal) return "per-goal";
+	// Only a still-fresh final-aggregate receipt on another goal defers this
+	// checkpoint to per-goal. A stale one (e.g. staled by `steer add_subgoal`
+	// appending goals after a terminal run) must not suppress re-minting,
+	// otherwise the run can never regain a verifiable final-aggregate receipt:
+	// the completion guard demands a fresh final-aggregate receipt while this
+	// gate would keep answering per-goal forever.
+	const existingFreshFinalAggregateGoal = requiredGoals.find(item => {
+		if (item.id === goal.id) return false;
+		const receipt = item.completionVerification;
+		if (receipt?.receiptKind !== "final-aggregate") return false;
+		return validateReceiptFreshBase({ plan, ledger, goal: item, receipt, receiptKind: "final-aggregate" }) === null;
+	});
+	if (existingFreshFinalAggregateGoal) return "per-goal";
 	const unfinishedRequiredGoals = requiredGoals.filter(
 		item => item.id !== goal.id && !TERMINAL_OR_SKIPPED_STATUSES.has(item.status),
 	);
@@ -3964,13 +3980,21 @@ export async function checkpointUltragoalGoal(input: {
 	const evidence = input.evidence.trim();
 	if (!evidence) throw new Error("checkpoint evidence is required");
 	const ledgerBefore = await readUltragoalLedger(input.cwd);
-	const matchingIdempotentEvent = ledgerBefore.find(
+	const matchingIdempotentEvents = ledgerBefore.filter(
 		event =>
 			event.event === "goal_checkpointed" &&
 			event.goalId === goal.id &&
 			event.status === input.status &&
 			event.evidence === evidence,
 	);
+	// Re-verification replays legitimately append repeated same-status,
+	// same-evidence checkpoint events for one goal. The recorded receipt must
+	// be compared against ITS OWN checkpoint event — resolved by the receipt's
+	// checkpointLedgerEventId, falling back to the latest match — never the
+	// oldest duplicate, which would wrongly report the current receipt stale.
+	const matchingIdempotentEvent =
+		matchingIdempotentEvents.find(event => event.eventId === goal.completionVerification?.checkpointLedgerEventId) ??
+		matchingIdempotentEvents.at(-1);
 	const batchMetadata = input.status === "complete" ? requireFreshValidationBatchMetadata(goal) : undefined;
 	if (batchMetadata && goal.completionVerification?.validationBatch) {
 		const receiptBatch = goal.completionVerification.validationBatch;
@@ -3987,7 +4011,35 @@ export async function checkpointUltragoalGoal(input: {
 	if (input.status === "complete" && goal.completionVerification?.validationBatch && !batchMetadata) {
 		throw new Error(`Goal ${goal.id} has stale validation batch completion receipt`);
 	}
-	if (goal.status === input.status && goal.evidence === evidence && matchingIdempotentEvent) {
+	// An identical-evidence complete replay is only a no-op while the recorded
+	// receipt still validates fresh. When the goal row itself is untouched
+	// (updatedAt still matches the receipt's verifiedAt) but later goal-tagged
+	// ledger events (e.g. blocker classifications) or plan growth staled the
+	// receipt, the replay is a genuine re-verification: it must run the full
+	// quality gate and mint a fresh receipt, otherwise a completed goal with a
+	// context-staled receipt can never be repaired (different evidence is
+	// rejected on complete goals by design). A mutated goal row keeps the
+	// fail-loud tamper handling in the idempotent branch below.
+	const staleCompleteReceiptReplay =
+		input.status === "complete" &&
+		goal.status === "complete" &&
+		goal.evidence === evidence &&
+		Boolean(matchingIdempotentEvent) &&
+		(!goal.completionVerification ||
+			(goal.completionVerification.verifiedAt === goal.updatedAt &&
+				validateReceiptFreshBase({
+					plan,
+					ledger: ledgerBefore,
+					goal,
+					receipt: goal.completionVerification,
+					receiptKind: goal.completionVerification.receiptKind,
+				}) !== null));
+	if (
+		goal.status === input.status &&
+		goal.evidence === evidence &&
+		matchingIdempotentEvent &&
+		!staleCompleteReceiptReplay
+	) {
 		if (batchMetadata) {
 			const receipt = goal.completionVerification;
 			const receiptBatch = receipt?.validationBatch;
@@ -4009,6 +4061,18 @@ export async function checkpointUltragoalGoal(input: {
 			)
 				throw new Error(`Goal ${goal.id} has stale validation batch metadata hash in close receipt`);
 		}
+		// A complete goal whose row changed after its receipt was verified is
+		// neither a clean no-op nor a repairable context-stale replay: fail loud
+		// instead of silently laundering a tampered/inconsistent durable row.
+		if (
+			input.status === "complete" &&
+			goal.completionVerification &&
+			goal.completionVerification.verifiedAt !== goal.updatedAt
+		) {
+			throw new Error(
+				`Goal ${goal.id} changed after its completion receipt was verified; refusing idempotent replay. Investigate the durable goals.json row before re-checkpointing.`,
+			);
+		}
 		// Idempotent re-checkpoint: this goal is already recorded in the target status with the same
 		// evidence, so skip the plan rewrite and ledger append to avoid duplicate goal_checkpointed
 		// events. The ledger is the dedup source of truth because it is exactly what a duplicate write
@@ -4020,7 +4084,7 @@ export async function checkpointUltragoalGoal(input: {
 	const changeSet = input.status === "complete" ? await computeCheckpointChangeSet(input.cwd) : undefined;
 	if (input.status === "complete") {
 		validatePipelineCheckpointSafety(plan, goal, changeSet);
-		validateCompleteCheckpointTargetGoal(goal);
+		if (!staleCompleteReceiptReplay) validateCompleteCheckpointTargetGoal(goal);
 	}
 	const qualityGateJson =
 		input.status === "complete"
@@ -4047,7 +4111,7 @@ export async function checkpointUltragoalGoal(input: {
 			blockedGoal.updatedAt = now;
 		}
 	}
-	const receiptKind = input.status === "complete" ? chooseReceiptKind(plan, goal, input.status) : null;
+	const receiptKind = input.status === "complete" ? chooseReceiptKind(plan, ledgerBefore, goal, input.status) : null;
 	const pendingCheckpointEventId = crypto.randomUUID();
 	if (input.status === "complete" && receiptKind && qualityGateJson && !Array.isArray(qualityGateJson)) {
 		goal.completionVerification = buildCompletionReceipt({