@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/builtin/loop-until-done.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runLoopUntilDone } from "./loop-until-done-runner.js";
 
 export default workflow({
@@ -15,7 +16,7 @@ export default workflow({
     }),
   },
   outputs: {
-    result: Type.String({ description: "Evidence-backed completion report or deterministic exhaustion report." }),
+    result: Type.String({ description: "Compact reference to the evidence-backed completion report, or the deterministic exhaustion report; read `result_path` for the full report." }),
     status: Type.Union([Type.Literal("complete"), Type.Literal("failed")], {
       description: "Complete when evidence satisfies the stop condition; failed when max_iterations is exhausted.",
     }),
@@ -27,5 +28,5 @@ export default workflow({
     remaining_work: Type.String({ description: "Actionable remaining work; empty only after proven completion." }),
     artifact_dir: Type.String({ description: "Run-specific directory containing loop artifacts." }),
   },
-  run: async (ctx) => await runLoopUntilDone(ctx),
+  run: async (ctx) => await runLoopUntilDone(withSteeringPropagationContext(ctx)),
 });

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

@@ -13,7 +13,16 @@ 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.";
 
 type DesignContext = {
   task(name: string, options: object): Promise<WorkflowTaskResult>;
@@ -44,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;
@@ -70,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,
         });
@@ -88,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),
     });
@@ -100,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}`,
@@ -137,46 +180,52 @@ 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([
-    ["role", "You are an opinionated staff design engineer."],
+    ["design_brief", args.prompt],
     [
-      "objective",
-      `Generate the first revision of a production-ready ${args.outputType} for: ${args.prompt}. Write it to disk as an interactive HTML preview the user can open in a browser. Apply the impeccable \`craft\` sub-skill to build the design with deliberate ordering and impeccable attention to detail. Every design decision must trace back to the brief, and every visual trait must be justified by the references, design system, or reference context.`,
+      "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.`,
     ],
-    ["design_brief", args.prompt],
-    ["design_system", args.designSystem],
     ["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],
     ["anti_design_slop_rules", ANTI_SLOP_RULES],
+    ["role", "You are an opinionated staff design engineer."],
+    [
+      "objective",
+      `Create the first production-ready ${args.outputType} for: ${args.prompt}. Write an interactive browser preview and apply impeccable \`craft\`; each decision must trace to the brief, references, design system, or reference context.`,
+    ],
     [
       "instructions",
       [
-        `1. Create the HTML artifact at exactly this path: ${args.previewPath}.`,
-        "2. Follow the `<reference_precedence>` rule: user-provided references in `<reference_context>` win over DESIGN.md/PRODUCT.md where they conflict; DESIGN.md fills gaps the references do not cover.",
-        "3. Heavily reference the `<reference_inspiration>` block while staying consistent with the imported user references; never copy a reference wholesale or invent traits it does not contain.",
-        `4. Build the artifact as the requested output_type (${args.outputType}). For prototypes/pages, render full layouts with realistic content. For components, render the component in 3+ representative contexts.`,
-        "5. Include structure, states, accessibility behavior, responsive behavior, and integration notes — but keep them in HTML comments inside the file so the rendered preview stays clean.",
-        "6. Do not use generic placeholder language when project conventions are available.",
-        "7. After writing the file, return a short markdown summary (NOT the HTML body) describing what you built, decisions made, and assumptions left for the user to confirm.",
+        `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 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.",
       ].join("\n"),
     ],
     [
       "output_format",
       [
-        "Return markdown with the headings below. DO NOT paste the HTML; the file at preview_artifact_path is the artifact.",
+        "In at most 500 words, return Markdown, not the HTML body:",
         "1. Artifact overview",
-        "2. Files written (must include the absolute path to preview.html)",
-        "3. UI structure and states (referenced by HTML section IDs)",
+        "2. Files written (including the absolute preview.html path)",
+        "3. UI structure and states (by HTML section ID)",
         "4. Accessibility and responsive behavior",
         "5. Implementation notes",
         "6. Assumptions / open questions",
+        GROUNDED_REPORTING,
       ].join("\n"),
     ],
   ]);
@@ -186,21 +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([
-    ["role", "You are an opinionated staff design engineer."],
     [
-      "objective",
-      `Generate the next ${args.outputType} revision for: ${args.prompt}. Update the HTML preview in place using only the user's captured feedback from the latest live review. Apply the impeccable \`craft\` and \`polish\` sub-skills with deliberate restraint: this is a focused revision, not an internal critique pass.`,
+      "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.`,
     ],
-    ["design_system", args.designSystem],
-    ["reference_inspiration", args.referencesBrief],
     ["reference_context", args.importContext],
     ["reference_precedence", REFERENCE_PRECEDENCE],
     ["preview_artifact_path", args.previewPath],
@@ -208,25 +258,29 @@ function buildGenerateRevisionPrompt(args: {
     ["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",
       [
-        "1. Read the current HTML at preview_artifact_path with your file-read tool.",
-        "2. Treat `<user_feedback>` as the only refinement brief. Do not invent separate critique, screenshot, audit, or gate findings.",
-        "3. Every user note or accepted live change MUST be visibly addressed in the revised preview, or explicitly explained as a conflict with DESIGN.md/reference precedence in your summary.",
-        `4. Overwrite ${args.previewPath} with the revised self-contained HTML file. Do not branch the artifact and do not create extra preview files.`,
-        "5. Preserve strong existing design decisions unless the user feedback requires a change.",
-        "6. After writing, return a concise markdown summary of what changed and any user feedback you could not apply. Do NOT paste the HTML body.",
+        "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",
       [
-        "Markdown with headings:",
+        "In at most 400 words, return Markdown, not the HTML body:",
         "1. Revised artifact (path only)",
-        "2. User feedback addressed (each note/live change → how it was applied, or why it was deferred/conflicts)",
+        "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"),
     ],
   ]);
@@ -241,45 +295,52 @@ 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([
-      ["role", "You are an opinionated staff design engineer."],
       [
-        "objective",
-        `Export the final ${outputType} for "${prompt}" as a rich HTML spec the engineering team can read directly in a browser. The spec must embed or link the approved preview so reviewers see exactly what is being implemented. Apply the impeccable \`document\` sub-skill to produce a rich HTML spec that bundles the approved preview together with implementation guidance for another design/frontend engineer to implement.`,
+        "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.`,
       ],
-      ["design_system", designSystem],
       ["preview_artifact_path", previewPath],
       ["spec_artifact_path", specPath],
       ["final_design_summary", "{previous}"],
+      ["html_rules", HTML_PREVIEW_RULES],
+      ["anti_design_slop_rules", ANTI_SLOP_RULES],
+      ["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.`,
+      ],
       [
         "instructions",
         [
-          `1. Read the approved HTML at preview_artifact_path. Use it as the canonical source of truth for the agreed design.`,
-          `2. Use the Write tool to create a rich HTML document at exactly: ${specPath}. The spec must be a single self-contained HTML5 file.`,
-          "3. The spec MUST contain, in order: (a) a sticky header with the design title + status + run id, (b) an Executive Summary section, (c) a 'Live Preview' section that EMBEDS the approved design via either an `<iframe srcdoc=\"...\">` containing the full preview HTML or a side-by-side rendered copy of the preview inside an `<article class=\"preview-frame\">` container, (d) the six DESIGN.md sections (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) rendered with swatches/tables/code blocks, (e) Implementation handoff (Recommended files + components | Implementation steps | Usage example | Accessibility & responsive checklist | Validation commands | Known limitations), (f) Appendix linking to the raw preview file path.",
-          "4. Style the spec itself with care: high-density legible typography, generous whitespace, code blocks with monospaced font, swatches that render with the actual hex/oklch values, copy-to-clipboard hints in HTML comments.",
-          `5. Embed the absolute preview path (${previewPath}) and file URL (${previewFileUrl}) prominently so the user can open the live preview separately.`,
-          "6. Preserve assumptions and known limitations so implementers do not treat uncertain items as facts.",
-          "7. Do not introduce design requirements that were absent from the final design or DESIGN.md.",
-          "8. After writing, return a concise markdown summary of what is in the spec (NOT the HTML).",
+          "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.`,
         ].join("\n"),
       ],
-      ["html_rules", HTML_PREVIEW_RULES],
-      ["anti_design_slop_rules", ANTI_SLOP_RULES],
       [
         "output_format",
         [
-          "Return markdown with headings (NOT the HTML):",
+          "In at most 600 words, return Markdown, not the HTML:",
           "1. Spec written to (absolute path)",
           "2. Sections included",
           "3. How to open the spec (playwright-cli command + manual fallback path)",
@@ -289,6 +350,7 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
           "7. Accessibility / responsive checklist",
           "8. Validation commands",
           "9. Known limitations",
+          GROUNDED_REPORTING,
         ].join("\n"),
       ],
     ]),
@@ -299,29 +361,28 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
   await designContext
     .task("final-display", {
       prompt: taggedPrompt([
-        ["role", "You are an opinionated staff design engineer."],
-        [
-          "objective",
-          "Make the rich HTML spec visible to the user. Open the final spec.html with the playwright-cli skill's `playwright-cli` command so the user can review the agreed design and implementation handoff. This is post-export — do NOT solicit change requests; if the user wants more changes, tell them to re-run the workflow. Degrade gracefully if browser automation is unavailable.",
-        ],
         ["spec_path", specPath],
         ["spec_file_url", specFileUrl],
         ["preview_path", previewPath],
         ["preview_file_url", previewFileUrl],
         ["browser_use_guidelines", browserBootstrapRules],
+        ["role", "You are an opinionated staff design engineer."],
+        [
+          "objective",
+          "Show the exported spec with the playwright-cli skill's `playwright-cli` command. Export is complete, so do not solicit changes; direct further changes to a new `/workflow open-claude-design` run and degrade gracefully when browser automation is unavailable.",
+        ],
         [
           "instructions",
           [
-            "1. Probe for `playwright-cli` availability using the bootstrap rules above.",
-            `2. If available, run \`playwright-cli open ${specFileUrl}\`. If that reports a missing browser executable, follow the bootstrap rules and retry once, then \`playwright-cli snapshot\`.`,
-            "3. Do NOT run `show --annotate` or otherwise invite change requests: export is done and there is no further refinement pass. If the user wants changes, tell them to re-run `/workflow open-claude-design`.",
-            `4. Always print, prominently, the absolute paths so the user can open them manually:\n   - Final spec: ${specPath}\n   - Approved preview: ${previewPath}`,
-            "5. Do not block the workflow; return a structured summary even if no tooling worked.",
+            `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}`,
+            "Unavailable tooling must not block the workflow; return the structured summary.",
           ].join("\n"),
         ],
         [
           "output_format",
-          "Markdown with: `display_method` | `spec_path` | `preview_path` | `manual_open_instructions` | `next_action_hint` (how to re-run the workflow for further changes).",
+          `Under 250 words, return Markdown with: \`display_method\` | \`spec_path\` | \`preview_path\` | \`manual_open_instructions\` | \`next_action_hint\` (how to re-run the workflow). ${GROUNDED_REPORTING}`,
         ],
       ]),
       ...designModelConfig,