@gajae-code/coding-agent 0.8.2 → 0.9.0

package/src/notifications/index.ts

@@ -33,8 +33,8 @@ import { registerAskAnswerSource } from "../tools/ask-answer-registry";
 import { registerTelegramFileSink } from "./attachment-registry";
 import {
 	getNotificationConfig,
-	isGloballyConfigured,
 	isSessionNotificationsEnabled,
+	isTelegramConfigured,
 	type NotificationConfig,
 	sessionTag,
 } from "./config";
@@ -350,6 +350,12 @@ interface SessionRuntime {
 	/** Assistant text already flushed before an ask this turn (turn-scoped dedupe
 	 * so turn_end does not re-emit the pre-ask lead-in). Reset each turn. */
 	preAskFlushedText?: string;
+	/** Live streaming: opt-in flag, monotonic per-turn ref, and emit throttle state. */
+	stream: boolean;
+	turnSeq?: number;
+	liveRef?: string;
+	lastLiveAt?: number;
+	lastLiveText?: string;
 	/** Cancels the postmortem cleanup that emits `session_closed` on process teardown. */
 	cancelPostmortemCleanup: () => void;
 }
@@ -383,6 +389,33 @@ export function notificationsEnabled(): boolean {
 	return process.env.GJC_NOTIFICATIONS === "1" || Boolean(process.env.GJC_NOTIFICATIONS_TOKEN);
 }
 
+// Live streaming (opt-in): emit throttled non-finalized `turn_stream` frames as
+// the assistant message streams so remote clients can edit ONE message live. The
+// finalized frame (turn_end) carries the same messageRef and stays authoritative,
+// so a dropped live frame self-heals. Off unless GJC_NOTIFICATIONS_STREAM=1.
+function streamingEnabled(): boolean {
+	return process.env.GJC_NOTIFICATIONS_STREAM === "1";
+}
+function streamIntervalMs(): number {
+	return Math.max(200, Number(process.env.GJC_NOTIFICATIONS_STREAM_INTERVAL_MS) || 500);
+}
+// Max chars of a turn's assistant text carried by the FINALIZED turn_stream (and
+// the pre-ask capture). Default 3500 keeps the mirror a glanceable per-turn
+// summary; a client that splits long messages (the Telegram daemon does so via
+// splitTelegramHtml, scheduling each chunk through the shared rate-limit pool so
+// the fan-out never bypasses the per-chat limit) can raise it with
+// GJC_NOTIFICATIONS_TURN_MAX to deliver full turns. The value is clamped to a
+// finite [280, TURN_TEXT_MAX_CEILING] range: a non-finite or non-positive env
+// (unset, NaN, Infinity, <= 0) falls back to the default, so the cap can never
+// be unbounded. Live frames are intentionally NOT raised — they stay one
+// editable preview message rather than fanning a long in-progress turn across
+// sends.
+const TURN_TEXT_MAX_CEILING = 40_000;
+function turnTextMax(): number {
+	const raw = Number(process.env.GJC_NOTIFICATIONS_TURN_MAX);
+	if (!Number.isFinite(raw) || raw <= 0) return 3500;
+	return Math.min(TURN_TEXT_MAX_CEILING, Math.max(280, raw));
+}
 function resolveSettings(settingsOverride?: Settings): ResolvedSettings {
 	if (settingsOverride)
 		return { settings: settingsOverride, cfg: getNotificationConfig(settingsOverride), settingsAvailable: true };
@@ -708,6 +741,7 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 				cancelPostmortemCleanup: () => {},
 				redact,
 				verbosity,
+				stream: streamingEnabled(),
 				sessionTag: tag,
 				busy: false,
 				pendingInbound: new Set<number>(),
@@ -724,7 +758,7 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 			});
 			logger.info(`notifications: serving session ${id} at ${endpoint.url} (unattended=${unattended})`);
 
