@gajae-code/coding-agent 0.3.1 → 0.4.0

package/src/extensibility/gjc-plugins/schema.ts

@@ -0,0 +1,79 @@
+import { GJC_PLUGIN_KIND, GjcPluginLoadError, type GjcPluginManifest, type SubskillFrontmatter } from "./types";
+
+const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "hooks", "mcp", "mcpServers", "agents"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireNonEmptyString(value: unknown, field: string, filePath: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new GjcPluginLoadError(
+			"invalid_frontmatter",
+			`Invalid sub-skill frontmatter in ${filePath}: ${field} must be a non-empty string`,
+		);
+	}
+	return value;
+}
+
+function requireStringArray(value: unknown, field: string, manifestPath: string): string[] {
+	if (!Array.isArray(value) || !value.every(item => typeof item === "string")) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: ${field} must be a string array`,
+		);
+	}
+	return [...value];
+}
+
+export function parseManifest(raw: unknown, manifestPath: string): GjcPluginManifest {
+	if (!isRecord(raw)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: expected object`,
+		);
+	}
+
+	for (const key of FORBIDDEN_MANIFEST_KEYS) {
+		if (Object.hasOwn(raw, key)) {
+			throw new GjcPluginLoadError("forbidden_surface", `Forbidden GJC plugin surface in ${manifestPath}: ${key}`);
+		}
+	}
+
+	if (raw.kind !== GJC_PLUGIN_KIND) {
+		throw new GjcPluginLoadError(
+			"invalid_kind",
+			`Invalid GJC plugin kind in ${manifestPath}: expected ${GJC_PLUGIN_KIND}`,
+		);
+	}
+	if (typeof raw.name !== "string" || raw.name.trim().length === 0) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: name must be a non-empty string`,
+		);
+	}
+	if (typeof raw.version !== "string" || raw.version.trim().length === 0) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: version must be a non-empty string`,
+		);
+	}
+
+	return {
+		name: raw.name,
+		version: raw.version,
+		kind: GJC_PLUGIN_KIND,
+		subskills: requireStringArray(raw.subskills, "subskills", manifestPath),
+		tools: requireStringArray(raw.tools, "tools", manifestPath),
+	};
+}
+
+export function parseSubskillFrontmatter(fm: Record<string, unknown>, filePath: string): SubskillFrontmatter {
+	return {
+		name: requireNonEmptyString(fm.name, "name", filePath),
+		binds_to: requireNonEmptyString(fm.binds_to, "binds_to", filePath),
+		phase: requireNonEmptyString(fm.phase, "phase", filePath),
+		activation_arg: requireNonEmptyString(fm.activation_arg, "activation_arg", filePath),
+		description: requireNonEmptyString(fm.description, "description", filePath),
+	};
+}

package/src/extensibility/gjc-plugins/state.ts

@@ -0,0 +1,29 @@
+import type { ActiveSubskillEntry } from "../../skill-state/active-state";
+import { readVisibleSkillActiveState } from "../../skill-state/active-state";
+import type { LoadedSubskillActivation } from "./types";
+
+export function toActiveSubskillEntry(activation: LoadedSubskillActivation): ActiveSubskillEntry {
+	return {
+		plugin: activation.plugin,
+		subskillName: activation.subskillName,
+		parent: activation.parent,
+		bindsTo: activation.bindsTo,
+		phase: activation.phase,
+		activationArg: activation.activationArg,
+		filePath: activation.filePath,
+		toolPaths: activation.toolPaths,
+	};
+}
+
+export async function readActiveSubskillsForParent(input: {
+	cwd: string;
+	sessionId?: string;
+	parent: string;
+	phase: string;
+}): Promise<ActiveSubskillEntry[]> {
+	const state = await readVisibleSkillActiveState(input.cwd, input.sessionId);
+	const parent = input.parent.trim();
+	const phase = input.phase.trim();
+	if (!state || !parent || !phase) return [];
+	return (state.active_subskills ?? []).filter(entry => entry.parent === parent && entry.phase === phase);
+}

