@gajae-code/coding-agent 0.2.1 → 0.2.3

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

@@ -1,8 +1,8 @@
 import * as fs from "node:fs/promises";
 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;
 
@@ -25,6 +25,8 @@ export interface WorkflowHudSummary {
 	updated_at?: string;
 }
 
+export type { WorkflowStateReceipt } from "./workflow-state-contract";
+
 export interface SkillActiveEntry {
 	skill: string;
 	phase?: string;
@@ -36,6 +38,10 @@ export interface SkillActiveEntry {
 	turn_id?: string;
 	hud?: WorkflowHudSummary;
 	stale?: boolean;
+	receipt?: WorkflowStateReceipt;
+	handoff_from?: string;
+	handoff_to?: string;
+	handoff_at?: string;
 }
 
 export interface SkillActiveState {
@@ -70,6 +76,10 @@ export interface SyncSkillActiveStateOptions {
 	nowIso?: string;
 	source?: string;
 	hud?: WorkflowHudSummary;
+	receipt?: WorkflowStateReceipt;
+	handoff_from?: string;
+	handoff_to?: string;
+	handoff_at?: string;
 }
 
 const HUD_TEXT_LIMIT = 80;
@@ -142,6 +152,36 @@ export function normalizeWorkflowHudSummary(raw: unknown): WorkflowHudSummary |
 	};
 }
 
+function normalizeWorkflowStateReceipt(raw: unknown): WorkflowStateReceipt | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const record = raw as Record<string, unknown>;
+	if (record.version !== 1) return undefined;
+	const skill = safeString(record.skill).trim();
+	if (!isCanonicalGjcWorkflowSkill(skill)) return undefined;
+	const owner = safeString(record.owner).trim();
+	if (owner !== "gjc-state-cli" && owner !== "gjc-runtime" && owner !== "gjc-hook") return undefined;
+	const command = sanitizeHudString(record.command, 120);
+	const statePath = sanitizeHudString(record.state_path, 240);
+	const storagePath = sanitizeHudString(record.storage_path, 240);
+	const mutatedAt = sanitizeHudString(record.mutated_at, 40);
+	const freshUntil = sanitizeHudString(record.fresh_until, 40);
+	const status = safeString(record.status).trim();
+	const mutationId = sanitizeHudString(record.mutation_id, 120);
+	if (!command || !statePath || !storagePath || !mutatedAt || !freshUntil || !mutationId) return undefined;
+	return {
+		version: 1,
+		skill,
+		owner,
+		command,
+		state_path: statePath,
+		storage_path: storagePath,
+		mutated_at: mutatedAt,
+		fresh_until: freshUntil,
+		status: status === "stale" ? "stale" : "fresh",
+		mutation_id: mutationId,
+	};
+}
+
 function encodePathSegment(value: string): string {
 	return encodeURIComponent(value).replaceAll(".", "%2E");
 }
@@ -150,31 +190,13 @@ 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>;
 	const skill = safeString(record.skill).trim();
 	if (!skill) return null;
 	const hud = normalizeWorkflowHudSummary(record.hud);
+	const receipt = normalizeWorkflowStateReceipt(record.receipt);
 	return {
 		...record,
 		skill,
@@ -185,7 +207,11 @@ 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,
 	};
 }
@@ -268,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;
@@ -282,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()];
@@ -337,7 +402,11 @@ 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 } : {}),
 	};
 	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, options.sessionId);
 	const rootState = (await readStateFile(rootPath)) ?? { version: 1, active_skills: [] };
@@ -370,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

@@ -5,14 +5,20 @@ import { LocalProtocolHandler, resolveLocalUrlToPath } from "../internal-urls/lo
 import { resolveToCwd } from "../tools/path-utils";
 import { ToolError } from "../tools/tool-errors";
 import { listActiveSkills, readVisibleSkillActiveState, type SkillActiveEntry } from "./active-state";
