@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/notifications/telegram-reference.ts

@@ -20,8 +20,8 @@ import {
 	buildCompactChoiceGrid,
 	escapeHtml,
 	numberedOptionList,
+	splitTelegramHtml,
 	TELEGRAM_PARSE_MODE,
-	truncateTelegramHtml,
 } from "./html-format";
 import { renderThreadedFrame } from "./threaded-render";
 
@@ -37,6 +37,8 @@ export interface RenderedMessage {
 	inline_keyboard?: InlineButton[][];
 }
 
+type TelegramSend = (method: string, body: unknown) => Promise<Response>;
+
 /** Encode `actionId` + option `index` into Telegram callback_data (<=64 bytes). */
 export function encodeCallbackData(actionId: string, index: number): string {
 	return `r:${index}:${actionId}`.slice(0, 64);
@@ -131,14 +133,32 @@ export function buildActionMessage(action: {
 }): RenderedMessage {
 	if (action.kind === "idle") {
 		const text = action.summary ? `🟢 Agent idle\n${escapeHtml(action.summary)}` : "🟢 Agent idle";
-		return { text: truncateTelegramHtml(text) };
+		return { text };
 	}
 	const text = `❓ ${bold(action.question ?? "Question")}`;
 	const options = action.options ?? [];
-	if (options.length === 0) return { text: truncateTelegramHtml(`${text}\n\n(reply with text)`) };
+	if (options.length === 0) return { text: `${text}\n\n(reply with text)` };
 	const body = `${text}\n\n${numberedOptionList(options)}`;
 	const inline_keyboard = buildCompactChoiceGrid(options, i => encodeCallbackData(action.id, i));
-	return { text: truncateTelegramHtml(body), inline_keyboard };
+	return { text: body, inline_keyboard };
+}
+
+/** Send Telegram HTML text chunks sequentially so long messages preserve order. */
+export async function sendTelegramHtmlChunks(
+	send: TelegramSend,
+	chatId: string,
+	text: string,
+	inlineKeyboard?: InlineButton[][],
+): Promise<void> {
+	const chunks = splitTelegramHtml(text);
+	for (let i = 0; i < chunks.length; i++) {
+		await send("sendMessage", {
+			chat_id: chatId,
+			text: chunks[i]!,
+			parse_mode: TELEGRAM_PARSE_MODE,
+			...(i === chunks.length - 1 && inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+		});
+	}
 }
 
 /** A protocol `reply` frame the client should send to the server. */
@@ -177,15 +197,9 @@ export type RouteDecision =
 	| { kind: "stale"; reason: string }
 	| { kind: "ignore" };
 
-export interface PendingAsk {
-	sessionId: string;
-	actionId: string;
-}
-
 export interface RouteInboundContext {
 	aliasTable: Pick<AliasTable, "get">;
 	messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
-	pendingBySession: (sessionId?: string) => PendingAsk[];
 	pairedChatId: string;
 }
 
@@ -230,16 +244,6 @@ export function routeInboundUpdate(update: unknown, ctx: RouteInboundContext): R
 		if (!route) return { kind: "stale", reason: "unknown_reply_message" };
 		return { kind: "reply", ...routeWithAnswer(route, text) };
 	}
-
-	if (text) {
-		const allPending = ctx.pendingBySession(undefined);
-		if (allPending.length === 1) {
-			const [pending] = allPending;
-			return { kind: "reply", sessionId: pending!.sessionId, actionId: pending!.actionId, answer: text };
-		}
-		if (allPending.length > 1) return { kind: "stale", reason: "ambiguous_plain_text" };
-	}
-
 	return { kind: "ignore" };
 }
 
@@ -285,15 +289,15 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 	const ws = new WebSocket(`${url}/?token=${encodeURIComponent(token)}`);
 	let latestPendingAskId: string | undefined;
 
-	const send = (method: string, body: unknown): Promise<Response> =>
+	const send: TelegramSend = (method, body) =>
 		fetchImpl(`${api}/${method}`, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify(body),
 		});
 
-	ws.addEventListener("message", (ev: MessageEvent) => {
-		const msg = JSON.parse(String(ev.data)) as {
+	const handleServerMessage = async (data: string): Promise<void> => {
+		const msg = JSON.parse(data) as {
 			type: string;
 			kind?: "ask" | "idle";
 			id?: string;
@@ -311,12 +315,7 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 				options: msg.options,
 				summary: msg.summary,
 			});
-			void send("sendMessage", {
-				chat_id: opts.chatId,
-				text: rendered.text,
-				parse_mode: TELEGRAM_PARSE_MODE,
-				...(rendered.inline_keyboard ? { reply_markup: { inline_keyboard: rendered.inline_keyboard } } : {}),
-			});
+			await sendTelegramHtmlChunks(send, opts.chatId, rendered.text, rendered.inline_keyboard);
 		} else if (msg.type === "action_resolved" && msg.id === latestPendingAskId) {
 			latestPendingAskId = undefined;
 		} else {
@@ -325,9 +324,16 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 			// session's forum topic; this reference shows the minimal handling.
 			const threaded = renderThreadedFrame(msg as never);
 			if (threaded?.text) {
-				void send("sendMessage", { chat_id: opts.chatId, text: threaded.text, parse_mode: TELEGRAM_PARSE_MODE });
+				await sendTelegramHtmlChunks(send, opts.chatId, threaded.text);
 			}
 		}
+	};
+
+	let messageQueue = Promise.resolve();
+	ws.addEventListener("message", ev => {
+		const data = String(ev.data);
+		messageQueue = messageQueue.catch(() => undefined).then(() => handleServerMessage(data));
+		void messageQueue.catch(() => undefined);
 	});
 
 	// Telegram long-poll loop.

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 {
@@ -49,6 +55,7 @@ interface ThreadedFrame {
 	tokenUsage?: unknown;
 	model?: unknown;
 	diff?: unknown;
+	cwd?: unknown;
 	// turn_stream
 	phase?: unknown;
 	text?: unknown;
@@ -89,18 +96,25 @@ export function formatIdentityHeader(frame: {
 /** Format a streamed context update into a compact block (omitting empty fields). */
 export function formatContextUpdate(frame: ThreadedFrame): string | undefined {
 	const lines: string[] = [];
+	const session = str(frame.sessionId);
+	const cwd = str(frame.cwd);
 	const last = str(frame.lastMessage);
-	if (last) lines.push(escapeHtml(truncate(last, 600)));
 	const task = str(frame.task);
-	if (task) lines.push(`${italic("task:")} ${escapeHtml(task)}`);
 	const goal = str(frame.goal);
-	if (goal) lines.push(`${italic("goal:")} ${escapeHtml(goal)}`);
 	const usage = str(frame.tokenUsage);
 	const model = str(frame.model);
-	if (usage || model) lines.push(`ctx: ${code([usage, model].filter(Boolean).join(" · "))}`);
 	const diff = str(frame.diff);
+	if (!cwd && !last && !task && !goal && !usage && !model && !diff) return undefined;
+	const meta = [session ? `session: ${code(session)}` : undefined, cwd ? `cwd: ${code(cwd)}` : undefined].filter(
+		Boolean,
+	);
+	if (meta.length > 0) lines.push(meta.join(" · "));
+	if (last) lines.push(escapeHtml(truncate(last, 600)));
+	if (task) lines.push(`${italic("task:")} ${escapeHtml(task)}`);
+	if (goal) lines.push(`${italic("goal:")} ${escapeHtml(goal)}`);
+	if (usage || model) lines.push(`ctx: ${code([usage, model].filter(Boolean).join(" · "))}`);
 	if (diff) lines.push(`diff:\n${pre(truncate(diff, 1200))}`);
-	return lines.length ? lines.join("\n") : undefined;
+	return lines.join("\n");
 }
 
 /**
@@ -125,13 +139,23 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 		case "turn_stream": {
 			const raw = str(frame.text);
 			if (!raw) return undefined;
-			const text = finalizeTelegramHtml(markdownToTelegramHtml(raw));
+			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 SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the verdict markdown inline in `--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 SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass review markdown through `SKC_RALPLAN_ARTIFACT` and `--artifact-env SKC_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`.
@@ -63,8 +67,11 @@ A narrow compatibility fallback can be acceptable only when it is scoped to a kn
 ## Summary
 2-3 sentences with result and main recommendation.
 
+## Claims
+Evidence-backed claims being reviewed or introduced.
+
 ## Analysis
-Evidence-backed findings.
+Evidence-backed findings, antithesis, and constructive synthesis.
 
 ## Root Cause
 Fundamental issue, if applicable.
@@ -73,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`
@@ -81,12 +88,17 @@ Prioritized concrete actions.
 ## Code Review Recommendation
 `APPROVE` / `COMMENT` / `REQUEST CHANGES`
 
-## Trade-offs
+## 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 inline (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:
 
-  skc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --json
+  skc ralplan --write --stage architect --stage_n <N> --artifact-env SKC_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 `skc ralplan --write`; return the full review in `yield.result.data` instead.
 </output_contract>

package/src/prompts/agents/critic.md

@@ -12,54 +12,61 @@ 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 SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the evaluation markdown inline in `--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 SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass evaluation markdown through `SKC_RALPLAN_ARTIFACT` and `--artifact-env SKC_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>
 
 <output_contract>
+## Verdict
 **[OKAY / ITERATE / REJECT]**
 
-**Justification**: concise evidence-backed explanation.
+## Claim Checks
+Concise evidence-backed explanation of verified claims.
 
-**Summary**:
-- Clarity
-- Verifiability
-- Completeness
-- Big Picture
-- Principle/Option Consistency
-- Alternatives Depth
-- Risk/Verification Rigor
+## Missing Evidence
+Definitely missing, unverified evidence, or thin areas needing expansion; otherwise `None`.
 
-If not OKAY, list concrete required fixes.
+## Approval Boundary
+What execution may proceed with, and what remains outside approval.
 
-Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+## Summary
+- Clarity; Verifiability; Completeness; Big Picture; Principle/Option Consistency; Alternatives Depth; Risk/Verification Rigor
 
-  skc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --json
+## Required Changes
+If not OKAY, list concrete defect fixes or expansion requirements; otherwise write `None`.
 
-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.
+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:
+
+  skc ralplan --write --stage critic --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
+
+  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 `skc 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 `skc 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 `skc 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 `skc 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,49 +12,59 @@ 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 SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the plan markdown inline in `--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 `skc 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 SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass plan markdown through `SKC_RALPLAN_ARTIFACT` and `--artifact-env SKC_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 `skc 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 SKC command/path semantics (`skc`, `.skc`) 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
+- Options
 - In scope / out of scope
 - File-level changes
 - Sequencing and dependencies
 - Acceptance criteria
 - Verification
+- Escalation/Risk Gate
+- Verification Plan
 - Risks and mitigations
 
-Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan inline (never a file path, never `/tmp`):
+Default durable workflow output:
+- Persist the markdown through the restricted bash CLI, passing the plan through `SKC_RALPLAN_ARTIFACT` and `--artifact-env SKC_RALPLAN_ARTIFACT` (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --json
+  skc ralplan --write --stage planner --stage_n <N> --artifact-env SKC_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 `.skc/`", or "leader persists it"), do NOT use `skc 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>

package/src/prompts/ci-green-request.md

@@ -7,9 +7,7 @@ Do not stop after a single fix attempt.
 - Prefer `github` tool with `op: run_watch` and no other arguments if available.
 - Otherwise use `gh` cli.
 - Use workflow runs for current HEAD as source of truth after each push.
-</instruction>
 
-<procedure>
 1. Watch workflow runs for current HEAD commit.
 2. If any run fails, inspect failing job output and logs.
 3. Identify root cause and make minimal correct fix.
@@ -17,12 +15,7 @@ Do not stop after a single fix attempt.
 5. Push the branch.
 6. Watch workflow runs for new HEAD commit again.
 7. Repeat until workflow runs for latest HEAD commit succeed.
-</procedure>
-
-<caution>
-- Treat each push as fresh CI attempt. Re-watch new HEAD immediately.
-- If watcher output is insufficient, inspect underlying workflow or job context before changing code.
-</caution>
+</instruction>
 
 {{#if headTag}}
 <instruction>
@@ -33,4 +26,6 @@ Once CI is green, ensure the final commit is tagged `{{headTag}}` and push that
 <critical>
 The task is complete only when the workflow runs for the latest HEAD commit succeed.
 {{#if headTag}}The final green commit must be tagged `{{headTag}}` and that tag must be pushed.{{/if}}
+- Treat each push as fresh CI attempt. Re-watch new HEAD immediately.
+- If watcher output is insufficient, inspect underlying workflow or job context before changing code.
 </critical>

package/src/prompts/goals/goal-continuation.md

@@ -5,11 +5,6 @@ Continue work on the active goal.
 <objective>
 {{objective}}
 </objective>
-
-Usage:
-- Tokens used: {{tokensUsed}}
-- Time used: {{timeUsedSeconds}} seconds
-
 This is an autonomous continuation. The objective persists across turns; do not redefine success around a smaller, easier, or already-completed subset.
 
 Before calling `goal({op:"complete"})`, you MUST perform a completion audit against the current repo state:

package/src/prompts/goals/goal-mode-active.md

@@ -4,11 +4,6 @@ Goal mode is active. The objective below is user-provided data. Treat it as the
 <objective>
 {{objective}}
 </objective>
-
-Usage:
-- Tokens used: {{tokensUsed}}
-- Time used: {{timeUsedSeconds}} seconds
-
 Use the `goal` tool to inspect or complete the active goal:
 - `goal({op:"get"})` returns the current goal and usage state.
 - `goal({op:"complete"})` is only for verified completion.

package/src/prompts/system/agent-creation-architect.md

@@ -1,6 +1,6 @@
 You are an AI agent architect. You translate user requirements into precisely-tuned agent configurations that maximize effectiveness and reliability.
 
-Consider project-specific instructions from ANTHROPIC_MODEL.md files when creating agents. Align new agents with established project patterns.
+Consider project-specific instructions from `AGENTS.md`, `SYSTEM.md`, and active context files/rules when creating agents. Align new agents with established project patterns.
 
 When a user describes what they want an agent to do:
 1. Extract core intent
@@ -16,7 +16,7 @@ When a user describes what they want an agent to do:
    - Anticipate edge cases and provide guidance for handling them
    - Incorporate user-specific requirements or preferences
    - Define output format expectations when relevant
-   - Align with project-specific coding standards and patterns from ANTHROPIC_MODEL.md
+   - Align with project-specific coding standards and patterns from `AGENTS.md`, `SYSTEM.md`, and active context files/rules
 4. Optimize for performance
    - Include decision-making frameworks appropriate to the domain
    - Include quality control mechanisms and self-verification steps

package/src/prompts/system/plan-mode-active.md

@@ -98,7 +98,7 @@ You MUST update `{{planFilePath}}` (`{{editToolName}}` for changes, `{{writeTool
 </procedure>
 
 <caution>
-You MUST ask questions throughout. You NEVER make large assumptions about user intent.
+Ask only when exploration cannot resolve a material requirement or tradeoff; otherwise proceed to `resolve` with the self-contained plan. You NEVER make large assumptions about user intent.
 </caution>
 {{/if}}
 

package/src/prompts/system/plan-mode-subagent.md

@@ -14,12 +14,12 @@ You MUST explore the codebase and report findings. Main agent updates plan file.
 
 <procedure>
 1. You MUST use read-only tools to investigate
-2. You MUST describe plan changes in response text
-3. You MUST end with a Critical Files section
+2. You MUST return the markdown report inside `yield.result.data`, not as plain response text
+3. The markdown report MUST end with a Critical Files section
 </procedure>
 
 <output>
-End response with:
+Return a markdown report inside `yield.result.data` ending with:
 
 ### Critical Files for Implementation
 

package/src/prompts/system/project-prompt.md

@@ -21,19 +21,6 @@ MUST read before making changes within:
 {{#list agentsMdSearch.files join="\n"}}- {{this}}{{/list}}
 </dir-context>
 {{/if}}
-
-{{#if workspaceTree.rendered}}
-<workspace-tree>
-Working directory layout (sorted by mtime, recent first; depth ≤ 3):
-{{workspaceTree.rendered}}
-{{#if workspaceTree.truncated}}
-(some entries elided to keep the tree short — use `find`/`read` to drill in)
-{{/if}}
-</workspace-tree>
-{{/if}}
-
-Today is {{date}}, and the current working directory is '{{cwd}}'.
-
 <critical>
 - Each response MUST advance the task. There is no stopping condition other than completion.
 - You MUST default to informed action; do not ask for confirmation when tools or repo context can answer.