package/src/extensibility/gjc-plugins/tools.ts

@@ -0,0 +1,47 @@
+import { logger } from "@gajae-code/utils";
+import { loadCustomTools } from "../custom-tools/loader";
+import type { CustomTool } from "../custom-tools/types";
+import { readActiveSubskillsForParent } from "./state";
+
+export async function loadActiveSubskillTools(input: {
+	cwd: string;
+	sessionId?: string;
+	parent: string;
+	phase: string;
+	reservedToolNames?: string[];
+}): Promise<CustomTool[]> {
+	const entries = await readActiveSubskillsForParent(input);
+	const toolPaths = [
+		...new Set(entries.flatMap(entry => entry.toolPaths ?? []).filter(path => path.trim().length > 0)),
+	];
+	if (toolPaths.length === 0) return [];
+
+	const reservedToolNames = new Set(input.reservedToolNames ?? []);
+	const result = await loadCustomTools(
+		toolPaths.map(path => ({ path })),
+		input.cwd,
+		input.reservedToolNames ?? [],
+	);
+
+	for (const error of result.errors) {
+		logger.warn("Skipping GJC plugin sub-skill tool", { path: error.path, error: error.error });
+	}
+
+	const tools: CustomTool[] = [];
+	const seenNames = new Set<string>();
+	for (const loadedTool of result.tools) {
+		const name = loadedTool.tool.name;
+		if (reservedToolNames.has(name)) {
+			logger.warn("Skipping GJC plugin sub-skill tool name because it conflicts with a reserved tool", { name });
+			continue;
+		}
+		if (seenNames.has(name)) {
+			logger.warn("Skipping duplicate GJC plugin sub-skill tool name", { name, path: loadedTool.path });
+			continue;
+		}
+		seenNames.add(name);
+		tools.push(loadedTool.tool);
+	}
+
+	return tools;
+}

package/src/extensibility/gjc-plugins/types.ts

@@ -0,0 +1,97 @@
+import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../../skill-state/active-state";
+
+export const GJC_PLUGIN_MANIFEST_FILENAME = "gajae-plugin.json";
+export const GJC_PLUGIN_KIND = "gajae-code-plugin";
+
+export const GJC_SUBSKILL_PARENT_SKILLS = CANONICAL_GJC_WORKFLOW_SKILLS;
+export type GjcSubskillParentSkill = CanonicalGjcWorkflowSkill;
+
+export const GJC_SUBSKILL_PARENT_AGENTS = ["executor", "architect", "planner", "critic"] as const;
+export type GjcSubskillParentAgent = (typeof GJC_SUBSKILL_PARENT_AGENTS)[number];
+
+export type GjcSubskillParent = GjcSubskillParentSkill | GjcSubskillParentAgent;
+
+export const GJC_AGENT_SUBSKILL_PHASES: Record<GjcSubskillParentAgent, string[]> = {
+	executor: ["prompt"],
+	architect: ["prompt"],
+	planner: ["prompt"],
+	critic: ["prompt"],
+};
+
+export interface GjcPluginManifest {
+	name: string;
+	version: string;
+	kind: "gajae-code-plugin";
+	subskills: string[];
+	tools: string[];
+}
+
+export interface SubskillFrontmatter {
+	name: string;
+	binds_to: string;
+	phase: string;
+	activation_arg: string;
+	description: string;
+}
+
+export interface LoadedSubskillBinding {
+	plugin: string;
+	subskillName: string;
+	parent: string;
+	bindsTo: string;
+	phase: string;
+	activationArg: string;
+	description: string;
+	filePath: string;
+	body: string;
+	toolPaths: string[];
+}
+
+export interface LoadedSubskillActivation {
+	activationArg: string;
+	plugin: string;
+	subskillName: string;
+	parent: string;
+	bindsTo: string;
+	phase: string;
+	filePath: string;
+	toolPaths: string[];
+}
+
+export interface PhaseScopedToolBinding {
+	plugin: string;
+	parent: string;
+	phase: string;
+	toolPath: string;
+}
+
+export interface LoadedGjcPlugin {
+	name: string;
+	version: string;
+	root: string;
+	manifestPath: string;
+	bindings: LoadedSubskillBinding[];
+	toolBindings: PhaseScopedToolBinding[];
+}
+
+export type GjcPluginLoadErrorCode =
+	| "forbidden_surface"
+	| "invalid_manifest"
+	| "invalid_frontmatter"
+	| "invalid_parent"
+	| "invalid_phase"
+	| "duplicate_arg"
+	| "duplicate_parent_phase"
+	| "missing_file"
+	| "invalid_kind";
+
+export class GjcPluginLoadError extends Error {
+	readonly code: GjcPluginLoadErrorCode;
+
+	constructor(code: GjcPluginLoadErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "GjcPluginLoadError";
+		this.code = code;
+	}
+}

package/src/extensibility/gjc-plugins/validation.ts

@@ -0,0 +1,76 @@
+import { isKnownWorkflowState } from "../../gjc-runtime/workflow-manifest";
+import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+import {
+	GJC_AGENT_SUBSKILL_PHASES,
+	GJC_SUBSKILL_PARENT_AGENTS,
+	GJC_SUBSKILL_PARENT_SKILLS,
+	GjcPluginLoadError,
+	type GjcSubskillParentAgent,
+	type LoadedSubskillBinding,
+	type SubskillFrontmatter,
+} from "./types";
+
+function isParentSkill(value: string): value is CanonicalGjcWorkflowSkill {
+	return (GJC_SUBSKILL_PARENT_SKILLS as readonly string[]).includes(value);
+}
+
+function isParentAgent(value: string): value is GjcSubskillParentAgent {
+	return (GJC_SUBSKILL_PARENT_AGENTS as readonly string[]).includes(value);
+}
+
+export function validateBinding(fm: SubskillFrontmatter): void {
+	const parent = fm.binds_to;
+	if (isParentSkill(parent)) {
+		if (!isKnownWorkflowState(parent, fm.phase)) {
+			throw new GjcPluginLoadError("invalid_phase", `Invalid GJC sub-skill phase for ${parent}: ${fm.phase}`);
+		}
+		return;
+	}
+
+	if (isParentAgent(parent)) {
+		if (!GJC_AGENT_SUBSKILL_PHASES[parent].includes(fm.phase)) {
+			throw new GjcPluginLoadError("invalid_phase", `Invalid GJC sub-skill phase for ${parent}: ${fm.phase}`);
+		}
+		return;
+	}
+
+	throw new GjcPluginLoadError("invalid_parent", `Invalid GJC sub-skill parent: ${parent}`);
+}
+
+export function buildParentArgMap(
+	bindings: readonly LoadedSubskillBinding[],
+): Map<string, Map<string, LoadedSubskillBinding>> {
+	const byParent = new Map<string, Map<string, LoadedSubskillBinding>>();
+	for (const binding of bindings) {
+		let byArg = byParent.get(binding.parent);
+		if (!byArg) {
+			byArg = new Map<string, LoadedSubskillBinding>();
+			byParent.set(binding.parent, byArg);
+		}
+		const existing = byArg.get(binding.activationArg);
+		if (existing) {
+			throw new GjcPluginLoadError(
+				"duplicate_arg",
+				`Duplicate GJC sub-skill activation_arg for ${binding.parent}: ${binding.activationArg} (${existing.filePath}, ${binding.filePath})`,
+			);
+		}
+		byArg.set(binding.activationArg, binding);
+	}
+	return byParent;
+}
+
+export function buildParentPhaseSet(bindings: readonly LoadedSubskillBinding[]): Set<string> {
+	const seen = new Map<string, LoadedSubskillBinding>();
+	for (const binding of bindings) {
+		const key = `${binding.parent}\u0000${binding.phase}`;
+		const existing = seen.get(key);
+		if (existing) {
+			throw new GjcPluginLoadError(
+				"duplicate_parent_phase",
+				`Duplicate GJC sub-skill parent/phase binding for ${binding.parent}/${binding.phase} (${existing.filePath}, ${binding.filePath})`,
+			);
+		}
+		seen.set(key, binding);
+	}
+	return new Set(seen.keys());
+}

package/src/extensibility/skills.ts

@@ -8,6 +8,8 @@ import { type Skill as CapabilitySkill, loadCapability } from "../discovery";
 import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
 import type { SkillPromptDetails } from "../session/messages";
 import { expandTilde } from "../tools/path-utils";
+import type { LoadedSubskillActivation } from "./gjc-plugins";
+import { buildSubskillInjection } from "./gjc-plugins/injection";
 export interface Skill {
 	name: string;
 	description: string;
@@ -280,6 +282,14 @@ export interface BuiltSkillPromptMessage {
 	details: SkillPromptDetails;
 }
 
+export interface BuildSkillPromptMessageContext {
+	subskillActivation?: LoadedSubskillActivation;
+	subskillActivationSet?: LoadedSubskillActivation[];
+	currentPhase?: string;
+	cwd?: string;
+	sessionId?: string;
+}
+
 export function getSkillSlashCommandName(skill: Pick<Skill, "name">): string {
 	return `skill:${skill.name}`;
 }
@@ -370,6 +380,7 @@ export function resolveSkillSlashCommands(
 export async function buildSkillPromptMessage(
 	skill: Pick<Skill, "name" | "filePath" | "content">,
 	args: string,
+	context?: BuildSkillPromptMessageContext,
 ): Promise<BuiltSkillPromptMessage> {
 	const content = typeof skill.content === "string" ? skill.content : await Bun.file(skill.filePath).text();
 	const body = content.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
@@ -378,14 +389,35 @@ export async function buildSkillPromptMessage(
 	if (trimmedArgs) {
 		metaLines.push(`User: ${trimmedArgs}`);
 	}
-	const message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
+	let message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
+	const details: SkillPromptDetails = {
+		name: skill.name,
+		path: skill.filePath,
+		args: trimmedArgs || undefined,
+		lineCount: body ? body.split("\n").length : 0,
+	};
+	if (context?.subskillActivationSet) {
+		details.subskillActivationSet = context.subskillActivationSet;
+	}
+	if (context) {
+		const injection = context.cwd
+			? await buildSubskillInjection({
+					cwd: context.cwd,
+					sessionId: context.sessionId,
+					skillName: skill.name,
+					activation: context.subskillActivation,
+					currentPhase: context.currentPhase,
+				})
+			: null;
+		if (injection) {
+			message += injection.block;
+			details.subskillActivation = injection.details ?? context.subskillActivation;
+		} else if (context.subskillActivation) {
+			details.subskillActivation = context.subskillActivation;
+		}
+	}
 	return {
 		message,
-		details: {
-			name: skill.name,
-			path: skill.filePath,
-			args: trimmedArgs || undefined,
-			lineCount: body ? body.split("\n").length : 0,
-		},
+		details,
 	};
 }

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

@@ -22,6 +22,7 @@ import {
 	canonicalWorkflowSkill,
 	describeWorkflowStateContract,
 	WORKFLOW_STATE_VERSION,
+	type WorkflowStateMutationOwner,
 	type WorkflowStateReceipt,
 } from "../skill-state/workflow-state-contract";
 import { renderCliWriteReceipt } from "./cli-write-receipt";
@@ -686,13 +687,14 @@ async function writeJsonAtomic(
 	cwd: string,
 	filePath: string,
 	value: unknown,
-	verb: "write" | "clear" | "handoff" = "write",
+	verb: "write" | "clear" | "handoff" | "reconcile" = "write",
 	options?: {
 		skill?: CanonicalGjcWorkflowSkill;
 		mutationId?: string;
 		force?: boolean;
 		fromPhase?: string;
 		toPhase?: string;
+		owner?: WorkflowStateMutationOwner;
 	},
 ): Promise<{ warning?: string; stamped: Record<string, unknown> }> {
 	const warning = options?.skill
@@ -709,7 +711,7 @@ async function writeJsonAtomic(
 		audit: {
 			category: "state",
 			verb,
-			owner: "gjc-state-cli",
+			owner: options?.owner ?? "gjc-state-cli",
 			skill: options?.skill,
 			mutationId: options?.mutationId,
 			fromPhase: options?.fromPhase,
@@ -957,6 +959,95 @@ async function syncWorkflowSkillState(options: {
 		// HUD sync is best-effort and must not change command semantics.
 	}
 }
+
+/**
+ * Reconcile a workflow skill's mode-state + active-state/HUD from a caller-derived
+ * payload. Unlike `gjc state write`, this is a derived repair: callers reconcile from
+ * an authoritative source (e.g. the ultragoal plan/ledger), where intermediate
+ * aggregate phases like ultragoal `active -> pending` are legitimate, so it bypasses
+ * ONLY verb transition-edge validation while preserving schema validation,
+ * unknown-phase rejection, version/checksum stamping, and audit/out-of-band tamper
+ * detection. Receipts carry `owner: "gjc-runtime"` and `verb: "reconcile"` so the
+ * provenance is distinguishable from a user-initiated write.
+ */
+export async function reconcileWorkflowSkillState(options: {
+	cwd: string;
+	mode: CanonicalGjcWorkflowSkill;
+	sessionId: string | undefined;
+	threadId?: string;
+	turnId?: string;
+	active: boolean;
+	phase: string;
+	payload: Record<string, unknown>;
+}): Promise<{ stateFile: string }> {
+	const { cwd, mode, sessionId, threadId, turnId, active, payload } = options;
+	const filePath = modeStateFile(cwd, mode, sessionId);
+	const existingRead = await readExistingStateForMutation(filePath);
+	const existingPayload = existingRead.kind === "valid" ? existingRead.value : {};
+	const nowIsoStr = nowIso();
+	const mutationId = `${mode}:reconcile:${nowIsoStr}`;
+
+	const trimmedPhase = options.phase.trim();
+	const manifestStates = new Set(getSkillManifest(mode).states.map(state => state.id));
+	if (!manifestStates.has(trimmedPhase)) {
+		throw new StateCommandError(2, `unknown ${mode} phase "${trimmedPhase}" for reconciliation`);
+	}
+
+	const fromPhase =
+		typeof existingPayload.current_phase === "string" ? existingPayload.current_phase.trim() : undefined;
+	const receipt = buildWorkflowStateReceipt({
+		cwd,
+		skill: mode,
+		owner: "gjc-runtime",
+		command: `gjc ${mode} (reconcile)`,
+		sessionId,
+		nowIso: nowIsoStr,
+		mutationId,
+	});
+	receipt.verb = "reconcile";
+	receipt.forced = true;
+	receipt.from_phase = fromPhase;
+	receipt.to_phase = trimmedPhase;
+
+	const merged = mergeWithNullDelete(existingPayload, payload);
+	merged.skill = mode;
+	merged.current_phase = trimmedPhase;
+	merged.active = active;
+	merged.version = WORKFLOW_STATE_VERSION;
+	merged.updated_at = nowIsoStr;
+	merged.receipt = receipt;
+	if (sessionId && typeof merged.session_id !== "string") merged.session_id = sessionId;
+
+	const validation = validateWorkflowStateEnvelope(mode, merged);
+	if (!validation.valid) throw new StateCommandError(2, validation.error ?? `invalid ${mode} state envelope`);
+
+	await writeJsonAtomic(cwd, filePath, merged, "reconcile", {
+		skill: mode,
+		mutationId,
+		force: true,
+		fromPhase,
+		toPhase: trimmedPhase,
+		owner: "gjc-runtime",
+	});
+
+	// Reconciliation drives the active-state/HUD update directly (not via the
+	// best-effort syncWorkflowSkillState wrapper) so a failed HUD/active-state write
+	// is surfaced to the caller and recorded as a reconcile failure, rather than
+	// silently leaving a stale chip behind a freshly reconciled mode-state.
+	await syncSkillActiveState({
+		cwd,
+		skill: mode,
+		active,
+		phase: trimmedPhase,
+		sessionId,
+		threadId,
+		turnId,
+		source: "gjc-runtime-reconcile",
+		hud: buildHudForMode(mode, merged),
+		receipt,
+	});
+	return { stateFile: filePath };
+}
 export async function readWorkflowStateJson(
 	cwd: string,
 	skill: CanonicalGjcWorkflowSkill,

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

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
+import type { ActiveSubskillEntry, SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
 import {
 	type AuditEntry,
 	buildWorkflowStateReceipt,
@@ -275,6 +275,21 @@ function activeEntryPath(cwd: string, sessionScope: string | ActiveSessionScope
 	return path.join(activeStateDir(cwd, sessionScope), `${encodePathSegment(normalizedSkill)}.json`);
 }
 
+function activeSubskillKey(entry: ActiveSubskillEntry): string {
+	return `${entry.parent}::${entry.phase}::${entry.activationArg}`;
+}
+
+function flattenActiveSubskills(entries: SkillActiveEntry[]): ActiveSubskillEntry[] {
+	const deduped = new Map<string, ActiveSubskillEntry>();
+	for (const entry of entries) {
+		if (entry.active === false || !Array.isArray(entry.active_subskills)) continue;
+		for (const subskill of entry.active_subskills) {
+			deduped.set(activeSubskillKey(subskill), subskill);
+		}
+	}
+	return [...deduped.values()];
+}
+
 function buildActiveSnapshot(entries: SkillActiveEntry[]): SkillActiveState {
 	const visible = entries.filter(entry => entry.active !== false);
 	const primary = visible[0];
@@ -288,6 +303,7 @@ function buildActiveSnapshot(entries: SkillActiveEntry[]): SkillActiveState {
 		thread_id: primary?.thread_id,
 		turn_id: primary?.turn_id,
 		active_skills: entries,
+		active_subskills: flattenActiveSubskills(visible),
 	};
 }
 

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

@@ -5,6 +5,7 @@ import { buildUltragoalHudSummary as buildWorkflowUltragoalHudSummary } from "..
 import { renderCliWriteReceipt } from "./cli-write-receipt";
 import { DEFAULT_ULTRAGOAL_OBJECTIVE } from "./goal-mode-request";
 import { renderUltragoalStatusMarkdown } from "./state-renderer";
+import { reconcileWorkflowSkillState } from "./state-runtime";
 import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
 
 export type UltragoalGjcGoalMode = "aggregate" | "per-story";
@@ -474,7 +475,6 @@ export function buildUltragoalHudSummary(
 		updatedAt: new Date().toISOString(),
 	});
 }
-
 function clampTitle(title: string): string {
 	return title.length > 80 ? `${title.slice(0, 77)}...` : title;
 }
@@ -1307,7 +1307,7 @@ function renderCompleteHandoff(
 	].join("\n");
 }
 
-export async function runNativeUltragoalCommand(args: string[], cwd = process.cwd()): Promise<UltragoalCommandResult> {
+async function dispatchUltragoalCommand(args: string[], cwd: string): Promise<UltragoalCommandResult> {
 	try {
 		const command = commandName(args);
 		const json = hasFlag(args, "--json");
@@ -1414,3 +1414,63 @@ export async function runNativeUltragoalCommand(args: string[], cwd = process.cw
 		return { status: 1, stderr: `${error instanceof Error ? error.message : String(error)}\n` };
 	}
 }
+
+const RECONCILE_COMMANDS = new Set([
+	"status",
+	"create",
+	"create-goals",
+	"complete-goals",
+	"checkpoint",
+	"steer",
+	"record-review-blockers",
+]);
+
+/**
+ * Derive a workflow-state payload from the ultragoal plan/ledger and reconcile the
+ * ultragoal mode-state + active-state/HUD so `gjc state ultragoal read`, the
+ * skill-tool chain guard, and the HUD chip mirror the plan/ledger. Session scope
+ * follows `gjc state` (`GJC_SESSION_ID`). This is a derived repair: it never changes
+ * the triggering command's status/stdout, but a failure is surfaced (stderr + a
+ * `reconcile_failed` ledger audit event) rather than silently swallowed. `status` is
+ * therefore a read PLUS a derived repair; it never mutates goals.json/ledger.jsonl
+ * beyond that reconcile-failure audit event.
+ */
+async function reconcileUltragoalState(cwd: string): Promise<void> {
+	const sessionId = process.env.GJC_SESSION_ID?.trim() || undefined;
+	try {
+		const summary = await getUltragoalStatus(cwd);
+		const status = summary.status;
+		const active = summary.exists && status !== "complete";
+		const payload: Record<string, unknown> = {
+			skill: "ultragoal",
+			status,
+			current_phase: status,
+			active,
+			goals: summary.goals.map(goal => ({ id: goal.id, title: goal.title, status: goal.status })),
+			counts: summary.counts,
+			active_goal_id: summary.currentGoal?.id ?? null,
+			ledger_path: summary.paths.ledgerPath,
+			brief_path: summary.paths.briefPath,
+			goals_path: summary.paths.goalsPath,
+		};
+		if (summary.gjcObjective) payload.gjc_objective = summary.gjcObjective;
+		await reconcileWorkflowSkillState({ cwd, mode: "ultragoal", sessionId, active, phase: status, payload });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		process.stderr.write(`ultragoal state reconciliation failed: ${message}\n`);
+		try {
+			await appendLedger(cwd, { type: "reconcile_failed", error: message });
+		} catch {
+			// Best-effort audit; never let a secondary failure change command semantics.
+		}
+	}
+}
+
+export async function runNativeUltragoalCommand(args: string[], cwd = process.cwd()): Promise<UltragoalCommandResult> {
+	const command = commandName(args);
+	const result = await dispatchUltragoalCommand(args, cwd);
+	if (result.status === 0 && RECONCILE_COMMANDS.has(command)) {
+		await reconcileUltragoalState(cwd);
+	}
+	return result;
+}

package/src/gjc-runtime/workflow-manifest.generated.json

@@ -1171,6 +1171,10 @@
     ],
     "skill": "ultragoal",
     "states": [
+      {
+        "id": "missing",
+        "terminal": true
+      },
       {
         "id": "goal-planning",
         "initial": true
@@ -1198,6 +1202,7 @@
       }
     ],
     "terminalStates": [
+      "missing",
       "failed",
       "complete",
       "handoff"

package/src/gjc-runtime/workflow-manifest.ts

@@ -212,8 +212,8 @@ export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest>
 	}),
 	ultragoal: manifest({
 		skill: "ultragoal",
-		states: ["goal-planning", "pending", "active", "blocked", "failed", "complete", "handoff"],
-		terminalStates: ["failed", "complete", "handoff"],
+		states: ["missing", "goal-planning", "pending", "active", "blocked", "failed", "complete", "handoff"],
+		terminalStates: ["missing", "failed", "complete", "handoff"],
 		transitions: [
 			{ from: "goal-planning", to: "pending", verb: "create-goals" },
 			{ from: "pending", to: "active", verb: "complete-goals" },