@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.8

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

@@ -1,347 +0,0 @@
-import type { WorkflowParallelOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "../src/shared/types.js";
-import {
-  REFERENCE_PRECEDENCE,
-  buildPlaywrightCliBootstrapRules,
-  discoveryDecisionSchema,
-  ensurePlaywrightCli,
-  joinResults,
-  prepareArtifactDir,
-  shouldEarlyExitForBrowser,
-  taggedPrompt,
-} from "./open-claude-design-utils.js";
-import { exportOpenClaudeDesign, refineOpenClaudeDesign } from "./open-claude-design-phases.js";
-import {
-  NO_REFERENCES_BRIEF,
-  buildReferenceDiscoveryPrompt,
-  designContextPath,
-  persistDesignContext,
-  persistReferencesBrief,
-  referencesBriefPath,
-  runDiscoveryAndInit,
-  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.";
-const DELEGATION_RULE =
-  "Delegate further only work genuinely independent and too large for a handful of tool calls; do not delegate self-verification, and prefer one subagent over several.";
-
-type OpenClaudeDesignOutputs = {
-  readonly output_type?: string; readonly design_system?: string; readonly artifact?: string; readonly handoff?: 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 };
-  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;
-};
-
-export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext): Promise<OpenClaudeDesignOutputs> {
-  const designContext = ctx;
-
-  // Initial deterministic setup step (no LLM): ensure the playwright-cli skill's
-  // `playwright-cli` command is installed before any design stage runs. Best-effort.
-  const playwrightCli = ensurePlaywrightCli();
-  const browserBootstrapRules = buildPlaywrightCliBootstrapRules(playwrightCli);
-
-  const inputs = designContext.inputs;
-  const prompt = inputs.prompt;
-  const discoverReferences = inputs.discover_references !== false;
-
-  const workflowCwd = designContext.cwd ?? process.cwd();
-  const { runId, artifactDir, previewPath, specPath } = prepareArtifactDir(
-    workflowCwd,
-  );
-  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
-  // cleanly up front (surfacing artifact paths) rather than generating a design
-  // no one can review. Gated off under NODE_ENV=test / runtimes without ctx.exit.
-  if (
-    shouldEarlyExitForBrowser(playwrightCli.available, process.env.NODE_ENV) &&
-    typeof designContext.exit === "function"
-  ) {
-    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: 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 = {
-    model: "anthropic/claude-opus-5:high",
-    fallbackModels: [
-      "github-copilot/claude-opus-5:high",
-      "anthropic/claude-fable-5:high",
-      "github-copilot/claude-fable-5:high",
-      "kimi-coding/k3:max",
-      "moonshotai/kimi-k3:max",
-      "moonshotai-cn/kimi-k3:max",
-      "anthropic/claude-opus-4-8:high",
-      "github-copilot/claude-opus-4.8:high",
-      "openai-codex/gpt-5.6-sol:xhigh",
-      "github-copilot/gpt-5.6-sol:xhigh",
-      "openai/gpt-5.6-sol:xhigh",
-      "xai/grok-4.6:xhigh",
-      "github-copilot/grok-4.6:xhigh",
-      "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.6",
-    ],
-  };
-  // Phase 1: combined discovery + init — one stage interviews the user via
-  // impeccable `shape`, then immediately runs impeccable `init` so PRODUCT.md /
-  // DESIGN.md are detected, created, or reconciled before design research.
-  const frontDoor = await runDiscoveryAndInit({
-    designContext,
-    prompt,
-    discoveryConfig: { ...designModelConfig, schema: discoveryDecisionSchema },
-  });
-  const discovery = frontDoor.discovery;
-  const designBrief = discovery.brief;
-  const outputType = discovery.output_type;
-  const references = discovery.references;
-  const projectContext = frontDoor.projectContext;
-
-  const userReferenceContext = references.length > 0
-    ? references.map((ref, index) => `${index + 1}. ${ref}`).join("\n")
-    : "No user-provided references were collected during discovery.";
-  const referenceHandlingRules = references.length > 0
-    ? [
-        REFERENCE_PRECEDENCE,
-        "For URL references, use browser/screenshot tooling when available and cite only observable traits.",
-        "For files, screenshots, or design docs, read or parse the source directly and quote concrete evidence.",
-        "Include a `Reference requirements` section so the generator receives the imported constraints.",
-      ].join("\n")
-    : "No user references to import. Focus on project context and curated reference-discovery when present.";
-
-  // Phase 3 (combined): a single fan-out gathers project design-system evidence
-  // and references. The ds-* stages now also import user URLs/files directly.
-  const dsSteps: WorkflowTaskStep[] = [
-    {
-      name: "ds-locator",
-      task: taggedPrompt([
-        ["user_references", userReferenceContext],
-        ["reference_handling", referenceHandlingRules],
-        ["browser_use_guidelines", browserBootstrapRules],
-        ["role", "You are an opinionated staff design engineer."],
-        [
-          "objective",
-          `Find UI/design-system sources for: ${designBrief}. Apply impeccable \`extract\` to codebase evidence and user reference URLs/files that should steer generation.`,
-        ],
-        ["delegation_rule", DELEGATION_RULE],
-        [
-          "instructions",
-          [
-            "Locate UI components, stylesheets, tokens, Storybook/examples, screenshots, tests, design docs, and user references.",
-            "Report concrete file, URL, or artifact paths and why each informs generation; separate primary sources, supporting examples, and reference-only inspiration.",
-            "If no explicit system exists, report the strongest implicit evidence such as repeated literals and dominant component patterns.",
-          ].join("\n"),
-        ],
-        [
-          "output_format",
-          `In at most 500 words, return Markdown sections: Project sources table | User reference sources | Reference requirements | Confidence notes. ${GROUNDED_REPORTING}`,
-        ],
-      ]),
-      ...designModelConfig,
-    },
-    {
-      name: "ds-analyzer",
-      task: taggedPrompt([
-        ["user_references", userReferenceContext],
-        ["reference_handling", referenceHandlingRules],
-        ["browser_use_guidelines", browserBootstrapRules],
-        [
-          "impeccable_skill",
-          "audit — score 0–4 across Accessibility, Performance, Theming, Responsive, Anti-patterns. Tag every finding P0 (blocks release) → P3 (polish). Document, do not fix.",
-        ],
-        ["role", "You are an opinionated staff design engineer."],
-        [
-          "objective",
-          `Independently audit UI constraints for: ${designBrief}. Scan the repository, assess evidence across impeccable's six quality dimensions, and capture or parse user references without relying on another stage's output.`,
-        ],
-        ["delegation_rule", DELEGATION_RULE],
-        [
-          "instructions",
-          [
-            "Inspect the UI stack, styling, tokens, responsive behavior, accessibility conventions, and component APIs.",
-            "Ground each claim in exact paths, symbols, code examples, screenshots, URLs, or quoted reference excerpts.",
-            "Identify integration constraints the generated design must follow, and state uncertainty when evidence is incomplete.",
-          ].join("\n"),
-        ],
-        [
-          "output_format",
-          `In at most 700 words, return Markdown sections in this order: Stack | Tokens | Components | Layout / responsiveness | Accessibility | Audit scores (per dimension, 0–4) | Reference requirements | Hard constraints for generation. ${GROUNDED_REPORTING}`,
-        ],
-      ]),
-      ...designModelConfig,
-    },
-    {
-      name: "ds-patterns",
-      task: taggedPrompt([
-        ["user_references", userReferenceContext],
-        ["reference_handling", referenceHandlingRules],
-        ["browser_use_guidelines", browserBootstrapRules],
-        ["role", "You are an opinionated staff design engineer."],
-        [
-          "objective",
-          `Extract reusable patterns and anti-patterns for: ${designBrief}. Apply impeccable \`extract\` to repository evidence and user references, translating them into generation guidance without relying on another stage's output.`,
-        ],
-        ["delegation_rule", DELEGATION_RULE],
-        [
-          "instructions",
-          [
-            "Find reusable naming, variant, composition, state, animation, and layout patterns.",
-            "Cite concrete paths, component/symbol names, reference URLs, or quoted file/screenshot evidence.",
-            "Identify generated-design anti-patterns using impeccable's 25 deterministic anti-patterns; do not generalize beyond repository or reference evidence.",
-          ].join("\n"),
-        ],
-        [
-          "output_format",
-          `In at most 600 words, return Markdown sections: Reusable patterns | Examples | Reference requirements | Anti-patterns | Generation implications. ${GROUNDED_REPORTING}`,
-        ],
-      ]),
-      ...designModelConfig,
-    },
-  ];
-
-  const onboardingAnalysis = await designContext.parallel(dsSteps, {
-    task: designBrief,
-  });
-  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,
-          designContextFile,
-          artifactDir,
-          browserBootstrapRules,
-        }),
-        reads: [designContextFile],
-        ...designModelConfig,
-      })
-    : undefined;
-
-  const referencesBriefRaw = (referenceResult?.text ?? "").trim();
-  const referencesBrief =
-    referencesBriefRaw.length > 0 ? referencesBriefRaw : NO_REFERENCES_BRIEF;
-  // 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
-    ? [
-        REFERENCE_PRECEDENCE,
-        "Reference sources:",
-        userReferenceContext,
-        "",
-        "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 refinement = await refineOpenClaudeDesign({
-    designContext,
-    prompt: designBrief,
-    outputType,
-    previewPath,
-    previewFileUrl,
-    browserBootstrapRules,
-    designContextFile,
-    referencesFile,
-    designModelConfig,
-    workflowCwd,
-    importContext,
-    ui: designContext.ui,
-  });
-  const latestDesign = refinement.latestDesign;
-
-  const exportResult = await exportOpenClaudeDesign({
-    designContext,
-    prompt: designBrief,
-    outputType,
-    previewPath,
-    previewFileUrl,
-    specPath,
-    specFileUrl,
-    browserBootstrapRules,
-    designContextFile,
-    referencesFile,
-    latestDesign,
-    designModelConfig,
-  });
-  const handoff = exportResult.handoff;
-
-  return {
-    output_type: outputType,
-    design_system: "project-derived design system",
-    artifact: latestDesign,
-    handoff: handoff.text,
-    import_context: importContext,
-    run_id: runId,
-    artifact_dir: artifactDir,
-    preview_path: previewPath,
-    preview_file_url: previewFileUrl,
-    spec_path: specPath,
-    spec_file_url: specFileUrl,
-    playwright_cli_status: playwrightCli.summary,
-  };
-}

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

