@bastani/atomic 0.9.14-alpha.1 → 0.9.14-alpha.2

package/dist/builtin/workflows/builtin/open-claude-design-live-protocol.ts

@@ -0,0 +1,305 @@
+/**
+ * open-claude-design ⇄ impeccable live protocol.
+ *
+ * In a chat session the agent owns the live poll loop, and "the review is over"
+ * needs no ceremony because the user simply keeps talking. A workflow stage
+ * boundary is a commit point, and the live contract's `"timeout" -> LOOP` is an
+ * instruction to a model rather than a constraint: a stage that concludes on a
+ * poll timeout would end a review the user never finished.
+ *
+ * So the workflow drives the protocol instead. Polling and replying are durable
+ * `ctx.tool` nodes; the model is invoked only for the events that need it
+ * (`generate`, `steer`, `manual_edit_apply`, and mount failures). Termination
+ * stops being a judgment and becomes the helper's own `exit` event.
+ *
+ * `timeout` is absorbed here rather than surfaced, so an idle hour costs no
+ * graph nodes. Every poll/reply invocation must, however, exit successfully;
+ * helper failures are surfaced instead of being mistaken for another timeout.
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/** JSON values emitted by the live helper. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+
+/** Events the live helper delivers. Anything unknown is treated as ignorable. */
+export type LiveEventType =
+	| "generate"
+	| "steer"
+	| "accept"
+	| "discard"
+	| "prefetch"
+	| "manual_edit_apply"
+	| "variant_mounted"
+	| "variant_mount_failed"
+	| "timeout"
+	| "exit";
+
+export type LiveEvent = {
+	readonly type: LiveEventType | string;
+	readonly id?: string;
+	readonly variant?: number;
+	readonly variantId?: string;
+	readonly url?: string;
+	readonly pageUrl?: string;
+	readonly error?: string;
+	readonly file?: string;
+	readonly sourceFile?: string;
+	readonly message?: string;
+	readonly data?: JsonValue;
+	readonly screenshot?: string;
+	readonly raw: string;
+	/** Preserve additional upstream event fields without narrowing their JSON shape. */
+	readonly [key: string]: JsonValue | undefined;
+};
+
+/** Events the model must handle before the loop may reply and poll again. */
+const MODEL_EVENTS = new Set<string>(["generate", "steer", "manual_edit_apply", "variant_mount_failed"]);
+
+export function needsModel(event: LiveEvent): boolean {
+	return MODEL_EVENTS.has(event.type);
+}
+
+/** Reply status the helper expects for each model-handled event. */
+export function replyTokenFor(event: LiveEvent): string {
+	if (event.type === "steer") return "steer_done";
+	return "done";
+}
+
+const LEGACY_REPLY_STATUSES = new Set(["done", "error", "complete", "discard", "discarded"]);
+
+function isJsonObject(value: JsonValue): value is { readonly [key: string]: JsonValue } {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Last JSON object printed by a live script, which is the event payload. */
+export function parseLiveEvent(stdout: string): LiveEvent {
+	const lines = stdout.split(/\r?\n/).filter((line) => line.trim().startsWith("{"));
+	for (const line of [...lines].reverse()) {
+		try {
+			const parsed = JSON.parse(line) as JsonValue;
+			if (!isJsonObject(parsed) || typeof parsed.type !== "string") continue;
+			// Keep the complete JSON event, not only the fields known by the old
+			// protocol. 4.1.1 adds mount diagnostics and structured reply data.
+			return { ...parsed, type: parsed.type, raw: line } as LiveEvent;
+		} catch {
+			/* not the event line */
+		}
+	}
+	// An unreadable poll is not an ending. Treat it as a timeout so the caller
+	// polls again rather than concluding a review nobody finished.
+	return { type: "timeout", raw: stdout };
+}
+
+export type LivePollDeps = {
+	readonly run?: (scriptPath: string, args: readonly string[], cwd: string, signal?: AbortSignal) => Promise<ScriptResult>;
+};
+
+export type LiveReplyInput = {
+	readonly workflowCwd: string;
+	readonly event: LiveEvent;
+	readonly status?: string;
+	/** Source/manifest path accepted by generate and mount-failure replies. */
+	readonly file?: string;
+	/** The helper's positional message argument (there is no --message flag). */
+	readonly message?: string;
+	/** Structured result accepted by manual_edit_apply replies. */
+	readonly data?: JsonValue;
+	readonly signal?: AbortSignal;
+	readonly deps?: LivePollDeps;
+};
+
+function assertSuccessfulScript(result: ScriptResult, operation: string): ScriptResult {
+	if (result.code !== 0) {
+		const details = result.stderr.length > 0 ? `: ${result.stderr}` : "";
+		throw new Error(`${operation} failed with exit code ${result.code}${details}`);
+	}
+	return result;
+}
+
+/**
+ * Poll until the helper delivers an event that matters. `timeout` events and
+ * unreadable output loop internally, so callers only ever see substantive
+ * events or `exit`.
+ */
+export async function pollLiveEvent(input: {
+	readonly workflowCwd: string;
+	readonly signal?: AbortSignal;
+	readonly deps?: LivePollDeps;
+}): Promise<LiveEvent> {
+	const script = liveScriptPath("live-poll.mjs");
+	const run = input.deps?.run ?? runNodeScript;
+	for (;;) {
+		if (input.signal?.aborted === true) return { type: "exit", raw: "aborted" };
+		const result = assertSuccessfulScript(await run(script, [], input.workflowCwd, input.signal), "live poll");
+		const event = parseLiveEvent(result.stdout);
+		if (event.type !== "timeout") return event;
+	}
+}
+
+/** Acknowledge a model-handled event so the helper unblocks the overlay. */
+export async function replyLiveEvent(input: LiveReplyInput): Promise<ScriptResult> {
+	const id = input.event.id;
+	if (typeof id !== "string" || id.length === 0 || id.startsWith("--")) {
+		throw new Error(`Cannot reply to ${input.event.type}: live event id is missing`);
+	}
+	if (LEGACY_REPLY_STATUSES.has(id)) {
+		throw new Error(`Cannot reply to live event ${id}: expected an event id before the reply status`);
+	}
+	const status = input.status ?? replyTokenFor(input.event);
+	if (status.length === 0 || status.startsWith("--")) {
+		throw new Error(`Cannot reply to live event ${id}: reply status is missing`);
+	}
+	const args = ["--reply", id, status];
+	const file = input.file ?? input.event.file;
+	const message = input.message ?? input.event.message;
+	const data = input.data ?? input.event.data;
+	if (file !== undefined) args.push("--file", file);
+	if (data !== undefined) args.push("--data", JSON.stringify(data));
+	if (message !== undefined) args.push(message);
+	const script = liveScriptPath("live-poll.mjs");
+	const run = input.deps?.run ?? runNodeScript;
+	return assertSuccessfulScript(await run(script, args, input.workflowCwd, input.signal), "live reply");
+}
+
+/**
+ * Absolute path to one of the impeccable live scripts.
+ *
+ * Always the copy that ships inside this package — `packages/workflows/skills`
+ * in the repository, `dist/builtin/workflows/skills` once bundled — which sits
+ * one level up from this module in both layouts, so `import.meta.url` finds it
+ * without the host naming a path.
+ *
+ * A project-vendored copy is deliberately NOT consulted. The workflow drives
+ * this protocol directly: it depends on `live-poll.mjs`'s CLI surface, its
+ * `--reply` tokens, and its JSON event vocabulary. The bundled scripts ship and
+ * are tested with this code, so they cannot drift from it; a forked copy in a
+ * project could, and would break the loop in ways no test here would catch.
+ */
+export function liveScriptPath(script: string): string {
+	return fileURLToPath(new URL(`../skills/impeccable/scripts/${script}`, import.meta.url));
+}
+
+export type ScriptResult = { readonly code: number; readonly stdout: string; readonly stderr: string };
+
+function runNodeScript(
+	scriptPath: string,
+	args: readonly string[],
+	cwd: string,
+	signal?: AbortSignal,
+): Promise<ScriptResult> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, [scriptPath, ...args], {
+			cwd,
+			env: { ...process.env, GH_PAGER: "cat" },
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		const onAbort = () => child.kill("SIGTERM");
+		signal?.addEventListener("abort", onAbort, { once: true });
+		child.stdout.on("data", (chunk: Buffer) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", (error) => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", onAbort);
+			resolve({ code: code ?? -1, stdout: stdout.trim(), stderr: stderr.trim() });
+		});
+	});
+}
+/** Prompt for the stage that handles one live event. */
+export function buildLiveEventPrompt(input: {
+	readonly event: LiveEvent;
+	readonly previewPath: string;
+}): string {
+	const shared = [
+		`<live_event>\n${input.event.raw}\n</live_event>`,
+		`<preview_path>${input.previewPath}</preview_path>`,
+		"<role>You are an opinionated staff design engineer inside an impeccable `live` session. The workflow owns the poll loop; handle exactly this one event and stop.</role>",
+	];
+	if (input.event.type === "generate") {
+		return [
+			...shared,
+			[
+				"<instructions>",
+				"Follow the live contract for a `generate` event:",
+				"1. Reuse `event.scaffold` when present and read the annotation screenshot when one is attached.",
+				"2. Extract the page identity FIRST, then produce three DISTINCT on-brand variants and publish them for the user to preview.",
+				"3. Apply the craft floors by construction as you write. Do not screenshot, re-render, or QA between generate and accept; the overlay preview is the verification channel.",
+				"Do not poll, do not reply, and do not exit the session: the workflow does that. Stop as soon as the variants are published.",
+				"</instructions>",
+			].join("\n"),
+		].join("\n\n");
+	}
+	if (input.event.type === "steer") {
+		return [
+			...shared,
+			[
+				"<instructions>",
+				"Follow the live contract for a `steer` event: read the message and pageUrl, then do the work — page edits, navigation help, or a short answer.",
+				"Do not poll, do not reply, and do not exit the session: the workflow does that. Stop when the steer is handled.",
+				"</instructions>",
+			].join("\n"),
+		].join("\n\n");
+	}
+	if (input.event.type === "variant_mount_failed") {
+		return [
+			...shared,
+			[
+				"<instructions>",
+				"The browser could not mount the published variant. Inspect the reported variant source/module, fix the compile or runtime failure, and stop after the repair.",
+				"Do not poll, do not reply, and do not exit the session: the workflow does that.",
+			].join("\n"),
+		].join("\n\n");
+	}
+	return [
+		...shared,
+		[
+			"<instructions>",
+			"Apply this manual edit event per the live contract, then stop. Do not poll, reply, or exit; the workflow does that.",
+			"</instructions>",
+		].join("\n"),
+	].join("\n\n");
+}
+
+/** Prompt for the stage that boots the session and hands the loop back to the workflow. */
+export function buildLiveSessionStartPrompt(input: {
+	readonly previewPath: string;
+	readonly previewFileUrl: string;
+	readonly browserBootstrapRules: string;
+	readonly round: number;
+}): string {
+	return [
+		`<preview_path>${input.previewPath}</preview_path>`,
+		`<preview_file_url>${input.previewFileUrl}</preview_file_url>`,
+		`<browser_use_guidelines>${input.browserBootstrapRules}</browser_use_guidelines>`,
+		"<role>You are an opinionated staff design engineer opening an impeccable `live` review session.</role>",
+		[
+			"<objective>",
+			`Start review session ${input.round}: boot live against the static preview and open it in the user's browser. Then STOP.`,
+			"</objective>",
+		].join("\n"),
+		[
+			"<instructions>",
+			"1. Drive `/skill:impeccable live` against the static preview: run `live.mjs` with `--target` pointed at the preview file, or the equivalent `.impeccable/live/config.json` entry, and open the URL that serves it.",
+			"2. Print the live `http://` review URL in plain text, plus the preview file URL as the manual fallback, so anyone attaching to this run can find the review.",
+			"3. Directly under the URL, print how the user ends the review, in plain text: click exit in the Impeccable overlay, close the browser tab, or say `exit live`. State that the review waits indefinitely until they do, and that ending it exports the design as it then stands, with no further round.",
+			"4. Do NOT start a poll loop. The workflow owns polling and will call you back for each event that needs you. Ending your turn does not end the review.",
+			"</instructions>",
+		].join("\n"),
+		"<output_format>Under 150 words: the live review URL, the manual fallback path, how to end the review, and whether the browser opened.</output_format>",
+	].join("\n\n");
+}

