@gajae-code/coding-agent 0.2.2 → 0.2.3

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

@@ -1,8 +1,11 @@
+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 { syncSkillActiveState } from "../skill-state/active-state";
 import { buildDeepInterviewHudSummary } from "../skill-state/workflow-hud";
+import { runNativeRalplanCommand } from "./ralplan-runtime";
+import { runNativeStateCommand } from "./state-runtime";
 
 /**
  * Native implementation of `gjc deep-interview`.
@@ -42,7 +45,15 @@ class DeepInterviewCommandError extends Error {
 	}
 }
 
-const VALUE_FLAGS = new Set(["--session-id", "--threshold", "--threshold-source"]);
+const VALUE_FLAGS = new Set([
+	"--session-id",
+	"--threshold",
+	"--threshold-source",
+	"--stage",
+	"--slug",
+	"--spec",
+	"--handoff",
+]);
 
 function flagValue(args: readonly string[], flag: string): string | undefined {
 	const index = args.indexOf(flag);
@@ -64,6 +75,56 @@ function encodeSessionSegment(value: string): string {
 	return encodeURIComponent(value).replaceAll(".", "%2E");
 }
 
+function defaultSpecSlug(now: Date = new Date()): string {
+	const yyyy = now.getUTCFullYear().toString().padStart(4, "0");
+	const mm = (now.getUTCMonth() + 1).toString().padStart(2, "0");
+	const dd = now.getUTCDate().toString().padStart(2, "0");
+	const hh = now.getUTCHours().toString().padStart(2, "0");
+	const min = now.getUTCMinutes().toString().padStart(2, "0");
+	return `${yyyy}-${mm}-${dd}-${hh}${min}-${randomBytes(2).toString("hex")}`;
+}
+
+function stateDirFor(cwd: string, sessionId: string | undefined): string {
+	return sessionId
+		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(sessionId))
+		: path.join(cwd, ".gjc", "state");
+}
+
+function deepInterviewStatePath(cwd: string, sessionId: string | undefined): string {
+	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 writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	const tmp = `${filePath}.tmp-${randomBytes(6).toString("hex")}`;
+	await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`);
+	await fs.rename(tmp, filePath);
+}
+
+async function resolveSpecContent(rawSpec: string, cwd: string): Promise<string> {
+	const candidate = path.isAbsolute(rawSpec) ? rawSpec : path.resolve(cwd, rawSpec);
+	try {
+		const stat = await fs.stat(candidate);
+		if (stat.isFile()) return await fs.readFile(candidate, "utf-8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code !== "ENOENT" && err.code !== "ENOTDIR") {
+			throw new DeepInterviewCommandError(2, `failed to read --spec ${candidate}: ${err.message}`);
+		}
+	}
+	return rawSpec;
+}
+
 interface ResolvedDeepInterviewArgs {
 	resolution: DeepInterviewResolution;
 	threshold: number;
@@ -73,6 +134,41 @@ interface ResolvedDeepInterviewArgs {
 	json: boolean;
 }
 
+export interface ResolvedDeepInterviewSpecWriteArgs {
+	stage: "final";
+	slug: string;
+	spec: string;
+	sessionId?: string;
+	json: boolean;
+	deliberate: boolean;
+	handoff?: "ralplan";
+}
+
+export interface PersistedDeepInterviewSpec {
+	slug: string;
+	path: string;
+	stage: "final";
+	sha256: string;
+	createdAt: string;
+	statePath: string;
+}
+
+interface DeepInterviewSpecWriteSummary {
+	skill: "deep-interview";
+	stage: "final";
+	slug: string;
+	path: string;
+	sha256: string;
+	created_at: string;
+	state_path: string;
+	handoff?: {
+		to: "ralplan";
+		mode: "deliberate";
+		state_path?: string;
+		run_id?: string;
+	};
+}
+
 async function readSettingsAmbiguityThreshold(
 	settingsPath: string,
 ): Promise<{ threshold: number; source: string } | undefined> {
@@ -109,6 +205,68 @@ async function resolveConfiguredAmbiguityThreshold(
 	return await readSettingsAmbiguityThreshold(userSettings);
 }
 
+function isDeepInterviewSpecWriteInvocation(args: readonly string[]): boolean {
+	return hasFlag(args, "--write");
+}
+
+async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promise<ResolvedDeepInterviewSpecWriteArgs> {
+	const stage = flagValue(args, "--stage")?.trim() || "final";
+	if (stage !== "final") {
+		throw new DeepInterviewCommandError(2, 'unknown --stage for deep-interview --write: expected "final"');
+	}
+
+	const slug = flagValue(args, "--slug")?.trim() || defaultSpecSlug();
+	assertSafePathComponent(slug, "slug");
+
+	const rawSpec = flagValue(args, "--spec");
+	if (rawSpec === undefined || rawSpec === "") {
+		throw new DeepInterviewCommandError(2, "--spec is required for deep-interview --write");
+	}
+
+	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
+	if (sessionId) assertSafePathComponent(sessionId, "session-id");
+
+	const rawHandoff = flagValue(args, "--handoff")?.trim() || undefined;
+	if (rawHandoff && rawHandoff !== "ralplan") {
+		throw new DeepInterviewCommandError(2, 'unknown --handoff target: expected "ralplan"');
+	}
+
+	const allowedFlags = new Set([
+		"--write",
+		"--stage",
+		"--slug",
+		"--spec",
+		"--session-id",
+		"--handoff",
+		"--deliberate",
+		"--json",
+	]);
+	let skipNext = false;
+	for (const arg of args) {
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (["--stage", "--slug", "--spec", "--session-id", "--handoff"].includes(arg)) {
+			skipNext = true;
+			continue;
+		}
+		if (arg.startsWith("-") && !allowedFlags.has(arg)) {
+			throw new DeepInterviewCommandError(2, `unknown flag for gjc deep-interview --write: ${arg}`);
+		}
+	}
+
+	return {
+		stage: "final",
+		slug,
+		spec: await resolveSpecContent(rawSpec, cwd),
+		sessionId,
+		json: hasFlag(args, "--json"),
+		deliberate: hasFlag(args, "--deliberate"),
+		handoff: rawHandoff as "ralplan" | undefined,
+	};
+}
+
 async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): Promise<ResolvedDeepInterviewArgs> {
 	const sessionId = flagValue(args, "--session-id")?.trim() || undefined;
 	if (sessionId) assertSafePathComponent(sessionId, "session-id");
@@ -173,6 +331,57 @@ async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): P
 	};
 }
 
+export async function persistDeepInterviewSpec(
+	cwd: string,
+	resolved: ResolvedDeepInterviewSpecWriteArgs,
+): Promise<PersistedDeepInterviewSpec> {
+	const specsDir = path.join(cwd, ".gjc", "specs");
+	await fs.mkdir(specsDir, { recursive: true });
+	const specPath = path.join(specsDir, `deep-interview-${resolved.slug}.md`);
+	const content = resolved.spec.endsWith("\n") ? resolved.spec : `${resolved.spec}\n`;
+	await fs.writeFile(specPath, content);
+
+	const sha256 = createHash("sha256").update(content).digest("hex");
+	const createdAt = new Date().toISOString();
+	await fs.appendFile(
+		path.join(specsDir, "deep-interview-index.jsonl"),
+		`${JSON.stringify({ slug: resolved.slug, stage: resolved.stage, path: specPath, created_at: createdAt, sha256 })}\n`,
+	);
+
+	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,
+		spec_slug: resolved.slug,
+		spec_path: specPath,
+		spec_sha256: sha256,
+		spec_stage: resolved.stage,
+		spec_persisted_at: createdAt,
+		updated_at: createdAt,
+	};
+	if (resolved.sessionId) payload.session_id = resolved.sessionId;
+	await writeJsonAtomic(statePath, payload);
+	await syncDeepInterviewHud({
+		cwd,
+		sessionId: resolved.sessionId,
+		phase: "handoff",
+		specStatus: "persisted",
+	});
+
+	return {
+		slug: resolved.slug,
+		path: specPath,
+		stage: resolved.stage,
+		sha256,
+		createdAt,
+		statePath,
+	};
+}
+
 async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepInterviewArgs): Promise<string> {
 	const stateDir = resolved.sessionId
 		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(resolved.sessionId))
@@ -232,11 +441,69 @@ async function syncDeepInterviewHud(options: {
 	}
 }
 
+async function handleSpecWrite(args: readonly string[], cwd: string): Promise<DeepInterviewCommandResult> {
+	const resolved = await resolveSpecWriteArgs(args, cwd);
+	const persisted = await persistDeepInterviewSpec(cwd, resolved);
+	const shouldHandoff = resolved.deliberate || resolved.handoff === "ralplan";
+	const summary: DeepInterviewSpecWriteSummary = {
+		skill: "deep-interview",
+		stage: persisted.stage,
+		slug: persisted.slug,
+		path: persisted.path,
+		sha256: persisted.sha256,
+		created_at: persisted.createdAt,
+		state_path: persisted.statePath,
+	};
+
+	if (shouldHandoff) {
+		const ralplanArgs = ["--deliberate", "--json"];
+		if (resolved.sessionId) ralplanArgs.push("--session-id", resolved.sessionId);
+		ralplanArgs.push(persisted.path);
+		const ralplanResult = await runNativeRalplanCommand(ralplanArgs, cwd);
+		if (ralplanResult.status !== 0) {
+			throw new DeepInterviewCommandError(
+				ralplanResult.status,
+				ralplanResult.stderr?.trim() || "failed to seed ralplan",
+			);
+		}
+
+		const handoffArgs = ["handoff", "--mode", "deep-interview", "--to", "ralplan", "--json"];
+		if (resolved.sessionId) handoffArgs.push("--session-id", resolved.sessionId);
+		const handoffResult = await runNativeStateCommand(handoffArgs, cwd);
+		if (handoffResult.status !== 0) {
+			throw new DeepInterviewCommandError(
+				handoffResult.status,
+				handoffResult.stderr?.trim() || "failed to hand off deep-interview to ralplan",
+			);
+		}
+
+		const ralplanPayload = ralplanResult.stdout ? (JSON.parse(ralplanResult.stdout) as Record<string, unknown>) : {};
+		summary.handoff = {
+			to: "ralplan",
+			mode: "deliberate",
+			state_path: typeof ralplanPayload.state_path === "string" ? ralplanPayload.state_path : undefined,
+			run_id: typeof ralplanPayload.run_id === "string" ? ralplanPayload.run_id : undefined,
+		};
+	}
+
+	const stdout = resolved.json
+		? `${JSON.stringify(summary, null, 2)}\n`
+		: [
+				`Persisted deep-interview ${persisted.stage} spec at ${persisted.path}.`,
+				shouldHandoff ? "Handed off deep-interview to ralplan (deliberate)." : undefined,
+				"",
+			]
+				.filter((line): line is string => Boolean(line))
+				.join("\n");
+	return { status: 0, stdout };
+}
+
 export async function runNativeDeepInterviewCommand(
 	args: string[],
 	cwd = process.cwd(),
 ): Promise<DeepInterviewCommandResult> {
 	try {
+		if (isDeepInterviewSpecWriteInvocation(args)) return await handleSpecWrite(args, cwd);
 		const resolved = await resolveDeepInterviewArgs(args, cwd);
 		if (!resolved.idea) {
 			throw new DeepInterviewCommandError(

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

@@ -3,12 +3,14 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import {
+	applyHandoffToActiveState,
 	CANONICAL_GJC_WORKFLOW_SKILLS,
 	type CanonicalGjcWorkflowSkill,
 	listActiveSkills,
 	readVisibleSkillActiveState,
 	syncSkillActiveState,
 } from "../skill-state/active-state";
+import { initialPhaseForSkill } from "../skill-state/initial-phase";
 import {
 	buildDeepInterviewHudSummary,
 	buildRalplanHudSummary,
@@ -60,11 +62,11 @@ function hasFlag(args: readonly string[], flag: string): boolean {
 	return args.includes(flag);
 }
 
-const FLAGS_WITH_VALUES = new Set(["--input", "--mode", "--session-id", "--thread-id", "--turn-id"]);
-const ACTION_NAMES = new Set(["read", "write", "clear", "contract"]);
+const FLAGS_WITH_VALUES = new Set(["--input", "--mode", "--session-id", "--thread-id", "--turn-id", "--to"]);
+const ACTION_NAMES = new Set(["read", "write", "clear", "contract", "handoff"]);
 
 interface ParsedInvocation {
-	action: "read" | "write" | "clear" | "contract";
+	action: "read" | "write" | "clear" | "contract" | "handoff";
 	positionalSkill?: string;
 }
 
@@ -169,10 +171,19 @@ async function resolveSelectors(
 	}
 	if (mode) assertKnownMode(mode);
 
+	// Session-id resolution order: explicit --session-id flag, then payload
+	// session_id, then GJC_SESSION_ID env var (set by AgentSession.sdk for
+	// agent-initiated CLI invocations). The env-var default keeps shell
+	// snippets in skill docs short while still routing writes/reads to the
+	// caller's session-scoped state files.
 	let sessionId = flagValue(args, "--session-id")?.trim() || undefined;
 	if (!sessionId && payload && typeof payload.session_id === "string") {
 		sessionId = payload.session_id.trim() || undefined;
 	}
+	if (!sessionId) {
+		const envSessionId = process.env.GJC_SESSION_ID?.trim();
+		if (envSessionId) sessionId = envSessionId;
+	}
 	if (sessionId) assertSafePathComponent(sessionId, "session-id");
 
 	const threadId = flagValue(args, "--thread-id")?.trim() || undefined;
@@ -396,7 +407,6 @@ async function syncWorkflowSkillState(options: {
 		// HUD sync is best-effort and must not change command semantics.
 	}
 }
-
 async function handleRead(
 	args: readonly string[],
 	cwd: string,
@@ -527,6 +537,163 @@ async function handleClear(
 	return { status: 0, stdout: `${JSON.stringify(cleared, null, 2)}\n` };
 }
 
+/**
+ * `handoff` exists in two distinct roles:
+ *   - As a verb: this CLI action, which atomically transitions caller→callee.
+ *     Writes the callee mode-state first, the caller mode-state second, then
+ *     syncs both `skill-active-state.json` files. Every intermediate crashed
+ *     state remains HUD-coherent: the active-state file either reflects the
+ *     old skill entirely or the new skill entirely, never both as active.
+ *   - As a phase: `current_phase: "handoff"` is set by this verb when demoting
+ *     the caller. Agents writing `current_phase: "handoff"` manually via
+ *     `gjc state <skill> write` are declaring "I am ready to be handed off";
+ *     the next agent-initiated `skill` tool call will then satisfy the phase
+ *     guard and may chain.
+ *
+ * `handoff` is in the terminal-phase set used by `isTerminalModeState` and by
+ * the skill tool's chain guard. A manual `current_phase: "handoff"` write does
+ * NOT mark `active: false` — only this verb does that — so a skill that wrote
+ * the phase remains in `skill-active-state.json` until a chain call (or
+ * explicit `clear`) demotes it.
+ */
+async function handleHandoff(
+	args: readonly string[],
+	cwd: string,
+	positionalSkill: string | undefined,
+): Promise<StateCommandResult> {
+	const selectors = await resolveSelectors(args, cwd, positionalSkill);
+	const { sessionId, threadId, turnId } = selectors;
+	const caller = selectors.mode ?? (await inferModeFromActiveState(cwd, sessionId));
+	if (!caller) {
+		throw new StateCommandError(
+			2,
+			"gjc state handoff requires --mode <caller>, positional <caller>, input.skill, or an active workflow in .gjc/state/skill-active-state.json",
+		);
+	}
+	const calleeRaw = flagValue(args, "--to")?.trim();
+	if (!calleeRaw) {
+		throw new StateCommandError(2, "gjc state handoff requires --to <callee>");
+	}
+	assertKnownMode(calleeRaw);
+	const callee = calleeRaw as CanonicalGjcWorkflowSkill;
+	if (callee === caller) {
+		throw new StateCommandError(2, `gjc state handoff: --to must differ from caller (both are "${caller}")`);
+	}
+
+	const callerPath = modeStateFile(cwd, caller, sessionId);
+	const calleePath = modeStateFile(cwd, callee, sessionId);
+	const existingCaller = await readJsonFile(callerPath);
+	if (!existingCaller) {
+		throw new StateCommandError(
+			2,
+			`gjc state ${caller} handoff: caller is not active (no mode-state file at ${callerPath})`,
+		);
+	}
+	const existingCallee = (await readJsonFile(calleePath)) ?? {};
+
+	const handoffAt = nowIso();
+	const callerReceipt = buildWorkflowStateReceipt({
+		cwd,
+		skill: caller,
+		owner: "gjc-state-cli",
+		command: `gjc state ${caller} handoff --to ${callee}`,
+		sessionId,
+		nowIso: handoffAt,
+	});
+	const calleeReceipt = buildWorkflowStateReceipt({
+		cwd,
+		skill: callee,
+		owner: "gjc-state-cli",
+		command: `gjc state ${caller} handoff --to ${callee}`,
+		sessionId,
+		nowIso: handoffAt,
+	});
+
+	const calleeInitial = initialPhaseForSkill(callee);
+	const mergedCalleeState: Record<string, unknown> = {
+		...existingCallee,
+		skill: callee,
+		version: typeof existingCallee.version === "number" ? existingCallee.version : 1,
+		active: true,
+		current_phase: calleeInitial,
+		handoff_from: caller,
+		handoff_at: handoffAt,
+		updated_at: handoffAt,
+		receipt: calleeReceipt,
+	};
+	if (sessionId && typeof mergedCalleeState.session_id !== "string") {
+		mergedCalleeState.session_id = sessionId;
+	}
+	const mergedCallerState: Record<string, unknown> = {
+		...existingCaller,
+		skill: caller,
+		active: false,
+		current_phase: "handoff",
+		handoff_to: callee,
+		handoff_at: handoffAt,
+		updated_at: handoffAt,
+		receipt: callerReceipt,
+	};
+
+	// Atomic write order (architecture blocker AR-3): mode-state files first,
+	// then a single atomic active-state mutation per file (session before root)
+	// via applyHandoffToActiveState. The single-write transaction prevents the
+	// HUD from observing a window where neither caller nor callee is active,
+	// and write order keeps the session-scoped source of truth ahead of the
+	// root aggregate. strict:true on the active-state read tolerates ENOENT
+	// only; corrupt JSON / IO failures propagate as non-zero CLI status.
+	await writeJsonAtomic(calleePath, mergedCalleeState);
+	await writeJsonAtomic(callerPath, mergedCallerState);
+	await applyHandoffToActiveState({
+		cwd,
+		nowIso: handoffAt,
+		strict: true,
+		caller: {
+			cwd,
+			skill: caller,
+			active: false,
+			phase: "handoff",
+			sessionId,
+			threadId,
+			turnId,
+			source: "gjc-state-cli",
+			hud: buildHudForMode(caller, mergedCallerState),
+			handoff_to: callee,
+			handoff_at: handoffAt,
+			receipt: callerReceipt,
+		},
+		callee: {
+			cwd,
+			skill: callee,
+			active: true,
+			phase: calleeInitial,
+			sessionId,
+			threadId,
+			turnId,
+			source: "gjc-state-cli",
+			hud: buildHudForMode(callee, mergedCalleeState),
+			handoff_from: caller,
+			handoff_at: handoffAt,
+			receipt: calleeReceipt,
+		},
+	});
+
+	return {
+		status: 0,
+		stdout: `${JSON.stringify(
+			{
+				from: caller,
+				to: callee,
+				handoff_at: handoffAt,
+				caller_state: mergedCallerState,
+				callee_state: mergedCalleeState,
+			},
+			null,
+			2,
+		)}\n`,
+	};
+}
+
 async function handleContract(
 	args: readonly string[],
 	cwd: string,
@@ -552,6 +719,8 @@ export async function runNativeStateCommand(args: string[], cwd = process.cwd())
 				return await handleClear(args, cwd, parsed.positionalSkill);
 			case "contract":
 				return await handleContract(args, cwd, parsed.positionalSkill);
+			case "handoff":
+				return await handleHandoff(args, cwd, parsed.positionalSkill);
 			default:
 				return { status: 2, stderr: `Unknown gjc state command: ${parsed.action}\n` };
 		}

