@bastani/atomic 0.9.11-alpha.8 → 0.9.11-alpha.9

package/dist/builtin/workflows/README.md

@@ -587,6 +587,8 @@ Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-p
 
 Named workflow launches always run as **background tasks** in interactive sessions. Run `/workflow connect <run>` to see agents working and chat with and steer each stage. Foreground launches are reserved for explicit user requests or technical requirements, with notice before launch. Press **F2** to open the same live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on a focused node, or click a visible graph node directly, to open that stage and answer locally, never as a modal dialog over the chat. `ctrl+x` is the workflow hierarchy chord: attached stage chats show **ctrl+x return to graph**, while graph surfaces show **ctrl+x leave graph · return to main chat**. Workflow surfaces consume it before configurable editor/tool actions. Composer and prompt drafts survive leaving a stage, and pending custom questions remain pending for reattachment. `ctrl+d` and `q` are not workflow navigation controls; ordinary editor/prompt Ctrl+D behavior and printable prompt `q` remain available. Existing `esc`, `ctrl+c`, and graph `h` close/hide behavior is unchanged. While the graph pane is active, vertical wheel/trackpad gestures pan vertically and horizontal gestures pan wide graphs left and right when the terminal reports them, without falling through to the main chat or terminal scrollback. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Press `ctrl+t` to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore workflow-chat scrolling. Archived read-only stage transcripts show the same copy-mode footer/status, allowing their transcript text to be selected and copied while preserving `esc` close and `ctrl+x` graph navigation. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
 
+Typing into an attached stage chat and pressing Enter steers: the message is consumed after the current assistant response finishes its tool batch and before the next model request, matching normal session steering. Ctrl+F queues a follow-up, consumed only when the agent would otherwise stop. Queued entries belong to the stage session rather than the pane, so leaving the stage and reattaching restores the pending `Steering:` / `Follow-up:` rows, and a detached stage node carries a `✉ N queued` badge in the graph.
+
 Named launches return only after startup admission, while the admitted workflow body and stages remain background work. Pre-body setup failures (including invalid input-bound reusable worktrees) are returned immediately from the original tool call as structured failed results with the concrete error and allocated run id; Atomic does not first claim that the workflow started, and it removes the unadmitted run so corrected inputs can be retried immediately. Failures after admission continue to use normal background status and lifecycle notices.
 
 Graceful quit is idempotent for already-paused runs and preserves unresolved `ctx.ui` prompts in DBOS. Pausing or interrupting a stage also holds every queued steering and follow-up item in place: no queued turn, late context-bearing delivery, or workflow continuation starts while the stage is paused, and the existing `resume` action releases the items once in their existing per-queue order without queue release itself starting a provider turn. Stable author-callsite-and-composed-nested-scope reservations are created before prompting and released by exact current-format token generation after answer checkpoint, rejection, or abort. Answering while quit/paused cannot advance workflow code until explicit resume.
@@ -761,6 +763,10 @@ For either workflow, keep PR/MR creation out of the task text and pass the origi
 
 Combined discovery/init → design-system/reference research → curated reference discovery with user preference check → separate forked generate and user-feedback chains → export/handoff pipeline. The `discovery` stage asks for output type and references, then runs impeccable init in the same stage so PRODUCT.md/DESIGN.md are detected, created, or reconciled. `ds-*` stages handle user-provided URL/file reference extraction directly, then `reference-discovery` uses that context and asks which curated direction you prefer (or asks for a reference image/path/URL if none fit). Export is only `exporter` plus `final-display`.
 
