@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -50,12 +50,38 @@ Use `goal({"op":"get"})` snapshots inside Ultragoal for ledger reconciliation. T
 
 ## Create goals
 
-1. Run one of:
+1. Decide on the brief. To produce **multiple** stories, separate them with a reserved `@goal:` delimiter line; the title follows on the same line and the objective is everything beneath it until the next delimiter:
+
+   ```text
+   Shared brief constraints / context go here (optional preamble).
+
+   @goal: Parse the intake CSVs
+   Ingest reviewer CSVs from the watch dir, validate headers, and reject
+   malformed rows with a per-row reason. Objectives can span multiple lines
+   and contain `code`, "quotes", or commands — no escaping needed.
+
+   @goal: Normalize records
+   Map raw rows onto the canonical schema and dedupe by record id.
+
+   @goal: Export the audit report
+   Emit an audit-ready report covering every accepted and rejected row.
+   ```
+
+   Delimiter contract:
+   - A `@goal` line is a story boundary **only** when it starts at column 0 (no leading whitespace) and the character right after `@goal` is `:`, whitespace (space or tab), or end-of-line. So `@goal: Title`, `@goal Title`, and a bare `@goal` line all open a story.
+   - `@goalish`, `@goals:`, `@goal-foo`, `@goal.foo`, `@goal/foo`, and any indented or mid-line `@goal` are ordinary objective text, not delimiters. To keep a literal `@goal` line inside an objective, indent it.
+   - A title-only block (no body) uses the title as its objective. An empty title borrows the first body line as the title. A block with **neither** title nor body is rejected — `create-goals` errors instead of writing a placeholder goal.
+   - **Preamble** (any text before the first `@goal` delimiter) is global context/constraints only; it is retained in the brief but is **not** turned into a goal. Every executable story needs its own `@goal` block.
+   - With **no** `@goal` delimiter anywhere, the whole brief becomes a single goal `G001` (unchanged legacy behavior).
+
+   Stories become `G001`, `G002`, … in order.
+
+2. Run one of:
    - `gjc ultragoal create-goals --brief "<brief>"`
    - `gjc ultragoal create-goals --brief-file <path>`
    - `cat <brief> | gjc ultragoal create-goals --from-stdin`
    - `gjc ultragoal create-goals --gjc-goal-mode per-story --brief "<brief>"` only when one GJC goal context per story is explicitly preferred
-2. Inspect `.gjc/ultragoal/goals.json` and refine if needed.
+3. Inspect `.gjc/ultragoal/goals.json` and refine if needed.
 
 ## Complete goals
 
@@ -137,26 +163,29 @@ Workers do not own ultragoal goal state, do not create worker ultragoal ledgers,
 
 ## Mandatory completion cleanup and review gate
 
-An ultragoal story cannot be checkpointed `complete` until the active agent has run the quality gate:
+An ultragoal story cannot be checkpointed `complete` until the active agent has run the quality gate. The gate is plan-first, contract-driven, and surface-based:
 
-1. Run targeted verification for the story.
+1. Run targeted implementation verification for the story.
 2. Run a cleanup/refactor review pass on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
 3. Rerun verification after the cleaner pass.
-4. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, or non-empty blockers are non-clean.
-5. If review is non-clean, do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
-
-1. Run targeted implementation verification for the story.
-2. Delegate an `architect` review covering all three lanes:
+4. Delegate an `architect` review covering all three lanes:
    - architecture-side: system boundaries, layering, data/control flow, operational risks.
    - product-side: user-visible behavior, acceptance criteria, edge cases, regressions.
    - code-side: maintainability, tests, integration points, and unsafe shortcuts.
