@bastani/atomic 0.9.13 → 0.9.14-alpha.2

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"),
         ],

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

@@ -1,12 +1,10 @@
 import type { WorkflowParallelOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "../src/shared/types.js";
 import {
-  DEFAULT_MAX_REFINEMENTS,
   REFERENCE_PRECEDENCE,
   buildPlaywrightCliBootstrapRules,
   discoveryDecisionSchema,
   ensurePlaywrightCli,
   joinResults,
-  positiveInteger,
   prepareArtifactDir,
   shouldEarlyExitForBrowser,
   taggedPrompt,
@@ -30,17 +28,19 @@ const DELEGATION_RULE =
 
 type OpenClaudeDesignOutputs = {
   readonly output_type?: string; readonly design_system?: string; readonly artifact?: string; readonly handoff?: string;
-  readonly approved_for_export?: boolean; readonly refinements_completed?: number; readonly import_context?: string; readonly run_id?: string;
+  readonly import_context?: string; readonly run_id?: string;
   readonly artifact_dir?: string; readonly preview_path?: string; readonly preview_file_url?: string; readonly spec_path?: string; readonly spec_file_url?: string;
   readonly playwright_cli_status?: string;
 };
 
 type OpenClaudeDesignContext = {
   readonly cwd?: string;
-  readonly inputs: { readonly prompt: string; readonly discover_references?: boolean; readonly max_refinements?: number };
+  readonly inputs: { readonly prompt: string; readonly discover_references?: boolean };
   exit?(options?: { readonly status?: string; readonly reason?: string; readonly outputs?: Partial<OpenClaudeDesignOutputs> }): never;
   task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
   parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+  /** Durable tool node; the workflow-driven live review loop is built from these. */
+  tool<T>(name: string, args: object, fn: (handle: { readonly signal: AbortSignal }) => Promise<T>): Promise<T>;
   readonly ui: LiveReviewGateUi;
 };
 
@@ -55,10 +55,6 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   const inputs = designContext.inputs;
   const prompt = inputs.prompt;
   const discoverReferences = inputs.discover_references !== false;
-  const maxRefinements = positiveInteger(
-    inputs.max_refinements,
-    DEFAULT_MAX_REFINEMENTS,
-  );
 
   const workflowCwd = designContext.cwd ?? process.cwd();
   const { runId, artifactDir, previewPath, specPath } = prepareArtifactDir(
@@ -122,17 +118,16 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
       "openai-codex/gpt-5.6-sol:xhigh",
       "github-copilot/gpt-5.6-sol:xhigh",
       "openai/gpt-5.6-sol:xhigh",
-      "xai/grok-4.5:high",
-      "zai/glm-5.2:xhigh",
-      "zai-coding-cn/glm-5.2:xhigh",
+      "xai/grok-4.6:high",
+      "zai/glm-5.3:high",
+      "zai-coding-cn/glm-5.3:high",
       "openrouter/anthropic/claude-opus-5:high",
       "openrouter/anthropic/claude-fable-5:high",
       "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/moonshotai/kimi-k3:max",
       "openrouter/openai/gpt-5.6-sol:xhigh",
       "openrouter/sakana/fugu-ultra:high",
-      "openrouter/x-ai/grok-4.5",
-      "openrouter/z-ai/glm-5.2:xhigh"
+      "openrouter/x-ai/grok-4.6",
     ],
   };
   // Phase 1: combined discovery + init — one stage interviews the user via
@@ -302,18 +297,12 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
       ].join("\n")
     : "No user reference was provided; infer the design direction from the brief, project design context, research, and curated reference inspiration.";
 
-  let latestDesign = "";
-  let approvedForExport = false;
-  let refinementCount = 0;
-
   const refinement = await refineOpenClaudeDesign({
     designContext,
     prompt: designBrief,
     outputType,
-    maxRefinements,
     previewPath,
     previewFileUrl,
-    artifactDir,
     browserBootstrapRules,
     designContextFile,
     referencesFile,
@@ -322,9 +311,7 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     importContext,
     ui: designContext.ui,
   });
-  latestDesign = refinement.latestDesign;
-  approvedForExport = refinement.approvedForExport;
-  refinementCount = refinement.refinementCount;
+  const latestDesign = refinement.latestDesign;
 
   const exportResult = await exportOpenClaudeDesign({
     designContext,
@@ -340,7 +327,6 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     latestDesign,
     designModelConfig,
   });
-  latestDesign = exportResult.latestDesign;
   const handoff = exportResult.handoff;
 
   return {
@@ -348,8 +334,6 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     design_system: "project-derived design system",
     artifact: latestDesign,
     handoff: handoff.text,
-    approved_for_export: approvedForExport,
-    refinements_completed: refinementCount,
     import_context: importContext,
     run_id: runId,
     artifact_dir: artifactDir,

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

@@ -244,80 +244,9 @@ export function persistDesignContext(artifactDir: string, content: string): void
 }
 
 // ---------------------------------------------------------------------------
