@gajae-code/coding-agent 0.2.2 → 0.2.3

package/src/setup/provider-onboarding.ts

@@ -5,14 +5,16 @@ import { YAML } from "bun";
 import { type ModelsConfig, ModelsConfigSchema } from "../config/models-config-schema";
 
 export type ProviderCompatibility = "openai" | "anthropic";
+export type ProviderSetupApi = "openai-responses" | "openai-completions" | "anthropic-messages";
 
 export interface ProviderSetupInput {
-	compatibility: ProviderCompatibility;
-	providerId: string;
-	baseUrl: string;
+	compatibility?: ProviderCompatibility;
+	preset?: string;
+	providerId?: string;
+	baseUrl?: string;
 	apiKey?: string;
 	apiKeyEnv?: string;
-	models: string[];
+	models?: string[];
 	modelsPath?: string;
 	force?: boolean;
 }
@@ -20,19 +22,93 @@ export interface ProviderSetupInput {
 export interface ProviderSetupResult {
 	providerId: string;
 	compatibility: ProviderCompatibility;
-	api: "openai-responses" | "anthropic-messages";
+	api: ProviderSetupApi;
 	baseUrl: string;
 	modelIds: string[];
 	modelsPath: string;
 	redactedApiKey: string;
 	credentialSource: "literal" | "env";
+	preset?: string;
+	presetName?: string;
 }
 
 type ProviderConfig = NonNullable<NonNullable<ModelsConfig["providers"]>[string]>;
+type ProviderCompatConfig = NonNullable<ProviderConfig["compat"]>;
+
+interface ProviderPreset {
+	id: string;
+	aliases: readonly string[];
+	name: string;
+	description: string;
+	compatibility: ProviderCompatibility;
+	api: ProviderSetupApi;
+	providerId: string;
+	baseUrl: string;
+	apiKeyEnv: string;
+	models: readonly string[];
+	compat?: ProviderCompatConfig;
+}
 
 const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 const REDACT_PREFIX = 4;
 const REDACT_SUFFIX = 4;
+// Preset compat values are onboarding snapshots for generated models.yml entries.
+// Keep them aligned with provider descriptor behavior without importing descriptor internals into setup UX.
+const MINIMAX_OPENAI_COMPAT: ProviderCompatConfig = {
+	supportsStore: false,
+	supportsDeveloperRole: false,
+	supportsReasoningEffort: false,
+	reasoningContentField: "reasoning_content",
+};
+
+const GLM_OPENAI_COMPAT: ProviderCompatConfig = {
+	supportsDeveloperRole: false,
+	supportsReasoningEffort: false,
+	thinkingFormat: "zai",
+	reasoningContentField: "reasoning_content",
+};
+
+export const PROVIDER_PRESETS: readonly ProviderPreset[] = [
+	{
+		id: "minimax",
+		aliases: ["minimax-code"],
+		name: "MiniMax Coding Plan",
+		description: "OpenAI-compatible MiniMax Coding Plan endpoint",
+		compatibility: "openai",
+		api: "openai-completions",
+		providerId: "minimax-code",
+		baseUrl: "https://api.minimax.io/v1",
+		apiKeyEnv: "MINIMAX_CODE_API_KEY",
+		models: ["MiniMax-M2.5"],
+		compat: MINIMAX_OPENAI_COMPAT,
+	},
+	{
+		id: "minimax-cn",
+		aliases: ["minimax-code-cn", "minimaxi"],
+		name: "MiniMax Coding Plan (China)",
+		description: "OpenAI-compatible MiniMax China endpoint",
+		compatibility: "openai",
+		api: "openai-completions",
+		providerId: "minimax-code-cn",
+		baseUrl: "https://api.minimaxi.com/v1",
+		apiKeyEnv: "MINIMAX_CODE_CN_API_KEY",
+		models: ["MiniMax-M2.5"],
+		compat: MINIMAX_OPENAI_COMPAT,
+	},
+	{
+		id: "glm",
+		aliases: ["zai", "z-ai", "bigmodel"],
+		name: "GLM / zAI",
+		description: "OpenAI-compatible GLM endpoint from zAI/BigModel",
+		compatibility: "openai",
+		api: "openai-completions",
+		providerId: "glm-proxy",
+		baseUrl: "https://api.z.ai/api/paas/v4",
+		apiKeyEnv: "ZAI_API_KEY",
+		models: ["glm-4.6"],
+		compat: GLM_OPENAI_COMPAT,
+	},
+];
 
 export function getDefaultModelsPath(): string {
 	return path.join(getAgentDir(), "models.yml");
@@ -51,6 +127,19 @@ export function parseProviderCompatibility(value: string): ProviderCompatibility
 	throw new Error("Provider compatibility must be 'openai' or 'anthropic'.");
 }
 
+export function findProviderPreset(value: string | undefined): ProviderPreset | undefined {
+	const normalized = value?.trim().toLowerCase();
+	if (!normalized) return undefined;
+	return PROVIDER_PRESETS.find(preset => preset.id === normalized || preset.aliases.includes(normalized));
+}
+
+export function formatProviderPresetList(): string {
+	return PROVIDER_PRESETS.map(preset => {
+		const aliases = preset.aliases.length > 0 ? ` (aliases: ${preset.aliases.join(", ")})` : "";
+		return `${preset.id}${aliases}: ${preset.description}`;
+	}).join("\n");
+}
+
 export function parseModelList(values: readonly string[]): string[] {
 	const models = values
 		.flatMap(value => value.split(","))
@@ -65,23 +154,82 @@ export function redactSecret(secret: string): string {
 	return `${trimmed.slice(0, REDACT_PREFIX)}…${trimmed.slice(-REDACT_SUFFIX)}`;
 }
 
-function apiForCompatibility(compatibility: ProviderCompatibility): ProviderSetupResult["api"] {
+function apiForCompatibility(compatibility: ProviderCompatibility): ProviderSetupApi {
 	return compatibility === "openai" ? "openai-responses" : "anthropic-messages";
 }
 
+function resolvePresetInput(input: ProviderSetupInput): {
+	compatibility: ProviderCompatibility;
+	preset?: ProviderPreset;
+	providerId?: string;
+	baseUrl?: string;
+	apiKey?: string;
+	apiKeyEnv?: string;
+	models: readonly string[];
+	api: ProviderSetupApi;
+	compat?: ProviderCompatConfig;
+} {
+	const preset = input.preset ? findProviderPreset(input.preset) : undefined;
+	if (input.preset && !preset) {
+		throw new Error(`Unknown provider preset '${input.preset}'. Available presets:\n${formatProviderPresetList()}`);
+	}
+	if (preset && input.compatibility && input.compatibility !== preset.compatibility) {
+		throw new Error(
+			`Provider preset '${preset.id}' is ${preset.compatibility}-compatible; omit --compat or use '${preset.compatibility}'.`,
+		);
+	}
+	if (preset && input.baseUrl !== undefined) {
+		throw new Error(
+			`Provider preset '${preset.id}' uses a fixed base URL; omit --base-url or use --compat openai for a custom provider.`,
+		);
+	}
+	if (preset && input.models && input.models.length > 0) {
+		throw new Error(
+			`Provider preset '${preset.id}' uses fixed model ids; omit --model or use --compat openai for a custom provider.`,
+		);
+	}
+	if (preset && input.apiKeyEnv !== undefined && input.apiKeyEnv.trim() !== preset.apiKeyEnv) {
+		throw new Error(
+			`Provider preset '${preset.id}' uses ${preset.apiKeyEnv}; omit --api-key-env or use --compat openai for a custom provider.`,
+		);
+	}
+	const compatibility = preset?.compatibility ?? input.compatibility;
+	if (!compatibility) {
+		throw new Error("Provider compatibility is required unless --preset is used.");
+	}
+	return {
+		compatibility,
+		preset,
+		providerId: input.providerId ?? preset?.providerId,
+		baseUrl: input.baseUrl ?? preset?.baseUrl,
+		apiKey: input.apiKey,
+		apiKeyEnv: input.apiKeyEnv ?? preset?.apiKeyEnv,
+		models: input.models && input.models.length > 0 ? input.models : (preset?.models ?? []),
+		api: preset?.api ?? apiForCompatibility(compatibility),
+		compat: preset?.compat,
+	};
+}
+
 function validateSetupInput(input: ProviderSetupInput): {
 	providerId: string;
 	baseUrl: string;
 	apiKey: string;
 	credentialSource: ProviderSetupResult["credentialSource"];
 	models: string[];
+	compatibility: ProviderCompatibility;
+	api: ProviderSetupApi;
+	compat?: ProviderCompatConfig;
+	preset?: ProviderPreset;
 } {
-	const providerId = normalizeProviderId(input.providerId);
+	const resolved = resolvePresetInput(input);
+	if (!resolved.providerId) throw new Error("Provider id is required.");
+	if (!resolved.baseUrl) throw new Error("Base URL is required.");
+	const providerId = normalizeProviderId(resolved.providerId);
 	if (!PROVIDER_ID_PATTERN.test(providerId)) {
 		throw new Error("Provider id must use lowercase letters, numbers, dots, underscores, or hyphens.");
 	}
 
-	const baseUrl = input.baseUrl.trim();
+	const baseUrl = resolved.baseUrl.trim();
 	let url: URL;
 	try {
 		url = new URL(baseUrl);
@@ -95,19 +243,29 @@ function validateSetupInput(input: ProviderSetupInput): {
 		throw new Error("Base URL must use https unless it targets localhost or a loopback address.");
 	}
 
-	const apiKeyEnv = input.apiKeyEnv?.trim();
+	const apiKeyEnv = resolved.apiKeyEnv?.trim();
 	if (apiKeyEnv) {
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) {
 			throw new Error("API key environment variable must be a valid environment variable name.");
 		}
 	}
-	const apiKey = apiKeyEnv ?? input.apiKey?.trim() ?? "";
+	const apiKey = apiKeyEnv ?? resolved.apiKey?.trim() ?? "";
 	if (!apiKey) throw new Error("API key is required.");
 
-	const models = parseModelList(input.models);
+	const models = parseModelList(resolved.models);
 	if (models.length === 0) throw new Error("At least one model id is required.");
 
-	return { providerId, baseUrl, apiKey, credentialSource: apiKeyEnv ? "env" : "literal", models };
+	return {
+		providerId,
+		baseUrl,
+		apiKey,
+		credentialSource: apiKeyEnv ? "env" : "literal",
+		models,
+		compatibility: resolved.compatibility,
+		api: resolved.api,
+		compat: resolved.compat,
+		preset: resolved.preset,
+	};
 }
 
 async function readModelsConfig(modelsPath: string): Promise<ModelsConfig> {
@@ -140,16 +298,16 @@ export async function addApiCompatibleProvider(input: ProviderSetupInput): Promi
 	const validated = validateSetupInput(input);
 	const modelsPath = input.modelsPath ?? getDefaultModelsPath();
 	const existing = await readModelsConfig(modelsPath);
-	const api = apiForCompatibility(input.compatibility);
 	if (existing.providers?.[validated.providerId] && !input.force) {
 		throw new Error(`Provider '${validated.providerId}' already exists. Use --force to replace it.`);
 	}
 	const provider: ProviderConfig = {
 		baseUrl: validated.baseUrl,
-		api,
+		api: validated.api,
 		auth: "apiKey",
 		models: validated.models.map(id => ({ id })),
 	};
+	if (validated.compat) provider.compat = validated.compat;
 	if (validated.credentialSource === "env") {
 		provider.apiKeyEnv = validated.apiKey;
 	} else {
@@ -165,13 +323,15 @@ export async function addApiCompatibleProvider(input: ProviderSetupInput): Promi
 	await writeModelsConfig(modelsPath, next);
 	return {
 		providerId: validated.providerId,
-		compatibility: input.compatibility,
-		api,
+		compatibility: validated.compatibility,
+		api: validated.api,
 		baseUrl: validated.baseUrl,
 		modelIds: validated.models,
 		modelsPath,
 		redactedApiKey: redactSecret(validated.apiKey),
 		credentialSource: validated.credentialSource,
+		preset: validated.preset?.id,
+		presetName: validated.preset?.name,
 	};
 }
 
@@ -189,6 +349,7 @@ function isLocalHttpHost(hostname: string): boolean {
 export function formatProviderSetupResult(result: ProviderSetupResult): string {
 	return [
 		`Provider '${result.providerId}' configured as ${result.compatibility}-compatible.`,
+		...(result.presetName ? [`Preset: ${result.presetName}`] : []),
 		`Models: ${result.modelIds.join(", ")}`,
 		`Base URL: ${result.baseUrl}`,
 		`API key: ${result.credentialSource === "env" ? `${result.redactedApiKey} (environment variable)` : result.redactedApiKey}`,

package/src/skill-state/active-state.ts

@@ -3,7 +3,6 @@ import * as path from "node:path";
 import type { WorkflowStateReceipt } from "./workflow-state-contract";
 
 export const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
-export const SKILL_ACTIVE_STALE_MS = 24 * 60 * 60 * 1000;
 
 export const CANONICAL_GJC_WORKFLOW_SKILLS = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
 
@@ -40,6 +39,9 @@ export interface SkillActiveEntry {
 	hud?: WorkflowHudSummary;
 	stale?: boolean;
 	receipt?: WorkflowStateReceipt;
+	handoff_from?: string;
+	handoff_to?: string;
+	handoff_at?: string;
 }
 
 export interface SkillActiveState {
@@ -75,6 +77,9 @@ export interface SyncSkillActiveStateOptions {
 	source?: string;
 	hud?: WorkflowHudSummary;
 	receipt?: WorkflowStateReceipt;
+	handoff_from?: string;
+	handoff_to?: string;
+	handoff_at?: string;
 }
 
 const HUD_TEXT_LIMIT = 80;
@@ -185,25 +190,6 @@ function entryKey(entry: Pick<SkillActiveEntry, "skill" | "session_id">): string
 	return `${entry.skill}::${safeString(entry.session_id).trim()}`;
 }
 
-function timestampMs(value: string | undefined): number | null {
-	if (!value) return null;
-	const ms = Date.parse(value);
-	return Number.isFinite(ms) ? ms : null;
-}
-
-function entryTimestampMs(entry: SkillActiveEntry): number | null {
-	return timestampMs(entry.hud?.updated_at) ?? timestampMs(entry.updated_at) ?? timestampMs(entry.activated_at);
-}
-
-function isFreshEntry(entry: SkillActiveEntry, nowMs = Date.now()): boolean {
-	const ms = entryTimestampMs(entry);
-	return ms === null || nowMs - ms <= SKILL_ACTIVE_STALE_MS;
-}
-
-function withDerivedStale(entry: SkillActiveEntry, nowMs = Date.now()): SkillActiveEntry {
-	return { ...entry, stale: !isFreshEntry(entry, nowMs) };
-}
-
 function normalizeEntry(raw: unknown): SkillActiveEntry | null {
 	if (!raw || typeof raw !== "object") return null;
 	const record = raw as Record<string, unknown>;
@@ -221,6 +207,9 @@ function normalizeEntry(raw: unknown): SkillActiveEntry | null {
 		session_id: safeString(record.session_id).trim() || undefined,
 		thread_id: safeString(record.thread_id).trim() || undefined,
 		turn_id: safeString(record.turn_id).trim() || undefined,
+		handoff_from: safeString(record.handoff_from).trim() || undefined,
+		handoff_to: safeString(record.handoff_to).trim() || undefined,
+		handoff_at: safeString(record.handoff_at).trim() || undefined,
 		...(hud ? { hud } : {}),
 		...(receipt ? { receipt } : {}),
 		stale: undefined,
@@ -305,6 +294,48 @@ async function readStateFile(filePath: string): Promise<SkillActiveState | null>
 	}
 }
 
+/**
+ * Raw read for handoff mutations. Returns the *unnormalized* parsed object so
+ * inactive entries remain visible to `rawActiveEntries` — `normalizeSkillActiveState`
+ * delegates to `listActiveSkills`, which filters out `active:false` rows for HUD
+ * purposes. Handoff history (e.g. previously demoted callers carrying
+ * `handoff_to`/`handoff_at` lineage) must survive across successive handoffs,
+ * so the on-disk `active_skills` array is preserved verbatim and the next
+ * write recomputes the per-skill row from there.
+ *
+ * Strict semantics: tolerates ENOENT only. Corrupt JSON / non-ENOENT I/O
+ * errors propagate so callers can surface a non-zero CLI status.
+ */
+async function readRawActiveStateForHandoff(filePath: string, strict: boolean): Promise<SkillActiveState | null> {
+	let raw: string;
+	try {
+		raw = await Bun.file(filePath).text();
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return null;
+		if (!strict) return null;
+		throw err;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object") return null;
+		return parsed as SkillActiveState;
+	} catch (err) {
+		if (!strict) return null;
+		throw err;
+	}
+}
+
+function rawActiveEntries(state: SkillActiveState | null): SkillActiveEntry[] {
+	if (!state || !Array.isArray(state.active_skills)) return [];
+	const out: SkillActiveEntry[] = [];
+	for (const candidate of state.active_skills) {
+		const normalized = normalizeEntry(candidate);
+		if (normalized) out.push(normalized);
+	}
+	return out;
+}
+
 function filterRootEntriesForSession(entries: SkillActiveEntry[], sessionId?: string): SkillActiveEntry[] {
 	const normalizedSessionId = safeString(sessionId).trim();
 	if (!normalizedSessionId) return entries;
@@ -319,12 +350,9 @@ function mergeVisibleEntries(
 	rootState: SkillActiveState | null,
 	sessionId?: string,
 ): SkillActiveEntry[] {
-	const nowMs = Date.now();
-	const rootEntries = filterRootEntriesForSession(listActiveSkills(rootState), sessionId).map(entry =>
-		withDerivedStale(entry, nowMs),
-	);
+	const rootEntries = filterRootEntriesForSession(listActiveSkills(rootState), sessionId);
 	const merged = new Map(rootEntries.map(entry => [entryKey(entry), entry]));
-	for (const entry of listActiveSkills(sessionState).map(candidate => withDerivedStale(candidate, nowMs))) {
+	for (const entry of listActiveSkills(sessionState)) {
 		merged.set(entryKey(entry), entry);
 	}
 	return [...merged.values()];
@@ -374,6 +402,9 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 		session_id: options.sessionId,
 		thread_id: options.threadId,
 		turn_id: options.turnId,
+		...(options.handoff_from ? { handoff_from: options.handoff_from } : {}),
+		...(options.handoff_to ? { handoff_to: options.handoff_to } : {}),
+		...(options.handoff_at ? { handoff_at: options.handoff_at } : {}),
 		...(hud ? { hud } : {}),
 		...(options.receipt ? { receipt: options.receipt } : {}),
 	};
@@ -408,3 +439,97 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 	};
 	await writeStateFile(sessionPath, nextSession);
 }
+
+export interface ApplyHandoffOptions {
+	cwd: string;
+	caller: SyncSkillActiveStateOptions;
+	callee: SyncSkillActiveStateOptions;
+	/** Shared timestamp; falls back to new Date().toISOString(). */
+	nowIso?: string;
+	/** When true, read errors other than ENOENT propagate. */
+	strict?: boolean;
+}
+
+/**
+ * Atomically apply a workflow-skill handoff to both the session-scoped and
+ * root `skill-active-state.json` files in a single write per file.
+ *
+ * Write order: **session first, root last**. The session file is the
+ * source of truth for HUD; the root aggregate must never lead the session
+ * during a handoff window. Each file is rewritten once with caller demoted
+ * to `active:false` (preserving `handoff_to`/`handoff_at` lineage) and
+ * callee promoted to `active:true` (with `handoff_from`/`handoff_at`).
+ */
+export async function applyHandoffToActiveState(options: ApplyHandoffOptions): Promise<void> {
+	const nowIso = options.nowIso ?? new Date().toISOString();
+	const callerEntry = buildSyncEntry(options.caller, nowIso);
+	const calleeEntry = buildSyncEntry(options.callee, nowIso);
+	const sessionId = options.callee.sessionId ?? options.caller.sessionId;
+	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, sessionId);
+	const readState = (filePath: string) => readRawActiveStateForHandoff(filePath, options.strict === true);
+
+	const applyEntries = (entries: SkillActiveEntry[]): SkillActiveEntry[] => {
+		const callerKey = entryKey(callerEntry);
+		const calleeKey = entryKey(calleeEntry);
+		const priorCaller = entries.find(e => entryKey(e) === callerKey);
+		const kept = entries.filter(e => entryKey(e) !== callerKey && entryKey(e) !== calleeKey);
+		// Merge prior lineage into the demoted caller so multi-step handoff
+		// chains preserve `handoff_from` from the previous transition while
+		// the new `handoff_to`/`handoff_at` describe this one.
+		const mergedCaller: SkillActiveEntry = priorCaller
+			? {
+					...callerEntry,
+					...(priorCaller.handoff_from && !callerEntry.handoff_from
+						? { handoff_from: priorCaller.handoff_from }
+						: {}),
+				}
+			: callerEntry;
+		return [...kept, mergedCaller, calleeEntry];
+	};
+	const buildNextState = (
+		prior: SkillActiveState | null,
+		entries: SkillActiveEntry[],
+		scope: "session" | "root",
+	): SkillActiveState => {
+		const visible = entries.filter(e => e.active !== false);
+		return {
+			...(prior ?? {}),
+			version: 1,
+			active: visible.length > 0,
+			skill: visible[0]?.skill ?? "",
+			phase: visible[0]?.phase ?? "",
+			...(scope === "session" ? { session_id: sessionId } : {}),
+			updated_at: nowIso,
+			source: options.callee.source ?? options.caller.source,
+			active_skills: entries,
+		};
+	};
+
+	if (sessionPath) {
+		const prior = await readState(sessionPath);
+		const next = buildNextState(prior, applyEntries(rawActiveEntries(prior)), "session");
+		await writeStateFile(sessionPath, next);
+	}
+	const priorRoot = await readState(rootPath);
+	const nextRoot = buildNextState(priorRoot, applyEntries(rawActiveEntries(priorRoot)), "root");
+	await writeStateFile(rootPath, nextRoot);
+}
+
+function buildSyncEntry(options: SyncSkillActiveStateOptions, nowIso: string): SkillActiveEntry {
+	const hud = normalizeWorkflowHudSummary(options.hud);
+	return {
+		skill: options.skill,
+		phase: options.phase,
+		active: options.active,
+		activated_at: nowIso,
+		updated_at: nowIso,
+		session_id: options.sessionId,
+		thread_id: options.threadId,
+		turn_id: options.turnId,
+		...(options.handoff_from ? { handoff_from: options.handoff_from } : {}),
+		...(options.handoff_to ? { handoff_to: options.handoff_to } : {}),
+		...(options.handoff_at ? { handoff_at: options.handoff_at } : {}),
+		...(hud ? { hud } : {}),
+		...(options.receipt ? { receipt: options.receipt } : {}),
+	};
+}

package/src/skill-state/deep-interview-mutation-guard.ts

@@ -12,7 +12,7 @@ import {
 } from "./workflow-state-contract";
 
 export const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE =
-	"Deep-interview is active; continue interviewing with `ask`, write/finalize pending specs through the required GJC workflow CLI, or use an explicit force override. Direct `.gjc/` and product-code edits are blocked until explicit execution approval.";
+	"Deep-interview phase boundary: continue gathering context/questions/risks and emit a handoff/spec before code edits. Mutation tools and patch execution are blocked while deep-interview is active; finalize specs through `gjc deep-interview --write --stage final` or hand off to an execution phase.";
 export const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE =
 	"Workflow state JSON is runtime-owned. Use `gjc state <skill> read|write --input '<json>'` for deep-interview, ralplan, ultragoal, and team. Planning artifacts under `.gjc/specs/` and `.gjc/plans/` remain allowed.";
 
@@ -88,7 +88,7 @@ async function readVisibleModeState(cwd: string, skill: string, sessionId?: stri
 }
 
 function isTerminalModeState(state: ModeState | null): boolean {
-	if (!state || state.active !== true) return true;
+	if (state?.active !== true) return true;
 	const phase = String(state.current_phase ?? "")
 		.trim()
 		.toLowerCase();
@@ -265,7 +265,7 @@ function relativeGjcSegments(cwd: string, rawPath: string): string[] | null {
 
 function blockedWorkflowStateSkill(cwd: string, rawPath: string): CanonicalGjcWorkflowSkill | null {
 	const segments = relativeGjcSegments(cwd, rawPath);
-	if (!segments || segments[0] !== ".gjc") return null;
+	if (segments?.[0] !== ".gjc") return null;
 	if (segments[1] === "specs" || segments[1] === "plans") return null;
 	if (segments[1] !== "state") return null;
 	const fileName = segments.at(-1) ?? "";
@@ -284,22 +284,12 @@ function firstBlockedWorkflowStateSkill(cwd: string, targets: ExtractedTargets):
 	return null;
 }
 
-function isGjcManagedPath(cwd: string, rawPath: string): boolean {
-	const segments = relativeGjcSegments(cwd, rawPath);
-	return segments?.[0] === ".gjc";
-}
-
 function isAllowlistedPath(cwd: string, rawPath: string): boolean {
 	const segments = relativeGjcSegments(cwd, rawPath);
-	if (!segments || segments[0] !== ".gjc") return false;
+	if (segments?.[0] !== ".gjc") return false;
 	return segments[1] === "specs" || segments[1] === "plans";
 }
 
-function hasGjcManagedTarget(cwd: string, targets: ExtractedTargets): boolean {
-	if (targets.unknown || targets.paths.length === 0) return false;
-	return targets.paths.some(rawPath => isGjcManagedPath(cwd, rawPath));
-}
-
 function allTargetsAllowlisted(cwd: string, targets: ExtractedTargets): boolean {
 	return (
 		!targets.unknown && targets.paths.length > 0 && targets.paths.every(rawPath => isAllowlistedPath(cwd, rawPath))
@@ -315,7 +305,7 @@ export async function assertDeepInterviewMutationRawPathsAllowed(input: {
 	if (input.forceOverride) return;
 	if (!(await isActiveDeepInterview(input.cwd, input.sessionId, input.threadId))) return;
 	const targets: ExtractedTargets = { paths: input.rawPaths, unknown: input.rawPaths.length === 0 };
-	if (hasGjcManagedTarget(input.cwd, targets)) {
+	if (targets.unknown || targets.paths.length > 0) {
 		throw new ToolError(DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE);
 	}
 }
@@ -350,15 +340,12 @@ export async function getDeepInterviewMutationDecision(
 			reason: "unknown-target",
 		};
 	}
-	if (hasGjcManagedTarget(input.cwd, targets) && !allTargetsAllowlisted(input.cwd, targets)) {
-		return {
-			blocked: true,
-			message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,
-			targets: targets.paths,
-			reason: "gjc-managed-target",
-		};
-	}
-	return { blocked: false, targets: targets.paths };
+	return {
+		blocked: true,
+		message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,
+		targets: targets.paths,
+		reason: allTargetsAllowlisted(input.cwd, targets) ? "handoff-artifact-tool-target" : "phase-boundary",
+	};
 }
 
 export async function assertDeepInterviewMutationAllowed(input: DeepInterviewMutationGuardInput): Promise<void> {

package/src/skill-state/initial-phase.ts

@@ -0,0 +1,17 @@
+import type { CanonicalGjcWorkflowSkill } from "./active-state";
+
+/**
+ * Canonical initial phase for each GJC workflow skill. Used by both
+ * `recordSkillActivation` (UserPromptSubmit hook seeding initial mode-state)
+ * and the `gjc state <caller> handoff --to <callee>` runtime when promoting
+ * the callee.
+ *
+ * Keeping this mapping in a neutral skill-state module avoids cycles between
+ * `gjc-runtime/state-runtime.ts` and `hooks/skill-state.ts` (which pulls in
+ * session-manager and ultragoal verification code).
+ */
+export function initialPhaseForSkill(skill: CanonicalGjcWorkflowSkill | string): string {
+	if (skill === "deep-interview") return "interviewing";
+	if (skill === "ultragoal") return "goal-planning";
+	return "planning";
+}