@gajae-code/coding-agent 0.4.1 → 0.4.2

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -96,11 +96,12 @@ Loop until `gjc ultragoal status` reports all goals complete:
 7. Before any `--status complete` checkpoint, run the mandatory final cleanup/review gate below. In aggregate mode, do **not** call `goal({"op":"complete"})` for intermediate stories; checkpoint each story with a fresh `goal({"op":"get"})` snapshot whose aggregate objective is still `active`. On the final story, use the same fresh active snapshot to create the final aggregate receipt first; only after that receipt exists may `goal({"op":"complete"})` run.
 8. Checkpoint the durable ledger with that fresh active snapshot. Complete checkpoints require `--quality-gate-json`; the runtime hook rejects closure without a clean architect review:
    `gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <goal-get-json-or-path> --quality-gate-json <quality-gate-json-or-path>`
+   A successful complete checkpoint is story completion, not automatic run completion. Read the checkpoint output: when it prints `Next ultragoal goal: <id>`, continue that active story under the same aggregate GJC goal; when it prints `All ultragoal goals are complete`, the durable run is terminal. `gjc ultragoal complete-goals` remains the supported manual next-story command if continuation output was missed.
 9. If blocked or failed, checkpoint failure:
    `gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
-11. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
+10. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
    `gjc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy GJC goal blocks goal create in this thread>" --gjc-goal-json <goal-get-json-or-path>`
-12. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
+11. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
 
 ## Dynamic steering
 

package/src/gjc-runtime/launch-tmux.ts

@@ -48,6 +48,7 @@ export interface TmuxLaunchContext {
 	currentBranch?: string | null;
 	existingBranchSessionName?: string | null;
 	project?: string | null;
+	diagnosticWriter?: (message: string) => void;
 }
 
 export interface TmuxSpawnResult {
@@ -120,6 +121,16 @@ function isInteractiveRootLaunch(parsed: Args, tty: TtyState): boolean {
 	);
 }
 
+function isBunVirtualPath(value: string | undefined): boolean {
+	return value?.startsWith("/$bunfs/") === true;
+}
+
+function formatTmuxLaunchDiagnostic(stage: string, stderr?: string): string {
+	const detail = stderr?.trim();
+	const suffix = detail ? ` ${detail.slice(0, 240)}` : "";
+	return `gjc --tmux failed after creating tmux session: ${stage}.${suffix}\n`;
+}
+
 function shellQuote(value: string): string {
 	if (value.length === 0) return "''";
 	return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -148,6 +159,9 @@ export function applyGjcTmuxProfile(context: GjcTmuxProfileContext): GjcTmuxProf
 function resolveCurrentGjcCommand(context: CommandResolutionContext): string[] {
 	const entrypoint = context.argv[1];
 	if (!entrypoint) return ["gjc"];
+	if (isBunVirtualPath(entrypoint)) {
+		return isBunVirtualPath(context.execPath) ? ["gjc"] : [context.execPath];
+	}
 	const resolvedEntrypoint = path.isAbsolute(entrypoint) ? entrypoint : path.resolve(context.cwd, entrypoint);
 	if (entrypoint.endsWith(".ts") || entrypoint.endsWith(".js") || entrypoint.endsWith(".mjs")) {
 		return [context.execPath, resolvedEntrypoint];
@@ -264,10 +278,19 @@ export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
 		});
 		if (profile.failures.length > 0) {
 			cleanupCreatedTmuxSession(plan, spawnSync, options);
-			return false;
+			const failure =
+				profile.failures.find(item => item.command.args.includes("@gjc-profile")) ?? profile.failures[0];
+			(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
+				formatTmuxLaunchDiagnostic("profile tagging failed", failure?.stderr),
+			);
+			return true;
 		}
 	}
 	if (created.exitCode !== 0) return false;
 	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", plan.sessionName], options);
-	return attached.exitCode === 0;
+	if (attached.exitCode === 0) return true;
+	(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
+		formatTmuxLaunchDiagnostic("attach failed", attached.stderr),
+	);
+	return true;
 }

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

@@ -1673,9 +1673,10 @@ function buildWorkerCommand(config: GjcTeamConfig, worker: GjcTeamWorker): strin
 		`You are ${worker.id} in gjc team ${config.team_name}.`,
 		`Team state root: ${config.state_root}.`,
 		workspace,
-		`Task: ${config.task}`,
+		`Team brief (context only): ${config.task}`,
+		"Before implementation, claim your worker-owned task and treat the claimed task record as the source of truth. Do not implement directly from the broad team brief.",
 		`Before claiming work, send startup ACK: gjc team api worker-startup-ack --input '{"team_name":"${config.team_name}","worker_id":"${worker.id}","protocol_version":"1"}' --json.`,
-		`Use gjc team api update-worker-status to report task-local activity, then claim-task/transition-task-status with this worker id; record completion_evidence (summary plus a passed command or verified inspection/artifact item) before completed, and do not mutate leader-owned goal state.`,
+		`Use gjc team api update-worker-status to report task-local activity, then claim-task/transition-task-status with this worker id; keep heartbeat current during long work, record completion_evidence (summary plus a passed command or verified inspection/artifact item) before completed, and do not mutate leader-owned goal state.`,
 	].join("\n");
 	const env = [
 		`GJC_TEAM_WORKER=${shellQuote(`${config.team_name}/${worker.id}`)}`,
@@ -1689,7 +1690,80 @@ function buildWorkerCommand(config: GjcTeamConfig, worker: GjcTeamWorker): strin
 	];
 	return `${env.join(" ")} ${config.worker_command} ${shellQuote(prompt)}`;
 }
+interface GjcTeamInitialLane {
+	label: string;
+	title: string;
+	body: string;
+}
+
+function normalizeLaneId(label: string): string {
+	return `lane-${sanitizeName(label).toLowerCase() || stableHash(label).slice(0, 8)}`;
+}
+
+function parseExplicitTeamLanes(task: string): GjcTeamInitialLane[] {
+	const lines = task.split(/\r?\n/);
+	const lanes: GjcTeamInitialLane[] = [];
+	let current: { label: string; title: string; body: string[] } | null = null;
+	const laneHeading = /^#{2,6}\s+Lane\s+([A-Za-z0-9]+)\s*(?:[—–-]\s*(.+))?\s*$/;
+	const boundaryHeading = /^#{1,6}\s+(?:Integration Owner|Verification Plan|ADR|Approval State)\b/i;
+
+	for (const line of lines) {
+		const match = line.match(laneHeading);
+		if (match) {
+			if (current) lanes.push({ ...current, body: current.body.join("\n").trim() });
+			current = {
+				label: match[1] ?? `${lanes.length + 1}`,
+				title: (match[2] ?? `Lane ${match[1] ?? lanes.length + 1}`).trim(),
+				body: [],
+			};
+			continue;
+		}
+		if (current && boundaryHeading.test(line)) {
+			lanes.push({ ...current, body: current.body.join("\n").trim() });
+			current = null;
+			continue;
+		}
+		if (current) current.body.push(line);
+	}
+	if (current) lanes.push({ ...current, body: current.body.join("\n").trim() });
+	return lanes.filter(lane => lane.body.length > 0 || lane.title.length > 0);
+}
+
+function hasAmbiguousLaneSplitIntent(task: string): boolean {
+	return (
+		/\bsplit\s+lanes?\s*:/i.test(task) || /\blanes?\s*:\s*[A-Z]\b/i.test(task) || /\bLane\s+[A-Z]\s*[—–-]/.test(task)
+	);
+}
+
 function buildInitialTasks(task: string, workers: GjcTeamWorker[]): GjcTeamTask[] {
+	const lanes = parseExplicitTeamLanes(task);
+	if (lanes.length > 0)
+		return lanes.map((lane, index) => {
+			const worker = workers[index % workers.length];
+			if (!worker) throw new Error("team_lane_requires_worker");
+			const laneTitle = `Lane ${lane.label} — ${lane.title}`;
+			const objective = [`${laneTitle}`, lane.body].filter(part => part.trim().length > 0).join("\n\n");
+			return {
+				id: `task-${index + 1}`,
+				subject: laneTitle,
+				description: objective,
+				title: laneTitle,
+				objective,
+				status: "pending",
+				owner: worker.id,
+				lane: normalizeLaneId(lane.label),
+				required_role: worker.role,
+				version: 1,
+				created_at: now(),
+				updated_at: now(),
+			};
+		});
+
+	if (workers.length > 1 && hasAmbiguousLaneSplitIntent(task))
+		throw new Error(
+			"ambiguous_team_lane_split: multi-worker team launch mentions lanes but does not provide explicit markdown lane sections such as `### Lane A — Title`",
+		);
+
 	return workers.map(worker => ({
 		id: `task-${worker.index}`,
 		subject: `Execute team brief (${worker.id})`,
@@ -2456,6 +2530,7 @@ export async function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTea
 		? { sessionName: "dry-run", windowIndex: "0", leaderPaneId: "%dry-run-leader", target: "dry-run:0" }
 		: readCurrentTmuxLeaderContext(tmuxCommand, env);
 	const initialWorkers = buildWorkers(options.workerCount, options.agentType, stateRoot);
+	const initialTasks = buildInitialTasks(options.task, initialWorkers);
 	const workers: GjcTeamWorker[] = [];
 	try {
 		for (const worker of initialWorkers)
@@ -2509,7 +2584,7 @@ export async function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTea
 		updated_at: createdAt,
 	});
 	await writePhase(dir, "starting");
-	for (const task of buildInitialTasks(options.task, config.workers)) await writeTask(dir, task);
+	for (const task of initialTasks) await writeTask(dir, task);
 	await appendEvent(dir, {
 		type: "team_started",
 		message: options.dryRun

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

@@ -3,6 +3,7 @@ import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import {
 	computeUltragoalPlanGeneration,
 	getUltragoalPaths,
+	getUltragoalRunCompletionState,
 	hashStructuredValue,
 	readUltragoalLedger,
 	readUltragoalPlan,
@@ -246,7 +247,8 @@ export async function readUltragoalVerificationState(input: {
 			message: "Ultragoal has recorded review blockers; complete blocker work and rerun verification.",
 		};
 	}
-	if (plan.goals.some(goal => goal.status === "blocked" || goal.status === "failed")) {
+	const runState = getUltragoalRunCompletionState(plan);
+	if (runState.incompleteGoals.some(goal => goal.status === "blocked" || goal.status === "failed")) {
 		return {
 			state: "active_dirty_quality_gate",
 			message: "Ultragoal has blocked or failed goals; record blockers or rerun verification.",
@@ -259,7 +261,21 @@ export async function readUltragoalVerificationState(input: {
 			message: "Ultragoal aggregate completion requires a fresh final aggregate receipt.",
 		};
 	}
-	return validateCompletionReceipt({ plan, ledger, goal: receiptTarget.goal, receiptKind: receiptTarget.receiptKind });
+	const receiptDiagnostic = validateCompletionReceipt({
+		plan,
+		ledger,
+		goal: receiptTarget.goal,
+		receiptKind: receiptTarget.receiptKind,
+	});
+	if (receiptDiagnostic.state !== "active_verified_complete") return receiptDiagnostic;
+	if (runState.incompleteGoals.length > 0) {
+		return {
+			state: "active_missing_final_receipt",
+			message: `Ultragoal still has incomplete required goals: ${runState.incompleteGoals.map(goal => goal.id).join(", ")}. Run \`gjc ultragoal complete-goals\` to continue.`,
+			goalId: receiptTarget.goal.id,
+		};
+	}
+	return receiptDiagnostic;
 }
 
 export async function assertCanCompleteCurrentGoal(input: {

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

@@ -228,18 +228,35 @@ function planSnapshotForReceipt(input: {
 	goal: UltragoalGoal;
 	beforeStatus: UltragoalGoalStatus;
 	targetGoalUpdatedAt: string;
+	receiptKind: UltragoalReceiptKind;
 }): unknown {
+	const targetGoalSnapshot = {
+		...input.goal,
+		status: input.beforeStatus,
+		updatedAt: input.targetGoalUpdatedAt,
+		evidence: undefined,
+		completedAt: undefined,
+		completionVerification: undefined,
+	};
+	const goals =
+		input.receiptKind === "final-aggregate"
+			? input.plan.goals.map(goal => ({
+					...goal,
+					status: goal.id === input.goal.id ? input.beforeStatus : goal.status,
+					updatedAt: goal.id === input.goal.id ? input.targetGoalUpdatedAt : goal.updatedAt,
+					evidence: goal.id === input.goal.id ? undefined : goal.evidence,
+					completedAt: goal.id === input.goal.id ? undefined : goal.completedAt,
+					completionVerification: undefined,
+				}))
+			: [targetGoalSnapshot];
 	return {
-		...input.plan,
-		updatedAt: undefined,
-		goals: input.plan.goals.map(goal => ({
-			...goal,
-			status: goal.id === input.goal.id ? input.beforeStatus : goal.status,
-			updatedAt: goal.id === input.goal.id ? input.targetGoalUpdatedAt : goal.updatedAt,
-			evidence: goal.id === input.goal.id ? undefined : goal.evidence,
-			completedAt: goal.id === input.goal.id ? undefined : goal.completedAt,
-			completionVerification: undefined,
-		})),
+		version: input.plan.version,
+		brief: input.plan.brief,
+		gjcGoalMode: input.plan.gjcGoalMode,
+		gjcObjective: input.plan.gjcObjective,
+		gjcObjectiveAliases: input.plan.gjcObjectiveAliases,
+		createdAt: input.plan.createdAt,
+		goals,
 	};
 }
 
@@ -264,6 +281,7 @@ export function computeUltragoalPlanGeneration(input: {
 			goal: input.goal,
 			beforeStatus: input.beforeStatus,
 			targetGoalUpdatedAt,
+			receiptKind: input.receiptKind,
 		}),
 	);
 	const requiredGoalSetHashBeforeCheckpoint = hashStructuredValue(
@@ -569,6 +587,31 @@ function chooseNextGoal(plan: UltragoalPlan, retryFailed: boolean): UltragoalGoa
 		(retryFailed ? plan.goals.find(goal => goal.status === "failed") : undefined)
 	);
 }
+export interface UltragoalRunCompletionState {
+	requiredGoals: UltragoalGoal[];
+	incompleteGoals: UltragoalGoal[];
+	nextGoal?: UltragoalGoal;
+	allComplete: boolean;
+	hasBlockers: boolean;
+	needsFinalAggregateReceipt: boolean;
+}
+
+export function getUltragoalRunCompletionState(
+	plan: UltragoalPlan,
+	options: { retryFailed?: boolean } = {},
+): UltragoalRunCompletionState {
+	const requiredGoals = requiredUltragoalGoals(plan);
+	const incompleteGoals = requiredGoals.filter(goal => !TERMINAL_OR_SKIPPED_STATUSES.has(goal.status));
+	const nextGoal = chooseNextGoal(plan, options.retryFailed === true);
+	return {
+		requiredGoals,
+		incompleteGoals,
+		nextGoal,
+		allComplete: requiredGoals.length > 0 && incompleteGoals.length === 0,
+		hasBlockers: incompleteGoals.some(goal => goal.status === "blocked" || goal.status === "review_blocked"),
+		needsFinalAggregateReceipt: plan.gjcGoalMode === "aggregate" && incompleteGoals.length === 0,
+	};
+}
 
 export async function startNextUltragoalGoal(input: { cwd: string; retryFailed?: boolean }): Promise<{
 	plan: UltragoalPlan;
@@ -578,7 +621,7 @@ export async function startNextUltragoalGoal(input: { cwd: string; retryFailed?:
 	const plan = await readUltragoalPlan(input.cwd);
 	if (!plan) throw new Error("No ultragoal plan found. Run `gjc ultragoal create-goals --brief ...` first.");
 	const goal = chooseNextGoal(plan, input.retryFailed === true);
-	if (!goal) return { plan, allComplete: plan.goals.every(item => TERMINAL_OR_SKIPPED_STATUSES.has(item.status)) };
+	if (!goal) return { plan, allComplete: getUltragoalRunCompletionState(plan).allComplete };
 	if (goal.status !== "active") {
 		const now = new Date().toISOString();
 		goal.status = "active";
@@ -639,7 +682,11 @@ function requireObjectArray(value: unknown, fieldName: string): JsonObject[] {
 function requiredStringField(row: JsonObject, key: string, fieldName: string): string {
 	const value = row[key];
 	if (typeof value !== "string" || value.trim().length === 0) {
-		throw new Error(`qualityGate ${fieldName}.${key} must be a non-empty string`);
+		const hint =
+			key === "obligation" && typeof row.description === "string" && row.description.trim().length > 0
+				? "; found description, but complete-checkpoint contractCoverage rows require obligation"
+				: "";
+		throw new Error(`qualityGate ${fieldName}.${key} must be a non-empty string${hint}`);
 	}
 	return value.trim();
 }
@@ -1015,6 +1062,17 @@ async function readRequiredCompletionQualityGate(cwd: string, value: string | un
 	return gate;
 }
 
+function snapshotUpdatedAtMilliseconds(value: unknown): number | null {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value !== "string" || value.trim().length === 0) return null;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) {
+		const parsed = Number.parseInt(trimmed, 10);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	const parsed = Date.parse(trimmed);
+	return Number.isFinite(parsed) ? parsed : null;
+}
 async function readGjcGoalSnapshot(input: {
 	cwd: string;
 	value: string | undefined;
@@ -1026,16 +1084,23 @@ async function readGjcGoalSnapshot(input: {
 }): Promise<unknown> {
 	if (!input.value?.trim()) {
 		if (!input.required) return undefined;
-		throw new Error(`${input.errorPrefix} require --gjc-goal-json from a fresh active goal({"op":"get"}) snapshot`);
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json from a fresh active goal({"op":"get"}) snapshot; this is the GJC goal-mode receipt, not the .gjc/ultragoal/goals.json goal record`,
+		);
 	}
 	const snapshot = await readStructuredValue(input.cwd, input.value);
 	const snapshotObject = qualityGateObject(snapshot);
 	const detailsObject = qualityGateObject(snapshotObject?.details);
 	const goalObject = qualityGateObject(snapshotObject?.goal) ?? qualityGateObject(detailsObject?.goal);
-	if (!goalObject) throw new Error(`${input.errorPrefix} require --gjc-goal-json with a goal object`);
-	const updatedAt = typeof goalObject.updatedAt === "number" ? goalObject.updatedAt : null;
+	if (!goalObject)
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json with a goal object from goal({"op":"get"}); pass the active GJC goal-mode snapshot, not the .gjc/ultragoal/goals.json goal record`,
+		);
+	const updatedAt = snapshotUpdatedAtMilliseconds(goalObject.updatedAt);
 	if (!updatedAt)
-		throw new Error(`${input.errorPrefix} require --gjc-goal-json goal.updatedAt from goal({"op":"get"})`);
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json goal.updatedAt as epoch milliseconds or an ISO timestamp from goal({"op":"get"}); pass the active GJC goal-mode snapshot, not the .gjc/ultragoal/goals.json goal record`,
+		);
 	const nowMilliseconds = Date.now();
 	if (updatedAt < nowMilliseconds - GJC_GOAL_SNAPSHOT_MAX_AGE_MILLISECONDS) {
 		throw new Error(`${input.errorPrefix} require a fresh --gjc-goal-json snapshot`);
@@ -1052,7 +1117,9 @@ async function readGjcGoalSnapshot(input: {
 		return snapshot;
 	}
 	if (!expectedObjectives.has(objective)) {
-		throw new Error(`${input.errorPrefix} require --gjc-goal-json objective to match the active Ultragoal objective`);
+		throw new Error(
+			`${input.errorPrefix} require --gjc-goal-json objective to match the active GJC goal-mode objective from goal({"op":"get"}), not the .gjc/ultragoal/goals.json goal ${input.goal?.id ?? "record"}`,
+		);
 	}
 	if (goalObject.status !== "active") {
 		throw new Error(`${input.errorPrefix} require --gjc-goal-json goal.status to be active`);
@@ -1147,6 +1214,54 @@ export async function checkpointUltragoalGoal(input: {
 	});
 	return plan;
 }
+export interface UltragoalCheckpointContinuation {
+	plan: UltragoalPlan;
+	checkpointedGoal: UltragoalGoal;
+	nextGoal?: UltragoalGoal;
+	startedNext: boolean;
+	allComplete: boolean;
+	incompleteGoals: UltragoalGoal[];
+}
+
+export async function checkpointAndContinueUltragoalGoal(input: {
+	cwd: string;
+	goalId: string;
+	status: UltragoalGoalStatus;
+	evidence: string;
+	gjcGoalJson?: string;
+	qualityGateJson?: string;
+	advanceNext?: boolean;
+	retryFailed?: boolean;
+}): Promise<UltragoalCheckpointContinuation> {
+	let plan = await checkpointUltragoalGoal(input);
+	const checkpointedGoal = plan.goals.find(goal => goal.id === input.goalId);
+	if (!checkpointedGoal) throw new Error(`No ultragoal goal found for ${input.goalId}.`);
+	if (input.status === "complete" && input.advanceNext === true) {
+		const beforeAdvance = getUltragoalRunCompletionState(plan, { retryFailed: input.retryFailed });
+		if (beforeAdvance.nextGoal && beforeAdvance.nextGoal.status !== "active") {
+			const started = await startNextUltragoalGoal({ cwd: input.cwd, retryFailed: input.retryFailed });
+			plan = started.plan;
+			const afterAdvance = getUltragoalRunCompletionState(plan, { retryFailed: input.retryFailed });
+			return {
+				plan,
+				checkpointedGoal,
+				nextGoal: started.goal,
+				startedNext: Boolean(started.goal),
+				allComplete: afterAdvance.allComplete,
+				incompleteGoals: afterAdvance.incompleteGoals,
+			};
+		}
+	}
+	const state = getUltragoalRunCompletionState(plan, { retryFailed: input.retryFailed });
+	return {
+		plan,
+		checkpointedGoal,
+		nextGoal: state.nextGoal,
+		startedNext: false,
+		allComplete: state.allComplete,
+		incompleteGoals: state.incompleteGoals,
+	};
+}
 
 export async function addUltragoalSubgoal(input: {
 	cwd: string;
@@ -1235,6 +1350,8 @@ function hasFlag(args: readonly string[], flag: string): boolean {
 	return args.includes(flag);
 }
 
+const HELP_FLAGS = new Set(["--help", "-h"]);
+
 const FLAGS_WITH_VALUES = new Set([
 	"--brief",
 	"--brief-file",
@@ -1250,6 +1367,10 @@ const FLAGS_WITH_VALUES = new Set([
 	"--rationale",
 ]);
 
+function isHelpArg(arg: string): boolean {
+	return HELP_FLAGS.has(arg);
+}
+
 function commandName(args: readonly string[]): string {
 	let skipNext = false;
 	for (const arg of args) {
@@ -1261,11 +1382,62 @@ function commandName(args: readonly string[]): string {
 			skipNext = true;
 			continue;
 		}
+		if (isHelpArg(arg)) continue;
 		if (!arg.startsWith("-")) return arg;
 	}
 	return "status";
 }
 
+function renderUltragoalHelp(args: readonly string[]): string | null {
+	if (!args.some(isHelpArg) && args[0] !== "help") return null;
+	const subject =
+		args[0] === "help" ? args.find((arg, index) => index > 0 && !arg.startsWith("-")) : commandName(args);
+	if (subject === "checkpoint") {
+		return [
+			"Run native GJC Ultragoal workflow commands",
+			"",
+			"USAGE",
+			"  $ gjc ultragoal checkpoint --goal-id <id> --status <status> --evidence <text> [FLAGS]",
+			"",
+			"FLAGS",
+			"      --goal-id=<value>            Durable .gjc/ultragoal goal id, e.g. G001",
+			"      --status=<value>             pending|active|complete|failed|blocked|review_blocked|superseded",
+			"      --evidence=<value>           Completion or checkpoint evidence text",
+			"      --quality-gate-json=<value>  JSON string or path for complete checkpoints",
+			'      --gjc-goal-json=<value>      JSON string or path containing the current goal({"op":"get"}) snapshot',
+			"      --json                       Output a machine-readable receipt",
+			"",
+			"COMPLETE CHECKPOINT RECEIPTS",
+			"  --quality-gate-json must be an object with architectReview, executorQa, and iteration.",
+			"  executorQa.contractCoverage[] rows require an obligation field; description is not a substitute.",
+			'  --gjc-goal-json must contain the active GJC goal-mode snapshot from goal({"op":"get"}), not the .gjc/ultragoal/goals.json goal record.',
+			"  goal.updatedAt may be epoch milliseconds or an ISO timestamp and must be fresh.",
+			"",
+			"EXAMPLES",
+			'  $ gjc ultragoal checkpoint --goal-id G001 --status blocked --evidence "waiting on review"',
+			'  $ gjc ultragoal checkpoint --goal-id G001 --status complete --evidence "tests passed" --gjc-goal-json ./goal.json --quality-gate-json ./quality-gate.json --json',
+			"",
+		].join("\n");
+	}
+	return [
+		"Run native GJC Ultragoal workflow commands",
+		"",
+		"USAGE",
+		"  $ gjc ultragoal <command> [FLAGS]",
+		"",
+		"COMMANDS",
+		"  status",
+		"  create-goals",
+		"  complete-goals",
+		"  checkpoint",
+		"  steer",
+		"  record-review-blockers",
+		"",
+		"Run `gjc ultragoal checkpoint --help` for complete checkpoint receipt requirements.",
+		"",
+	].join("\n");
+}
+
 async function readBrief(cwd: string, args: readonly string[]): Promise<string> {
 	const inline = flagValue(args, "--brief");
 	if (inline !== undefined) return inline;
@@ -1306,8 +1478,54 @@ function renderCompleteHandoff(
 		"",
 	].join("\n");
 }
+function renderCheckpointContinuation(
+	result: UltragoalCheckpointContinuation,
+	status: UltragoalGoalStatus,
+	json: boolean,
+	cwd: string,
+): string {
+	if (json)
+		return renderCliWriteReceipt({
+			ok: true,
+			goal_id: result.checkpointedGoal.id,
+			status,
+			goals_path: getUltragoalPaths(cwd).goalsPath,
+			completion_receipt_kind: result.checkpointedGoal.completionVerification?.receiptKind,
+			quality_gate_hash: result.checkpointedGoal.completionVerification?.qualityGateHash,
+			all_complete: result.allComplete,
+			next_goal_id: result.nextGoal?.id,
+			next_goal_status: result.nextGoal?.status,
+			started_next: result.startedNext,
+			incomplete_goal_ids: result.incompleteGoals.map(goal => goal.id),
+		});
+	const lines = [`Checkpointed ${result.checkpointedGoal.id} as ${status}.`];
+	if (status === "complete") {
+		if (result.allComplete) {
+			lines.push("All ultragoal goals are complete.");
+		} else if (result.nextGoal) {
+			lines.push(`Next ultragoal goal: ${result.nextGoal.id} — ${result.nextGoal.title}`);
+			lines.push(`Objective: ${result.nextGoal.objective}`);
+			lines.push(`GJC objective: ${result.plan.gjcObjective}`);
+			lines.push(
+				result.startedNext
+					? "The next ultragoal goal is active; continue the current aggregate GJC goal and checkpoint this story when verified."
+					: "Run `gjc ultragoal complete-goals` to activate the next ultragoal story.",
+			);
+		}
+	} else if (status === "failed") {
+		lines.push("Resume failed goals with `gjc ultragoal complete-goals --retry-failed` after the blocker is fixed.");
+	} else if (status === "blocked" || status === "review_blocked") {
+		lines.push(
+			"Blocked ultragoal work must be resolved with explicit blocker work or steering before final completion.",
+		);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
 
 async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<UltragoalCommandResult> {
+	const help = renderUltragoalHelp(args);
+	if (help) return { status: 0, stdout: help };
 	try {
 		const command = commandName(args);
 		const json = hasFlag(args, "--json");
@@ -1344,27 +1562,18 @@ async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<Ul
 				const goalId = flagValue(args, "--goal-id") ?? "";
 				const status = parseGoalStatus(flagValue(args, "--status"));
 				const evidence = flagValue(args, "--evidence") ?? "";
-				const plan = await checkpointUltragoalGoal({
+				const result = await checkpointAndContinueUltragoalGoal({
 					cwd,
 					goalId,
 					status,
 					evidence,
 					gjcGoalJson: flagValue(args, "--gjc-goal-json"),
 					qualityGateJson: flagValue(args, "--quality-gate-json"),
+					advanceNext: status === "complete",
 				});
-				const goal = plan.goals.find(item => item.id === goalId);
 				return {
 					status: 0,
-					stdout: json
-						? renderCliWriteReceipt({
-								ok: true,
-								goal_id: goalId,
-								status,
-								goals_path: getUltragoalPaths(cwd).goalsPath,
-								completion_receipt_kind: goal?.completionVerification?.receiptKind,
-								quality_gate_hash: goal?.completionVerification?.qualityGateHash,
-							})
-						: `ultragoal checkpoint goal-id=${goalId} status=${status}\n`,
+					stdout: renderCheckpointContinuation(result, status, json, cwd),
 				};
 			}
 			case "steer": {
@@ -1469,7 +1678,8 @@ async function reconcileUltragoalState(cwd: string): Promise<void> {
 export async function runNativeUltragoalCommand(args: string[], cwd = process.cwd()): Promise<UltragoalCommandResult> {
 	const command = commandName(args);
 	const result = await dispatchUltragoalCommand(args, cwd);
-	if (result.status === 0 && RECONCILE_COMMANDS.has(command)) {
+	const isHelp = args.some(isHelpArg) || args[0] === "help";
+	if (!isHelp && result.status === 0 && RECONCILE_COMMANDS.has(command)) {
 		await reconcileUltragoalState(cwd);
 	}
 	return result;