@gajae-code/coding-agent 0.11.10 → 0.12.0

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

@@ -1,13 +1,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 { getConfigRootDir } from "@gajae-code/utils";
 import { YAML } from "bun";
+import { syncSkillActiveState } from "../skill-state/active-state";
+import { deriveDeepInterviewHud } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
-import { scoreToUnits } from "./deep-interview-ambiguity";
-import { runDeepInterviewDraftCommand } from "./deep-interview-draft";
-import { runDeepInterviewPostCommitEffects } from "./deep-interview-recorder";
-import { isDeepInterviewRepairVerb, runDeepInterviewRepairCommand } from "./deep-interview-repair";
+import { isDeepInterviewStageVerb, runDeepInterviewStageCommand } from "./deep-interview-stage";
 import {
 	assertDeepInterviewInputWithinLimit,
 	assertDeepInterviewIntentReview,
@@ -19,20 +18,12 @@ import {
 	MAX_INITIAL_CONTEXT_LENGTH,
 	normalizeDeepInterviewEnvelope,
 	reviewDeepInterviewIntent,
-	validateDeepInterviewV1Envelope,
 } from "./deep-interview-state";
 import { runNativeRalplanCommand } from "./ralplan-runtime";
 import { modeStatePath, sessionSpecsDir } from "./session-layout";
-import { resolveGjcSessionForWrite } from "./session-resolution";
+import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { runNativeStateCommand } from "./state-runtime";
-import {
-	appendJsonl,
-	readExistingStateForMutation,
-	verifyWorkflowEnvelopeReceiptValue,
-	withWorkflowStateLock,
-	writeArtifact,
-	writeWorkflowEnvelopeAtomic,
-} from "./state-writer";
+import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
 import { assertSafePathComponent, CommandError, flagValue, hasFlag } from "./workflow-cli-common";
 
 export * from "./deep-interview-recorder";
@@ -364,7 +355,7 @@ async function readSettingsAmbiguityThreshold(
 	} catch (error) {
 		const err = error as NodeJS.ErrnoException;
 		if (err.code === "ENOENT") return undefined;
-		throw new Error(`failed to read deep-interview threshold config ${settingsPath}: ${err.message}`);
+		return undefined;
 	}
 	let parsed: unknown;
 	try {
@@ -374,7 +365,7 @@ async function readSettingsAmbiguityThreshold(
 	}
 	const candidate = (parsed as { gjc?: { deepInterview?: { ambiguityThreshold?: unknown } } })?.gjc?.deepInterview
 		?.ambiguityThreshold;
-	if (typeof candidate !== "number" || !isIntegralScore(candidate) || candidate <= 0) {
+	if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0 || candidate > 1) {
 		return undefined;
 	}
 	return { threshold: candidate, source: settingsPath };
@@ -383,30 +374,21 @@ async function readSettingsAmbiguityThreshold(
 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");
+	return path.join(getConfigRootDir(), "agent", "config.yml");
 }
 
 async function readModernSettingsAmbiguityThreshold(): Promise<{ threshold: number; source: string } | undefined> {
 	const modernConfigPath = modernSettingsPath();
-	let raw: string;
-	try {
-		raw = await fs.readFile(modernConfigPath, "utf-8");
-	} catch (error) {
-		const err = error as NodeJS.ErrnoException;
-		if (err.code === "ENOENT") return undefined;
-		throw new Error(`failed to read deep-interview threshold config ${modernConfigPath}: ${err.message}`);
-	}
 	let parsed: unknown;
 	try {
-		parsed = YAML.parse(raw);
+		parsed = YAML.parse(await fs.readFile(modernConfigPath, "utf-8"));
 	} catch {
 		return undefined;
 	}
 	const candidate = (parsed as { gjc?: { deepInterview?: { ambiguityThreshold?: unknown } } })?.gjc?.deepInterview
 		?.ambiguityThreshold;
-	if (typeof candidate !== "number" || !isIntegralScore(candidate) || candidate <= 0) return undefined;
+	if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0 || candidate > 1)
+		return undefined;
 	return { threshold: candidate, source: modernConfigPath };
 }
 
@@ -418,8 +400,7 @@ async function resolveConfiguredAmbiguityThreshold(
 	const projectSettings = path.join(cwd, ".gjc", "settings.json");
 	const projectValue = await readSettingsAmbiguityThreshold(projectSettings);
 	if (projectValue) return projectValue;
-	const configDir = process.env.GJC_CONFIG_DIR?.trim() || path.join(os.homedir(), ".gjc");
-	const userSettings = path.join(configDir, "settings.json");
+	const userSettings = path.join(getConfigRootDir(), "settings.json");
 	return await readSettingsAmbiguityThreshold(userSettings);
 }
 
@@ -521,15 +502,6 @@ async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promi
 	};
 }
 