-// 2. Live interactive QA prompt (user-feedback display/review stages)
+// 2. Live interactive QA prompt (the user-feedback review session)
 // ---------------------------------------------------------------------------
 
-/**
- * Build the interactive-QA prompt for the `user-feedback-*` stages. Drives
- * `/skill:impeccable live` against the static preview so the user can pick
- * elements in the browser, annotate, and accept on-brand variants; degrades to
- * `playwright-cli show --annotate` and finally to a manual file path. The output
- * labels (`user_notes`, `annotated_snapshot`, `live_changes`) are parsed by the
- * generate/user-feedback loop.
- */
-export function buildLivePreviewDisplayPrompt(args: {
-  readonly previewPath: string;
-  readonly previewFileUrl: string;
-  readonly browserBootstrapRules: string;
-  readonly iteration?: number;
-  readonly maxRefinements?: number;
-  readonly final?: boolean;
-}): string {
-  const isInitial = args.iteration === undefined;
-  const isFinal = args.final === true;
-  const label = isInitial
-    ? "the just-generated HTML artifact"
-    : "the revised preview";
-  const objective = isFinal
-    ? `Show the user ${label} as the FINAL refinement pass and let them review it in the browser. This is the last automated iteration, so do NOT solicit change requests this run cannot apply — if the user wants further changes, tell them to re-run \`/workflow open-claude-design\`. Drive \`/skill:impeccable live\` for viewing/QA when possible; degrade gracefully.`
-    : `Make ${label} visible to the user, run an interactive design-QA session against it, then capture the user's feedback for the refinement loop. Drive \`/skill:impeccable live\` against the static preview when possible; degrade gracefully when browser automation is unavailable.`;
-  const interactiveQa = isFinal
-    ? [
-        `1. Open the preview for a final review: run \`/skill:impeccable live\` (or \`playwright-cli open ${args.previewFileUrl}\`) so the user can inspect ${label} in the browser.`,
-        "2. Make clear this is the final automated refinement pass. Do NOT promise to apply further annotations; instead, tell the user exactly how to re-run the workflow to iterate again.",
-      ].join("\n")
-    : [
-        `1. Run \`/skill:impeccable live\` targeted at the preview file so the user can pick elements in the browser, annotate them, and compare on-brand variants. The preview is a single static HTML file at ${args.previewPath}; point live at it (configure \`.impeccable/live/config.json\` for that file or pass \`--target ${args.previewPath}\` per the live reference) and open ${args.previewFileUrl} in the browser.`,
-        `2. The moment the live review is reachable — and BEFORE starting any long-poll wait — print the exact review URL in plain text: the live \`http://\` URL when the live server is up, plus ${args.previewFileUrl} as the manual fallback. Anyone attaching to this stage mid-run must see where the review is happening from your first lines of output.`,
-        "3. For each element the user picks, follow the live contract: read any annotation screenshot, extract the page identity FIRST, then generate three DISTINCT on-brand variants and let the user accept one. Accepted variants are written into the preview HTML in place; do NOT branch the artifact.",
-        "4. Also handle the live `steer` path for page-level direction the user types/speaks, and treat any freeform prompt as the ceiling on direction.",
-        "5. Keep iterating until the user signals they are done with this round.",
-      ].join("\n");
-  const outputFormat = isFinal
-    ? [
-        "Markdown with: `display_method` (live | playwright-annotate | manual), `preview_path`, and `next_action_hint` (how to re-run the workflow for further changes).",
-        "Do NOT collect `user_notes` or `live_changes`: this final pass cannot apply them, so don't invite feedback that would go nowhere.",
-      ].join("\n")
-    : [
-        "Markdown with these exact labels so the refinement loop can parse the captured feedback:",
-        "`display_method` (live | playwright-annotate | manual)",
-        "`preview_path`",
-        "`live_changes` (summary of every element/variant the user ACCEPTED in the live session; `none` when no live edits were made)",
-        "`annotated_snapshot` (path to any annotated screenshot, if captured)",
-        "`user_notes` (the user's verbatim notes/annotations for the next iteration; `none` when the user gave no notes)",
-        "`next_action_hint`",
-      ].join("\n");
-  return taggedPrompt([
-    ["preview_path", args.previewPath],
-    ["preview_file_url", args.previewFileUrl],
-    ["browser_use_guidelines", args.browserBootstrapRules],
-    [
-      "role",
-      "You are an opinionated staff design engineer running interactive `live` QA in a real browser.",
-    ],
-    ["objective", objective],
-    ["interactive_live_qa", interactiveQa],
-    [
-      "graceful_degradation",
-      [
-        `If \`/skill:impeccable live\` cannot boot, open the preview with \`playwright-cli open ${args.previewFileUrl}\`, then run \`playwright-cli snapshot\`${isFinal ? "" : " and `playwright-cli show --annotate` for user notes"}. If the browser executable is missing, follow the bootstrap rules and retry once.`,
-        `If \`playwright-cli\` is unavailable, tell the user to open ${args.previewPath} or ${args.previewFileUrl} manually.`,
-        "Unavailable tooling must not block the workflow; return a non-empty status.",
-      ].join("\n"),
-    ],
-    ["output_format", `${outputFormat}\nKeep the report under 250 words. ${GROUNDED_REPORTING}`],
-  ]);
-}
 
 // ---------------------------------------------------------------------------
 // 3. Deterministic live-review gate (run-level HIL prompt, issue #2060)