package/src/hooks/skill-state.ts

@@ -112,6 +112,9 @@ export interface ModeState {
 	thread_id?: string;
 	cwd?: string;
 	updated_at?: string;
+	handoff_from?: string;
+	handoff_to?: string;
+	handoff_at?: string;
 	[key: string]: unknown;
 }
 
@@ -220,11 +223,10 @@ function encodeStatePathSegment(value: string): string {
 	return encodeURIComponent(value).replaceAll(".", "%2E");
 }
 
-function initialPhaseForSkill(skill: GjcWorkflowSkill): string {
-	if (skill === "deep-interview") return "interviewing";
-	if (skill === "ultragoal") return "goal-planning";
-	return "planning";
-}
+import { initialPhaseForSkill } from "../skill-state/initial-phase";
+
+// Re-export for existing callers and tests that imported it from this module.
+export { initialPhaseForSkill };
 
 function modeStateFileName(skill: GjcWorkflowSkill): string {
 	return `${skill}-state.json`;
@@ -347,7 +349,7 @@ function isTerminalModeState(state: ModeState | null): boolean {
 	const phase = String(state.current_phase ?? "")
 		.trim()
 		.toLowerCase();
-	return ["complete", "completed", "failed", "cancelled", "canceled", "inactive"].includes(phase);
+	return ["complete", "completed", "handoff", "failed", "cancelled", "canceled", "inactive"].includes(phase);
 }
 
 async function readVisibleModeState(