+Each refinement round pauses at a deterministic run-level prompt before its `user-feedback-*` stage starts (the stage's browser long-poll never sets `awaiting_input`, so the gate is where the wait surfaces). The prompt fires the needs-attention badge and names the preview path and `file://` URL; choose `Start live review` to open the browser session (the stage prints the live `http://` review URL first — see it with `/workflow connect`), or `Skip remaining review rounds and export as-is` to accept the current design. Headless runs skip the gate. A feedback stage that fails outright fails the run; only a completed review with no requested changes counts as approval.
+
+Research context moves between stages as artifact files, not inline prompt payloads: the project design context is written to `<artifact_dir>/design-context.md` and the curated references brief to `<artifact_dir>/references.md`; `reference-discovery` reads the design context, and the generate and exporter stages read both files via `reads`. Only verbatim user annotations and the word-capped prior design summary travel inline.
+
 ```text
 /workflow open-claude-design prompt="Design a kanban board component"
 ```

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

@@ -13,7 +13,13 @@ import {
   userAnnotationsBlock,
   type PreviewFeedback,
 } from "./open-claude-design-feedback.js";
-import { buildLivePreviewDisplayPrompt } from "./open-claude-design-setup.js";
+import {
+  LIVE_REVIEW_GATE_OPTIONS,
+  buildLiveReviewGateMessage,
+  buildLivePreviewDisplayPrompt,
+  isUiUnavailableRejection,
+  type LiveReviewGateUi,
+} from "./open-claude-design-setup.js";
 
 const GROUNDED_REPORTING =
   "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
@@ -47,17 +53,18 @@ type RefineOptions = {
   readonly previewFileUrl: string;
   readonly artifactDir: string;
   readonly browserBootstrapRules: string;
-  readonly designSystem: string;
-  readonly generationContext: readonly WorkflowTaskResult[];
+  /** Path to the persisted design-context.md artifact (issue #2121). */
+  readonly designContextFile: string;
+  /** Path to the persisted references.md artifact (issue #2121). */
+  readonly referencesFile: string;
   readonly designModelConfig: ModelConfig;
   readonly workflowCwd: string;
-  readonly referencesBrief?: string;
   readonly importContext?: string;
+  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, designSystem, designModelConfig, workflowCwd } = options;
-  const referencesBrief = options.referencesBrief ?? "";
+  const { designContext, prompt, outputType, maxRefinements, previewPath, previewFileUrl, artifactDir, browserBootstrapRules, designContextFile, referencesFile, designModelConfig, workflowCwd } = options;
   const importContext = options.importContext ?? "";
   let latestDesign = "";
   let latestGenerateSessionFile: string | undefined;
@@ -73,17 +80,17 @@ export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{
           prompt,
           outputType,
           previewPath,
-          designSystem,
-          referencesBrief,
+          designContextFile,
+          referencesFile,
           importContext,
         })
       : buildGenerateRevisionPrompt({
           prompt,
           outputType,
           previewPath,
-          designSystem,
+          designContextFile,
+          referencesFile,
           latestDesign,
-          referencesBrief,
           importContext,
           feedback: pendingFeedback,
         });
@@ -91,11 +98,17 @@ export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{
       assertUserAnnotationsThreaded(generatePrompt, [pendingFeedback], generateStageName);
     }
 
+    // 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,
-      previous: pendingFeedback === undefined
-        ? options.generationContext
-        : { name: "current-design", text: latestDesign },
+      reads: [designContextFile, referencesFile],
+      ...(pendingFeedback === undefined
+        ? {}
+        : { previous: { name: "current-design", text: latestDesign } }),
       ...designModelConfig,
       ...forkContinuationOptions(latestGenerateSessionFile),
     });
@@ -103,22 +116,49 @@ export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{
     latestGenerateSessionFile = generated.sessionFile ?? latestGenerateSessionFile;
     refinementCount = iteration;
 
-    const userFeedbackResult = await designContext
-      .task(`user-feedback-${iteration}`, {
-        prompt: buildLivePreviewDisplayPrompt({
-          previewPath,
-          previewFileUrl,
-          browserBootstrapRules,
-          iteration,
-          maxRefinements,
-        }),
-        ...designModelConfig,
-        ...forkContinuationOptions(latestUserFeedbackSessionFile),
-      })
-      .catch(() => undefined);
+    // 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;
+    }
+
+    // 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),
+    });
 
     latestUserFeedbackSessionFile =