@@ -333,9 +262,9 @@ export type LiveReviewGateUi = {
 };
 
 /**
- * Choices for the deterministic gate raised before every `user-feedback-*`
- * stage. The first entry starts the browser review round; the second accepts
- * the current design and skips straight to export.
+ * Choices for the deterministic gate raised before the live review session.
+ * The first entry starts the session; the second accepts the current design
+ * and skips straight to export.
  */
 export const LIVE_REVIEW_GATE_OPTIONS = [
   "Start live review",
@@ -343,27 +272,31 @@ export const LIVE_REVIEW_GATE_OPTIONS = [
 ] as const;
 
 /**
- * Message for the deterministic run-level prompt raised before each
- * `user-feedback-*` stage. The stage's browser long-poll never sets
- * `awaiting_input`, so without this gate the run is indistinguishable from
- * active compute while it waits on a human (issue #2060). Raising a `ctx.ui`
- * prompt sets the run-level pending prompt, which fires the needs-attention
- * badge and carries the preview URL to the root session deterministically.
+ * Message for the deterministic run-level prompt raised before the live
+ * review session. The browser long-poll never sets `awaiting_input`, so
+ * without this gate the run is indistinguishable from active compute while it
+ * waits on a human (issue #2060). Raising a `ctx.ui` prompt sets the run-level
+ * pending prompt, which fires the needs-attention badge and carries the
+ * preview URL to the root session deterministically.
  */
 export function buildLiveReviewGateMessage(args: {
-  readonly iteration: number;
-  readonly maxRefinements: number;
+  readonly round: number;
   readonly previewPath: string;
   readonly previewFileUrl: string;
 }): string {
   return [
-    `Design review round ${args.iteration} of ${args.maxRefinements} is ready for your browser review.`,
+    `Design review session ${args.round} is ready for your browser review.`,
     "",
     `Preview file: ${args.previewPath}`,
     `Preview URL: ${args.previewFileUrl}`,
     "",
-    `"${LIVE_REVIEW_GATE_OPTIONS[0]}" opens an interactive browser session; the user-feedback stage prints the live http:// review URL as soon as its server is up (attach with /workflow connect to see it, or open the preview URL above directly).`,
-    `"${LIVE_REVIEW_GATE_OPTIONS[1]}" accepts the current design and proceeds to export.`,
+    `"${LIVE_REVIEW_GATE_OPTIONS[0]}" opens an interactive browser session; the session-start stage prints the live http:// review URL as soon as its server is up (attach with /workflow connect to see it, or open the preview URL above directly).`,
+    "The session is unbounded: pick elements, accept variants, and steer for as long as you like, and everything you accept lands in the preview as you go.",
+    "",
+    "YOU end the review, and nothing else does. It keeps waiting through any amount of silence.",
+    "End it by clicking exit in the Impeccable overlay, closing the browser tab, or saying \"exit live\".",
+    "The moment you do, the design you are looking at is exported. There is no further round and no confirmation, so end the session only when the preview is what you want handed off.",
+    `"${LIVE_REVIEW_GATE_OPTIONS[1]}" accepts the current design and proceeds to export without opening a session.`,
   ].join("\n");
 }
 

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

@@ -17,7 +17,6 @@ export const OUTPUT_TYPES = [
 ] as const;
 export type OutputType = (typeof OUTPUT_TYPES)[number];
 export const DEFAULT_OUTPUT_TYPE: OutputType = "prototype";
-export const DEFAULT_MAX_REFINEMENTS = 3;
 
 type PromptSection = readonly [tag: string, content: string];
 
@@ -30,11 +29,6 @@ export function taggedPrompt(sections: readonly PromptSection[]): string {
     .join("\n\n");
 }
 
-export function positiveInteger(value: number | undefined, fallback: number): number {
-  return typeof value === "number" && Number.isFinite(value) && value > 0
-    ? Math.floor(value)
-    : fallback;
-}
 
 export function normalizeOutputType(value: string | undefined): OutputType {
   return value !== undefined &&

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

@@ -5,22 +5,17 @@ export type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "c
 export type OpenClaudeDesignWorkflowInputs = {
   readonly prompt: string;
   readonly discover_references: boolean;
-  readonly max_refinements: number;
 };
 
 export type OpenClaudeDesignWorkflowRunInputs = {
   readonly prompt: string;
   readonly discover_references?: boolean;
-  readonly max_refinements?: number;
 };
-
 export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
   readonly output_type?: string;
   readonly design_system?: string;
   readonly artifact?: string;
   readonly handoff?: string;
-  readonly approved_for_export?: boolean;
-  readonly refinements_completed?: number;
   readonly import_context?: string;
   readonly run_id?: string;
   readonly artifact_dir?: string;