@gajae-code/coding-agent 0.1.1 → 0.1.2

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

@@ -1,3 +1,4 @@
+import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
@@ -23,6 +24,7 @@ export interface UltragoalGoal {
 	completedAt?: string;
 	evidence?: string;
 	steering?: Record<string, unknown>;
+	completionVerification?: UltragoalCompletionVerification;
 }
 
 export interface UltragoalPlan {
@@ -36,6 +38,36 @@ export interface UltragoalPlan {
 	updatedAt: string;
 }
 
+export type UltragoalReceiptKind = "per-goal" | "final-aggregate";
+
+export interface UltragoalCompletionVerification {
+	schemaVersion: 1;
+	receiptId: string;
+	verifiedAt: string;
+	goalId: string;
+	receiptKind: UltragoalReceiptKind;
+	goalStatusBeforeCheckpoint: UltragoalGoalStatus;
+	gjcGoalMode: UltragoalGjcGoalMode;
+	gjcObjective: string;
+	qualityGateHash: string;
+	planGeneration: string;
+	basis: {
+		planHashBeforeCheckpoint: string;
+		latestRelevantLedgerEventIdBeforeCheckpoint: string | null;
+		goalUpdatedAtBeforeCheckpoint: string;
+		relevantGoalIdsBeforeCheckpoint: string[];
+		requiredGoalSetHashBeforeCheckpoint: string;
+	};
+	checkpointLedgerEventId: string;
+}
+
+export interface UltragoalLedgerEvent extends JsonObject {
+	eventId?: string;
+	event?: string;
+	goalId?: string;
+	timestamp?: string;
+}
+
 export interface UltragoalPaths {
 	dir: string;
 	briefPath: string;
@@ -65,8 +97,33 @@ interface JsonObject {
 }
 
 const TERMINAL_OR_SKIPPED_STATUSES = new Set<UltragoalGoalStatus>(["complete", "superseded"]);
+const CLEAN_ARCHITECT_STATUS = "CLEAR";
+const APPROVE_RECOMMENDATION = "APPROVE";
+const PASSED_STATUS = "passed";
+
 const SCHEDULABLE_STATUSES = new Set<UltragoalGoalStatus>(["pending", "active", "failed"]);
 
+function stableStructuredValue(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(item => stableStructuredValue(item));
+	if (value && typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		const output: Record<string, unknown> = {};
+		for (const key of Object.keys(record).sort()) {
+			const item = record[key];
+			if (item !== undefined) output[key] = stableStructuredValue(item);
+		}
+		return output;
+	}
+	return value;
+}
+
+export function hashStructuredValue(value: unknown): string {
+	return crypto
+		.createHash("sha256")
+		.update(JSON.stringify(stableStructuredValue(value)))
+		.digest("hex");
+}
+
 export function getUltragoalPaths(cwd: string): UltragoalPaths {
 	const dir = path.join(cwd, ".gjc", "ultragoal");
 	return {
@@ -87,11 +144,30 @@ async function ensureUltragoalDir(paths: UltragoalPaths): Promise<void> {
 	await fs.mkdir(paths.dir, { recursive: true });
 }
 
-async function appendLedger(cwd: string, event: JsonObject): Promise<void> {
+async function appendLedger(cwd: string, event: JsonObject): Promise<UltragoalLedgerEvent> {
 	const paths = getUltragoalPaths(cwd);
 	await ensureUltragoalDir(paths);
-	const entry = { ...event, timestamp: new Date().toISOString() };
+	const entry: UltragoalLedgerEvent = {
+		eventId: typeof event.eventId === "string" ? event.eventId : crypto.randomUUID(),
+		...event,
+		timestamp: new Date().toISOString(),
+	};
 	await fs.appendFile(paths.ledgerPath, `${JSON.stringify(entry)}\n`);
+	return entry;
+}
+
+export async function readUltragoalLedger(cwd: string): Promise<UltragoalLedgerEvent[]> {
+	try {
+		const raw = await Bun.file(getUltragoalPaths(cwd).ledgerPath).text();
+		return raw
+			.split(/\r?\n/)
+			.map(line => line.trim())
+			.filter(line => line.length > 0)
+			.map(line => JSON.parse(line) as UltragoalLedgerEvent);
+	} catch (error) {
+		if (isEnoent(error)) return [];
+		throw error;
+	}
 }
 
 async function writePlan(cwd: string, plan: UltragoalPlan): Promise<void> {
@@ -159,6 +235,10 @@ function normalizePlan(raw: unknown): UltragoalPlan {
 				typeof goalRecord.steering === "object" && goalRecord.steering !== null
 					? (goalRecord.steering as Record<string, unknown>)
 					: undefined,
+			completionVerification:
+				typeof goalRecord.completionVerification === "object" && goalRecord.completionVerification !== null
+					? (goalRecord.completionVerification as UltragoalCompletionVerification)
+					: undefined,
 		};
 	});
 	const aliases = Array.isArray(record.gjcObjectiveAliases)
@@ -303,6 +383,201 @@ async function readStructuredValue(cwd: string, value: string): Promise<unknown>
 		throw error;
 	}
 }
+function qualityGateObject(value: unknown): JsonObject | null {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as JsonObject) : null;
+}
+
+function requiredReceiptGoals(plan: UltragoalPlan): UltragoalGoal[] {
+	return plan.goals.filter(goal => goal.status !== "superseded");
+}
+
+function chooseReceiptKind(
+	plan: UltragoalPlan,
+	goal: UltragoalGoal,
+	status: UltragoalGoalStatus,
+): UltragoalReceiptKind {
+	if (status !== "complete") return "per-goal";
+	const incomplete = requiredReceiptGoals(plan).filter(item => item.id !== goal.id && item.status !== "complete");
+	return incomplete.length === 0 ? "final-aggregate" : "per-goal";
+}
+
+function relevantGoalIds(plan: UltragoalPlan, goal: UltragoalGoal, receiptKind: UltragoalReceiptKind): string[] {
+	const ids = receiptKind === "final-aggregate" ? requiredReceiptGoals(plan).map(item => item.id) : [goal.id];
+	return [...new Set(ids)].sort();
+}
+
+function ledgerEventTouchesGoals(event: UltragoalLedgerEvent, goalIds: readonly string[]): boolean {
+	if (typeof event.goalId === "string" && goalIds.includes(event.goalId)) return true;
+	const eventGoalIds = Array.isArray(event.goalIds) ? event.goalIds : [];
+	return eventGoalIds.some(item => typeof item === "string" && goalIds.includes(item));
+}
+
+export function computeUltragoalPlanGeneration(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receiptKind: UltragoalReceiptKind;
+	beforeStatus: UltragoalGoalStatus;
+	excludeEventId?: string;
+}): UltragoalCompletionVerification["basis"] & { planGeneration: string } {
+	const goalIds = relevantGoalIds(input.plan, input.goal, input.receiptKind);
+	const planBeforeCheckpoint = structuredClone(input.plan) as UltragoalPlan;
+	const goalBeforeCheckpoint = planBeforeCheckpoint.goals.find(goal => goal.id === input.goal.id);
+	const receipt = input.goal.completionVerification;
+	const goalUpdatedAtBeforeCheckpoint = receipt?.basis.goalUpdatedAtBeforeCheckpoint ?? input.goal.updatedAt;
+	if (goalBeforeCheckpoint) {
+		goalBeforeCheckpoint.status = input.beforeStatus;
+		goalBeforeCheckpoint.updatedAt = goalUpdatedAtBeforeCheckpoint;
+		delete goalBeforeCheckpoint.completedAt;
+		delete goalBeforeCheckpoint.completionVerification;
+	}
+	const relevantLedger = input.ledger.filter(event => {
+		if (input.excludeEventId && event.eventId === input.excludeEventId) return false;
+		return ledgerEventTouchesGoals(event, goalIds);
+	});
+	const latestRelevantEvent = relevantLedger.at(-1) ?? null;
+	const basis = {
+		planHashBeforeCheckpoint: hashStructuredValue(planBeforeCheckpoint),
+		latestRelevantLedgerEventIdBeforeCheckpoint:
+			typeof latestRelevantEvent?.eventId === "string" ? latestRelevantEvent.eventId : null,
+		goalUpdatedAtBeforeCheckpoint,
+		relevantGoalIdsBeforeCheckpoint: goalIds,
+		requiredGoalSetHashBeforeCheckpoint: hashStructuredValue(goalIds),
+	};
+	return {
+		...basis,
+		planGeneration: hashStructuredValue({
+			receiptKind: input.receiptKind,
+			goalId: input.goal.id,
+			beforeStatus: input.beforeStatus,
+			basis,
+		}),
+	};
+}
+
+function buildCompletionReceipt(input: {
+	plan: UltragoalPlan;
+	ledger: readonly UltragoalLedgerEvent[];
+	goal: UltragoalGoal;
+	receiptKind: UltragoalReceiptKind;
+	beforeStatus: UltragoalGoalStatus;
+	qualityGateJson: JsonObject;
+	now: string;
+	checkpointLedgerEventId: string;
+}): UltragoalCompletionVerification {
+	const generation = computeUltragoalPlanGeneration({
+		plan: input.plan,
+		ledger: input.ledger,
+		goal: input.goal,
+		receiptKind: input.receiptKind,
+		beforeStatus: input.beforeStatus,
+		excludeEventId: input.checkpointLedgerEventId,
+	});
+	return {
+		schemaVersion: 1,
+		receiptId: crypto.randomUUID(),
+		verifiedAt: input.now,
+		goalId: input.goal.id,
+		receiptKind: input.receiptKind,
+		goalStatusBeforeCheckpoint: input.beforeStatus,
+		gjcGoalMode: input.plan.gjcGoalMode,
+		gjcObjective: input.plan.gjcObjective,
+		qualityGateHash: hashStructuredValue(input.qualityGateJson),
+		planGeneration: generation.planGeneration,
+		basis: {
+			planHashBeforeCheckpoint: generation.planHashBeforeCheckpoint,
+			latestRelevantLedgerEventIdBeforeCheckpoint: generation.latestRelevantLedgerEventIdBeforeCheckpoint,
+			goalUpdatedAtBeforeCheckpoint: generation.goalUpdatedAtBeforeCheckpoint,
+			relevantGoalIdsBeforeCheckpoint: generation.relevantGoalIdsBeforeCheckpoint,
+			requiredGoalSetHashBeforeCheckpoint: generation.requiredGoalSetHashBeforeCheckpoint,
+		},
+		checkpointLedgerEventId: input.checkpointLedgerEventId,
+	};
+}
+function nonEmptyStringArray(value: unknown): string[] | null {
+	if (!Array.isArray(value)) return null;
+	const items = value.filter(item => typeof item === "string" && item.trim().length > 0);
+	return items.length === value.length && items.length > 0 ? items : null;
+}
+
+function emptyArray(value: unknown): boolean {
+	return Array.isArray(value) && value.length === 0;
+}
+
+function assertCleanSection(
+	section: JsonObject | null,
+	checks: Record<string, string>,
+	commandField: string,
+	pathPrefix: string,
+): void {
+	if (!section) throw new Error(`qualityGate.${pathPrefix} is required`);
+	for (const [field, expected] of Object.entries(checks)) {
+		if (section[field] !== expected) throw new Error(`qualityGate.${pathPrefix}.${field} must be ${expected}`);
+	}
+	if (!nonEmptyString(section.evidence)) throw new Error(`qualityGate.${pathPrefix}.evidence is required`);
+	if (!nonEmptyStringArray(section[commandField]))
+		throw new Error(`qualityGate.${pathPrefix}.${commandField} is required`);
+	if (!emptyArray(section.blockers)) throw new Error(`qualityGate.${pathPrefix}.blockers must be empty`);
+}
+
+async function readRequiredCompletionQualityGate(cwd: string, value: string | undefined): Promise<JsonObject> {
+	if (!value?.trim()) {
+		throw new Error("complete checkpoints require --quality-gate-json; requires --quality-gate-json");
+	}
+	const gate = await readStructuredValue(cwd, value);
+	const gateObject = qualityGateObject(gate);
+	if (!gateObject) throw new Error("qualityGate must be a JSON object");
+	const legacyCodeReview = qualityGateObject(gateObject.codeReview);
+	if (
+		legacyCodeReview &&
+		(legacyCodeReview.recommendation !== APPROVE_RECOMMENDATION ||
+			legacyCodeReview.architectStatus !== CLEAN_ARCHITECT_STATUS)
+	) {
+		throw new Error(
+			"checkpoint --status complete requires architect review approval: codeReview.recommendation must be APPROVE and codeReview.architectStatus must be CLEAR",
+		);
+	}
+	const allowedKeys = new Set(["architectReview", "executorQa", "iteration"]);
+	const unsupportedKeys = Object.keys(gateObject).filter(key => !allowedKeys.has(key));
+	if (unsupportedKeys.length > 0) {
+		throw new Error(`qualityGate contains unsupported keys: ${unsupportedKeys.join(", ")}`);
+	}
+	assertCleanSection(
+		qualityGateObject(gateObject.architectReview),
+		{
+			architectureStatus: CLEAN_ARCHITECT_STATUS,
+			productStatus: CLEAN_ARCHITECT_STATUS,
+			codeStatus: CLEAN_ARCHITECT_STATUS,
+			recommendation: APPROVE_RECOMMENDATION,
+		},
+		"commands",
+		"architectReview",
+	);
+	assertCleanSection(
+		qualityGateObject(gateObject.executorQa),
+		{
+			status: PASSED_STATUS,
+			e2eStatus: PASSED_STATUS,
+			redTeamStatus: PASSED_STATUS,
+		},
+		"e2eCommands",
+		"executorQa",
+	);
+	const executorQa = qualityGateObject(gateObject.executorQa);
+	if (!nonEmptyStringArray(executorQa?.redTeamCommands))
+		throw new Error("qualityGate.executorQa.redTeamCommands is required");
+	assertCleanSection(
+		qualityGateObject(gateObject.iteration),
+		{
+			status: PASSED_STATUS,
+		},
+		"rerunCommands",
+		"iteration",
+	);
+	const iteration = qualityGateObject(gateObject.iteration);
+	if (iteration?.fullRerun !== true) throw new Error("qualityGate.iteration.fullRerun must be true");
+	return gateObject;
+}
 
 export async function checkpointUltragoalGoal(input: {
 	cwd: string;
@@ -318,7 +593,44 @@ export async function checkpointUltragoalGoal(input: {
 	if (!goal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
 	const evidence = input.evidence.trim();
 	if (!evidence) throw new Error("checkpoint evidence is required");
+	const qualityGateJson =
+		input.status === "complete"
+			? await readRequiredCompletionQualityGate(input.cwd, input.qualityGateJson)
+			: input.qualityGateJson
+				? await readStructuredValue(input.cwd, input.qualityGateJson)
+				: undefined;
+	if (input.status === "complete" && !input.gjcGoalJson?.trim()) {
+		throw new Error("complete checkpoints require --gjc-goal-json with a fresh get_goal snapshot");
+	}
 	const now = new Date().toISOString();
+	const ledgerBefore = await readUltragoalLedger(input.cwd);
+	const beforeStatus = goal.status;
+	if (input.status === "complete") {
+		const blockedGoalId =
+			typeof goal.steering?.kind === "string" && goal.steering.kind === "review_blocker"
+				? nonEmptyString(goal.steering.blockedGoalId)
+				: null;
+		const blockedGoal = blockedGoalId ? plan.goals.find(item => item.id === blockedGoalId) : undefined;
+		if (blockedGoal?.status === "review_blocked") {
+			blockedGoal.status = "superseded";
+			blockedGoal.evidence = `Resolved by verification blocker story ${goal.id}: ${evidence}`;
+			blockedGoal.updatedAt = now;
+		}
+	}
+	const receiptKind = input.status === "complete" ? chooseReceiptKind(plan, goal, input.status) : null;
+	const pendingCheckpointEventId = crypto.randomUUID();
+	if (input.status === "complete" && receiptKind && qualityGateJson && !Array.isArray(qualityGateJson)) {
+		goal.completionVerification = buildCompletionReceipt({
+			plan,
+			ledger: ledgerBefore,
+			goal,
+			receiptKind,
+			beforeStatus,
+			qualityGateJson: qualityGateJson as JsonObject,
+			now,
+			checkpointLedgerEventId: pendingCheckpointEventId,
+		});
+	}
 	goal.status = input.status;
 	goal.evidence = evidence;
 	goal.updatedAt = now;
@@ -326,12 +638,13 @@ export async function checkpointUltragoalGoal(input: {
 	plan.updatedAt = now;
 	await writePlan(input.cwd, plan);
 	await appendLedger(input.cwd, {
+		eventId: pendingCheckpointEventId,
 		event: "goal_checkpointed",
 		goalId: goal.id,
 		status: input.status,
 		evidence,
 		gjcGoalJson: input.gjcGoalJson ? await readStructuredValue(input.cwd, input.gjcGoalJson) : undefined,
-		qualityGateJson: input.qualityGateJson ? await readStructuredValue(input.cwd, input.qualityGateJson) : undefined,
+		qualityGateJson,
 	});
 	return plan;
 }
@@ -480,7 +793,8 @@ function renderCompleteHandoff(
 		`Ultragoal handoff: ${result.goal.id} — ${result.goal.title}`,
 		`Objective: ${result.goal.objective}`,
 		`GJC objective: ${result.plan.gjcObjective}`,
-		"Call get_goal({}); create_goal only if no active GJC goal exists, then complete this GJC story and checkpoint it.",
+		"Call get_goal({}); create_goal only if no active GJC goal exists, then complete this GJC story.",
+		"Before checkpointing complete, obtain a passing architectReview (architecture/product/code CLEAR + APPROVE) and executorQa (e2e/red-team passed); record blockers instead of completing on any finding.",
 		"",
 	].join("\n");
 }

package/src/goals/tools/goal-tool.ts

@@ -4,6 +4,7 @@ import { Text } from "@gajae-code/tui";
 import { formatNumber, prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
+import { assertCanCompleteCurrentGoal } from "../../gjc-runtime/ultragoal-guard";
 import type { Theme, ThemeColor } from "../../modes/theme/theme";
 import createGoalDescription from "../../prompts/tools/create-goal.md" with { type: "text" };
 import getGoalDescription from "../../prompts/tools/get-goal.md" with { type: "text" };
@@ -128,6 +129,11 @@ async function executeGoalOperation(session: ToolSession, params: GoalToolInput)
 		const dropped = await runtime.dropGoal();
 		return buildGoalToolResponse(dropped ?? null);
 	}
+	try {
+		await assertCanCompleteCurrentGoal({ cwd: session.cwd, currentGoal: session.getGoalModeState?.()?.goal ?? null });
+	} catch (error) {
+		throw new ToolError(error instanceof Error ? error.message : String(error));
+	}
 	const completed = await runtime.completeGoalFromTool();
 	return buildGoalToolResponse(completed, { includeCompletionReport: true });
 }
@@ -135,7 +141,7 @@ async function executeGoalOperation(session: ToolSession, params: GoalToolInput)
 export class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
 	readonly name = "goal";
 	readonly label = "Goal";
-	readonly loadMode = "essential";
+	readonly loadMode = "essential" as const;
 	readonly description = prompt.render(goalDescription);
 	readonly parameters = goalSchema;
 	readonly strict = true;
@@ -161,7 +167,7 @@ export class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
 export class GetGoalTool implements AgentTool<typeof getGoalSchema, GoalToolDetails> {
 	readonly name = "get_goal";
 	readonly label = "Get Goal";
-	readonly loadMode = "essential";
+	readonly loadMode = "essential" as const;
 	readonly description = prompt.render(getGoalDescription);
 	readonly parameters = getGoalSchema;
 	readonly strict = true;
@@ -191,7 +197,7 @@ export class GetGoalTool implements AgentTool<typeof getGoalSchema, GoalToolDeta
 export class CreateGoalTool implements AgentTool<typeof createGoalSchema, GoalToolDetails> {
 	readonly name = "create_goal";
 	readonly label = "Create Goal";
-	readonly loadMode = "essential";
+	readonly loadMode = "essential" as const;
 	readonly description = prompt.render(createGoalDescription);
 	readonly parameters = createGoalSchema;
 	readonly strict = true;
@@ -225,7 +231,7 @@ export class CreateGoalTool implements AgentTool<typeof createGoalSchema, GoalTo
 export class UpdateGoalTool implements AgentTool<typeof updateGoalSchema, GoalToolDetails> {
 	readonly name = "update_goal";
 	readonly label = "Update Goal";
-	readonly loadMode = "essential";
+	readonly loadMode = "essential" as const;
 	readonly description = prompt.render(updateGoalDescription);
 	readonly parameters = updateGoalSchema;
 	readonly strict = true;

package/src/hooks/native-skill-hook.ts

@@ -152,6 +152,16 @@ function readTurnId(payload: HookPayload): string | undefined {
 	return safeString(payload.turn_id ?? payload.turnId).trim() || undefined;
 }
 
+function readSessionFile(payload: HookPayload): string | undefined {
+	return (
+		safeString(
+			payload.session_file ?? payload.sessionFile ?? payload.transcript_path ?? payload.transcriptPath,
+		).trim() ||
+		process.env.GJC_SESSION_FILE?.trim() ||
+		undefined
+	);
+}
+
 export async function dispatchGjcNativeSkillHook(
 	payload: HookPayload,
 	options: GjcNativeHookDispatchOptions = {},
@@ -180,7 +190,22 @@ export async function dispatchGjcNativeSkillHook(
 					sessionId: readSessionId(payload),
 					threadId: readThreadId(payload),
 					stateDir: options.stateDir,
+					prompt,
+					sessionFile: readSessionFile(payload),
 				});
+		if (activeUltragoalContext?.startsWith("BLOCK_ULTRAGOAL_COMPLETION:")) {
+			return {
+				hookEventName,
+				outputJson: {
+					decision: "block",
+					reason: activeUltragoalContext,
+					hookSpecificOutput: {
+						hookEventName,
+						additionalContext: activeUltragoalContext,
+					},
+				},
+			};
+		}
 		return {
 			hookEventName,
 			outputJson:
@@ -205,6 +230,7 @@ export async function dispatchGjcNativeSkillHook(
 				sessionId: readSessionId(payload),
 				threadId: readThreadId(payload),
 				stateDir: options.stateDir,
+				sessionFile: readSessionFile(payload),
 			}),
 		};
 	}

package/src/hooks/skill-state.ts

@@ -1,6 +1,8 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
+import { isUltragoalBypassPrompt, readUltragoalVerificationState } from "../gjc-runtime/ultragoal-guard";
+import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
 import {
 	compareSkillKeywordMatches,
 	GJC_SKILL_KEYWORD_DEFINITIONS,
@@ -124,6 +126,7 @@ export interface StopHookInput {
 	sessionId?: string;
 	threadId?: string;
 	stateDir?: string;
+	sessionFile?: string;
 }
 
 export interface UserPromptSubmitStateInput {
@@ -131,6 +134,8 @@ export interface UserPromptSubmitStateInput {
 	sessionId?: string;
 	threadId?: string;
 	stateDir?: string;
+	prompt?: string;
+	sessionFile?: string;
 }
 
 function escapeRegex(value: string): string {
@@ -361,6 +366,19 @@ function stateMatchesContext(state: ModeState, sessionId?: string, threadId?: st
 	return true;
 }
 
+async function readCurrentGoalObjectiveFromSessionFile(sessionFile: string | undefined): Promise<string | null> {
+	const trimmed = sessionFile?.trim();
+	if (!trimmed) return null;
+	const entries = (await loadEntriesFromFile(trimmed)).filter(
+		(entry): entry is SessionEntry => entry.type !== "session",
+	);
+	const context = buildSessionContext(entries);
+	const goal = context.modeData?.goal;
+	if (typeof goal !== "object" || goal === null) return null;
+	const objective = (goal as { objective?: unknown }).objective;
+	return typeof objective === "string" && objective.trim().length > 0 ? objective.trim() : null;
+}
+
 export async function buildActiveUltragoalPromptContext(input: UserPromptSubmitStateInput): Promise<string | null> {
 	const visibleModeState = await readVisibleModeState(input.cwd, "ultragoal", input.sessionId, input.stateDir);
 	if (!visibleModeState) return null;
@@ -368,6 +386,22 @@ export async function buildActiveUltragoalPromptContext(input: UserPromptSubmitS
 	if (!stateMatchesContext(visibleModeState.state, input.sessionId, input.threadId)) return null;
 
 	const phase = String(visibleModeState.state.current_phase ?? "active");
+	const objective =
+		(await readCurrentGoalObjectiveFromSessionFile(input.sessionFile)) ??
+		(typeof visibleModeState.state.objective === "string"
+			? visibleModeState.state.objective
+			: typeof visibleModeState.state.gjcObjective === "string"
+				? visibleModeState.state.gjcObjective
+				: "");
+	if (input.prompt && isUltragoalBypassPrompt(input.prompt) && objective) {
+		const diagnostic = await readUltragoalVerificationState({
+			cwd: input.cwd,
+			currentGoal: { objective },
+		});
+		if (!["inactive", "unrelated_goal", "active_verified_complete"].includes(diagnostic.state)) {
+			return `BLOCK_ULTRAGOAL_COMPLETION: ${diagnostic.message} Use durable blocker work or run strict \`gjc ultragoal checkpoint --status complete --quality-gate-json <file> --gjc-goal-json <file>\` before completion.`;
+		}
+	}
 	return `Ultragoal is active (phase: ${phase}; state: ${visibleModeState.statePath}). If the user prompt is a steering request, use \`gjc ultragoal steer\` to add or steer subgoals. Normal prose should not mutate Ultragoal state.`;
 }
 
@@ -384,6 +418,31 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 		if (isTerminalModeState(modeState)) continue;
 		const phase = String(modeState?.current_phase ?? entry.phase ?? skillState.phase ?? "active");
 		const statePath = modeStatePath(resolvedStateDir, entry.skill, input.sessionId);
+		if (entry.skill === "ultragoal") {
+			const objective =
+				(await readCurrentGoalObjectiveFromSessionFile(input.sessionFile)) ??
+				(typeof modeState?.objective === "string"
+					? modeState.objective
+					: typeof modeState?.gjcObjective === "string"
+						? modeState.gjcObjective
+						: "");
+			if (objective) {
+				const diagnostic = await readUltragoalVerificationState({
+					cwd: input.cwd,
+					currentGoal: { objective },
+				});
+				if (diagnostic.state === "active_verified_complete") continue;
+				if (!["inactive", "unrelated_goal"].includes(diagnostic.state)) {
+					const ultragoalMessage = `GJC ultragoal verification is blocking stop: ${diagnostic.message} Run strict checkpoint verification or record review blockers before stopping.`;
+					return {
+						decision: "block",
+						reason: ultragoalMessage,
+						stopReason: `gjc_ultragoal_verification_${diagnostic.state}`,
+						systemMessage: ultragoalMessage,
+					};
+				}
+			}
+		}
 		const systemMessage = `GJC skill "${entry.skill}" is still active (phase: ${phase}; state: ${statePath}). Continue or explicitly finish/cancel the skill before stopping.`;
 		return {
 			decision: "block",

package/src/main.ts

@@ -480,21 +480,6 @@ async function maybeAutoChdir(parsed: Args): Promise<void> {
 	}
 }
 
-/** Discover SYSTEM.md file if no CLI system prompt was provided */
-function discoverSystemPromptFile(): string | undefined {
-	// Check project-local first (.gjc/SYSTEM.md, .pi/SYSTEM.md legacy)
-	const projectPath = findConfigFile("SYSTEM.md", { user: false });
-	if (projectPath) {
-		return projectPath;
-	}
-	// If not found, check SYSTEM.md file in the global directory.
-	const globalPath = findConfigFile("SYSTEM.md", { user: true });
-	if (globalPath) {
-		return globalPath;
-	}
-	return undefined;
-}
-
 /** Discover APPEND_SYSTEM.md file if no CLI append system prompt was provided */
 function discoverAppendSystemPromptFile(): string | undefined {
 	const projectPath = findConfigFile("APPEND_SYSTEM.md", { user: false });
@@ -519,8 +504,7 @@ async function buildSessionOptions(
 		cwd: parsed.cwd ?? getProjectDir(),
 	};
 
-	// Auto-discover SYSTEM.md if no CLI system prompt provided
-	const systemPromptSource = parsed.systemPrompt ?? discoverSystemPromptFile();
+	const systemPromptSource = parsed.systemPrompt;
 	const resolvedSystemPrompt = await resolvePromptInput(systemPromptSource, "system prompt");
 	const appendPromptSource = parsed.appendSystemPrompt ?? discoverAppendSystemPromptFile();
 	const resolvedAppendPrompt = await resolvePromptInput(appendPromptSource, "append system prompt");