-      userFeedbackResult?.sessionFile ?? latestUserFeedbackSessionFile;
+      userFeedbackResult.sessionFile ?? latestUserFeedbackSessionFile;
     const feedback = toPreviewFeedback({
       iteration,
       stageName: `user-feedback-${iteration}`,
@@ -140,15 +180,21 @@ function buildInitialGeneratePrompt(args: {
   readonly prompt: string;
   readonly outputType: string;
   readonly previewPath: string;
-  readonly designSystem: string;
-  readonly referencesBrief: string;
+  readonly designContextFile: string;
+  readonly referencesFile: string;
   readonly importContext: string;
 }): string {
   return taggedPrompt([
     ["design_brief", args.prompt],
-    ["design_system", args.designSystem],
+    [
+      "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 before designing.`,
+    ],
     ["reference_context", args.importContext],
-    ["reference_inspiration", args.referencesBrief],
+    [
+      "reference_inspiration_file",
+      `Read the file at ${args.referencesFile} for the curated reference inspiration to heavily emulate.`,
+    ],
     ["reference_precedence", REFERENCE_PRECEDENCE],
     ["preview_artifact_path", args.previewPath],
     ["html_rules", HTML_PREVIEW_RULES],
@@ -161,8 +207,9 @@ function buildInitialGeneratePrompt(args: {
     [
       "instructions",
       [
+        `First read the design-context and reference-inspiration files named above; they are the design system and reference authority for every decision. If a file is missing, say so and proceed from the brief.`,
         `Create the HTML artifact exactly at ${args.previewPath}.`,
-        "Follow <reference_precedence>; heavily reference <reference_inspiration> without copying wholesale or inventing traits.",
+        "Follow <reference_precedence>; heavily reference the reference-inspiration file without copying wholesale or inventing traits.",
         `Build the requested output_type (${args.outputType}): render full realistic layouts for prototypes/pages, or the component in at least three representative contexts.`,
         "Include structure, states, accessibility, responsive behavior, and integration notes as HTML comments so the preview stays clean.",
         "Use project language rather than generic placeholders when conventions exist. Add no features or abstractions beyond this design brief.",
@@ -188,16 +235,22 @@ function buildGenerateRevisionPrompt(args: {
   readonly prompt: string;
   readonly outputType: string;
   readonly previewPath: string;
-  readonly designSystem: string;
+  readonly designContextFile: string;
+  readonly referencesFile: string;
   readonly latestDesign: string;
-  readonly referencesBrief: string;
   readonly importContext: string;
   readonly feedback: PreviewFeedback;
 }): string {
   const annotations = userAnnotationsBlock([args.feedback]);
   return taggedPrompt([
-    ["design_system", args.designSystem],
-    ["reference_inspiration", args.referencesBrief],
+    [
+      "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],
@@ -242,18 +295,29 @@ type ExportOptions = {
   readonly specPath: string;
   readonly specFileUrl: string;
   readonly browserBootstrapRules: string;
-  readonly designSystem: string;
+  /** Path to the persisted design-context.md artifact (issue #2121). */
+  readonly designContextFile: string;
+  /** Path to the persisted references.md artifact (issue #2121). */
+  readonly referencesFile: string;
   readonly latestDesign: string;
   readonly designModelConfig: ModelConfig;
 };
 
 export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{ readonly latestDesign: string; readonly handoff: WorkflowTaskResult; }> {
-  const { designContext, prompt, outputType, previewPath, previewFileUrl, specPath, specFileUrl, browserBootstrapRules, designSystem, designModelConfig } = options;
+  const { designContext, prompt, outputType, previewPath, previewFileUrl, specPath, specFileUrl, browserBootstrapRules, designContextFile, referencesFile, designModelConfig } = options;
   const latestDesign = options.latestDesign;
 
   const handoff = await designContext.task("exporter", {
+    reads: [designContextFile, referencesFile],
     prompt: taggedPrompt([
-      ["design_system", designSystem],
+      [
+        "design_context_file",
+        `Read the file at ${designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* design-system evidence to document.`,
+      ],
+      [
+        "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.`,
+      ],
       ["preview_artifact_path", previewPath],
       ["spec_artifact_path", specPath],
       ["final_design_summary", "{previous}"],
@@ -267,7 +331,7 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
       [
         "instructions",
         [
-          "Read preview_artifact_path as the canonical approved design, then 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 approved 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.`,

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

@@ -15,8 +15,12 @@ import { exportOpenClaudeDesign, refineOpenClaudeDesign } from "./open-claude-de
 import {
   NO_REFERENCES_BRIEF,
   buildReferenceDiscoveryPrompt,
+  designContextPath,
+  persistDesignContext,
   persistReferencesBrief,
+  referencesBriefPath,
   runDiscoveryAndInit,
+  type LiveReviewGateUi,
 } from "./open-claude-design-setup.js";
 
 const GROUNDED_REPORTING =
@@ -37,6 +41,7 @@ type OpenClaudeDesignContext = {
   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[]>;
+  readonly ui: LiveReviewGateUi;
 };
 
 export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext): Promise<OpenClaudeDesignOutputs> {
@@ -61,6 +66,10 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   );
   const previewFileUrl = `file://${previewPath}`;
   const specFileUrl = `file://${specPath}`;
+  const partialArtifactOutputs = {
+    playwright_cli_status: playwrightCli.summary, run_id: runId, artifact_dir: artifactDir,
+    preview_path: previewPath, preview_file_url: previewFileUrl, spec_path: specPath, spec_file_url: specFileUrl,
+  };
 
   // Browser-centric workflow: the discovery/preview review and the interactive
   // `live` QA loop need the playwright-cli browser. If it is unavailable, exit
@@ -72,13 +81,31 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   ) {
     designContext.exit({
       reason: `open-claude-design needs the playwright-cli skill's browser for interactive design review, which is unavailable (${playwrightCli.error ?? playwrightCli.summary}). No design was generated. Install it (\`npm install -g @playwright/cli@latest\` + \`npx playwright install chromium\`) and re-run.`,
-      outputs: {
-        playwright_cli_status: playwrightCli.summary, run_id: runId, artifact_dir: artifactDir,
-        preview_path: previewPath, preview_file_url: previewFileUrl, spec_path: specPath, spec_file_url: specFileUrl,
-      },
+      outputs: partialArtifactOutputs,
     });
   }
 
+  // design-context.md / references.md are required `reads` inputs for the
+  // reference-discovery, generate, and exporter stages. A failed write must
+  // not let those stages dispatch against nonexistent context: exit the run
+  // as `blocked` through ctx.exit (mirroring the browser early-exit) with the
+  // artifact paths surfaced, or propagate the error when ctx.exit is absent.
+  const persistRequiredContextOrExit = (persist: () => void): void => {
+    try {
+      persist();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      if (typeof designContext.exit === "function") {
+        designContext.exit({
+          status: "blocked",
+          reason: `${detail} No design was generated.`,
+          outputs: partialArtifactOutputs,
+        });
+      }
+      throw error;
+    }
+  };
+
   // Anthropic-heavy chain for design taste. Opus stays at :xhigh here because
   // visual quality, rather than cost per task, is the primary objective.
   const designModelConfig = {
@@ -229,31 +256,41 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   });
   const onboardingSummary = joinResults(onboardingAnalysis);
 
+  // Large research context is handed to later stages as an artifact file plus
+  // `reads`, never as an inline prompt embed or `previous` payload, so one
+  // oversized research result cannot become one oversized prompt message
+  // (issue #2121; same failure class as the #1499 413).
+  const designSystem = [
+    "Project design context from `/skill:impeccable init` and PRODUCT.md/DESIGN.md:",
+    projectContext.summary,
+    "",
+    "Design-system and user-reference evidence:",
+    onboardingSummary,
+  ].join("\n\n");
+  persistRequiredContextOrExit(() => persistDesignContext(artifactDir, designSystem));
+  const designContextFile = designContextPath(artifactDir);
+
   const referenceResult = discoverReferences
     ? await designContext.task("reference-discovery", {
         prompt: buildReferenceDiscoveryPrompt({
           prompt: designBrief,
           outputType,
-          designContextHint: [
-            projectContext.summary,
-            "Design-system/reference discovery evidence from codebase design discovery stages:",
-            onboardingSummary,
-          ].join("\n\n"),
+          designContextFile,
           artifactDir,
           browserBootstrapRules,
         }),
-        previous: onboardingAnalysis,
+        reads: [designContextFile],
         ...designModelConfig,
       })
     : undefined;
-  const contextResults = referenceResult === undefined
-    ? onboardingAnalysis
-    : [...onboardingAnalysis, referenceResult];
 
   const referencesBriefRaw = (referenceResult?.text ?? "").trim();
   const referencesBrief =
     referencesBriefRaw.length > 0 ? referencesBriefRaw : NO_REFERENCES_BRIEF;
-  if (referencesBriefRaw.length > 0) persistReferencesBrief(artifactDir, referencesBrief);
+  // Always persist so the generate stages' `reads` target exists even when
+  // discovery is skipped or returned nothing.
+  persistRequiredContextOrExit(() => persistReferencesBrief(artifactDir, referencesBrief));
+  const referencesFile = referencesBriefPath(artifactDir);
 
   const importContext = references.length > 0
     ? [
@@ -261,16 +298,9 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
         "Reference sources:",
         userReferenceContext,
         "",
-        onboardingSummary,
+        "Full design-system and reference evidence: read the design-context file.",
       ].join("\n")
     : "No user reference was provided; infer the design direction from the brief, project design context, research, and curated reference inspiration.";
-  const designSystem = [
-    "Project design context from `/skill:impeccable init` and PRODUCT.md/DESIGN.md:",
-    projectContext.summary,
-    "",
-    "Design-system and user-reference evidence:",
-    onboardingSummary,
-  ].join("\n\n");
 
   let latestDesign = "";
   let approvedForExport = false;
@@ -285,12 +315,12 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     previewFileUrl,
     artifactDir,
     browserBootstrapRules,
-    designSystem,
-    generationContext: contextResults,
+    designContextFile,
+    referencesFile,
     designModelConfig,
     workflowCwd,
-    referencesBrief,
     importContext,
+    ui: designContext.ui,
   });
   latestDesign = refinement.latestDesign;
   approvedForExport = refinement.approvedForExport;
@@ -305,7 +335,8 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     specPath,
     specFileUrl,
     browserBootstrapRules,
-    designSystem,
+    designContextFile,
+    referencesFile,
     latestDesign,
     designModelConfig,
   });

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

@@ -3,7 +3,7 @@
  *
  * Capabilities that delegate to the accessible `impeccable` skill
  * (`/skill:impeccable …`), factored into this module so the runner and phases
- * files stay under the 500-line file-length gate:
+ * files stay focused:
  *
  *   1. Discovery + init front door: one `discovery` stage runs
  *      `/skill:impeccable shape` and `/skill:impeccable init`, interviews the
@@ -130,10 +130,22 @@ export const REFERENCE_DESIGN_SITES: readonly { readonly name: string; readonly
 export const NO_REFERENCES_BRIEF =
   "Reference discovery was skipped. Generate from the project design system and the prompt; do not fabricate external references.";
 
+/** Artifact filenames for large stage-to-stage context handoffs (issue #2121). */
+export const DESIGN_CONTEXT_FILENAME = "design-context.md";
+export const REFERENCES_BRIEF_FILENAME = "references.md";
+
+export function designContextPath(artifactDir: string): string {
+  return join(artifactDir, DESIGN_CONTEXT_FILENAME);
+}
+
+export function referencesBriefPath(artifactDir: string): string {
+  return join(artifactDir, REFERENCES_BRIEF_FILENAME);
+}
+
 export function buildReferenceDiscoveryPrompt(args: {
   readonly prompt: string;
   readonly outputType: string;
-  readonly designContextHint: string;
+  readonly designContextFile: string;
   readonly artifactDir: string;
   readonly browserBootstrapRules: string;
 }): string {
@@ -142,7 +154,10 @@ export function buildReferenceDiscoveryPrompt(args: {
   ).join("\n");
   return taggedPrompt([
     ["reference_galleries", siteList],
-    ["design_context", args.designContextHint],
+    [
+      "design_context_file",
+      `Read the file at ${args.designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* discovery evidence before curating. Do not proceed from assumptions when the file is readable; if it is missing, say so and curate from the brief alone.`,
+    ],
     ["browser_use_guidelines", args.browserBootstrapRules],
     ["screenshot_dir", args.artifactDir],
     [
@@ -161,7 +176,7 @@ export function buildReferenceDiscoveryPrompt(args: {
         `Capture motion across the entire page: start \`playwright-cli video-start ${join(args.artifactDir, "ref-<site>-<n>.webm")}\`, scroll smoothly in small increments with waits (using \`playwright-cli run-code\` or repeated \`playwright-cli mousewheel 0 600\`) so animations fire and lazy content loads, then run \`playwright-cli video-stop\`.`,
         `Also run \`playwright-cli screenshot --full-page --filename=${join(args.artifactDir, "ref-<site>-<n>.png")}\`; this still is the minimum when video is unavailable.`,
         "Record the actual destination URL, title, and author. For each reference, cite observed layout, typography, color, spacing, and motion traits rather than inferred traits.",
-        "Assess fit against DESIGN.md, PRODUCT.md, and the ds-* discovery evidence in <design_context>; prefer on-brand references and flag departures.",
+        "Assess fit against DESIGN.md, PRODUCT.md, and the ds-* discovery evidence in the design-context file; prefer on-brand references and flag departures.",
         "Use ask_user_question to ask which reference direction they prefer, offering 2-4 strongest options plus `None of these fit`. If none fit, ask them to provide a reference image, screenshot, URL, or local file path and record the answer.",
         "If `playwright-cli` is unavailable or automation is blocked, use web search / page fetch to reach actual pages and mark missing recordings or screenshots. Never fabricate references or visual claims; report galleries with no usable result.",
       ].join("\n"),
@@ -181,16 +196,53 @@ export function buildReferenceDiscoveryPrompt(args: {
   ]);
 }
 
-/** Persist the curated references brief to `<artifactDir>/references.md`. Best-effort. */
-export function persistReferencesBrief(artifactDir: string, brief: string): void {
+/**
+ * Write a context artifact that downstream stages consume via `reads`.
+ * These files are required stage inputs, not best-effort durability copies:
+ * a swallowed write failure would let reference-discovery, generate, and
+ * exporter stages dispatch against nonexistent design/reference context, so
+ * a failure propagates and stops the workflow (issue #2121, Greptile P1).
+ */
+function writeRequiredContextArtifact(
+  artifactDir: string,
+  filePath: string,
+  content: string,
+  label: string,
+): void {
   try {
     mkdirSync(artifactDir, { recursive: true });
-    writeFileSync(join(artifactDir, "references.md"), `${brief}\n`);
-  } catch {
-    /* best-effort durability; never block the workflow */
+    writeFileSync(filePath, `${content}\n`);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `open-claude-design: failed to write the required ${label} artifact at ${filePath}. Downstream stages read this file via \`reads\` and must not run without it (${detail})`,
+      { cause: error },
+    );
   }
 }
 
+/**
+ * Persist the curated references brief to `<artifactDir>/references.md`.
+ * Downstream generate stages consume this file via `reads` instead of an
+ * inline prompt embed; a write failure propagates (issue #2121).
+ */
+export function persistReferencesBrief(artifactDir: string, brief: string): void {
+  writeRequiredContextArtifact(artifactDir, referencesBriefPath(artifactDir), brief, "references-brief");
+}
+
+/**
+ * Persist the composed project design context (impeccable init summary plus
+ * ds-* discovery evidence) to `<artifactDir>/design-context.md`.
+ * Reference-discovery, generate, and exporter stages consume this file via
+ * `reads` instead of an inline prompt embed, so one oversized research result
+ * cannot become an oversized single prompt message. A write failure
+ * propagates rather than letting those stages run without their design
+ * context (issue #2121).
+ */
+export function persistDesignContext(artifactDir: string, content: string): void {
+  writeRequiredContextArtifact(artifactDir, designContextPath(artifactDir), content, "design-context");
+}
+
 // ---------------------------------------------------------------------------
 // 2. Live interactive QA prompt (user-feedback display/review stages)
 // ---------------------------------------------------------------------------
@@ -226,9 +278,10 @@ export function buildLivePreviewDisplayPrompt(args: {
       ].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. 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.",
-        "3. Also handle the live `steer` path for page-level direction the user types/speaks, and treat any freeform prompt as the ceiling on direction.",
-        "4. Keep iterating until the user signals they are done with this round.",
+        `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
     ? [
@@ -265,3 +318,63 @@ export function buildLivePreviewDisplayPrompt(args: {
     ["output_format", `${outputFormat}\nKeep the report under 250 words. ${GROUNDED_REPORTING}`],
   ]);
 }
+
+// ---------------------------------------------------------------------------
+// 3. Deterministic live-review gate (run-level HIL prompt, issue #2060)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal structural slice of `ctx.ui` the live-review gate needs. Kept
+ * structural so the runner/phases modules stay decoupled from the full
+ * WorkflowRunContext type.
+ */
+export type LiveReviewGateUi = {
+  select<T extends string>(message: string, options: readonly T[]): Promise<T>;
+};
+
+/**
+ * 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.
+ */
+export const LIVE_REVIEW_GATE_OPTIONS = [
+  "Start live review",
+  "Skip remaining review rounds and export as-is",
+] 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.
+ */
+export function buildLiveReviewGateMessage(args: {
+  readonly iteration: number;
+  readonly maxRefinements: number;
+  readonly previewPath: string;
+  readonly previewFileUrl: string;
+}): string {
+  return [
+    `Design review round ${args.iteration} of ${args.maxRefinements} 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.`,
+  ].join("\n");
+}
+
+/**
+ * True only for the executor's unavailable-UI rejections (no UI adapter, or
+ * headless/non-interactive mode; see `executor-hil.ts` `makeRejectingUIContext`
+ * and the prompt-node unavailable errors). The live-review gate degrades to
+ * running the review for exactly these; every other rejection — interruption,
+ * durable checkpoint persistence failure, exit — must propagate so the
+ * workflow stops instead of opening a review against an invalid run state.
+ */
+export function isUiUnavailableRejection(error: unknown): boolean {
+  return error instanceof Error && /ctx\.ui\.\w+ (?:prompt node )?is unavailable/.test(error.message);
+}

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.11-alpha.8",
+  "version": "0.9.11-alpha.9",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -79,11 +79,11 @@
   },
   "dependencies": {
     "jiti": "^2.7.0",
-    "typebox": "^1.3.6"
+    "typebox": "^1.3.7"
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.82.1"
+    "@earendil-works/pi-tui": "^0.83.0"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {