@gajae-code/coding-agent 0.2.4 → 0.3.0

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

@@ -2,10 +2,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 { Settings } from "../config/settings";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildDeepInterviewHudSummary } from "../skill-state/workflow-hud";
 import { runNativeRalplanCommand } from "./ralplan-runtime";
 import { runNativeStateCommand } from "./state-runtime";
+import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
 
 /**
  * Native implementation of `gjc deep-interview`.
@@ -104,13 +106,6 @@ async function readJsonObject(filePath: string): Promise<Record<string, unknown>
 	return {};
 }
 
-async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	const tmp = `${filePath}.tmp-${randomBytes(6).toString("hex")}`;
-	await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`);
-	await fs.rename(tmp, filePath);
-}
-
 async function resolveSpecContent(rawSpec: string, cwd: string): Promise<string> {
 	const candidate = path.isAbsolute(rawSpec) ? rawSpec : path.resolve(cwd, rawSpec);
 	try {
@@ -202,9 +197,29 @@ async function readSettingsAmbiguityThreshold(
 	return { threshold: candidate, source: settingsPath };
 }
 
+async function readModernSettingsAmbiguityThreshold(
+	cwd: string,
+): Promise<{ threshold: number; source: string } | undefined> {
+	const settings = await Settings.init({ cwd });
+	const modernConfigPath = path.join(settings.getAgentDir(), "config.yml");
+	let parsed: unknown;
+	try {
+		parsed = (await import("bun")).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" || !Number.isFinite(candidate) || candidate <= 0 || candidate > 1)
+		return undefined;
+	return { threshold: candidate, source: modernConfigPath };
+}
+
 async function resolveConfiguredAmbiguityThreshold(
 	cwd: string,
 ): Promise<{ threshold: number; source: string } | undefined> {
+	const modernValue = await readModernSettingsAmbiguityThreshold(cwd);
+	if (modernValue) return modernValue;
 	const projectSettings = path.join(cwd, ".gjc", "settings.json");
 	const projectValue = await readSettingsAmbiguityThreshold(projectSettings);
 	if (projectValue) return projectValue;
@@ -373,17 +388,19 @@ export async function persistDeepInterviewSpec(
 	cwd: string,
 	resolved: ResolvedDeepInterviewSpecWriteArgs,
 ): Promise<PersistedDeepInterviewSpec> {
-	const specsDir = path.join(cwd, ".gjc", "specs");
-	await fs.mkdir(specsDir, { recursive: true });
-	const specPath = path.join(specsDir, `deep-interview-${resolved.slug}.md`);
+	const specPath = path.join(cwd, ".gjc", "specs", `deep-interview-${resolved.slug}.md`);
 	const content = resolved.spec.endsWith("\n") ? resolved.spec : `${resolved.spec}\n`;
-	await fs.writeFile(specPath, content);
+	await writeArtifact(specPath, content, {
+		cwd,
+		audit: { category: "artifact", verb: "write", owner: "gjc-runtime", skill: "deep-interview" },
+	});
 
 	const sha256 = createHash("sha256").update(content).digest("hex");
 	const createdAt = new Date().toISOString();
-	await fs.appendFile(
-		path.join(specsDir, "deep-interview-index.jsonl"),
-		`${JSON.stringify({ slug: resolved.slug, stage: resolved.stage, path: specPath, created_at: createdAt, sha256 })}\n`,
+	await appendJsonl(
+		path.join(cwd, ".gjc", "specs", "deep-interview-index.jsonl"),
+		{ slug: resolved.slug, stage: resolved.stage, path: specPath, created_at: createdAt, sha256 },
+		{ cwd, audit: { category: "ledger", verb: "append", owner: "gjc-runtime", skill: "deep-interview" } },
 	);
 
 	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
@@ -402,7 +419,10 @@ export async function persistDeepInterviewSpec(
 		updated_at: createdAt,
 	};
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await writeJsonAtomic(statePath, payload);
+	await writeJsonAtomic(statePath, payload, {
+		cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "deep-interview" },
+	});
 	await syncDeepInterviewHud({
 		cwd,
 		sessionId: resolved.sessionId,
@@ -421,11 +441,7 @@ export async function persistDeepInterviewSpec(
 }
 
 async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepInterviewArgs): Promise<string> {
-	const stateDir = resolved.sessionId
-		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(resolved.sessionId))
-		: path.join(cwd, ".gjc", "state");
-	await fs.mkdir(stateDir, { recursive: true });
-	const statePath = path.join(stateDir, "deep-interview-state.json");
+	const statePath = deepInterviewStatePath(cwd, resolved.sessionId);
 	const now = new Date().toISOString();
 	const payload: Record<string, unknown> = {
 		active: true,
@@ -448,7 +464,10 @@ async function seedDeepInterviewState(cwd: string, resolved: ResolvedDeepIntervi
 		(payload.state as Record<string, unknown>).language = resolved.language;
 	}
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await fs.writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+	await writeJsonAtomic(statePath, payload, {
+		cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "deep-interview" },
+	});
 	return statePath;
 }
 

package/src/gjc-runtime/goal-mode-request.ts

@@ -8,6 +8,7 @@ import {
 	type ModeChangeEntry,
 	type SessionEntry,
 } from "../session/session-manager";
+import { removeFileAudited, writeJsonAtomic } from "./state-writer";
 
 export const GJC_SESSION_FILE_ENV = "GJC_SESSION_FILE";
 export const GJC_SESSION_ID_ENV = "GJC_SESSION_ID";
@@ -88,8 +89,10 @@ export async function writePendingGoalModeRequest(input: {
 		goalsPath: input.goalsPath,
 	};
 	const filePath = requestPath(input.cwd);
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await Bun.write(filePath, `${JSON.stringify(request, null, 2)}\n`);
+	await writeJsonAtomic(filePath, request, {
+		cwd: input.cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-runtime" },
+	});
 	return request;
 }
 
@@ -153,6 +156,8 @@ export async function writeCurrentSessionGoalModeState(input: {
 		mode: "goal",
 		data: { goal: state.goal },
 	};
+	// The session transcript file lives outside `.gjc/` (GJC_SESSION_FILE), so it is not a
+	// sanctioned-writer target; append directly.
 	await fs.appendFile(sessionFile, `${JSON.stringify(entry)}\n`);
 	return { status: "updated", goal: state.goal, sessionFile };
 }
@@ -176,7 +181,10 @@ export async function consumePendingGoalModeRequest(cwd: string): Promise<Pendin
 	) {
 		return null;
 	}
-	await fs.unlink(filePath).catch(error => {
+	await removeFileAudited(filePath, {
+		cwd,
+		audit: { category: "prune", verb: "remove", owner: "gjc-runtime" },
+	}).catch(error => {
 		if (!isEnoent(error)) throw error;
 	});
 	return { ...candidate, objective: candidate.objective.trim() } as PendingGoalModeRequest;

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

@@ -3,6 +3,8 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildRalplanHudSummary } from "../skill-state/workflow-hud";
+import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
+import { appendJsonl, writeArtifact, writeJsonAtomic } from "./state-writer";
 
 /**
  * Native implementation of `gjc ralplan`.
@@ -110,6 +112,7 @@ function defaultRunId(now: Date = new Date()): string {
 }
 
 async function resolveArtifactContent(rawArtifact: string, cwd: string): Promise<string> {
+	if (isRestrictedRoleAgentBash()) return rawArtifact;
 	const candidate = path.isAbsolute(rawArtifact) ? rawArtifact : path.resolve(cwd, rawArtifact);
 	try {
 		const stat = await fs.stat(candidate);
@@ -171,8 +174,10 @@ async function persistActiveRunId(cwd: string, sessionId: string | undefined, ru
 	if (typeof existing.skill !== "string") existing.skill = "ralplan";
 	if (typeof existing.active !== "boolean") existing.active = true;
 	existing.updated_at = new Date().toISOString();
-	await fs.mkdir(path.dirname(statePath), { recursive: true });
-	await fs.writeFile(statePath, `${JSON.stringify(existing, null, 2)}\n`);
+	await writeJsonAtomic(statePath, existing, {
+		cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+	});
 }
 
 async function resolveArtifactArgs(args: readonly string[], cwd: string): Promise<ResolvedArtifactArgs> {
@@ -218,27 +223,36 @@ interface PersistedArtifact {
 
 async function persistArtifact(resolved: ResolvedArtifactArgs, cwd: string): Promise<PersistedArtifact> {
 	const runDir = path.join(cwd, ".gjc", "plans", "ralplan", resolved.runId);
-	await fs.mkdir(runDir, { recursive: true });
+
 	const fileName = `stage-${pad2(resolved.stageN)}-${resolved.stage}.md`;
 	const filePath = path.join(runDir, fileName);
 	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\n`;
-	await fs.writeFile(filePath, content);
+	await writeArtifact(filePath, content, {
+		cwd,
+		audit: { category: "artifact", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+	});
 
 	const sha256 = createHash("sha256").update(content).digest("hex");
 	const createdAt = new Date().toISOString();
-	const indexLine = `${JSON.stringify({
+	const indexEntry = {
 		stage: resolved.stage,
 		stage_n: resolved.stageN,
 		path: filePath,
 		created_at: createdAt,
 		sha256,
-	})}\n`;
-	await fs.appendFile(path.join(runDir, "index.jsonl"), indexLine);
+	};
+	await appendJsonl(path.join(runDir, "index.jsonl"), indexEntry, {
+		cwd,
+		audit: { category: "ledger", verb: "append", owner: "gjc-runtime", skill: "ralplan" },
+	});
 
 	let pendingApprovalPath: string | undefined;
 	if (resolved.stage === "final") {
 		pendingApprovalPath = path.join(runDir, "pending-approval.md");
-		await fs.writeFile(pendingApprovalPath, content);
+		await writeArtifact(pendingApprovalPath, content, {
+			cwd,
+			audit: { category: "artifact", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+		});
 	}
 
 	return {
@@ -380,7 +394,7 @@ async function seedRalplanState(
 	const stateDir = resolved.sessionId
 		? path.join(cwd, ".gjc", "state", "sessions", encodeSessionSegment(resolved.sessionId))
 		: path.join(cwd, ".gjc", "state");
-	await fs.mkdir(stateDir, { recursive: true });
+
 	const statePath = path.join(stateDir, "ralplan-state.json");
 	// Reuse an existing run id when present so a re-invocation of `gjc ralplan "task"` doesn't
 	// orphan in-progress artifacts under a fresh run id.
@@ -401,7 +415,10 @@ async function seedRalplanState(
 	if (resolved.architectKind) payload.architect_kind = resolved.architectKind;
 	if (resolved.criticKind) payload.critic_kind = resolved.criticKind;
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await fs.writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+	await writeJsonAtomic(statePath, payload, {
+		cwd,
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "ralplan" },
+	});
 	return { statePath, runId };
 }
 

package/src/gjc-runtime/restricted-role-agent-bash.ts

@@ -0,0 +1,5 @@
+export const GJC_RESTRICTED_ROLE_AGENT_BASH_ENV = "GJC_RESTRICTED_ROLE_AGENT_BASH";
+
+export function isRestrictedRoleAgentBash(): boolean {
+	return process.env[GJC_RESTRICTED_ROLE_AGENT_BASH_ENV] === "1";
+}

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

@@ -0,0 +1,86 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/active-state";
+import { getSkillManifest } from "./workflow-manifest";
+
+export type StateGraphSkill = CanonicalGjcWorkflowSkill | "all";
+export type StateGraphFormat = "ascii" | "mermaid" | "dot";
+
+function assertGraphFormat(format: string): asserts format is StateGraphFormat {
+	if (format !== "ascii" && format !== "mermaid" && format !== "dot") {
+		throw new Error(`Invalid graph format: ${format}. Expected one of: ascii, mermaid, dot.`);
+	}
+}
+
+function skillsFor(skill: StateGraphSkill): CanonicalGjcWorkflowSkill[] {
+	return skill === "all" ? [...CANONICAL_GJC_WORKFLOW_SKILLS] : [skill];
+}
+
+function renderAscii(skill: StateGraphSkill): string {
+	const chunks = skillsFor(skill).map(item => {
+		const manifest = getSkillManifest(item);
+		const states = manifest.states
+			.map(state => {
+				const markers = [state.initial ? "initial" : undefined, state.terminal ? "terminal" : undefined]
+					.filter(Boolean)
+					.join(", ");
+				return `  - ${state.id}${markers ? ` (${markers})` : ""}`;
+			})
+			.join("\n");
+		const transitions = manifest.transitions
+			.map(transition => `  - ${transition.from} -> ${transition.to} [${transition.verb}]`)
+			.join("\n");
+		return `${manifest.skill} (${manifest.graphLabel})\nstates:\n${states}\ntransitions:\n${transitions}`;
+	});
+	return `${chunks.join("\n\n")}\n`;
+}
+
+function renderMermaid(skill: StateGraphSkill): string {
+	const lines = ["stateDiagram-v2"];
+	for (const item of skillsFor(skill)) {
+		const manifest = getSkillManifest(item);
+		lines.push(`  state "${manifest.graphLabel}" as ${item} {`);
+		lines.push(`    [*] --> ${manifest.initialState}`);
+		for (const transition of manifest.transitions) {
+			lines.push(`    ${transition.from} --> ${transition.to}: ${transition.verb}`);
+		}
+		for (const terminal of manifest.terminalStates) {
+			lines.push(`    ${terminal} --> [*]`);
+		}
+		lines.push("  }");
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function dotId(skill: CanonicalGjcWorkflowSkill, state: string): string {
+	return `"${skill}:${state}"`;
+}
+
+function renderDot(skill: StateGraphSkill): string {
+	const lines = ["digraph gjc_state {", "  rankdir=LR;"];
+	for (const item of skillsFor(skill)) {
+		const manifest = getSkillManifest(item);
+		lines.push(`  subgraph "cluster_${item}" {`);
+		lines.push(`    label="${manifest.graphLabel}";`);
+		for (const state of manifest.states) {
+			const shape = state.terminal ? "doublecircle" : "circle";
+			lines.push(`    ${dotId(item, state.id)} [label="${state.id}", shape=${shape}];`);
+		}
+		lines.push(`    "${item}:__start" [label="", shape=point];`);
+		lines.push(`    "${item}:__start" -> ${dotId(item, manifest.initialState)};`);
+		for (const transition of manifest.transitions) {
+			lines.push(
+				`    ${dotId(item, transition.from)} -> ${dotId(item, transition.to)} [label="${transition.verb}"];`,
+			);
+		}
+		lines.push("  }");
+	}
+	lines.push("}");
+	return `${lines.join("\n")}\n`;
+}
+
+export function renderStateGraph(skill: StateGraphSkill, format: string = "ascii"): string {
+	assertGraphFormat(format);
+	if (format === "mermaid") return renderMermaid(skill);
+	if (format === "dot") return renderDot(skill);
+	return renderAscii(skill);
+}

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

@@ -0,0 +1,132 @@
+import * as fs from "node:fs/promises";
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { initialPhaseForSkill } from "../skill-state/initial-phase";
+import { canonicalWorkflowSkill, WORKFLOW_STATE_RECEIPT_VERSION } from "../skill-state/workflow-state-contract";
+import { writeWorkflowEnvelopeAtomic } from "./state-writer";
+import { getSkillManifest } from "./workflow-manifest";
+
+export interface NormalizeLegacyStateResult {
+	state: Record<string, unknown>;
+	changed: boolean;
+}
+
+export interface MigrateAndPersistLegacyStateArgs {
+	cwd: string;
+	skill: string;
+	statePath: string;
+	sessionId?: string;
+}
+
+export interface MigrateAndPersistLegacyStateResult {
+	migrated: boolean;
+	path: string;
+}
+
+const RECEIPT_STRING_FIELDS = [
+	"command",
+	"state_path",
+	"storage_path",
+	"mutated_at",
+	"fresh_until",
+	"mutation_id",
+] as const;
+
+function cloneRecord(record: Record<string, unknown>): Record<string, unknown> {
+	return { ...record };
+}
+
+function canonicalSkillOrThrow(skill: string): CanonicalGjcWorkflowSkill {
+	const canonical = canonicalWorkflowSkill(skill);
+	if (!canonical) throw new Error(`Unsupported GJC workflow skill: ${skill}`);
+	return canonical;
+}
+
+function safeString(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function legacyPhaseForSkill(skill: CanonicalGjcWorkflowSkill, phase: string): string {
+	if (phase === "planning") return initialPhaseForSkill(skill);
+	return phase;
+}
+
+function normalizePhase(skill: CanonicalGjcWorkflowSkill, value: unknown): string {
+	const manifest = getSkillManifest(skill);
+	const manifestStates = new Set(manifest.states.map(state => state.id));
+	const phase = legacyPhaseForSkill(skill, safeString(value).trim());
+	return manifestStates.has(phase) ? phase : manifest.initialState;
+}
+
+function receiptWithRequiredFields(raw: unknown, skill: CanonicalGjcWorkflowSkill): Record<string, unknown> {
+	const receipt =
+		raw && typeof raw === "object" && !Array.isArray(raw) ? cloneRecord(raw as Record<string, unknown>) : {};
+	receipt.version = WORKFLOW_STATE_RECEIPT_VERSION;
+	receipt.skill = skill;
+	if (receipt.owner !== "gjc-state-cli" && receipt.owner !== "gjc-runtime" && receipt.owner !== "gjc-hook") {
+		receipt.owner = "gjc-state-cli";
+	}
+	if (receipt.status !== "fresh" && receipt.status !== "stale") receipt.status = "stale";
+	for (const field of RECEIPT_STRING_FIELDS) {
+		if (typeof receipt[field] !== "string") receipt[field] = "";
+	}
+	return receipt;
+}
+
+function recordsEqual(left: Record<string, unknown>, right: Record<string, unknown>): boolean {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+
+/**
+ * Pure legacy state normalizer for background/internal readers.
+ *
+ * Readers that need compatibility with old on-disk workflow state shapes must call
+ * this in-memory helper and must never call `migrateAndPersistLegacyState`. The
+ * persist variant is reserved for explicit state migration commands because it is
+ * the only path allowed to write normalized upgrades back to `.gjc/state/**`.
+ */
+export function normalizeLegacyState(raw: Record<string, unknown>, skill: string): NormalizeLegacyStateResult {
+	const canonicalSkill = canonicalSkillOrThrow(skill);
+	const state = cloneRecord(raw);
+	state.skill = canonicalSkill;
+	if (typeof state.version !== "number") state.version = 1;
+	if (typeof state.active !== "boolean") state.active = true;
+
+	const sourcePhase = typeof state.current_phase === "string" ? state.current_phase : state.phase;
+	const normalizedPhase = normalizePhase(canonicalSkill, sourcePhase);
+	state.current_phase = normalizedPhase;
+	if ("phase" in state && typeof state.phase === "string") state.phase = normalizedPhase;
+	state.receipt = receiptWithRequiredFields(state.receipt, canonicalSkill);
+
+	return { state, changed: !recordsEqual(raw, state) };
+}
+
+export async function migrateAndPersistLegacyState(
+	args: MigrateAndPersistLegacyStateArgs,
+): Promise<MigrateAndPersistLegacyStateResult> {
+	const canonicalSkill = canonicalSkillOrThrow(args.skill);
+	const raw = JSON.parse(await fs.readFile(args.statePath, "utf-8")) as unknown;
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error(`Workflow state file must contain a JSON object: ${args.statePath}`);
+	}
+	const { state, changed } = normalizeLegacyState(raw as Record<string, unknown>, canonicalSkill);
+	if (!changed) return { migrated: false, path: args.statePath };
+
+	const persistedPath = await writeWorkflowEnvelopeAtomic(args.statePath, state, {
+		cwd: args.cwd,
+		receipt: {
+			cwd: args.cwd,
+			skill: canonicalSkill,
+			owner: "gjc-state-cli",
+			command: `gjc state ${canonicalSkill} migrate`,
+			sessionId: args.sessionId,
+		},
+		audit: {
+			cwd: args.cwd,
+			skill: canonicalSkill,
+			verb: "migrate",
+			owner: "gjc-state-cli",
+			category: "state",
+		},
+	});
+	return { migrated: true, path: persistedPath };
+}