-3. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path.
-4. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
+5. Delegate an `executor` QA/red-team lane to build and run the e2e/read-teaming QA suite appropriate for the story. This lane must try to break the change, not just confirm the happy path. It must start from the approved plan/spec/acceptance criteria, then user-facing contracts, and only then implementation code as supporting evidence. Plan/code mismatches are blockers, not items to paper over with implementation intent.
+6. The executor QA/red-team lane must prove evidence by the real surface under test:
+   - GUI/web surfaces require browser automation plus a screenshot or image verdict.
+   - CLI surfaces require logs or terminal transcripts from real invocation.
+   - API/package surfaces require external consumer or black-box tests through the public interface.
+   - Algorithm/math surfaces require boundary, property, adversarial, and failure-mode cases.
+7. The executor QA/red-team lane must report a matrix using `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`. Not-applicable rows are allowed only in `contractCoverage` and `surfaceEvidence`; each `status: "not_applicable"` row requires `contractRef` plus `reason`. `adversarialCases` rows cannot be not-applicable.
+8. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, every required matrix row is present, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, missing or shallow matrix rows, plan/code mismatches, or non-empty blockers are non-clean.
+9. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:
    ```sh
    gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve verification blockers" --objective "<blocker-resolution objective>" --evidence "<architect/executor findings>" --gjc-goal-json <active-goal-get-json-or-path>
    ```
-5. Complete or steer through the blocker story, then rerun the full blocking verification loop. Repeat until all verifier lanes are clean.
-6. Only after the loop is clean, checkpoint the story as complete with a structured quality gate and a fresh active `goal({"op":"get"})` snapshot. The checkpoint creates a receipt; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before `goal({"op":"complete"})` is allowed.
+10. Complete or steer through the blocker story, then rerun the full blocking verification loop. Repeat until all verifier lanes are clean.
+11. Only after the loop is clean, checkpoint the story as complete with a structured quality gate and a fresh active `goal({"op":"get"})` snapshot. The checkpoint creates a receipt; `goals.json.status` alone is not proof. In aggregate mode, the final aggregate receipt must exist before `goal({"op":"complete"})` is allowed.
 
 The native `checkpoint --status complete` command rejects missing or shallow gates. `--quality-gate-json` must include:
 
@@ -178,6 +207,70 @@ The native `checkpoint --status complete` command rejects missing or shallow gat
     "evidence": "executor-built e2e and red-team QA commands/results",
     "e2eCommands": ["bun test:e2e"],
     "redTeamCommands": ["bun test:red-team"],
+    "artifactRefs": [
+      {
+        "id": "browser-run",
+        "kind": "browser-automation",
+        "path": "artifacts/browser-run.json",
+        "description": "browser automation transcript invoking the approved user-facing flow"
+      },
+      {
+        "id": "gui-screenshot",
+        "kind": "screenshot",
+        "path": "artifacts/gui-screenshot.png",
+        "description": "screenshot or image-verdict evidence for the GUI/web result"
+      },
+      {
+        "id": "adversarial-report",
+        "kind": "failure-mode-test",
+        "path": "artifacts/adversarial-report.txt",
+        "description": "boundary, property, adversarial, or failure-mode result"
+      }
+    ],
+    "contractCoverage": [
+      {
+        "id": "contract-goal",
+        "contractRef": "approved plan/spec/acceptance criterion or user-facing contract id",
+        "obligation": "required behavior from the approved contract",
+        "status": "covered",
+        "surfaceEvidenceRefs": ["surface-gui"],
+        "adversarialCaseRefs": ["case-invalid-input"]
+      },
+      {
+        "id": "contract-out-of-scope",
+        "contractRef": "contract intentionally outside this story",
+        "obligation": "explicitly omitted approved-contract surface",
+        "status": "not_applicable",
+        "reason": "why this contract does not apply to the current story"
+      }
+    ],
+    "surfaceEvidence": [
+      {
+        "id": "surface-gui",
+        "contractRef": "user-facing surface or public interface under test",
+        "surface": "gui|web|cli|api|package|algorithm|math",
+        "invocation": "real browser action, CLI command, API/package consumer call, or algorithm/property check",
+        "verdict": "passed",
+        "artifactRefs": ["browser-run", "gui-screenshot"]
+      },
+      {
+        "id": "surface-out-of-scope",
+        "contractRef": "surface intentionally outside this story",
+        "surface": "gui|web|cli|api|package|algorithm|math",
+        "status": "not_applicable",
+        "reason": "why this surface does not apply to the current story"
+      }
+    ],
+    "adversarialCases": [
+      {
+        "id": "case-invalid-input",
+        "contractRef": "approved plan/spec/acceptance criterion or user-facing contract id",
+        "scenario": "boundary/property/adversarial/failure-mode input or user action",
+        "expectedBehavior": "contract-required rejection, handling, or invariant preservation",
+        "verdict": "passed",
+        "artifactRefs": ["adversarial-report"]
+      }
+    ],
     "blockers": []
   },
   "iteration": {

package/src/eval/py/executor.ts

@@ -1,5 +1,6 @@
 import { getProjectDir, logger } from "@gajae-code/utils";
 import { Settings } from "../../config/settings";
+import { formatCrashDiagnosticNotice, writeCrashReport } from "../../debug/crash-diagnostics";
 import { OutputSink } from "../../session/streaming-output";
 import type { ToolSession } from "../../tools";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../../tools/output-meta";
@@ -62,6 +63,8 @@ export interface PythonExecutorOptions {
 
 export interface PythonKernelExecutor {
 	execute: (code: string, options?: KernelExecuteOptions) => Promise<KernelExecuteResult>;
+	getExitCode?: () => number | null;
+	peekStderr?: () => string;
 }
 
 export interface PythonResult {
@@ -446,12 +449,29 @@ async function executeWithKernel(
 			const annotation = result.timedOut
 				? formatKernelTimeoutAnnotation(executionTimeoutMs, result.kernelKilled ?? false)
 				: undefined;
+			let crashNotice: string | null = null;
+			if (result.kernelKilled) {
+				crashNotice = formatCrashDiagnosticNotice(
+					await writeCrashReport(
+						{
+							kind: "python",
+							exitCode: kernel.getExitCode?.(),
+							cancelled: false,
+							timedOut: result.timedOut,
+							stderr: kernel.peekStderr?.(),
+							protocol: "eval.py.kernel",
+						},
+						{ cwd: options?.cwd },
+					),
+				);
+			}
+			const notice = [annotation, crashNotice].filter(text => text).join("; ") || undefined;
 			return {
 				exitCode: undefined,
 				cancelled: true,
 				displayOutputs,
 				stdinRequested: result.stdinRequested,
-				...(await sink.dump(annotation)),
+				...(await sink.dump(notice)),
 			};
 		}
 

package/src/eval/py/kernel.ts

@@ -183,6 +183,8 @@ export class PythonKernel {
 	#disposed = false;
 	#shutdownConfirmed = false;
 	#exitedPromise: Promise<number> | null = null;
+	#exitCode: number | null = null;
+	#stderrTail = "";
 	#pending = new Map<string, PendingExecution>();
 	#readBuffer = "";
 
@@ -230,6 +232,7 @@ export class PythonKernel {
 		kernel.#stdin = proc.stdin;
 		kernel.#exitedPromise = proc.exited;
 		void kernel.#exitedPromise.then(code => {
+			kernel.#exitCode = code;
 			kernel.#alive = false;
 			kernel.#abortPendingExecutions(`Python kernel exited with code ${code}`, { kernelKilled: true });
 		});
@@ -255,6 +258,14 @@ export class PythonKernel {
 		return this.#alive && !this.#disposed;
 	}
 
+	getExitCode(): number | null {
+		return this.#exitCode;
+	}
+
+	peekStderr(): string {
+		return this.#stderrTail;
+	}
+
 	async execute(code: string, options?: KernelExecuteOptions): Promise<KernelExecuteResult> {
 		if (!this.isAlive()) {
 			throw new Error("Python kernel is not running");
@@ -493,6 +504,10 @@ export class PythonKernel {
 					const { done, value } = await reader.read();
 					if (done) break;
 					const text = decoder.decode(value);
+					this.#stderrTail += text;
+					if (this.#stderrTail.length > 4096) {
+						this.#stderrTail = this.#stderrTail.slice(-4096);
+					}
 					if (text.trim()) {
 						logger.warn("Python runner stderr", { text });
 					}

package/src/exec/bash-executor.ts

@@ -5,7 +5,9 @@
  */
 import * as fs from "node:fs/promises";
 import { executeShell, type MinimizerOptions, Shell } from "@gajae-code/natives";
+import { postmortem } from "@gajae-code/utils";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
+import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
 import { OutputSink } from "../session/streaming-output";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
@@ -58,6 +60,30 @@ export interface BashResult {
 const shellSessions = new Map<string, Shell>();
 const brokenShellSessions = new Set<string>();
 
+/** Number of persistent shell sessions currently retained (owner gauge). */
+export function getShellSessionCount(): number {
+	return shellSessions.size;
+}
+
+/**
+ * Dispose all persistent shell sessions: abort in-flight work and drop the
+ * strong references so the native shells can be finalized. Healthy persistent
+ * sessions are otherwise retained for the whole process lifetime (MEM-7). This
+ * is registered as a postmortem cleanup so shutdown/signals release native
+ * shell resources, and is also callable directly (e.g. on owner teardown).
+ */
+export async function disposeAllShellSessions(): Promise<void> {
+	// Snapshot and drop strong references up front so concurrent callers cannot
+	// reuse a session that is being torn down, then await every native abort so
+	// shutdown/signal cleanup does not return before resources are released.
+	const sessions = [...shellSessions.values()];
+	shellSessions.clear();
+	brokenShellSessions.clear();
+	await Promise.allSettled(sessions.map(session => session.abort()));
+}
+
+postmortem.register("bash-executor:shell-sessions", () => disposeAllShellSessions());
+
 async function resolveShellCwd(cwd: string | undefined): Promise<string | undefined> {
 	if (!cwd) return undefined;
 
@@ -280,6 +306,21 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			}
 		}
 
+		const crashReport = await writeCrashReport(
+			{
+				kind: "bash",
+				command: [shell, "-lc", finalCommand],
+				exitCode: winner.result.exitCode,
+				stderr: undefined,
+			},
+			{ cwd: commandCwd },
+		);
+		const crashNotice = formatCrashDiagnosticNotice(crashReport);
+		if (crashNotice) {
+			const separator = "\n";
+			sink.push(`${separator}${crashNotice}\n`);
+		}
+
 		// Normal completion
 		return {
 			exitCode: winner.result.exitCode,

package/src/extensibility/custom-tools/types.ts

@@ -109,6 +109,7 @@ export type CustomToolSessionEvent =
 			maxAttempts: number;
 			delayMs: number;
 			errorMessage: string;
+			unbounded?: boolean;
 	  }
 	| {
 			reason: "auto_retry_end";

package/src/extensibility/extensions/types.ts

@@ -116,6 +116,12 @@ export interface ExtensionUIDialogOptions {
 	 * hint; non-TUI bridges (RPC, ACP) drop it and do not serialize it.
 	 */
 	wrapFocused?: boolean;
+	/**
+	 * For interactive TUI select dialogs, cap the title/prompt area to this
+	 * many rows and let PageUp/PageDown scroll that prompt locally. This is a
+	 * select-only rendering hint; non-TUI bridges drop it and do not serialize it.
+	 */
+	scrollTitleRows?: number;
 }
 
 /** Raw terminal input listener for extensions. */

package/src/extensibility/shared-events.ts

@@ -226,6 +226,7 @@ export interface AutoRetryStartEvent {
 	maxAttempts: number;
 	delayMs: number;
 	errorMessage: string;
+	unbounded?: boolean;
 }
 
 /** Fired when auto-retry ends */

package/src/gjc-runtime/cli-write-receipt.ts

@@ -0,0 +1,31 @@
+/**
+ * CLI write/mutation receipt shaping (Workstream B, v4).
+ *
+ * `CliWriteReceipt` is the compact **stdout presentation** returned by a GJC
+ * mutation command. It carries only routing/audit fields a caller needs; it
+ * NEVER echoes the persisted body (full `state` envelope, ultragoal `plan`,
+ * team task body, ralplan `task`, etc.) — echoing those back is a redundant
+ * token leak because the caller already has the content it just wrote.
+ *
+ * This is intentionally a *separate* concept from the persisted
+ * `WorkflowStateReceipt` (the on-disk envelope `receipt` integrity field).
+ * Do NOT use `CliWriteReceipt` as a persistence schema or validate persisted
+ * envelopes against it.
+ */
+export interface CliWriteReceipt {
+	ok: boolean;
+	[field: string]: unknown;
+}
+
+/**
+ * Serialize a write/mutation receipt to compact stdout JSON.
+ * `undefined` fields are dropped so optional routing fields stay absent
+ * rather than serialized as `null`.
+ */
+export function renderCliWriteReceipt(receipt: Record<string, unknown>): string {
+	const out: Record<string, unknown> = {};
+	for (const key of Object.keys(receipt)) {
+		if (receipt[key] !== undefined) out[key] = receipt[key];
+	}
+	return `${JSON.stringify(out)}\n`;
+}

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

@@ -4,8 +4,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { buildDeepInterviewHudSummary } from "../skill-state/workflow-hud";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 import { runNativeRalplanCommand } from "./ralplan-runtime";
 import { runNativeStateCommand } from "./state-runtime";
+import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
 
 /**
  * Native implementation of `gjc deep-interview`.
@@ -94,23 +96,6 @@ function deepInterviewStatePath(cwd: string, sessionId: string | undefined): str
 	return path.join(stateDirFor(cwd, sessionId), "deep-interview-state.json");
 }
 
-async function readJsonObject(filePath: string): Promise<Record<string, unknown>> {
-	try {
-		const parsed = JSON.parse(await fs.readFile(filePath, "utf-8"));
-		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
-	} catch {
-		// Missing/corrupt state should not prevent the sanctioned persistence CLI from writing a receipt.
-	}
-	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 {
@@ -150,6 +135,7 @@ export interface ResolvedDeepInterviewSpecWriteArgs {
 	json: boolean;
 	deliberate: boolean;
 	handoff?: "ralplan";
+	force: boolean;
 }
 
 export interface PersistedDeepInterviewSpec {
@@ -167,6 +153,8 @@ interface DeepInterviewSpecWriteSummary {
 	slug: string;
 	path: string;
 	sha256: string;
+	spec_path: string;
+	sha: string;
 	created_at: string;
 	state_path: string;
 	handoff?: {
@@ -202,9 +190,34 @@ async function readSettingsAmbiguityThreshold(
 	return { threshold: candidate, source: settingsPath };
 }
 
+function modernSettingsPath(): string {
+	const configDir = process.env.GJC_CODING_AGENT_DIR?.trim() || process.env.PI_CODING_AGENT_DIR?.trim();
+	if (configDir) return path.join(configDir, "config.yml");
+	const configRoot = process.env.GJC_CONFIG_DIR?.trim() || process.env.PI_CONFIG_DIR?.trim();
+	if (configRoot) return path.join(configRoot, "agent", "config.yml");
+	return path.join(os.homedir(), ".gjc", "agent", "config.yml");
+}
+
+async function readModernSettingsAmbiguityThreshold(): Promise<{ threshold: number; source: string } | undefined> {
+	const modernConfigPath = modernSettingsPath();
+	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();
+	if (modernValue) return modernValue;
 	const projectSettings = path.join(cwd, ".gjc", "settings.json");
 	const projectValue = await readSettingsAmbiguityThreshold(projectSettings);
 	if (projectValue) return projectValue;
@@ -277,6 +290,7 @@ async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promi
 		"--handoff",
 		"--deliberate",
 		"--json",
+		"--force",
 	]);
 	let skipNext = false;
 	for (const arg of args) {
@@ -300,6 +314,7 @@ async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promi
 		sessionId,
 		json: hasFlag(args, "--json"),
 		deliberate: hasFlag(args, "--deliberate"),
+		force: hasFlag(args, "--force"),
 		handoff: rawHandoff as "ralplan" | undefined,
 	};
 }
@@ -373,27 +388,37 @@ 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 statePath = deepInterviewStatePath(cwd, resolved.sessionId);
+	const existingRead = await readExistingStateForMutation(statePath);
+	if (existingRead.kind === "corrupt" && !resolved.force) {
+		throw new DeepInterviewCommandError(
+			2,
+			`existing deep-interview state is corrupt or tampered (${existingRead.error}); use --force to overwrite ${statePath}`,
+		);
+	}
+	const existing = existingRead.kind === "valid" ? existingRead.value : {};
+
+	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);
-	const existing = await readJsonObject(statePath);
 	const payload: Record<string, unknown> = {
 		...existing,
 		active: true,
 		current_phase: "handoff",
 		skill: "deep-interview",
-		version: typeof existing.version === "number" ? existing.version : 1,
+		version: WORKFLOW_STATE_VERSION,
 		spec_slug: resolved.slug,
 		spec_path: specPath,
 		spec_sha256: sha256,
@@ -402,7 +427,24 @@ export async function persistDeepInterviewSpec(
 		updated_at: createdAt,
 	};
 	if (resolved.sessionId) payload.session_id = resolved.sessionId;
-	await writeJsonAtomic(statePath, payload);
+	await writeWorkflowEnvelopeAtomic(statePath, payload, {
+		cwd,
+		receipt: {
+			cwd,
+			skill: "deep-interview",
+			owner: "gjc-runtime",
+			command: "gjc deep-interview persist-spec-state",
+			sessionId: resolved.sessionId,
+			nowIso: createdAt,
+		},
+		audit: {
+			category: "state",
+			verb: "write",
+			owner: "gjc-runtime",
+			skill: "deep-interview",
+			forced: resolved.force,
+		},
+	});
 	await syncDeepInterviewHud({
 		cwd,
 		sessionId: resolved.sessionId,
@@ -421,16 +463,13 @@ 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,
 		current_phase: "interviewing",
 		skill: "deep-interview",
+		version: WORKFLOW_STATE_VERSION,
 		resolution: resolved.resolution,
 		threshold: resolved.threshold,
 		threshold_source: resolved.thresholdSource,
@@ -448,7 +487,18 @@ 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 writeWorkflowEnvelopeAtomic(statePath, payload, {
+		cwd,
+		receipt: {
+			cwd,
+			skill: "deep-interview",
+			owner: "gjc-runtime",
+			command: "gjc deep-interview seed",
+			sessionId: resolved.sessionId,
+			nowIso: now,
+		},
+		audit: { category: "state", verb: "write", owner: "gjc-runtime", skill: "deep-interview" },
+	});
 	return statePath;
 }
 
@@ -493,6 +543,8 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 		slug: persisted.slug,
 		path: persisted.path,
 		sha256: persisted.sha256,
+		spec_path: persisted.path,
+		sha: persisted.sha256,
 		created_at: persisted.createdAt,
 		state_path: persisted.statePath,
 	};
@@ -530,10 +582,14 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 	}
 
 	const stdout = resolved.json
-		? `${JSON.stringify(summary, null, 2)}\n`
+		? `${JSON.stringify(summary)}\n`
 		: [
-				`Persisted deep-interview ${persisted.stage} spec at ${persisted.path}.`,
-				shouldHandoff ? "Handed off deep-interview to ralplan (deliberate)." : undefined,
+				`deep-interview spec_path=${persisted.path}`,
+				`sha=${persisted.sha256}`,
+				`state_path=${persisted.statePath}`,
+				shouldHandoff
+					? `handoff=ralplan run_id=${summary.handoff?.run_id ?? ""} state_path=${summary.handoff?.state_path ?? ""}`
+					: undefined,
 				"",
 			]
 				.filter((line): line is string => Boolean(line))
@@ -572,14 +628,14 @@ export async function runNativeDeepInterviewCommand(
 			idea: resolved.idea,
 			language: resolved.language,
 			state_path: statePath,
-			handoff: "Run `/skill:deep-interview` inside the GJC agent to drive the Socratic interview loop.",
+			handoff: "/skill:deep-interview",
 		};
 		const stdout = resolved.json
-			? `${JSON.stringify(summary, null, 2)}\n`
+			? `${JSON.stringify(summary)}\n`
 			: [
-					`Seeded deep-interview ${resolved.resolution} run at ${statePath}.`,
-					`Threshold: ${(resolved.threshold * 100).toFixed(0)}% (source: ${resolved.thresholdSource}).`,
-					"Run `/skill:deep-interview` inside the GJC agent to execute the interview.",
+					`deep-interview seed state_path=${statePath}`,
+					`resolution=${resolved.resolution} threshold=${resolved.threshold} threshold_source=${resolved.thresholdSource}`,
+					"handoff=/skill:deep-interview",
 					"",
 				].join("\n");
 		return { status: 0, stdout };