@gajae-code/coding-agent 0.3.0 → 0.3.2

package/src/gjc-runtime/deep-interview-runtime.ts

@@ -2,12 +2,12 @@ import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import { Settings } from "../config/settings";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildDeepInterviewHudSummary } from "../skill-state/workflow-hud";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 import { runNativeRalplanCommand } from "./ralplan-runtime";
 import { runNativeStateCommand } from "./state-runtime";
-import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
+import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
 
 /**
  * Native implementation of `gjc deep-interview`.
@@ -96,16 +96,6 @@ function deepInterviewStatePath(cwd: string, sessionId: string | undefined): str
 	return path.join(stateDirFor(cwd, sessionId), "deep-interview-state.json");
 }
 
-async function readJsonObject(filePath: string): Promise<Record<string, unknown>> {
-	try {
-		const parsed = JSON.parse(await fs.readFile(filePath, "utf-8"));
-		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
-	} catch {
-		// Missing/corrupt state should not prevent the sanctioned persistence CLI from writing a receipt.
-	}
-	return {};
-}
-
 async function resolveSpecContent(rawSpec: string, cwd: string): Promise<string> {
 	const candidate = path.isAbsolute(rawSpec) ? rawSpec : path.resolve(cwd, rawSpec);
 	try {
@@ -145,6 +135,7 @@ export interface ResolvedDeepInterviewSpecWriteArgs {
 	json: boolean;
 	deliberate: boolean;
 	handoff?: "ralplan";
+	force: boolean;
 }
 
 export interface PersistedDeepInterviewSpec {
@@ -162,6 +153,8 @@ interface DeepInterviewSpecWriteSummary {
 	slug: string;
 	path: string;
 	sha256: string;
+	spec_path: string;
+	sha: string;
 	created_at: string;
 	state_path: string;
 	handoff?: {
@@ -197,11 +190,16 @@ async function readSettingsAmbiguityThreshold(
 	return { threshold: candidate, source: settingsPath };
 }
 
-async function readModernSettingsAmbiguityThreshold(
-	cwd: string,
-): Promise<{ threshold: number; source: string } | undefined> {
-	const settings = await Settings.init({ cwd });
-	const modernConfigPath = path.join(settings.getAgentDir(), "config.yml");
+function modernSettingsPath(): string {
+	const configDir = process.env.GJC_CODING_AGENT_DIR?.trim() || process.env.PI_CODING_AGENT_DIR?.trim();
+	if (configDir) return path.join(configDir, "config.yml");
+	const configRoot = process.env.GJC_CONFIG_DIR?.trim() || process.env.PI_CONFIG_DIR?.trim();
+	if (configRoot) return path.join(configRoot, "agent", "config.yml");
+	return path.join(os.homedir(), ".gjc", "agent", "config.yml");
+}
+
+async function readModernSettingsAmbiguityThreshold(): Promise<{ threshold: number; source: string } | undefined> {
+	const modernConfigPath = modernSettingsPath();
 	let parsed: unknown;
 	try {
 		parsed = (await import("bun")).YAML.parse(await fs.readFile(modernConfigPath, "utf-8"));
@@ -218,7 +216,7 @@ async function readModernSettingsAmbiguityThreshold(
 async function resolveConfiguredAmbiguityThreshold(
 	cwd: string,
 ): Promise<{ threshold: number; source: string } | undefined> {
-	const modernValue = await readModernSettingsAmbiguityThreshold(cwd);
+	const modernValue = await readModernSettingsAmbiguityThreshold();
 	if (modernValue) return modernValue;
 	const projectSettings = path.join(cwd, ".gjc", "settings.json");
 	const projectValue = await readSettingsAmbiguityThreshold(projectSettings);
@@ -292,6 +290,7 @@ async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promi
 		"--handoff",
 		"--deliberate",
 		"--json",
+		"--force",
 	]);
 	let skipNext = false;
 	for (const arg of args) {
@@ -315,6 +314,7 @@ async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promi
 		sessionId,
 		json: hasFlag(args, "--json"),
 		deliberate: hasFlag(args, "--deliberate"),
+		force: hasFlag(args, "--force"),
 		handoff: rawHandoff as "ralplan" | undefined,
 	};
 }
@@ -388,6 +388,16 @@ export async function persistDeepInterviewSpec(
 	cwd: string,
 	resolved: ResolvedDeepInterviewSpecWriteArgs,
 ): Promise<PersistedDeepInterviewSpec> {
+	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
+	const existingRead = await readExistingStateForMutation(statePath);
+	if (existingRead.kind === "corrupt" && !resolved.force) {
+		throw new DeepInterviewCommandError(
+			2,
+			`existing deep-interview state is corrupt or tampered (${existingRead.error}); use --force to overwrite ${statePath}`,
+		);
+	}
+	const existing = existingRead.kind === "valid" ? existingRead.value : {};
+
 	const specPath = path.join(cwd, ".gjc", "specs", `deep-interview-${resolved.slug}.md`);
 	const content = resolved.spec.endsWith("\n") ? resolved.spec : `${resolved.spec}\n`;
 	await writeArtifact(specPath, content, {
@@ -403,14 +413,12 @@ export async function persistDeepInterviewSpec(
 		{ cwd, audit: { category: "ledger", verb: "append", owner: "gjc-runtime", skill: "deep-interview" } },
 	);
 
-	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
-	const existing = await readJsonObject(statePath);
 	const payload: Record<string, unknown> = {
 		...existing,
 		active: true,
 		current_phase: "handoff",
 		skill: "deep-interview",
-		version: typeof existing.version === "number" ? existing.version : 1,
+		version: WORKFLOW_STATE_VERSION,
 		spec_slug: resolved.slug,
 		spec_path: specPath,
 		spec_sha256: sha256,
@@ -419,9 +427,23 @@ export async function persistDeepInterviewSpec(
 		updated_at: createdAt,
 	};
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await writeJsonAtomic(statePath, payload, {
+	await writeWorkflowEnvelopeAtomic(statePath, payload, {
 		cwd,
-		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "deep-interview" },
+		receipt: {
+			cwd,
+			skill: "deep-interview",
+			owner: "gjc-runtime",
+			command: "gjc deep-interview persist-spec-state",
+			sessionId: resolved.sessionId,
+			nowIso: createdAt,
+		},
+		audit: {
+			category: "state",
+			verb: "write",
+			owner: "gjc-runtime",
+			skill: "deep-interview",
+			forced: resolved.force,
+		},
 	});
 	await syncDeepInterviewHud({
 		cwd,
@@ -447,6 +469,7 @@ async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepIntervi
 		active: true,
 		current_phase: "interviewing",
 		skill: "deep-interview",
+		version: WORKFLOW_STATE_VERSION,
 		resolution: resolved.resolution,
 		threshold: resolved.threshold,
 		threshold_source: resolved.thresholdSource,
@@ -464,8 +487,16 @@ async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepIntervi
 		(payload.state as Record<string, unknown>).language = resolved.language;
 	}
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await writeJsonAtomic(statePath, payload, {
+	await writeWorkflowEnvelopeAtomic(statePath, payload, {
 		cwd,
+		receipt: {
+			cwd,
+			skill: "deep-interview",
+			owner: "gjc-runtime",
+			command: "gjc deep-interview seed",
+			sessionId: resolved.sessionId,
+			nowIso: now,
+		},
 		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "deep-interview" },
 	});
 	return statePath;
@@ -512,6 +543,8 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 		slug: persisted.slug,
 		path: persisted.path,
 		sha256: persisted.sha256,
+		spec_path: persisted.path,
+		sha: persisted.sha256,
 		created_at: persisted.createdAt,
 		state_path: persisted.statePath,
 	};
@@ -549,10 +582,14 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 	}
 
 	const stdout = resolved.json
-		? `${JSON.stringify(summary, null, 2)}\n`
+		? `${JSON.stringify(summary)}\n`
 		: [
-				`Persisted deep-interview ${persisted.stage} spec at ${persisted.path}.`,
-				shouldHandoff ? "Handed off deep-interview to ralplan (deliberate)." : undefined,
+				`deep-interview spec_path=${persisted.path}`,
+				`sha=${persisted.sha256}`,
+				`state_path=${persisted.statePath}`,
+				shouldHandoff
+					? `handoff=ralplan run_id=${summary.handoff?.run_id ?? ""} state_path=${summary.handoff?.state_path ?? ""}`
+					: undefined,
 				"",
 			]
 				.filter((line): line is string => Boolean(line))
@@ -591,14 +628,14 @@ export async function runNativeDeepInterviewCommand(
 			idea: resolved.idea,
 			language: resolved.language,
 			state_path: statePath,
-			handoff: "Run `/skill:deep-interview` inside the GJC agent to drive the Socratic interview loop.",
+			handoff: "/skill:deep-interview",
 		};
 		const stdout = resolved.json
-			? `${JSON.stringify(summary, null, 2)}\n`
+			? `${JSON.stringify(summary)}\n`
 			: [
-					`Seeded deep-interview ${resolved.resolution} run at ${statePath}.`,
-					`Threshold: ${(resolved.threshold * 100).toFixed(0)}% (source: ${resolved.thresholdSource}).`,
-					"Run `/skill:deep-interview` inside the GJC agent to execute the interview.",
+					`deep-interview seed state_path=${statePath}`,
+					`resolution=${resolved.resolution} threshold=${resolved.threshold} threshold_source=${resolved.thresholdSource}`,
+					"handoff=/skill:deep-interview",
 					"",
 				].join("\n");
 		return { status: 0, stdout };

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

@@ -3,8 +3,11 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildRalplanHudSummary } from "../skill-state/workflow-hud";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
+import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
-import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
+import { migrateWorkflowState } from "./state-migrations";
+import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
 
 /**
  * Native implementation of `gjc ralplan`.
@@ -39,6 +42,17 @@ const KNOWN_CRITIC_KINDS = new Set(["openai-code"]);
 
 const PATH_COMPONENT_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 
+const SUBAGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+
+const KNOWN_FALLBACK_REASONS = new Set([
+	"context_unavailable",
+	"not_found",
+	"no_runner",
+	"resume_failed",
+	"process_restart",
+	"missing_record",
+]);
+
 class RalplanCommandError extends Error {
 	constructor(
 		public readonly exitStatus: number,
@@ -57,6 +71,12 @@ const VALUE_FLAGS = new Set([
 	"--session-id",
 	"--architect",
 	"--critic",
+	"--planner-id",
+	"--planner-resumable",
+	"--fallback-reason",
+	"--fallback-attempted-id",
+	"--fallback-stage-n",
+	"--fallback-receipt-path",
 ]);
 
 function flagValue(args: readonly string[], flag: string): string | undefined {
@@ -145,37 +165,188 @@ function ralplanStatePath(cwd: string, sessionId: string | undefined): string {
 }
 
 async function readActiveRunId(cwd: string, sessionId: string | undefined): Promise<string | undefined> {
-	try {
-		const raw = await fs.readFile(ralplanStatePath(cwd, sessionId), "utf-8");
-		const parsed = JSON.parse(raw) as { run_id?: unknown };
-		const candidate = typeof parsed.run_id === "string" ? parsed.run_id.trim() : "";
-		if (!candidate) return undefined;
-		assertSafePathComponent(candidate, "run-id");
-		return candidate;
-	} catch {
-		return undefined;
+	const statePath = ralplanStatePath(cwd, sessionId);
+	const existingRead = await readExistingStateForMutation(statePath);
+	if (existingRead.kind === "absent") return undefined;
+	if (existingRead.kind === "corrupt") {
+		throw new RalplanCommandError(
+			2,
+			`existing ralplan state is corrupt or tampered (${existingRead.error}); refusing to overwrite ${statePath}`,
+		);
 	}
+	const candidate = typeof existingRead.value.run_id === "string" ? existingRead.value.run_id.trim() : "";
+	if (!candidate) return undefined;
+	assertSafePathComponent(candidate, "run-id");
+	return candidate;
 }
 
 async function persistActiveRunId(cwd: string, sessionId: string | undefined, runId: string): Promise<void> {
 	const statePath = ralplanStatePath(cwd, sessionId);
-	let existing: Record<string, unknown> = {};
-	try {
-		const raw = await fs.readFile(statePath, "utf-8");
-		const parsed = JSON.parse(raw);
-		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-			existing = parsed as Record<string, unknown>;
-		}
-	} catch {
-		// fresh receipt; fall through to create
+	const existingRead = await readExistingStateForMutation(statePath);
+	if (existingRead.kind === "corrupt") {
+		throw new RalplanCommandError(
+			2,
+			`existing ralplan state is corrupt or tampered (${existingRead.error}); refusing to overwrite ${statePath}`,
+		);
 	}
-	if (existing.run_id === runId) return;
+	let existing: Record<string, unknown> = existingRead.kind === "valid" ? existingRead.value : {};
+
+	if (existing.run_id === runId && existing.version === WORKFLOW_STATE_VERSION) return;
 	existing.run_id = runId;
 	if (typeof existing.skill !== "string") existing.skill = "ralplan";
 	if (typeof existing.active !== "boolean") existing.active = true;
+	if (typeof existing.current_phase !== "string") existing.current_phase = "planner";
+	existing = migrateWorkflowState(existing, "ralplan").state;
 	existing.updated_at = new Date().toISOString();
-	await writeJsonAtomic(statePath, existing, {
+	await writeWorkflowEnvelopeAtomic(statePath, existing, {
 		cwd,
+		receipt: { cwd, skill: "ralplan", owner: "gjc-runtime", command: "gjc ralplan persist-run-id", sessionId },
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+	});
+}
+
+/* --------------------------- planner run-state --------------------------- */
+
+interface PlannerStateUpdate {
+	subagentId?: string;
+	resumable?: boolean;
+	fallbackReason?: string;
+	fallbackAttemptedId?: string;
+	fallbackStageN?: number;
+	fallbackReceiptPath?: string;
+}
+
+function parseBooleanFlag(raw: string, flag: string): boolean {
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	throw new RalplanCommandError(2, `invalid ${flag}: ${raw}. Expected "true" or "false".`);
+}
+
+function assertSubagentId(value: string, label: string): void {
+	if (!SUBAGENT_ID_RE.test(value)) {
+		throw new RalplanCommandError(2, `invalid ${label}: ${value}`);
+	}
+}
+
+function plannerFlagValue(args: readonly string[], flag: string): string | undefined {
+	const value = flagValue(args, flag);
+	if (value === undefined && hasFlag(args, flag)) {
+		throw new RalplanCommandError(2, `missing value for ${flag}.`);
+	}
+	return value;
+}
+
+/**
+ * Parse the optional persisted-Planner metadata flags that may ride alongside a
+ * `--write`. Returns `undefined` when none are present so existing writes are
+ * unaffected. Throws `RalplanCommandError` on any malformed value. This records
+ * a same-session audit/routing hint, not a durable subagent registry.
+ */
+function parsePlannerStateArgs(args: readonly string[]): PlannerStateUpdate | undefined {
+	const subagentId = plannerFlagValue(args, "--planner-id");
+	const resumableRaw = plannerFlagValue(args, "--planner-resumable");
+	const fallbackReason = plannerFlagValue(args, "--fallback-reason");
+	const fallbackAttemptedId = plannerFlagValue(args, "--fallback-attempted-id");
+	const fallbackStageNRaw = plannerFlagValue(args, "--fallback-stage-n");
+	const fallbackReceiptPath = plannerFlagValue(args, "--fallback-receipt-path");
+
+	const anyPresent = [
+		subagentId,
+		resumableRaw,
+		fallbackReason,
+		fallbackAttemptedId,
+		fallbackStageNRaw,
+		fallbackReceiptPath,
+	].some(value => value !== undefined);
+	if (!anyPresent) return undefined;
+
+	const update: PlannerStateUpdate = {};
+
+	if (subagentId !== undefined) {
+		assertSubagentId(subagentId, "--planner-id");
+		update.subagentId = subagentId;
+	}
+	if (resumableRaw !== undefined) {
+		update.resumable = parseBooleanFlag(resumableRaw, "--planner-resumable");
+	}
+
+	const anyFallback = [fallbackReason, fallbackAttemptedId, fallbackStageNRaw, fallbackReceiptPath].some(
+		value => value !== undefined,
+	);
+	if (anyFallback) {
+		if (!fallbackReason) {
+			throw new RalplanCommandError(2, "--fallback-reason is required when recording planner fallback metadata.");
+		}
+		if (!KNOWN_FALLBACK_REASONS.has(fallbackReason)) {
+			throw new RalplanCommandError(
+				2,
+				`invalid --fallback-reason: ${fallbackReason}. Expected one of: ${[...KNOWN_FALLBACK_REASONS].join(", ")}.`,
+			);
+		}
+		update.fallbackReason = fallbackReason;
+		if (fallbackAttemptedId === undefined) {
+			throw new RalplanCommandError(
+				2,
+				"--fallback-attempted-id is required when recording planner fallback metadata.",
+			);
+		}
+		assertSubagentId(fallbackAttemptedId, "--fallback-attempted-id");
+		update.fallbackAttemptedId = fallbackAttemptedId;
+		if (fallbackStageNRaw === undefined) {
+			throw new RalplanCommandError(2, "--fallback-stage-n is required when recording planner fallback metadata.");
+		}
+		update.fallbackStageN = parseStageN(fallbackStageNRaw);
+		if (fallbackReceiptPath !== undefined) {
+			if (fallbackReceiptPath.trim() === "") {
+				throw new RalplanCommandError(2, "--fallback-receipt-path must not be empty.");
+			}
+			update.fallbackReceiptPath = fallbackReceiptPath;
+		}
+	}
+
+	return update;
+}
+
+/** Snake-case projection of a PlannerStateUpdate for state JSON + receipts. Omitted fields stay absent — an unknown `planner_resumable` is encoded by omission, never literal null. */
+function plannerStatePayload(update: PlannerStateUpdate): Record<string, unknown> {
+	const payload: Record<string, unknown> = {};
+	if (update.subagentId !== undefined) payload.planner_subagent_id = update.subagentId;
+	if (update.resumable !== undefined) payload.planner_resumable = update.resumable;
+	if (update.fallbackReason !== undefined) payload.planner_fallback_reason = update.fallbackReason;
+	if (update.fallbackAttemptedId !== undefined) payload.planner_fallback_attempted_id = update.fallbackAttemptedId;
+	if (update.fallbackStageN !== undefined) payload.planner_fallback_stage_n = update.fallbackStageN;
+	if (update.fallbackReceiptPath !== undefined) payload.planner_fallback_receipt_path = update.fallbackReceiptPath;
+	return payload;
+}
+
+/**
+ * Merge persisted-Planner metadata into the ralplan run-state JSON. Same-session
+ * audit/routing hint only — it records what the caller has already proven and is
+ * NOT a durable cross-process subagent registry.
+ */
+async function applyPlannerStateUpdate(
+	cwd: string,
+	sessionId: string | undefined,
+	update: PlannerStateUpdate,
+): Promise<void> {
+	const statePath = ralplanStatePath(cwd, sessionId);
+	const existingRead = await readExistingStateForMutation(statePath);
+	if (existingRead.kind === "corrupt") {
+		throw new RalplanCommandError(
+			2,
+			`existing ralplan state is corrupt or tampered (${existingRead.error}); refusing to overwrite ${statePath}`,
+		);
+	}
+	let existing: Record<string, unknown> = existingRead.kind === "valid" ? existingRead.value : {};
+	Object.assign(existing, plannerStatePayload(update));
+	if (typeof existing.skill !== "string") existing.skill = "ralplan";
+	if (typeof existing.active !== "boolean") existing.active = true;
+	if (typeof existing.current_phase !== "string") existing.current_phase = "planner";
+	existing = migrateWorkflowState(existing, "ralplan").state;
+	existing.updated_at = new Date().toISOString();
+	await writeWorkflowEnvelopeAtomic(statePath, existing, {
+		cwd,
+		receipt: { cwd, skill: "ralplan", owner: "gjc-runtime", command: "gjc ralplan planner-state", sessionId },
 		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
 	});
 }
@@ -296,8 +467,12 @@ async function syncRalplanHud(options: {
 }
 
 async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
+	const plannerState = parsePlannerStateArgs(args);
 	const resolved = await resolveArtifactArgs(args, cwd);
 	const persisted = await persistArtifact(resolved, cwd);
+	if (plannerState) {
+		await applyPlannerStateUpdate(cwd, resolved.sessionId, plannerState);
+	}
 	await syncRalplanHud({
 		cwd,
 		sessionId: resolved.sessionId,
@@ -315,6 +490,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		created_at: persisted.createdAt,
 	};
 	if (persisted.pendingApprovalPath) payload.pending_approval_path = persisted.pendingApprovalPath;
+	if (plannerState) payload.planner_state = plannerStatePayload(plannerState);
 	const stdout = resolved.json
 		? `${JSON.stringify(payload, null, 2)}\n`
 		: `Persisted ralplan ${persisted.stage} stage ${persisted.stageN} at ${persisted.path}.\n`;
@@ -406,6 +582,7 @@ async function seedRalplanState(
 		active: true,
 		current_phase: "planner",
 		skill: "ralplan",
+		version: WORKFLOW_STATE_VERSION,
 		mode: resolved.deliberate ? "deliberate" : "short",
 		interactive: resolved.interactive,
 		task: resolved.task,
@@ -415,8 +592,15 @@ async function seedRalplanState(
 	if (resolved.architectKind) payload.architect_kind = resolved.architectKind;
 	if (resolved.criticKind) payload.critic_kind = resolved.criticKind;
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await writeJsonAtomic(statePath, payload, {
+	await writeWorkflowEnvelopeAtomic(statePath, payload, {
 		cwd,
+		receipt: {
+			cwd,
+			skill: "ralplan",
+			owner: "gjc-runtime",
+			command: "gjc ralplan seed",
+			sessionId: resolved.sessionId,
+		},
 		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
 	});
 	return { statePath, runId };
@@ -441,26 +625,19 @@ async function handleConsensusHandoff(args: readonly string[], cwd: string): Pro
 	const summary = {
 		skill: "ralplan",
 		mode,
-		interactive: resolved.interactive,
-		architect: resolved.architectKind ?? "default",
-		critic: resolved.criticKind ?? "default",
-		task: resolved.task,
 		state_path: statePath,
 		run_id: runId,
-		handoff: "Run `/skill:ralplan` inside the GJC agent to drive the Planner / Architect / Critic consensus loop.",
+		handoff: "/skill:ralplan",
 	};
 	const stdout = resolved.json
-		? `${JSON.stringify(summary, null, 2)}\n`
+		? renderCliWriteReceipt({ ok: true, ...summary })
 		: [
-				`Seeded ralplan ${summary.mode} run (${resolved.interactive ? "interactive" : "automated"}) at ${statePath}.`,
-				`Active run_id: ${runId}`,
-				resolved.architectKind ? `Architect: ${resolved.architectKind}` : undefined,
-				resolved.criticKind ? `Critic: ${resolved.criticKind}` : undefined,
-				"Run `/skill:ralplan` inside the GJC agent to execute the consensus loop.",
+				`ralplan seed run_id=${runId}`,
+				`state_path=${statePath}`,
+				`mode=${mode} interactive=${resolved.interactive} architect=${resolved.architectKind ?? "default"} critic=${resolved.criticKind ?? "default"}`,
+				"handoff=/skill:ralplan",
 				"",
-			]
-				.filter((line): line is string => Boolean(line))
-				.join("\n");
+			].join("\n");
 	return { status: 0, stdout };
 }
 

package/src/gjc-runtime/state-migrations.ts

@@ -1,7 +1,11 @@
 import * as fs from "node:fs/promises";
 import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
-import { canonicalWorkflowSkill, WORKFLOW_STATE_RECEIPT_VERSION } from "../skill-state/workflow-state-contract";
+import {
+	canonicalWorkflowSkill,
+	WORKFLOW_STATE_RECEIPT_VERSION,
+	WORKFLOW_STATE_VERSION,
+} from "../skill-state/workflow-state-contract";
 import { writeWorkflowEnvelopeAtomic } from "./state-writer";
 import { getSkillManifest } from "./workflow-manifest";
 
@@ -21,6 +25,17 @@ export interface MigrateAndPersistLegacyStateResult {
 	migrated: boolean;
 	path: string;
 }
+export interface MigrateWorkflowStateResult {
+	state: Record<string, unknown>;
+	fromVersion: number;
+	toVersion: number;
+	changed: boolean;
+}
+
+export type WorkflowStateMigration = (
+	state: Record<string, unknown>,
+	skill: CanonicalGjcWorkflowSkill,
+) => Record<string, unknown>;
 
 const RECEIPT_STRING_FIELDS = [
 	"command",
@@ -75,6 +90,41 @@ function receiptWithRequiredFields(raw: unknown, skill: CanonicalGjcWorkflowSkil
 function recordsEqual(left: Record<string, unknown>, right: Record<string, unknown>): boolean {
 	return JSON.stringify(left) === JSON.stringify(right);
 }
+function migrateV1ToV2(state: Record<string, unknown>, skill: CanonicalGjcWorkflowSkill): Record<string, unknown> {
+	const migrated = cloneRecord(state);
+	migrated.version = WORKFLOW_STATE_VERSION;
+	migrated.skill = skill;
+
+	const sourcePhase = typeof migrated.current_phase === "string" ? migrated.current_phase : migrated.phase;
+	const normalizedPhase = normalizePhase(skill, sourcePhase);
+	migrated.current_phase = normalizedPhase;
+	if ("phase" in migrated && typeof migrated.phase === "string") migrated.phase = normalizedPhase;
+
+	return migrated;
+}
+
+const MIGRATIONS: Record<number, WorkflowStateMigration> = {
+	1: migrateV1ToV2,
+};
+
+export function migrateWorkflowState(raw: Record<string, unknown>, skill: string): MigrateWorkflowStateResult {
+	const canonicalSkill = canonicalSkillOrThrow(skill);
+	const fromVersion = typeof raw.version === "number" ? raw.version : 1;
+	if (fromVersion >= WORKFLOW_STATE_VERSION) {
+		return { state: raw, fromVersion, toVersion: fromVersion, changed: false };
+	}
+
+	let version = fromVersion;
+	let state = raw;
+	let changed = false;
+	while (version < WORKFLOW_STATE_VERSION && MIGRATIONS[version]) {
+		state = MIGRATIONS[version](state, canonicalSkill);
+		version += 1;
+		changed = true;
+	}
+
+	return { state, fromVersion, toVersion: version, changed };
+}
 
 /**
  * Pure legacy state normalizer for background/internal readers.
@@ -90,14 +140,11 @@ export function normalizeLegacyState(raw: Record<string, unknown>, skill: string
 	state.skill = canonicalSkill;
 	if (typeof state.version !== "number") state.version = 1;
 	if (typeof state.active !== "boolean") state.active = true;
-
-	const sourcePhase = typeof state.current_phase === "string" ? state.current_phase : state.phase;
-	const normalizedPhase = normalizePhase(canonicalSkill, sourcePhase);
-	state.current_phase = normalizedPhase;
-	if ("phase" in state && typeof state.phase === "string") state.phase = normalizedPhase;
+	if (typeof state.updated_at !== "string") state.updated_at = new Date().toISOString();
 	state.receipt = receiptWithRequiredFields(state.receipt, canonicalSkill);
 
-	return { state, changed: !recordsEqual(raw, state) };
+	const migrated = migrateWorkflowState(state, canonicalSkill).state;
+	return { state: migrated, changed: !recordsEqual(raw, migrated) };
 }
 
 export async function migrateAndPersistLegacyState(