-			if (settingsAvailable && settings && isGloballyConfigured(cfg)) {
+			if (settingsAvailable && settings && isTelegramConfigured(cfg)) {
 				try {
 					await ensureTelegramDaemonRunning({ settings, cwd: ctx.cwd, sessionId: id });
 				} catch (e) {
@@ -1063,7 +1097,15 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 		if (!text || text === rt.preAskFlushedText) return;
 		rt.preAskFlushedText = text;
 		try {
-			rt.server.pushFrame(JSON.stringify({ type: "turn_stream", sessionId: id, phase: "finalized", text }));
+			rt.server.pushFrame(
+				JSON.stringify({
+					type: "turn_stream",
+					sessionId: id,
+					phase: "finalized",
+					text,
+					...(rt.liveRef ? { messageRef: rt.liveRef } : {}),
+				}),
+			);
 		} catch (e) {
 			logger.warn(`notifications: pushFrame (turn) failed: ${String(e)}`);
 		}
@@ -1087,12 +1129,43 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 		const id = sessionId(ctx);
 		const rt = runtimes.get(id);
 		if (!rt) return;
-		const text = rt.redact ? undefined : summaryFromMessage(event.message, 3500);
+		const text = rt.redact ? undefined : summaryFromMessage(event.message, turnTextMax());
 		if (text) flushTurnText(rt, id, text);
 		// Reset per-turn streaming state so the next turn starts fresh and a later
 		// turn with identical text is not falsely deduped.
 		rt.currentTurnText = undefined;
 		rt.preAskFlushedText = undefined;
+		rt.liveRef = undefined;
+		rt.lastLiveAt = undefined;
+		rt.lastLiveText = undefined;
+	});
+
+	// Live streaming (opt-in): push throttled in-progress assistant text as
+	// non-finalized turn_stream frames so remote clients edit one message as the
+	// turn streams. The finalized frame (turn_end) carries the same messageRef and
+	// lands the authoritative text. Suppressed under redaction.
+	api.on("message_update", (event, ctx) => {
+		const id = sessionId(ctx);
+		const rt = runtimes.get(id);
+		if (!rt?.stream || rt.redact) return;
+		if ((event.message as { role?: unknown }).role !== "assistant") return;
+		if (rt.liveRef === undefined) {
+			rt.turnSeq = (rt.turnSeq ?? 0) + 1;
+			rt.liveRef = String(rt.turnSeq);
+		}
+		const now = Date.now();
+		if (now - (rt.lastLiveAt ?? 0) < streamIntervalMs()) return;
+		const text = summaryFromMessage(event.message, 3500);
+		if (!text || text === rt.lastLiveText) return;
+		rt.lastLiveAt = now;
+		rt.lastLiveText = text;
+		try {
+			rt.server.pushFrame(
+				JSON.stringify({ type: "turn_stream", sessionId: id, phase: "live", text, messageRef: rt.liveRef }),
+			);
+		} catch (e) {
+			logger.warn(`notifications: pushFrame (live) failed: ${String(e)}`);
+		}
 	});
 
 	// Stream agent-produced images (computer/browser/tool screenshots) as
@@ -1106,7 +1179,7 @@ export function createNotificationsExtension(api: ExtensionAPI, options: { setti
 		// flush can emit it before the ask prompt. Role-scoped: message_end also
 		// fires for the user prompt, which must never be mirrored back as turn output.
 		if ((event.message as { role?: unknown }).role === "assistant") {
-			const turnText = summaryFromMessage(event.message, 3500);
+			const turnText = summaryFromMessage(event.message, turnTextMax());
 			if (turnText) rt.currentTurnText = turnText;
 		}
 		for (const img of imageAttachmentsFromMessage(event.message)) {

package/src/notifications/telegram-daemon-cli.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { YAML } from "bun";
 import type { Settings } from "../config/settings";
-import { getNotificationConfig, isGloballyConfigured } from "./config";
+import { getNotificationConfig, isTelegramConfigured } from "./config";
 import { daemonPaths } from "./daemon-paths";
 import type { TelegramDaemonOptions } from "./telegram-daemon";
 
@@ -146,7 +146,7 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 	const resolvedAgentDir = agentDir ?? process.env.GJC_CODING_AGENT_DIR ?? path.join(process.cwd(), ".gjc", "agent");
 	const settings = await resolveDaemonSettings(resolvedAgentDir, deps);
 	const cfg = getNotificationConfig(settings as Settings);
-	if (!isGloballyConfigured(cfg) || !cfg.botToken || !cfg.chatId) return;
+	if (!isTelegramConfigured(cfg)) return;
 	const { clearTelegramControlRequest, readTelegramControlRequest } = await import("./telegram-daemon-control");
 	const Daemon: TelegramDaemonConstructor =
 		deps.DaemonImpl ?? (await import("./telegram-daemon")).TelegramNotificationDaemon;

package/src/notifications/telegram-daemon-control.ts

@@ -20,7 +20,7 @@ import type {
 	DaemonStatus,
 } from "../daemon/control-types";
 import { resolveGjcRuntimeSpawnInfo } from "../daemon/runtime";
-import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
+import { getNotificationConfig, isTelegramConfigured, tokenFingerprint } from "./config";
 import {
 	daemonPaths,
 	isFreshLiveOwner,
@@ -159,7 +159,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 	async status(): Promise<DaemonStatus> {
 		const runtime = this.runtimeInfo();
 		const cfg = getNotificationConfig(this.settings);
-		const configured = isGloballyConfigured(cfg) && Boolean(cfg.botToken) && Boolean(cfg.chatId);
+		const configured = isTelegramConfigured(cfg);
 		if (!configured) {
 			return { kind: this.kind, configured: false, health: "not_configured", runtime };
 		}

package/src/notifications/telegram-daemon.ts

@@ -8,7 +8,7 @@ import { withFileLock } from "../config/file-lock";
 import type { Settings } from "../config/settings";
 import type { DaemonRuntimeInfo } from "../daemon/control-types";
 import { resolveGjcRuntimeSpawnInfo } from "../daemon/runtime";
-import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
+import { getNotificationConfig, isTelegramConfigured, tokenFingerprint } from "./config";
 import { parseInThreadConfigCommand } from "./config-commands";
 import { daemonPaths } from "./daemon-paths";
 import {
@@ -636,7 +636,7 @@ export async function ensureTelegramDaemonRunning(
 	deps: TelegramDaemonDeps = {},
 ): Promise<EnsureDaemonResult> {
 	const cfg = getNotificationConfig(input.settings);
-	if (!isGloballyConfigured(cfg) || !cfg.botToken || !cfg.chatId) return "disabled";
+	if (!isTelegramConfigured(cfg)) return "disabled";
 	const root = notificationRootForCwd(input.cwd);
 	const fp = tokenFingerprint(cfg.botToken);
 	const spawned = await spawnTelegramDaemonOwner(
@@ -869,6 +869,8 @@ interface PendingThreadedFrame {
 export class TelegramNotificationDaemon {
 	readonly aliasTable: AliasTable;
 	readonly messageRoutes = new Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>();
+	/** Telegram message id backing each streamed `${sessionId}:${coalesceKey}`, for in-place edits. */
+	private readonly liveMessages = new Map<string, number>();
 	readonly sessions = new Map<string, SessionSocket>();
 	private readonly runtime: NotificationOperatorRuntime;
 	private readonly sessionRouter: OperatorEventRouter<SessionSocket>;
@@ -1666,6 +1668,9 @@ export class TelegramNotificationDaemon {
 			})) as { ok?: boolean };
 			if (res?.ok === false) return;
 			this.topics.delete(sessionId);
+			for (const k of [...this.liveMessages.keys()]) {
+				if (k.startsWith(`${sessionId}:`)) this.liveMessages.delete(k);
+			}
 			this.topicOwnerByIdentity.forEach((ownerSessionId, identityKey) => {
 				if (ownerSessionId === sessionId) this.topicOwnerByIdentity.delete(identityKey);
 			});
@@ -1795,11 +1800,25 @@ export class TelegramNotificationDaemon {
 
 	/** Drain the shared rate-limit pool and deliver each granted send to its topic. */
 	private async flushPool(): Promise<void> {
-		for (const item of this.pool.drain()) {
+		const batch = this.pool.drain();
+		// Within a batch a finalized frame supersedes any still-queued live frame for
+		// the same streamed message (finalized outranks live), so drop the stale live
+		// edit — otherwise the authoritative final text could be overwritten by an
+		// older partial delivered right after it.
+		const finalizedKeys = new Set<string>();
+		for (const item of batch) {
+			if (item.lane === "finalized" && item.coalesceKey !== undefined) {
+				finalizedKeys.add(`${item.sessionId}:${item.coalesceKey}`);
+			}
+		}
+		for (const item of batch) {
 			const { send, topicId } = item.payload;
 			if (topicId && !(await this.pairedChatIsPrivate())) continue;
 			// Threaded topic when available; otherwise deliver flat to the paired chat.
 			const threadField = topicId ? { message_thread_id: Number(topicId) } : {};
+			const ckey = send.editable ? item.coalesceKey : undefined;
+			const editKey = ckey !== undefined ? `${item.sessionId}:${ckey}` : undefined;
+			if (item.lane === "live" && editKey && finalizedKeys.has(editKey)) continue;
 			try {
 				if (send.method === "sendPhoto" && send.photoBase64) {
 					// Real photo upload (the default botApi multiparts base64 -> file).
@@ -1822,21 +1841,79 @@ export class TelegramNotificationDaemon {
 						parse_mode: TELEGRAM_PARSE_MODE,
 					});
 				} else if (send.text) {
-					for (const text of splitTelegramHtml(send.text)) {
-						await this.botApi.call("sendMessage", {
+					const chunks = splitTelegramHtml(send.text);
+					const existingId = editKey ? this.liveMessages.get(editKey) : undefined;
+					if (editKey && existingId !== undefined && chunks.length === 1) {
+						// In-place edit of the streamed message. An unchanged edit is
+						// rejected by Telegram ("message is not modified") and swallowed.
+						await this.botApi.call("editMessageText", {
 							chat_id: this.opts.chatId,
-							...threadField,
-							text,
+							message_id: existingId,
+							text: chunks[0],
 							parse_mode: TELEGRAM_PARSE_MODE,
 						});
+					} else {
+						// A single granted slot MUST map to a single Telegram send. When the
+						// rendered text splits into multiple chunks (e.g. a long finalized
+						// turn raised via GJC_NOTIFICATIONS_TURN_MAX), deliver the first
+						// chunk on this token and re-submit the remaining chunks as their
+						// own pool items so each consumes a token on a later drain.
+						// Otherwise one frame would fan out into many sends against a single
+						// slot, bypassing the per-chat rate-limit / fairness invariant.
+						const res = (await this.botApi.call("sendMessage", {
+							chat_id: this.opts.chatId,
+							...threadField,
+							text: chunks[0]!,
+							parse_mode: TELEGRAM_PARSE_MODE,
+						})) as { result?: { message_id?: number } };
+						for (let i = 1; i < chunks.length; i++) {
+							// Continuation chunks are fresh, non-editable text sends: no
+							// coalesce key (they neither replace nor are replaced by other
+							// frames) and no media payload.
+							this.pool.submit({
+								sessionId: item.sessionId,
+								lane: item.lane,
+								payload: {
+									send: {
+										...send,
+										method: "sendMessage",
+										text: chunks[i]!,
+										editable: false,
+										coalesceKey: undefined,
+										photoBase64: undefined,
+										documentBase64: undefined,
+									},
+									topicId,
+								},
+							});
+						}
+						const firstMessageId = res?.result?.message_id;
+						if (editKey && ckey !== undefined && firstMessageId !== undefined) {
+							this.recordLiveMessage(item.sessionId, ckey, firstMessageId);
+						}
 					}
 				}
 			} catch {
-				// Best-effort: a failed send must never stop the daemon.
+				// Best-effort: a failed send/edit must never stop the daemon.
 			}
 		}
 	}
 
+	/**
+	 * Track the Telegram message id backing a streamed `(sessionId, coalesceKey)`
+	 * so later live/finalized frames edit it in place. Evicts this session's stale
+	 * same-category entries (e.g. prior turns) so the map stays bounded.
+	 */
+	private recordLiveMessage(sessionId: string, coalesceKey: string, messageId: number): void {
+		const mapKey = `${sessionId}:${coalesceKey}`;
+		const category = coalesceKey.split(":")[0] ?? "";
+		const prefix = `${sessionId}:${category}:`;
+		for (const k of [...this.liveMessages.keys()]) {
+			if (k !== mapKey && k.startsWith(prefix)) this.liveMessages.delete(k);
+		}
+		this.liveMessages.set(mapKey, messageId);
+	}
+
 	/**
 	 * Threaded Mode is unavailable (the bot owner has not enabled forum topics in
 	 * @BotFather, so `createForumTopic` fails). Deliver the rendered frame flat to

package/src/notifications/threaded-render.ts

@@ -32,6 +32,12 @@ export interface ThreadedSend {
 	coalesceKey?: string;
 	/** True for the one-time identity header (the daemon pins it once). */
 	identity?: boolean;
+	/**
+	 * When true the daemon may deliver this as an in-place edit of the message
+	 * previously sent under the same `(sessionId, coalesceKey)` instead of a new
+	 * message. Set for streamed turn frames so live + finalized share one message.
+	 */
+	editable?: boolean;
 }
 
 interface ThreadedFrame {
@@ -135,11 +141,21 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 			if (!raw) return undefined;
 			const text = markdownToTelegramHtml(raw);
 			const finalized = frame.phase === "finalized";
+			// A per-turn ref ties the streamed live edits and the finalized text to
+			// ONE message. Without a ref (streaming off), finalized keeps its legacy
+			// keyless behaviour: a fresh message per turn.
+			const ref = str(frame.messageRef);
+			const coalesceKey = finalized
+				? ref
+					? `turn:${ref}`
+					: undefined
+				: `turn:${ref ?? str(frame.sessionId) ?? ""}`;
 			return {
 				method: "sendMessage",
 				lane: finalized ? "finalized" : "live",
 				text,
-				coalesceKey: finalized ? undefined : `turn:${str(frame.messageRef) ?? str(frame.sessionId) ?? ""}`,
+				coalesceKey,
+				editable: coalesceKey !== undefined,
 			};
 		}
 		case "image_attachment": {

package/src/prompts/agents/architect.md

@@ -19,18 +19,20 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 - Assess architecture, boundaries, interfaces, tradeoffs, and long-horizon maintainability.
 - Verify spec compliance before style concerns.
 - Review security, correctness, performance, and code quality with severity-rated feedback.
+- Provide the strongest fair antithesis to risky plans, then synthesize a better path when possible.
+- Broaden thin plans with missed architectural sub-scope, viable options, and concrete design constraints.
 - Surface an architectural status: `CLEAR`, `WATCH`, or `BLOCK`.
 - Surface a code-review recommendation: `APPROVE`, `COMMENT`, or `REQUEST CHANGES`.
 </goals>
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the verdict markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use restricted `bash` only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass review markdown through `GJC_RALPLAN_ARTIFACT` and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Never approve code or plans you have not grounded in inspected files.
 - Never give generic advice detached from this codebase.
 - Never approve CRITICAL or HIGH severity issues.
 - Do not skip spec compliance to jump to style nitpicks.
-- Be constructive: explain why an issue matters and how to fix it.
+- Be constructive: explain why an issue matters and how to fix it or strengthen the design.
 </constraints>
 
 <review_stages>
@@ -38,9 +40,10 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 2. Gather file-backed evidence.
 3. Stage 1 — Spec compliance: does the implementation or plan solve the requested problem without missing or extra behavior?
 4. Stage 2 — Architecture: boundaries, coupling, data flow, failure modes, maintainability, and tradeoffs.
-5. Stage 3 — Code quality/security/performance: only after spec compliance and root-cause checks.
-6. Rate each issue by severity: CRITICAL, HIGH, MEDIUM, LOW.
-7. Return architectural status and code-review recommendation.
+5. Stage 3 — Constructive synthesis: where the plan is thin, add options, constraints, or design shape that would make it stronger.
+6. Stage 4 — Code quality/security/performance: only after spec compliance and root-cause checks.
+7. Rate each issue by severity: CRITICAL, HIGH, MEDIUM, LOW.
+8. Return architectural status and code-review recommendation.
 </review_stages>
 
 <root_cause_fallback_policy>
@@ -53,7 +56,8 @@ A narrow compatibility fallback can be acceptable only when it is scoped to a kn
 - Important claims cite concrete files or inspected evidence.
 - Root cause is identified when reviewing a defect.
 - Recommendations are concrete and implementable.
-- Tradeoffs are acknowledged.
+- Tradeoffs and antithesis are acknowledged without becoming adversarial-only.
+- Thin plans receive constructive synthesis or broadening when useful.
 - Issues include severity and fix suggestions.
 - Architectural Status is one of `CLEAR`, `WATCH`, or `BLOCK`.
 - Code Review Recommendation is one of `APPROVE`, `COMMENT`, or `REQUEST CHANGES`.
@@ -67,7 +71,7 @@ A narrow compatibility fallback can be acceptable only when it is scoped to a kn
 Evidence-backed claims being reviewed or introduced.
 
 ## Analysis
-Evidence-backed findings.
+Evidence-backed findings, antithesis, and constructive synthesis.
 
 ## Root Cause
 Fundamental issue, if applicable.
@@ -76,7 +80,7 @@ Fundamental issue, if applicable.
 For each issue: severity, file/reference, impact, fix suggestion.
 
 ## Recommendations
-Prioritized concrete actions.
+Prioritized concrete actions, including additive design options for thin plans.
 
 ## Architectural Status
 `CLEAR` / `WATCH` / `BLOCK`
@@ -87,9 +91,14 @@ Prioritized concrete actions.
 ## Tradeoffs
 Table or bullets comparing viable options when relevant.
 
-Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown through the `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
+Structured findings:
+- Report every issue through `report_finding` as you confirm it, mapping severity CRITICAL → P0, HIGH → P1, MEDIUM → P2, LOW → P3. The Findings section summarizes what you reported; `report_finding` is the structured channel the caller's pipeline consumes.
+
+Persistence (ralplan runs only):
+- Only when your assignment is part of an active ralplan run (the assignment references a ralplan stage or `stage_n`), persist the full review through the restricted bash CLI:
 
   gjc ralplan --write --stage architect --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
-Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (Architectural Status + Code Review Recommendation). Never paste the full review body back into your response — the caller reads the persisted artifact when it needs the full text.
+  Use the assignment-provided `stage_n`; if a duplicate-write error occurs, retry with the incremented N. Then return ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus compact verdict (Architectural Status + Code Review Recommendation) in `yield.result.data`. Never paste the full review body back; the caller reads the persisted artifact when needed.
+- Otherwise (any non-ralplan invocation), do NOT call `gjc ralplan --write`; return the full review in `yield.result.data` instead.
 </output_contract>

package/src/prompts/agents/critic.md

@@ -12,32 +12,34 @@ You are Critic. Decide whether a work plan is actionable before execution begins
 </identity>
 
 <goal>
-Review plan clarity, completeness, verification, big-picture fit, referenced files, and representative implementation paths. Return OKAY when executors can proceed without guessing; return REJECT or ITERATE with concrete fixes when they cannot.
+Review plan clarity, completeness, verification, big-picture fit, referenced files, and representative implementation paths. Return OKAY when executors can proceed without guessing; return ITERATE or REJECT with concrete fixes when they cannot. A valid ITERATE reason is “spec too thin here — expand” with specific enrichment requests, not only defect findings.
 </goal>
 
 <constraints>
 - Read-only: do not write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the evaluation markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use restricted `bash` only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass evaluation markdown through `GJC_RALPLAN_ARTIFACT` and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - A lone file path is valid input; read and evaluate it.
 - Reject YAML-only plans as invalid plan format when a human-readable plan is required.
 - Do not invent problems; report no issues found when the plan passes.
-- Escalate routing needs upward: planner for plan revision, analyst for requirements, architect for code analysis.
-- For consensus planning, reject shallow alternatives, driver contradictions, vague risks, weak verification, or missing acceptance criteria.
+- Escalate routing needs upward: planner for plan revision, the deep-interview skill for requirements gathering, architect for code analysis.
+- For consensus planning, reject shallow alternatives, driver contradictions, vague risks, weak verification, missing acceptance criteria, or under-specified areas needing expansion before execution.
 </constraints>
 
 <execution_loop>
 1. Read the plan and referenced artifacts.
 2. Extract and verify file references.
-3. Evaluate clarity, verifiability, completeness, and big-picture fit.
+3. Evaluate clarity, verifiability, completeness, big-picture fit, and principle/option consistency.
 4. Simulate two or three representative implementation tasks against actual files.
-5. Issue OKAY, ITERATE, or REJECT with specific evidence.
+5. Distinguish fatal defects from thin areas that need additive detail.
+6. Issue OKAY, ITERATE, or REJECT with specific evidence and required changes.
 </execution_loop>
 
 <success_criteria>
 - Every referenced file that matters is verified or called out as unverified.
 - Representative tasks have been mentally simulated.
 - Verdict is clear: OKAY, ITERATE, or REJECT.
-- Rejections list the top critical improvements with actionable wording.
+- ITERATE may request concrete expansion: assumptions, acceptance criteria, options, missed sub-scope, or verification detail.
+- Rejections list top critical improvements with actionable wording.
 - Certainty is differentiated: definitely missing versus possibly unclear.
 </success_criteria>
 
@@ -49,26 +51,22 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 Concise evidence-backed explanation of verified claims.
 
 ## Missing Evidence
-Definitely missing or unverified evidence, or `None`.
+Definitely missing, unverified evidence, or thin areas needing expansion; otherwise `None`.
 
 ## Approval Boundary
 What execution may proceed with, and what remains outside approval.
 
 ## Summary
-- Clarity
-- Verifiability
-- Completeness
-- Big Picture
-- Principle/Option Consistency
-- Alternatives Depth
-- Risk/Verification Rigor
+- Clarity; Verifiability; Completeness; Big Picture; Principle/Option Consistency; Alternatives Depth; Risk/Verification Rigor
 
 ## Required Changes
-If not OKAY, list concrete required fixes; otherwise write `None`.
+If not OKAY, list concrete defect fixes or expansion requirements; otherwise write `None`.
 
-Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown through the `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
+Persistence (ralplan runs only):
+- Only when your assignment is part of an active ralplan run (the assignment references a ralplan stage or `stage_n`), persist the full evaluation through the restricted bash CLI:
 
   gjc ralplan --write --stage critic --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
-Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (OKAY / ITERATE / REJECT). Never paste the full evaluation body back into your response — the caller reads the persisted artifact when it needs the full text.
+  Use the assignment-provided `stage_n`; if a duplicate-write error occurs, retry with the incremented N. Then return ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus compact verdict (OKAY / ITERATE / REJECT) in `yield.result.data`. Never paste the full evaluation body back; the caller reads the persisted artifact when needed.
+- Otherwise (any non-ralplan invocation), do NOT call `gjc ralplan --write`; return the full evaluation in `yield.result.data` instead.
 </output_contract>

package/src/prompts/agents/executor.md

@@ -35,25 +35,28 @@ Explore just enough context, implement the smallest correct change, and leave co
 This mode activates only when the assignment explicitly labels Executor as Ultragoal completion QA/red-team or asks for `executorQa` red-team evidence. Otherwise, preserve ordinary Executor behavior.
 
 When active:
-- Start from the approved plan/spec/acceptance criteria, then user-facing contracts, then implementation code only as supporting evidence. Treat plan/code mismatches as blockers.
-- Exercise the real user-facing invocation rather than inspecting internals alone. Live artifacts must be runtime-valid: GUI/web needs a real automation transcript plus non-uniform screenshot; CLI needs executed argv-only replay; native/desktop/TUI needs a real screenshot, PTY capture with control codes, or app-automation transcript. API/package surfaces need a real artifact file or typed receipt whose artifact `kind` contains `api`, `package`, `consumer`, `black-box`, or `test-report`; good kinds include `api-package-test-report`, `package-consumer-report`, and `black-box-api-receipt`. Algorithm/math surfaces need a real artifact file or typed receipt whose artifact `kind` contains `property`, `boundary`, `edge`, `adversarial`, `failure`, `math`, `algorithm`, or `test-report`; good kinds include `property-test-report` and `algorithm-boundary-report`. `inlineEvidence` is supplemental only and is never sole proof for live surfaces.
-- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments: `bun --version`, `node --version`, deterministic `bun/node -e "console.log(...)"`, `npm|pnpm|yarn --version`, `npm|pnpm|yarn list`, read-only `git status|rev-parse|merge-base|diff|show|log` with safe args, and `gjc read|status`. Mark any other command with audited `replayExempt` metadata plus a valid structural fallback artifact. `replayExempt` must use exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`; allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
-- Native/TUI evidence must be structural, not prose-only: screenshot, app transcript, or PTY artifact with terminal control codes.
-- Do not call the `ask` tool while an Ultragoal run is active; record unresolved decisions with `gjc ultragoal record-review-blockers`.
-- Try to break the work with adversarial cases, not just happy-path confirmations.
-- Report the QA matrix with the final field names `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`.
-- Include artifact refs for every executed surface and adversarial case: transcript ids, log paths, screenshots, image verdicts, CLI replay records, PTY captures, test outputs, or other durable evidence.
-- Use `status: "not_applicable"` only for rows in `executorQa.contractCoverage` and `executorQa.surfaceEvidence`; each not-applicable row requires `contractRef` plus `reason`. `executorQa.adversarialCases` rows cannot be not-applicable.
-- Report blockers for any missing plan/spec/acceptance source, contract ambiguity, plan/code mismatch, untestable surface, failed adversarial case, shallow evidence, or missing artifact ref.
+- Follow the exact `executorQa` contract provided in the assignment (matrix shape, row fields, artifact/replay rules); the runtime validates it strictly. If the assignment omits the contract, read the ultragoal SKILL's executor QA section before producing evidence.
+- Start from the approved plan/spec/acceptance criteria, then user-facing contracts; treat plan/code mismatches as blockers.
+- Exercise the real user-facing invocation and try adversarial cases, not only happy paths. `inlineEvidence` is supplemental only and never sole proof for live surfaces.
+- Do not call `ask`; record unresolved decisions with `gjc ultragoal record-review-blockers`.
+- Report blockers for missing plan/spec/acceptance source, contract ambiguity, plan/code mismatch, untestable surface, failed adversarial case, shallow evidence, or missing artifact refs.
 </ultragoal_red_team_mode>
 
 <success_criteria>
 - Requested behavior is implemented in the assigned scope.
 - Modified files match existing style and contracts.
 - No temporary/debug leftovers remain.
-- Final output lists changed files, important decisions, and verification performed or intentionally left to the parent.
 </success_criteria>
 
+<output_contract>
+Yield with `result.data` containing:
+- `changed_files`: paths touched, with one-line purpose each
+- `decisions`: important implementation decisions and assumptions
+- `verification`: checks performed, or precise verification left to the parent
+- `blockers`: unresolved blockers with attempted fixes; empty when none
+- In ultragoal red-team mode, `result.data` instead carries the `executorQa` matrix with its exact camelCase field names (`contractCoverage`, `surfaceEvidence`, `adversarialCases`, `artifactRefs`); the runtime validates those names verbatim — do not rename them to snake_case.
+</output_contract>
+
 <failure_recovery>
 Try another approach, split the blocker smaller, and re-check repo evidence before escalating. After materially different failed approaches, stop adding risk and report the blocker with attempted fixes.
 </failure_recovery>

package/src/prompts/agents/planner.md

@@ -12,38 +12,35 @@ You are Planner. Turn requests into actionable work plans. You plan; you do not
 </identity>
 
 <goal>
-Leave execution with a right-sized, evidence-grounded plan: scope, steps, acceptance criteria, risks, verification, and handoff guidance.
+Leave execution with a right-sized, evidence-grounded plan: scope, steps, acceptance criteria, risks, verification, and handoff guidance. When input is thin, enrich it: identify underspecified areas, propose assumptions/options, surface missed sub-scope, and add testable acceptance details instead of merely sequencing what was stated.
 </goal>
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the plan markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
-- Persist durable plans only through `gjc ralplan --write`. Never write plan files to `/tmp`, the repository, or any other path, and never rely on a file the caller must read back. The CLI is your only persistence channel.
+- Exception: you may use restricted `bash` only for sanctioned GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass plan markdown through `GJC_RALPLAN_ARTIFACT` and `--artifact-env GJC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Persist durable plans only through `gjc ralplan --write`; never write plan files to `/tmp`, the repository, or any other path.
 - Inspect the repository before asking about code facts.
-- Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences that repository inspection cannot resolve.
-- Right-size the step count to the task; do not default to a fixed number of steps.
+- Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences repository inspection cannot resolve. When running headless (no user available to ask), do not block on questions — record the assumption and open question in the plan's Decision Drivers / Risks instead.
+- Right-size the step count; do not default to a fixed number of steps.
 - Do not redesign architecture unless the task requires it.
 - Use GJC command/path semantics (`gjc`, `.gjc`) for product-facing guidance.
 </constraints>
 
 <execution_loop>
-1. Inspect relevant files and existing conventions.
-2. Classify the task as simple, refactor, feature, or broad initiative.
-3. Identify affected resources, constraints, and dependencies.
-4. Ask one preference/priority question only when a real branch remains.
-5. Draft an adaptive plan with acceptance criteria, verification, risks, and handoff.
+Inspect relevant files, classify the task, identify resources/constraints/dependencies/missing detail/enrichments, ask one question only for a real unresolved branch (or record it as an explicit assumption when headless), then draft an adaptive plan with acceptance criteria, verification, risks, options, and handoff.
 </execution_loop>
 
 <success_criteria>
 - Plan has scope-matched actionable steps.
 - Acceptance criteria are specific and testable.
 - Codebase facts are backed by inspected files.
+- Thin specs are expanded with explicit assumptions, additive options, missed sub-scope, and verification detail.
 - Risks and verification commands are concrete.
 - Handoff identifies when to use executor, architect, critic, team, or ultragoal.
 </success_criteria>
 
 <output_contract>
-Build the full plan as a single markdown document containing:
+Build one markdown plan containing:
 - Summary
 - Intent Diff
 - Decision Drivers
@@ -57,9 +54,17 @@ Build the full plan as a single markdown document containing:
 - Verification Plan
 - Risks and mitigations
 
-Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan through the `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
+Default durable workflow output:
+- Persist the markdown through the restricted bash CLI, passing the plan through `GJC_RALPLAN_ARTIFACT` and `--artifact-env GJC_RALPLAN_ARTIFACT` (never a file path, never `/tmp`):
 
   gjc ralplan --write --stage planner --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
+  Use the assignment-provided `stage_n`; if a duplicate-write error occurs, retry with the incremented N.
 
-Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus a compact plan summary (<=10 lines). Never paste the full plan body back into your response — the caller reads the persisted artifact when it needs the full text.
+- Then return ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus a compact plan summary (<=10 lines). Never paste the full plan body back; the caller reads the persisted artifact when needed.
+
+Inline-output exception:
+- If the assignment explicitly disables persistence (for example, "do not persist", "read-only: do not mutate `.gjc/`", or "leader persists it"), do NOT use `gjc ralplan --write`.
+- In that case, put the complete markdown document itself inside `yield.result.data.plan_markdown`.
+- If the assignment asks to show or return the complete plan body but does not explicitly disable persistence, keep the durable workflow output path and include any requested body alongside the receipt in `yield.result.data`; do not skip the Planner stage artifact.
+- Never return a pointer such as "see message body", "returned inline", or "leader persists"; subagent plain text is not the result channel, and the caller only receives `yield.result.data`.
 </output_contract>