+import {
+	type CanonicalGjcWorkflowSkill,
+	sanctionedWorkflowStateCommand,
+	workflowModeStateFileName,
+} from "./workflow-state-contract";
 
 export const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE =
-	"Deep-interview is active; either continue interviewing with `ask`, or write/finalize the pending spec under `.gjc/specs/` / update state under `.gjc/state/`. Do not edit product code 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.";
 
 const BLOCKED_TOOL_NAMES = new Set(["edit", "write", "ast_edit"]);
 const ARCHIVE_OR_SQLITE_BASE_RE = /^(.+?\.(?:tar\.gz|sqlite3|sqlite|db3|zip|tgz|tar|db))(?:$|:)/i;
 const INTERNAL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
-const GLOB_META_RE = /[*?[\]{}]/;
 const VIM_FILE_SWITCH_RE = /^\s*:(?:e|e!|edit|edit!)(?:\s+([^<\r\n]+))?(?:<CR>|\r|\n|$)/i;
 
 type ToolWithEditMode = AgentTool & {
@@ -26,6 +32,8 @@ export interface DeepInterviewMutationGuardInput {
 	threadId?: string;
 	tool: ToolWithEditMode;
 	args: unknown;
+	forceOverride?: boolean;
+	enforceWorkflowState?: boolean;
 }
 
 interface ExtractedTargets {
@@ -38,6 +46,7 @@ export interface DeepInterviewMutationDecision {
 	message?: string;
 	targets: string[];
 	reason?: string;
+	command?: string;
 }
 
 interface ModeState {
@@ -79,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();
@@ -246,34 +255,57 @@ function resolveRawPath(cwd: string, rawPath: string): { absolutePath?: string;
 	}
 }
 
-function isAllowlistedPath(cwd: string, rawPath: string): boolean {
+function relativeGjcSegments(cwd: string, rawPath: string): string[] | null {
 	const { absolutePath, unknown } = resolveRawPath(cwd, rawPath);
-	if (unknown || !absolutePath) return false;
+	if (unknown || !absolutePath) return null;
 	const relative = path.relative(path.resolve(cwd), path.resolve(absolutePath));
-	if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) return false;
-	const segments = normalizePosix(relative).split("/").filter(Boolean);
-	return segments[0] === ".gjc" && (segments[1] === "specs" || segments[1] === "state");
+	if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) return null;
+	return normalizePosix(relative).split("/").filter(Boolean);
 }
 
-function allTargetsAllowlisted(cwd: string, targets: ExtractedTargets): boolean {
-	if (targets.unknown || targets.paths.length === 0) return false;
-	return targets.paths.every(rawPath => {
-		if (GLOB_META_RE.test(rawPath)) {
-			return isAllowlistedPath(cwd, rawPath);
-		}
-		return isAllowlistedPath(cwd, rawPath);
-	});
+function blockedWorkflowStateSkill(cwd: string, rawPath: string): CanonicalGjcWorkflowSkill | null {
+	const segments = relativeGjcSegments(cwd, rawPath);
+	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) ?? "";
+	for (const skillName of ["deep-interview", "ralplan", "ultragoal", "team"] as const) {
+		if (fileName === workflowModeStateFileName(skillName)) return skillName;
+	}
+	if (fileName === "skill-active-state.json") return "deep-interview";
+	return null;
 }
 
+function firstBlockedWorkflowStateSkill(cwd: string, targets: ExtractedTargets): CanonicalGjcWorkflowSkill | null {
+	for (const rawPath of targets.paths) {
+		const skill = blockedWorkflowStateSkill(cwd, rawPath);
+		if (skill) return skill;
+	}
+	return null;
+}
+
+function isAllowlistedPath(cwd: string, rawPath: string): boolean {
+	const segments = relativeGjcSegments(cwd, rawPath);
+	if (segments?.[0] !== ".gjc") return false;
+	return segments[1] === "specs" || segments[1] === "plans";
+}
+
+function allTargetsAllowlisted(cwd: string, targets: ExtractedTargets): boolean {
+	return (
+		!targets.unknown && targets.paths.length > 0 && targets.paths.every(rawPath => isAllowlistedPath(cwd, rawPath))
+	);
+}
 export async function assertDeepInterviewMutationRawPathsAllowed(input: {
 	cwd: string;
 	sessionId?: string;
 	threadId?: string;
 	rawPaths: string[];
+	forceOverride?: boolean;
 }): Promise<void> {
+	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 (!allTargetsAllowlisted(input.cwd, targets)) {
+	if (targets.unknown || targets.paths.length > 0) {
 		throw new ToolError(DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE);
 	}
 }
@@ -282,18 +314,37 @@ export async function getDeepInterviewMutationDecision(
 	input: DeepInterviewMutationGuardInput,
 ): Promise<DeepInterviewMutationDecision> {
 	if (!BLOCKED_TOOL_NAMES.has(input.tool.name)) return { blocked: false, targets: [] };
+	const targets = extractTargets(input.tool, input.args);
+	if (input.enforceWorkflowState !== false) {
+		const stateSkill = firstBlockedWorkflowStateSkill(input.cwd, targets);
+		if (stateSkill) {
+			const command = sanctionedWorkflowStateCommand(stateSkill);
+			return {
+				blocked: true,
+				message: `${WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE}\nUse: ${command}`,
+				targets: targets.paths,
+				reason: "workflow-state-target",
+				command,
+			};
+		}
+	}
 	if (!(await isActiveDeepInterview(input.cwd, input.sessionId, input.threadId))) {
 		return { blocked: false, targets: [] };
 	}
-	const targets = extractTargets(input.tool, input.args);
-	if (allTargetsAllowlisted(input.cwd, targets)) {
-		return { blocked: false, targets: targets.paths };
+	if (input.forceOverride) return { blocked: false, targets: [] };
+	if (targets.unknown) {
+		return {
+			blocked: true,
+			message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,
+			targets: targets.paths,
+			reason: "unknown-target",
+		};
 	}
 	return {
 		blocked: true,
 		message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,
 		targets: targets.paths,
-		reason: targets.unknown ? "unknown-target" : "product-target",
+		reason: allTargetsAllowlisted(input.cwd, targets) ? "handoff-artifact-tool-target" : "phase-boundary",
 	};
 }
 

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";
+}

package/src/skill-state/workflow-hud.ts

@@ -1,6 +1,12 @@
 import type { WorkflowHudChip, WorkflowHudSummary } from "./active-state";
 
-interface DeepInterviewHudState {
+interface WorkflowGateHudState {
+	approvalStatus?: string;
+	blockedReason?: string;
+	nextAction?: string;
+}
+
+interface DeepInterviewHudState extends WorkflowGateHudState {
 	phase?: string;
 	ambiguity?: number;
 	threshold?: number;
@@ -11,7 +17,7 @@ interface DeepInterviewHudState {
 	updatedAt?: string;
 }
 
-interface RalplanHudState {
+interface RalplanHudState extends WorkflowGateHudState {
 	stage?: string;
 	waiting?: string;
 	iteration?: number;
@@ -27,7 +33,7 @@ interface UltragoalLikeGoal {
 	status: string;
 }
 
-interface UltragoalHudState {
+interface UltragoalHudState extends WorkflowGateHudState {
 	status: string;
 	currentGoal?: UltragoalLikeGoal;
 	counts: Record<string, number>;
@@ -41,7 +47,7 @@ interface TeamHudWorker {
 	status?: string;
 }
 
-interface TeamHudState {
+interface TeamHudState extends WorkflowGateHudState {
 	phase: string;
 	task_total: number;
 	task_counts: Record<string, number>;
@@ -66,6 +72,14 @@ function chip(
 	return { label, value, priority, ...(severity ? { severity } : {}) };
 }
 
+function gateChips(state: WorkflowGateHudState, gatePriority: number): Array<WorkflowHudChip | null> {
+	return [
+		chip("gate", state.approvalStatus, gatePriority, state.approvalStatus === "approved" ? "success" : "warning"),
+		chip("blocked", state.blockedReason, gatePriority + 10, "blocked"),
+		chip("next", state.nextAction, gatePriority + 20),
+	];
+}
+
 function compactChips(chips: Array<WorkflowHudChip | null>): WorkflowHudChip[] {
 	return chips.filter((item): item is WorkflowHudChip => item !== null);
 }
@@ -74,6 +88,7 @@ export function buildDeepInterviewHudSummary(state: DeepInterviewHudState): Work
 	return {
 		version: 1,
 		chips: compactChips([
+			...gateChips(state, 5),
 			chip("phase", state.phase, 10),
 			chip("ambiguity", [percent(state.ambiguity), percent(state.threshold)].filter(Boolean).join("/"), 20),
 			chip("round", state.roundCount === undefined ? undefined : String(state.roundCount), 30),
@@ -100,6 +115,7 @@ export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSumma
 		summary: state.latestSummary,
 		chips: compactChips([
 			state.pendingApproval ? { label: "pending", value: "approval", priority: 5, severity: "warning" } : null,
+			...gateChips(state, 6),
 			chip("stage", state.stage, 10),
 			chip("waiting", state.waiting, 20),
 			chip("iter", state.iteration === undefined ? undefined : String(state.iteration), 30),
@@ -120,6 +136,7 @@ export function buildUltragoalHudSummary(state: UltragoalHudState): WorkflowHudS
 			chip("goals", `${complete}/${total}`, 10),
 			chip("current", state.currentGoal ? `${state.currentGoal.id}:${state.currentGoal.title}` : state.status, 20),
 			chip("status", state.status, 30, state.status === "complete" ? "success" : undefined),
+			...gateChips(state, 40),
 		]),
 		details: state.latestLedgerEvent
 			? compactChips([
@@ -153,7 +170,8 @@ export function buildTeamHudSummary(state: TeamHudState): WorkflowHudSummary {
 			chip("phase", state.phase, 10),
 			chip("workers", `${state.workers.length - failedWorkers}/${state.workers.length}`, 20),
 			chip("tasks", `${completed}/${state.task_total}`, 30),
-			chip("latest", latest, 50),
+			...gateChips(state, 40),
+			chip("latest", latest, 70),
 		]),
 		...(state.updated_at ? { updated_at: state.updated_at } : {}),
 	};

package/src/skill-state/workflow-state-contract.ts

@@ -0,0 +1,121 @@
+import * as path from "node:path";
+import { CANONICAL_GJC_WORKFLOW_SKILLS, type CanonicalGjcWorkflowSkill, SKILL_ACTIVE_STATE_FILE } from "./active-state";
+
+export type { CanonicalGjcWorkflowSkill };
+
+export const WORKFLOW_STATE_RECEIPT_VERSION = 1;
+export const WORKFLOW_STATE_RECEIPT_FRESH_MS = 30 * 60 * 1000;
+
+export type WorkflowStateMutationOwner = "gjc-state-cli" | "gjc-runtime" | "gjc-hook";
+export type WorkflowStateReceiptStatus = "fresh" | "stale";
+
+export interface WorkflowStateReceipt {
+	version: 1;
+	skill: CanonicalGjcWorkflowSkill;
+	owner: WorkflowStateMutationOwner;
+	command: string;
+	state_path: string;
+	storage_path: string;
+	mutated_at: string;
+	fresh_until: string;
+	status: WorkflowStateReceiptStatus;
+	mutation_id: string;
+}
+
+function safeString(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function encodePathSegment(value: string): string {
+	return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+
+export function workflowModeStateFileName(skill: CanonicalGjcWorkflowSkill): string {
+	return `${skill}-state.json`;
+}
+
+export function workflowStateStoragePath(cwd: string, skill: CanonicalGjcWorkflowSkill, sessionId?: string): string {
+	const normalizedSessionId = safeString(sessionId).trim();
+	if (normalizedSessionId) {
+		return path.join(
+			cwd,
+			".gjc",
+			"state",
+			"sessions",
+			encodePathSegment(normalizedSessionId),
+			workflowModeStateFileName(skill),
+		);
+	}
+	return path.join(cwd, ".gjc", "state", workflowModeStateFileName(skill));
+}
+
+export function workflowActiveStatePath(cwd: string, sessionId?: string): string {
+	const normalizedSessionId = safeString(sessionId).trim();
+	if (normalizedSessionId) {
+		return path.join(
+			cwd,
+			".gjc",
+			"state",
+			"sessions",
+			encodePathSegment(normalizedSessionId),
+			SKILL_ACTIVE_STATE_FILE,
+		);
+	}
+	return path.join(cwd, ".gjc", "state", SKILL_ACTIVE_STATE_FILE);
+}
+
+export function buildWorkflowStateReceipt(input: {
+	cwd: string;
+	skill: CanonicalGjcWorkflowSkill;
+	owner: WorkflowStateMutationOwner;
+	command: string;
+	sessionId?: string;
+	nowIso?: string;
+	mutationId?: string;
+}): WorkflowStateReceipt {
+	const mutatedAt = input.nowIso ?? new Date().toISOString();
+	const freshUntil = new Date(Date.parse(mutatedAt) + WORKFLOW_STATE_RECEIPT_FRESH_MS).toISOString();
+	return {
+		version: WORKFLOW_STATE_RECEIPT_VERSION,
+		skill: input.skill,
+		owner: input.owner,
+		command: input.command,
+		state_path: workflowActiveStatePath(input.cwd, input.sessionId),
+		storage_path: workflowStateStoragePath(input.cwd, input.skill, input.sessionId),
+		mutated_at: mutatedAt,
+		fresh_until: freshUntil,
+		status: "fresh",
+		mutation_id: input.mutationId ?? `${input.skill}:${mutatedAt}`,
+	};
+}
+
+export function workflowReceiptStatus(
+	receipt: WorkflowStateReceipt | undefined,
+	nowMs = Date.now(),
+): WorkflowStateReceiptStatus | undefined {
+	if (!receipt) return undefined;
+	const freshUntilMs = Date.parse(receipt.fresh_until);
+	if (!Number.isFinite(freshUntilMs)) return "stale";
+	return nowMs <= freshUntilMs ? "fresh" : "stale";
+}
+
+export function canonicalWorkflowSkill(value: string): CanonicalGjcWorkflowSkill | null {
+	return (CANONICAL_GJC_WORKFLOW_SKILLS as readonly string[]).includes(value)
+		? (value as CanonicalGjcWorkflowSkill)
+		: null;
+}
+
+export function sanctionedWorkflowStateCommand(skill: CanonicalGjcWorkflowSkill): string {
+	return `gjc state ${skill} write --input '<json>'`;
+}
+
+export function describeWorkflowStateContract(skill: CanonicalGjcWorkflowSkill): string[] {
+	return [
+		`Sanctioned mutation path: gjc state ${skill} read|write --input '<json>'`,
+		`Canonical active HUD state: .gjc/state/${SKILL_ACTIVE_STATE_FILE} and .gjc/state/sessions/<session>/${SKILL_ACTIVE_STATE_FILE}`,
+		`Skill mode state: .gjc/state/${workflowModeStateFileName(skill)} or .gjc/state/sessions/<session>/${workflowModeStateFileName(skill)}`,
+		"Receipts include version, skill, owner, command, state_path, storage_path, mutated_at, fresh_until, status, and mutation_id.",
+		"Receipts are fresh for 30 minutes; older receipts are stale and render as HUD warnings.",
+		"Planning artifacts under .gjc/specs/** and .gjc/plans/** remain writable outside the state command.",
+	];
+}