package/dist/builtin/workflows/builtin/open-claude-design-phases.ts

@@ -6,17 +6,16 @@ import {
   taggedPrompt,
 } from "./open-claude-design-utils.js";
 import {
-  assertUserAnnotationsThreaded,
-  hasMeaningfulFeedback,
-  persistPreviewFeedback,
-  toPreviewFeedback,
-  userAnnotationsBlock,
-  type PreviewFeedback,
-} from "./open-claude-design-feedback.js";
+  buildLiveEventPrompt,
+  buildLiveSessionStartPrompt,
+  needsModel,
+  pollLiveEvent,
+  replyLiveEvent,
+  replyTokenFor,
+} from "./open-claude-design-live-protocol.js";
 import {
   LIVE_REVIEW_GATE_OPTIONS,
   buildLiveReviewGateMessage,
-  buildLivePreviewDisplayPrompt,
   isUiUnavailableRejection,
   type LiveReviewGateUi,
 } from "./open-claude-design-setup.js";
@@ -27,6 +26,8 @@ const GROUNDED_REPORTING =
 type DesignContext = {
   task(name: string, options: object): Promise<WorkflowTaskResult>;
   parallel(steps: readonly object[], options: { readonly task: string }): Promise<WorkflowTaskResult[]>;
+  /** Durable tool node; the live review loop is built from these. */
+  tool<T>(name: string, args: object, fn: (handle: { readonly signal: AbortSignal }) => Promise<T>): Promise<T>;
 };
 
 type ModelConfig = Record<string, object | string | readonly string[]>;