-function isIntegralScore(value: number): boolean {
-	try {
-		scoreToUnits(value);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): Promise<ResolvedDeepInterviewArgs> {
 	const session = resolveGjcSessionForWrite(cwd, {
 		flagValue: flagValue(args, "--session-id"),
@@ -550,10 +522,10 @@ async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): P
 	const thresholdOverride = flagValue(args, "--threshold");
 	if (thresholdOverride !== undefined) {
 		const parsed = Number(thresholdOverride);
-		if (!isIntegralScore(parsed) || parsed <= 0) {
+		if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
 			throw new DeepInterviewCommandError(
 				2,
-				`invalid --threshold: ${thresholdOverride}. Expected integral 1e-4 units in (0, 1].`,
+				`invalid --threshold: ${thresholdOverride}. Expected 0 < threshold <= 1.`,
 			);
 		}
 		threshold = parsed;
@@ -571,16 +543,7 @@ async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): P
 
 	const ideaParts: string[] = [];
 	let skipNext = false;
-	let positionalOnly = false;
 	for (const arg of args) {
-		if (positionalOnly) {
-			ideaParts.push(arg);
-			continue;
-		}
-		if (arg === "--") {
-			positionalOnly = true;
-			continue;
-		}
 		if (skipNext) {
 			skipNext = false;
 			continue;
@@ -754,13 +717,13 @@ export async function persistDeepInterviewSpec(
 			forced: resolved.force,
 		},
 	});
-	await runDeepInterviewPostCommitEffects({
+	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "deep-interview-runtime", path: statePath });
+	await syncDeepInterviewHud({
 		cwd,
-		statePath,
-		sessionId: resolved.sessionId ?? "",
-		envelope: normalizeDeepInterviewEnvelope(payload),
-		revision: 0,
-		writer: "deep-interview-runtime",
+		sessionId: resolved.sessionId,
+		payload,
+		phase: "handoff",
+		specStatus: "persisted",
 	});
 
 	return {
@@ -773,169 +736,91 @@ export async function persistDeepInterviewSpec(
 	};
 }
 
-function isEmptyPendingTopology(value: unknown): boolean {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const topology = value as Record<string, unknown>;
-	return (
-		topology.status === "pending" &&
-		Array.isArray(topology.components) &&
-		topology.components.length === 0 &&
-		Array.isArray(topology.deferred_components) &&
-		topology.deferred_components.length === 0
-	);
-}
-function isUnresolvedNativeSetup(value: unknown): boolean {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const state = value as Record<string, unknown>;
-	return (
-		state.setup !== null &&
-		typeof state.setup === "object" &&
-		!Array.isArray(state.setup) &&
-		(state.setup as Record<string, unknown>).status === "unresolved"
-	);
-}
-async function seedDeepInterviewState(
-	cwd: string,
-	resolved: ResolvedDeepInterviewArgs,
-): Promise<{ statePath: string; warnings: unknown[] }> {
+async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepInterviewArgs): Promise<string> {
 	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
-	return withWorkflowStateLock(
-		`${statePath}.kickoff`,
-		async () => {
-			const existing = await readExistingStateForMutation(statePath);
-			if (existing.kind === "valid") {
-				try {
-					if (verifyWorkflowEnvelopeReceiptValue(existing.value, statePath) !== "native-valid")
-						throw new Error("invalid receipt");
-					validateDeepInterviewV1Envelope(existing.value);
-				} catch {
-					throw new DeepInterviewCommandError(3, "DI_STATE_CORRUPT");
-				}
-				const phase =
-					typeof existing.value.current_phase === "string" ? existing.value.current_phase : "interviewing";
-				if (phase === "complete" || phase === "handoff" || existing.value.active === false)
-					throw new DeepInterviewCommandError(3, "DI_PHASE_NOT_REPAIRABLE");
-				const priorState =
-					existing.value.state && typeof existing.value.state === "object" && !Array.isArray(existing.value.state)
-						? (existing.value.state as Record<string, unknown>)
-						: {};
-				const exactEmptyNativeSeed =
-					isUnresolvedNativeSetup(priorState) &&
-					priorState.type === (resolved.trace ? "brownfield" : "greenfield") &&
-					existing.value.skill === "deep-interview" &&
-					existing.value.active === true &&
-					phase === "interviewing" &&
-					existing.value.resolution === resolved.resolution &&
-					existing.value.threshold === resolved.threshold &&
-					existing.value.threshold_source === resolved.thresholdSource &&
-					priorState.initial_idea === resolved.idea &&
-					priorState.intent_contract_required === true &&
-					Array.isArray(priorState.rounds) &&
-					priorState.rounds.length === 0 &&
-					Array.isArray(priorState.established_facts) &&
-					priorState.established_facts.length === 0 &&
-					Array.isArray(priorState.ontology_snapshots) &&
-					priorState.ontology_snapshots.length === 0 &&
-					Array.isArray(priorState.auto_researched_rounds) &&
-					priorState.auto_researched_rounds.length === 0 &&
-					Array.isArray(priorState.auto_answered_rounds) &&
-					priorState.auto_answered_rounds.length === 0 &&
-					isEmptyPendingTopology(priorState.topology) &&
-					priorState.architect_failures === 0 &&
-					priorState.current_ambiguity === 1 &&
-					JSON.stringify(existing.value.trace) === JSON.stringify(resolved.trace) &&
-					JSON.stringify(existing.value.language) === JSON.stringify(resolved.language);
-				if (exactEmptyNativeSeed) return { statePath, warnings: [] };
-				throw new DeepInterviewCommandError(2, "DI_INTERVIEW_ALREADY_ACTIVE");
-			}
-			if (existing.kind === "corrupt") throw new DeepInterviewCommandError(3, "DI_STATE_CORRUPT");
-			const now = new Date().toISOString();
-			const type = resolved.trace ? "brownfield" : "greenfield";
-			const payload: Record<string, unknown> = {
-				active: true,
-				current_phase: "interviewing",
-				schema_version: 1,
-				skill: "deep-interview",
-				version: WORKFLOW_STATE_VERSION,
-				resolution: resolved.resolution,
-				threshold: resolved.threshold,
-				threshold_units: scoreToUnits(resolved.threshold),
-				threshold_source: resolved.thresholdSource,
-				state: {
-					setup: { status: "unresolved" },
-					type,
-					initial_idea: resolved.idea,
-					intent_contract_required: true,
-					rounds: [],
-					established_facts: [],
-					topology: { status: "pending", components: [], deferred_components: [] },
-					ontology_snapshots: [],
-					auto_researched_rounds: [],
-					auto_answered_rounds: [],
-					architect_failures: 0,
-					current_ambiguity: 1.0,
-					threshold: resolved.threshold,
-					threshold_units: scoreToUnits(resolved.threshold),
-					threshold_source: resolved.thresholdSource,
-				},
-				updated_at: now,
-			};
-			validateDeepInterviewV1Envelope(payload);
-			if (resolved.trace) {
-				payload.trace = resolved.trace;
-				(payload.state as Record<string, unknown>).trace = resolved.trace;
-				(payload.state as Record<string, unknown>).trace_summary = resolved.trace;
-				(payload.state as Record<string, unknown>).codebase_context = {
-					source: "trace",
-					summary: resolved.trace.findings,
-					relevant_paths: resolved.trace.relevant_paths,
-					project_hints: resolved.trace.project_hints,
-				};
-			}
-			if (resolved.language) {
-				payload.language = resolved.language;
-				(payload.state as Record<string, unknown>).language = resolved.language;
-			}
-			if (resolved.sessionId) payload.session_id = resolved.sessionId;
-			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",
-					sessionId: resolved.sessionId,
-				},
-			});
-			const stamped = await readExistingStateForMutation(statePath);
-			if (stamped.kind !== "valid") throw new DeepInterviewCommandError(3, "DI_STATE_CORRUPT");
-			try {
-				if (verifyWorkflowEnvelopeReceiptValue(stamped.value, statePath) !== "native-valid")
-					throw new Error("invalid receipt");
-				validateDeepInterviewV1Envelope(stamped.value);
-			} catch {
-				throw new DeepInterviewCommandError(3, "DI_STATE_CORRUPT");
-			}
-			const warnings = await runDeepInterviewPostCommitEffects({
-				cwd,
-				statePath,
-				sessionId: resolved.sessionId ?? "",
-				envelope: normalizeDeepInterviewEnvelope(stamped.value),
-				revision: typeof stamped.value.state_revision === "number" ? stamped.value.state_revision : 0,
-				writer: "deep-interview-runtime",
-			});
-			return { statePath, warnings };
+	assertDeepInterviewInputWithinLimit(resolved.idea, MAX_INITIAL_CONTEXT_LENGTH, "initial_idea");
+	const now = new Date().toISOString();
+	const payload: Record<string, unknown> = {
+		active: true,
+		current_phase: "interviewing",
+		skill: "deep-interview",
+		version: WORKFLOW_STATE_VERSION,
+		resolution: resolved.resolution,
+		threshold: resolved.threshold,
+		threshold_source: resolved.thresholdSource,
+		state: {
+			initial_idea: resolved.idea,
+			intent_contract_required: true,
+			rounds: [],
+			established_facts: [],
+			current_ambiguity: 1.0,
+			threshold: resolved.threshold,
+			threshold_source: resolved.thresholdSource,
 		},
-		{ cwd },
-	);
+		updated_at: now,
+	};
+	if (resolved.trace) {
+		payload.trace = resolved.trace;
+		(payload.state as Record<string, unknown>).trace = resolved.trace;
+		(payload.state as Record<string, unknown>).trace_summary = resolved.trace;
+		(payload.state as Record<string, unknown>).codebase_context = {
+			source: "trace",
+			summary: resolved.trace.findings,
+			relevant_paths: resolved.trace.relevant_paths,
+			project_hints: resolved.trace.project_hints,
+		};
+	}
+	if (resolved.language) {
+		payload.language = resolved.language;
+		(payload.state as Record<string, unknown>).language = resolved.language;
+	}
+	if (resolved.sessionId) payload.session_id = resolved.sessionId;
+	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",
+			sessionId: resolved.sessionId,
+		},
+	});
+	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "deep-interview-runtime", path: statePath });
+	await syncDeepInterviewHud({ cwd, sessionId: resolved.sessionId, payload, phase: "interviewing" });
+	return statePath;
+}
+
+async function syncDeepInterviewHud(options: {
+	cwd: string;
+	sessionId?: string;
+	payload: Record<string, unknown>;
+	phase?: string;
+	specStatus?: string;
+}): Promise<void> {
+	try {
+		const phase =
+			options.phase ??
+			(typeof options.payload.current_phase === "string" ? options.payload.current_phase : "interviewing");
+		await syncSkillActiveState({
+			cwd: options.cwd,
+			skill: "deep-interview",
+			active: phase !== "complete",
+			phase,
+			sessionId: options.sessionId,
+			source: "gjc-deep-interview-native",
+			hud: deriveDeepInterviewHud(options.payload, { phase, specStatus: options.specStatus }),
+		});
+	} catch {
+		// HUD sync is best-effort and must not change command semantics.
+	}
 }
 
 async function handleSpecWrite(args: readonly string[], cwd: string): Promise<DeepInterviewCommandResult> {
@@ -1001,68 +886,23 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 				.join("\n");
 	return { status: 0, stdout };
 }