@@ -1,313 +0,0 @@
-/**
- * open-claude-design setup helpers.
- *
- * Capabilities that delegate to the accessible `impeccable` skill
- * (`/skill:impeccable …`), factored into this module so the runner and phases
- * files stay focused:
- *
- *   1. Discovery + init front door: one `discovery` stage runs
- *      `/skill:impeccable shape` and `/skill:impeccable init`, interviews the
- *      user for the design brief/output type/references, then lets impeccable
- *      detect/create/reconcile PRODUCT.md and DESIGN.md in the same stage.
- *   2. Reference discovery: browse five curated galleries (Awwwards,
- *      recent.design, Dribbble, Monet, Motionsites) and synthesize a references
- *      brief the generator heavily emulates.
- *   3. Live interactive QA prompt: drive `/skill:impeccable live` against the
- *      static preview.html so the user picks elements, annotates, and accepts
- *      on-brand variants in the browser. cross-ref: impeccable `reference/live.md`.
- */
-
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import type { WorkflowTaskResult } from "../src/shared/types.js";
-import {
-  OUTPUT_TYPES,
-  discoveryDecisionFromResult,
-  taggedPrompt,
-  type DiscoveryDecision,
-} from "./open-claude-design-utils.js";
-
-type SetupModelConfig = Record<string, object | string | readonly string[]>;
-type SetupDesignContext = {
-  task(name: string, options: object): Promise<WorkflowTaskResult>;
-};
-
-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.";
-
-// ---------------------------------------------------------------------------
-// 0. Discovery + init front door (one workflow stage)
-// ---------------------------------------------------------------------------
-
-export type ProjectDesignContextResult = {
-  readonly summary: string;
-};
-
-export function renderDiscoveryContext(discovery: DiscoveryDecision): string {
-  return [
-    `Confirmed design brief: ${discovery.brief}`,
-    `Output type: ${discovery.output_type}`,
-    discovery.references.length > 0
-      ? `References to emulate (take precedence over DESIGN.md/PRODUCT.md): ${discovery.references.join(", ")}`
-      : "References to emulate: none provided.",
-  ].join("\n");
-}
-
-function buildDiscoveryInitPrompt(prompt: string): string {
-  const outputTypes = OUTPUT_TYPES.join(", ");
-  return `/skill:impeccable shape
-/skill:impeccable init
-
-${taggedPrompt([
-    ["role", "You are an opinionated staff designer running the open-claude-design front door."],
-    [
-      "objective",
-      `In one stage, confirm the design brief, output type, and references for: ${prompt}. Then run impeccable's \`init\` so PRODUCT.md and DESIGN.md are detected, created, or reconciled before design research; do not wait for another init stage.`,
-    ],
-    [
-      "interview",
-      [
-        "Use `ask_user_question` for important gaps not inferable from the request or repository.",
-        `Cover the product and core jobs/screens, one output type (${outputTypes}), and references to emulate (URLs, local paths, screenshots, or design docs).`,
-        "Ask 2-3 questions per round and present inferred answers as options rather than facts.",
-        "User references are the PRIMARY visual authority and override conflicting DESIGN.md/PRODUCT.md guidance.",
-      ].join("\n"),
-    ],
-    [
-      "init_instructions",
-      [
-        "After confirmation, run `/skill:impeccable init` in this stage. Let impeccable init perform its own PRODUCT.md/DESIGN.md detection rather than relying on runner detection.",
-        "Create missing files when needed and reconcile existing ones without silently overwriting them; ask only about genuine gaps.",
-        "When headless, infer the most defensible brief/register from the prompt and repository, record explicit `## Gaps / Assumptions`, and do not block.",
-      ].join("\n"),
-    ],
-    [
-      "output_format",
-      `Return the structured fields \`brief\`, \`output_type\` (one of ${outputTypes}), and \`references\` (verbatim URL/path array, empty when none). In at most 250 words, summarize PRODUCT.md/DESIGN.md changes and assumptions. ${GROUNDED_REPORTING}`,
-    ],
-  ])}`;
-}
-
-export async function runDiscoveryAndInit(args: {
-  readonly designContext: SetupDesignContext;
-  readonly prompt: string;
-  readonly discoveryConfig: SetupModelConfig;
-}): Promise<{
-  readonly discovery: DiscoveryDecision;
-  readonly discoveryContext: string;
-  readonly projectContext: ProjectDesignContextResult;
-}> {
-  const result = await args.designContext.task("discovery", {
-    prompt: buildDiscoveryInitPrompt(args.prompt),
-    ...args.discoveryConfig,
-  });
-  const discovery = discoveryDecisionFromResult(result, args.prompt);
-  return {
-    discovery,
-    discoveryContext: renderDiscoveryContext(discovery),
-    projectContext: {
-      summary: [
-        "Ran `/skill:impeccable shape` + `/skill:impeccable init` in the combined discovery stage.",
-        (result.text ?? "").trim(),
-      ].filter((part) => part.length > 0).join("\n\n"),
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// 1. Reference discovery
-// ---------------------------------------------------------------------------
-
-/** Curated galleries of beautiful, current reference designs. */
-export const REFERENCE_DESIGN_SITES: readonly { readonly name: string; readonly url: string }[] = [
-  { name: "Awwwards", url: "https://www.awwwards.com/websites/" },
-  { name: "recent.design", url: "https://recent.design/" },
-  { name: "Dribbble (recent shots)", url: "https://dribbble.com/shots/recent" },
-  { name: "Monet", url: "https://www.monet.design/c" },
-  { name: "Motionsites", url: "https://motionsites.ai/" },
-];
-
-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 designContextFile: string;
-  readonly artifactDir: string;
-  readonly browserBootstrapRules: string;
-}): string {
-  const siteList = REFERENCE_DESIGN_SITES.map(
-    (site, index) => `${index + 1}. ${site.name} — ${site.url}`,
-  ).join("\n");
-  return taggedPrompt([
-    ["reference_galleries", siteList],
-    [
-      "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],
-    [
-      "role",
-      "You are an opinionated staff design engineer curating current, best-in-class visual references.",
-    ],
-    [
-      "objective",
-      `Curate references for a ${args.outputType} serving: ${args.prompt}. Open actual design pages, capture motion with scroll-through video when possible and a full-page screenshot as fallback, record destination URLs, and apply impeccable \`extract\` to report concrete observed traits.`,
-    ],
-    [
-      "instructions",
-      [
-        "Use the playwright-cli skill to open each gallery; if `playwright-cli` reports a missing browser executable, follow the bootstrap rules and retry once.",
-        "From each gallery, choose 1-3 fitting designs and CLICK INTO each actual live or project-detail page; do not capture only the grid or thumbnail.",
-        `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 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"),
-    ],
-    [
-      "output_format",
-      [
-        "In at most 900 words, return these Markdown sections:",
-        "1. Curated references (table: Source gallery | Work (title/author) | Full page URL (destination) | Scroll-through video path | Full-page screenshot path | Transferable trait (incl. motion) | On-brand?)",
-        "2. User preference check (selected direction, or none plus the requested/provided reference)",
-        "3. Synthesis (3-5 strongest directions ranked by fit, including motion to reproduce)",
-        "4. What to avoid (observed anti-references)",
-        "5. Verification notes (actual-page video/screenshot versus search-only)",
-        GROUNDED_REPORTING,
-      ].join("\n"),
-    ],
-  ]);
-}
-
-/**
- * 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(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 (the user-feedback review session)
-// ---------------------------------------------------------------------------
-
-
-// ---------------------------------------------------------------------------
-// 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 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",
-  "Skip remaining review rounds and export as-is",
-] as const;
-
-/**
- * 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 round: number;
-  readonly previewPath: string;
-  readonly previewFileUrl: string;
-}): string {
-  return [
-    `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 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");
-}
-
-/**
- * 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);
-}