@@ -48,10 +49,8 @@ type RefineOptions = {
   readonly designContext: DesignContext;
   readonly prompt: string;
   readonly outputType: string;
-  readonly maxRefinements: number;
   readonly previewPath: string;
   readonly previewFileUrl: string;
-  readonly artifactDir: string;
   readonly browserBootstrapRules: string;
   /** Path to the persisted design-context.md artifact (issue #2121). */
   readonly designContextFile: string;
@@ -63,117 +62,116 @@ type RefineOptions = {
   readonly ui: LiveReviewGateUi;
 };
 
-export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{ readonly latestDesign: string; readonly approvedForExport: boolean; readonly refinementCount: number; }> {
-  const { designContext, prompt, outputType, maxRefinements, previewPath, previewFileUrl, artifactDir, browserBootstrapRules, designContextFile, referencesFile, designModelConfig, workflowCwd } = options;
+/**
+ * Generate a design, then review it in one live session.
+ *
+ * The live session is itself unbounded: the user picks elements, accepts
+ * on-brand variants written into `preview.html` in place, and steers, until
+ * they leave. The preview is exported as it stands when the session ends.
+ */
+export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{ readonly latestDesign: string }> {
+  const { designContext, prompt, outputType, previewPath, previewFileUrl, browserBootstrapRules, designContextFile, referencesFile, designModelConfig, workflowCwd } = options;
   const importContext = options.importContext ?? "";
-  let latestDesign = "";
-  let latestGenerateSessionFile: string | undefined;
-  let latestUserFeedbackSessionFile: string | undefined;
-  let pendingFeedback: PreviewFeedback | undefined;
-  let approvedForExport = false;
-  let refinementCount = 0;
 
-  for (let iteration = 1; iteration <= maxRefinements; iteration += 1) {
-    const generateStageName = `generate-${iteration}`;
-    const generatePrompt = pendingFeedback === undefined
-      ? buildInitialGeneratePrompt({
-          prompt,
-          outputType,
-          previewPath,
-          designContextFile,
-          referencesFile,
-          importContext,
-        })
-      : buildGenerateRevisionPrompt({
-          prompt,
-          outputType,
-          previewPath,
-          designContextFile,
-          referencesFile,
-          latestDesign,
-          importContext,
-          feedback: pendingFeedback,
-        });
-    if (pendingFeedback !== undefined) {
-      assertUserAnnotationsThreaded(generatePrompt, [pendingFeedback], generateStageName);
-    }
+  // Large research context travels by artifact file (`reads` + explicit read
+  // instructions in the prompt), not as an inline payload (issue #2121).
+  const generated = await designContext.task("generate-1", {
+    prompt: buildInitialGeneratePrompt({
+      prompt,
+      outputType,
+      previewPath,
+      designContextFile,
+      referencesFile,
+      importContext,
+    }),
+    reads: [designContextFile, referencesFile],
+    ...designModelConfig,
+  });
 
-    // Large research context travels by artifact file (`reads` + explicit
-    // read instructions in the prompt), not as an inline `previous` payload,
-    // so a single oversized research result cannot become a single oversized
-    // prompt message (issue #2121). Only the revision loop threads the small,
-    // word-capped prior design summary inline.
-    const generated = await designContext.task(generateStageName, {
-      prompt: generatePrompt,
-      reads: [designContextFile, referencesFile],
-      ...(pendingFeedback === undefined
-        ? {}
-        : { previous: { name: "current-design", text: latestDesign } }),
-      ...designModelConfig,
-      ...forkContinuationOptions(latestGenerateSessionFile),
+  // The browser review waits on a long-poll rather than an awaiting-input
+  // stage, so raise the run-level prompt before opening the session. Only the
+  // executor's unavailable-UI rejection degrades to running the review;
+  // lifecycle failures must propagate and stop the workflow.
+  const gateChoice = await options.ui
+    .select(
+      buildLiveReviewGateMessage({ round: 1, previewPath, previewFileUrl }),
+      LIVE_REVIEW_GATE_OPTIONS,
+    )
+    .catch((error: unknown) => {
+      if (isUiUnavailableRejection(error)) return LIVE_REVIEW_GATE_OPTIONS[0];
+      throw error;
     });
-    latestDesign = generated.text;
-    latestGenerateSessionFile = generated.sessionFile ?? latestGenerateSessionFile;
-    refinementCount = iteration;
+  if (gateChoice === LIVE_REVIEW_GATE_OPTIONS[0]) {
+    await runLiveReviewSession({
+      designContext,
+      round: 1,
+      reviewStageName: "user-feedback-1",
+      previewPath,
+      previewFileUrl,
+      browserBootstrapRules,
+      designModelConfig,
+      workflowCwd,
+    });
+  }
 
-    // Deterministic live-review gate (issue #2060): the user-feedback stage
-    // waits on a browser long-poll that never sets `awaiting_input`, so raise
-    // a run-level `ctx.ui` prompt first. It fires the needs-attention badge,
-    // names the preview URL, and syncs the review to the user's presence.
-    // Only the executor's unavailable-UI rejection (headless / no adapter)
-    // degrades to running the review; lifecycle failures such as interruption
-    // or a failed durable checkpoint must propagate and stop the workflow.
-    const gateChoice = await options.ui
-      .select(
-        buildLiveReviewGateMessage({ iteration, maxRefinements, previewPath, previewFileUrl }),
-        LIVE_REVIEW_GATE_OPTIONS,
-      )
-      .catch((error: unknown) => {
-        if (isUiUnavailableRejection(error)) return LIVE_REVIEW_GATE_OPTIONS[0];
-        throw error;
-      });
-    if (gateChoice === LIVE_REVIEW_GATE_OPTIONS[1]) {
-      approvedForExport = true;
-      break;
-    }
+  return { latestDesign: generated.text };
+}
 
-    // A rejected feedback stage propagates and fails the run (issue #2123;
-    // the #1499 catch-then-approve path). Browser/tooling trouble never
-    // rejects: playwright-cli is auto-installed up front, the runner exits
-    // early when the browser is unavailable, and the stage prompt requires a
-    // degraded non-empty report instead of failing. What rejects here is
-    // model/infra failure — provider errors, fallback exhaustion, broken
-    // session forks — and that must never be laundered into approval. Only a
-    // resolved result with no meaningful notes means the user approved.
-    const userFeedbackResult = await designContext.task(`user-feedback-${iteration}`, {
-      prompt: buildLivePreviewDisplayPrompt({
-        previewPath,
-        previewFileUrl,
-        browserBootstrapRules,
-        iteration,
-        maxRefinements,
-      }),
-      ...designModelConfig,
-      ...forkContinuationOptions(latestUserFeedbackSessionFile),
-    });
+type LiveReviewSessionOptions = {
+  readonly designContext: DesignContext;
+  readonly round: number;
+  readonly reviewStageName: string;
+  readonly previewPath: string;
+  readonly previewFileUrl: string;
+  readonly browserBootstrapRules: string;
+  readonly designModelConfig: ModelConfig;
+  readonly workflowCwd: string;
+};
 
-    latestUserFeedbackSessionFile =
-      userFeedbackResult.sessionFile ?? latestUserFeedbackSessionFile;
-    const feedback = toPreviewFeedback({
-      iteration,
-      stageName: `user-feedback-${iteration}`,
-      result: userFeedbackResult,
-    });
-    persistPreviewFeedback({ artifactDir, workflowCwd, feedback });
+/**
+ * Run one live review session until the helper emits its terminal `exit` event.
+ *
+ * The workflow owns the poll loop: `ctx.tool` polls and replies, and the model
+ * is called back only for the events that need it. Termination is the helper's
+ * `exit` event rather than a model's judgment that a review looked finished,
+ * which is what prevents a poll timeout from ending an active review.
+ */
+async function runLiveReviewSession(options: LiveReviewSessionOptions): Promise<void> {
+  const { designContext, round, reviewStageName, previewPath, previewFileUrl, browserBootstrapRules, designModelConfig, workflowCwd } = options;
+  let sessionFile: string | undefined;
 
-    if (!hasMeaningfulFeedback(feedback)) {
-      approvedForExport = true;
-      break;
-    }
-    pendingFeedback = feedback;
-  }
+  const start = await designContext.task(`${reviewStageName}-start`, {
+    prompt: buildLiveSessionStartPrompt({ previewPath, previewFileUrl, browserBootstrapRules, round }),
+    ...designModelConfig,
+  });
+  sessionFile = start.sessionFile;
 
-  return { latestDesign, approvedForExport, refinementCount };
+  for (let index = 1; ; index += 1) {
+		// `timeout` is absorbed inside the poll, so an idle hour costs no nodes and
+		// never looks like an ending.
+		const event = await designContext.tool(`live-poll-${round}-${index}`, { round, index }, async ({ signal }) =>
+			pollLiveEvent({ workflowCwd, signal }),
+		);
+		if (event.type === "exit") break;
+		// `variant_mounted` is journal-only. All other non-model events are
+		// acknowledged by the helper itself and do not mint a model stage.
+		if (!needsModel(event)) continue;
+		if (event.id === undefined || event.id.length === 0) {
+			throw new Error(`Live ${event.type} event is missing its id`);
+		}
+		const response = await designContext.task(`live-${event.type}-${round}-${index}`, {
+			prompt: buildLiveEventPrompt({ event, previewPath }),
+			...designModelConfig,
+			...forkContinuationOptions(sessionFile),
+		});
+		sessionFile = response.sessionFile ?? sessionFile;
+		const status = replyTokenFor(event);
+		await designContext.tool(
+			`live-reply-${round}-${index}`,
+			{ round, index, eventId: event.id, status },
+			async ({ signal }) => replyLiveEvent({ workflowCwd, event, status, signal }),
+		);
+  }
 }
 
 function buildInitialGeneratePrompt(args: {
@@ -231,60 +229,6 @@ function buildInitialGeneratePrompt(args: {
   ]);
 }
 
-function buildGenerateRevisionPrompt(args: {
-  readonly prompt: string;
-  readonly outputType: string;
-  readonly previewPath: string;
-  readonly designContextFile: string;
-  readonly referencesFile: string;
-  readonly latestDesign: string;
-  readonly importContext: string;
-  readonly feedback: PreviewFeedback;
-}): string {
-  const annotations = userAnnotationsBlock([args.feedback]);
-  return taggedPrompt([
-    [
-      "design_context_file",
-      `Read the file at ${args.designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* design-system evidence.`,
-    ],
-    [
-      "reference_inspiration_file",
-      `Read the file at ${args.referencesFile} for the curated reference inspiration.`,
-    ],
-    ["reference_context", args.importContext],
-    ["reference_precedence", REFERENCE_PRECEDENCE],
-    ["preview_artifact_path", args.previewPath],
-    ["user_feedback", annotations.text],
-    ["current_design_summary", args.latestDesign],
-    ["html_rules", HTML_PREVIEW_RULES],
-    ["anti_design_slop_rules", ANTI_SLOP_RULES],
-    ["role", "You are an opinionated staff design engineer."],
-    [
-      "objective",
-      `Revise the ${args.outputType} for: ${args.prompt}. Update the preview in place from only the latest live-review feedback, applying impeccable \`craft\` and \`polish\` with restraint rather than adding an internal critique.`,
-    ],
-    [
-      "instructions",
-      [
-        "Read the current HTML at preview_artifact_path. Treat <user_feedback> as the only refinement brief; do not invent critique, screenshot, audit, or gate findings.",
-        "Address every user note and accepted live change visibly, or identify its DESIGN.md/reference-precedence conflict in the summary.",
-        `Overwrite ${args.previewPath} with one revised self-contained HTML file; do not branch or create extra previews.`,
-        "Preserve strong decisions unless feedback requires change; add no unrelated features or abstractions.",
-      ].join("\n"),
-    ],
-    [
-      "output_format",
-      [
-        "In at most 400 words, return Markdown, not the HTML body:",
-        "1. Revised artifact (path only)",
-        "2. User feedback addressed (each note/live change and its application or conflict)",
-        "3. Changes applied",
-        "4. Trade-offs / unresolved user feedback",
-        GROUNDED_REPORTING,
-      ].join("\n"),
-    ],
-  ]);
-}
 
 type ExportOptions = {
   readonly designContext: DesignContext;
@@ -316,7 +260,7 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
       ],
       [
         "reference_inspiration_file",
-        `Read the file at ${referencesFile} for the curated reference research that informed the approved design; use it wherever the spec cites visual direction or reference provenance.`,
+        `Read the file at ${referencesFile} for the curated reference research that informed the final design; use it wherever the spec cites visual direction or reference provenance.`,
       ],
       ["preview_artifact_path", previewPath],
       ["spec_artifact_path", specPath],
@@ -326,12 +270,12 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
       ["role", "You are an opinionated staff design engineer."],
       [
         "objective",
-        `Export the final ${outputType} for "${prompt}" as a rich browser-readable HTML spec. Apply impeccable \`document\` and embed or link the approved preview so implementation reviewers see the agreed design.`,
+        `Export the final ${outputType} for "${prompt}" as a rich browser-readable HTML spec. Apply impeccable \`document\` and embed or link the final preview so implementation reviewers see the design as exported.`,
       ],
       [
         "instructions",
         [
-          "First read the design-context file named above, then read preview_artifact_path as the canonical approved design, and use the Write tool to create one self-contained HTML5 file at spec_artifact_path.",
+          "First read the design-context file named above, then read preview_artifact_path as the canonical final design, and use the Write tool to create one self-contained HTML5 file at spec_artifact_path.",
           "In order, include: sticky header with title/status/run id; Executive Summary; Live Preview embedding the full preview via `<iframe srcdoc=\"...\">` or a side-by-side rendered copy in `<article class=\"preview-frame\">`; the six DESIGN.md sections (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) rendered with swatches, tables, and code blocks; Implementation handoff (Recommended files + components, Implementation steps, Usage example, Accessibility & responsive checklist, Validation commands, Known limitations); and an appendix linking the raw preview path.",
           "Use dense legible typography, generous whitespace, monospaced code, rendered hex/oklch swatches, and copy-to-clipboard hints in HTML comments.",
           `Show the absolute preview path (${previewPath}) and file URL (${previewFileUrl}) prominently. Preserve assumptions and limitations; introduce no requirement absent from the final design or DESIGN.md.`,
@@ -375,8 +319,8 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
           "instructions",
           [
             `Use the bootstrap rules, run \`playwright-cli open ${specFileUrl}\`, and if a browser executable is missing follow those rules and retry once before \`playwright-cli snapshot\`.`,
-            "Do not run `show --annotate` or invite changes because no refinement pass remains.",
-            `Prominently print the manual paths:\n- Final spec: ${specPath}\n- Approved preview: ${previewPath}`,
+            "Do not run `show --annotate` or invite changes because the review session has ended.",
+            `Prominently print the manual paths:\n- Final spec: ${specPath}\n- Preview: ${previewPath}`,
             "Unavailable tooling must not block the workflow; return the structured summary.",
           ].join("\n"),
         ],