-function isDeepInterviewRepairInvocation(args: readonly string[]): boolean {
-	const separator = args.indexOf("--");
-	return (separator === -1 || separator > 0) && isDeepInterviewRepairVerb(args[0] ?? "");
-}
-function isDeepInterviewDraftInvocation(args: readonly string[]): boolean {
-	const separator = args.indexOf("--");
-	return (separator === -1 || separator > 0) && args[0] === "draft";
-}
-function draftCommandArgs(args: readonly string[]): string[] {
-	const normalized: string[] = [];
-	for (let index = 1; index < args.length; index++) {
-		const argument = args[index];
-		if (argument === "--for") {
-			normalized.push("--kind", args[++index] ?? "");
-			continue;
-		}
-		normalized.push(argument);
-		if (argument === "--json" && !args[index + 1]?.startsWith("--")) continue;
-		if (argument === "--json") normalized.push("true");
-	}
-	return normalized;
-}
 
 export async function runNativeDeepInterviewCommand(
 	args: string[],
 	cwd = process.cwd(),
 ): Promise<DeepInterviewCommandResult> {
 	try {
+		const [firstArg, ...restArgs] = args;
+		if (isDeepInterviewStageVerb(firstArg)) return await runDeepInterviewStageCommand(firstArg, restArgs, cwd);
 		if (isDeepInterviewSpecWriteInvocation(args)) return await handleSpecWrite(args, cwd);
-		if (isDeepInterviewRepairInvocation(args)) return await runDeepInterviewRepairCommand(args, cwd);
-		if (isDeepInterviewDraftInvocation(args)) return await runDeepInterviewDraftCommand(draftCommandArgs(args), cwd);
 		const resolved = await resolveDeepInterviewArgs(args, cwd);
 		if (!resolved.idea) {
-			const existing = await readExistingStateForMutation(deepInterviewStatePath(cwd, resolved.sessionId));
-			if (existing.kind === "valid") {
-				const phase =
-					typeof existing.value.current_phase === "string" ? existing.value.current_phase : "interviewing";
-				if (phase === "complete" || existing.value.active === false)
-					throw new DeepInterviewCommandError(
-						2,
-						"deep-interview session is terminal; start a new session to kick off another interview.",
-					);
-				const state = existing.value.state as Record<string, unknown> | undefined;
-				return {
-					status: 0,
-					stdout: `${JSON.stringify({
-						skill: "deep-interview",
-						resumed: true,
-						session_id: resolved.sessionId ?? null,
-						state_path: deepInterviewStatePath(cwd, resolved.sessionId),
-						state_revision: existing.value.state_revision ?? 0,
-						idea: typeof state?.initial_idea === "string" ? state.initial_idea : null,
-						handoff: "/skill:deep-interview",
-					})}\n`,
-				};
-			}
 			throw new DeepInterviewCommandError(
 				2,
 				'gjc deep-interview requires an idea, e.g. `gjc deep-interview "<idea>"`.',
 			);
 		}
-		const seeded = await seedDeepInterviewState(cwd, resolved);
+		const statePath = await seedDeepInterviewState(cwd, resolved);
 
 		const summary = {
 			skill: "deep-interview",
@@ -1072,14 +912,13 @@ export async function runNativeDeepInterviewCommand(
 			idea: resolved.idea,
 			language: resolved.language,
 			trace: resolved.trace,
-			state_path: seeded.statePath,
-			warnings: seeded.warnings,
+			state_path: statePath,
 			handoff: "/skill:deep-interview",
 		};
 		const stdout = resolved.json
 			? `${JSON.stringify(summary)}\n`
 			: [
-					`deep-interview seed state_path=${seeded.statePath}`,
+					`deep-interview seed state_path=${statePath}`,
 					`resolution=${resolved.resolution} threshold=${resolved.threshold} threshold_source=${resolved.thresholdSource}`,
 					resolved.trace ? `trace=enabled bounded_paths=${resolved.trace.relevant_paths.length}` : undefined,
 					"handoff=/skill:deep-interview",