@bastani/atomic 0.9.11-alpha.1 → 0.9.11-alpha.11

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
@@ -32,6 +32,9 @@ 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)
 // ---------------------------------------------------------------------------
@@ -56,36 +59,31 @@ function buildDiscoveryInitPrompt(prompt: string): string {
 /skill:impeccable init
 
 ${taggedPrompt([
-    [
-      "role",
-      "You are an opinionated staff designer running the open-claude-design front door.",
-    ],
+    ["role", "You are an opinionated staff designer running the open-claude-design front door."],
     [
       "objective",
-      `In ONE workflow stage, first shape the request into a confirmed design brief, output type, and reference list for: ${prompt}. Then immediately run impeccable's \`init\` setup so PRODUCT.md and DESIGN.md are detected, created, or reconciled before downstream design research. Do not ask for or wait on a separate init stage.`,
+      `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 your `ask_user_question` tool for important gaps you cannot infer from the request or repo.",
-        `Cover: (a) what to build and core jobs/screens; (b) output type — one of ${outputTypes}; (c) references to emulate (URLs, local paths, screenshots, or design docs).`,
-        "Ask 2-3 questions per round; propose inferred answers as options, not finished facts.",
-        "User-provided references are the PRIMARY visual authority and take precedence over DESIGN.md/PRODUCT.md where they conflict.",
+        "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 the brief is confirmed, run `/skill:impeccable init` in this same stage.",
-        "Let impeccable init perform its own PRODUCT.md/DESIGN.md detection; do not rely on precomputed detection from the workflow runner.",
-        "Create missing PRODUCT.md and/or DESIGN.md when needed, and reconcile existing files against the confirmed brief. Never silently overwrite existing files.",
-        "When the files already exist, keep it light: load them, reconcile against the brief, and only ask about genuine gaps.",
-        "If headless, infer the most defensible brief/register from the prompt and repo signals, write explicit `## Gaps / Assumptions`, and never block.",
+        "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 final answer with: \`brief\` (confirmed expanded design brief), \`output_type\` (one of ${outputTypes}), and \`references\` (array of verbatim URLs/paths; empty array when none). In your visible summary, also include PRODUCT.md/DESIGN.md files written or reconciled and any assumptions.`,
+      `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}`,
     ],
   ])}`;
 }
@@ -132,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 {
@@ -143,59 +153,96 @@ export function buildReferenceDiscoveryPrompt(args: {
     (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 and design researcher curating best-in-class, current visual references.",
+      "You are an opinionated staff design engineer curating current, best-in-class visual references.",
     ],
     [
       "objective",
-      `Find beautiful, current reference designs the team can heavily reference to build a stunning ${args.outputType} for: ${args.prompt}. Open each gallery, CLICK THROUGH to the actual design pages of interest, and — ideally — record a scroll-through video of each page so its ANIMATIONS are captured (with a full-page screenshot as a supplement/fallback) plus its real destination URL. Apply the impeccable \`extract\` sub-skill to lift concrete, citable design traits — never vague adjectives.`,
+      `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.`,
     ],
-    ["reference_galleries", siteList],
-    ["design_context", args.designContextHint],
-    ["browser_use_guidelines", args.browserBootstrapRules],
-    ["screenshot_dir", args.artifactDir],
     [
       "instructions",
       [
-        "1. Use the playwright-cli skill to open each gallery above; if `playwright-cli` reports a missing browser executable, follow the bootstrap rules and retry once.",
-        "2. On each gallery, scan the thumbnail grid and pick 1-3 designs of interest whose aesthetic fits this brief.",
-        "3. CLICK INTO each chosen design to open its ACTUAL page — the live site or project detail the thumbnail links to (for example the gallery's 'visit site' / shot-detail link). Do NOT capture the gallery grid or the thumbnail; navigate to the real design page first.",
-        `4. Capture the design's MOTION, not just a still: record a scroll-through video of the ENTIRE page so scroll-triggered animations, parallax, reveals, and transitions are captured. Start with \`playwright-cli video-start ${join(args.artifactDir, "ref-<site>-<n>.webm")}\`, then scroll smoothly from top to bottom — a \`playwright-cli run-code\` script that scrolls in small increments with short waits, or repeated \`playwright-cli mousewheel 0 600\` with pauses — so animations fire and lazy content loads, then \`playwright-cli video-stop\`.`,
-        `5. ALSO take a FULL-PAGE still as a supplement/fallback: \`playwright-cli screenshot --full-page --filename=${join(args.artifactDir, "ref-<site>-<n>.png")}\`. If video recording is unavailable, the full-page screenshot is the minimum.`,
-        "6. Record the FULL destination URL you actually landed on (the live site / project URL, not the gallery listing URL), plus the work's title and author.",
-        "7. For every reference, extract the CONCRETE transferable trait (layout topology, type pairing, color strategy, spacing rhythm) AND the MOTION vocabulary you saw in the recording (entrance animations, scroll reveals, easing, parallax, hover/active states) — cite what you observed on the real page, not what you imagine.",
-        "8. For on-brand fit, consult the project's DESIGN.md / PRODUCT.md and the ds-* discovery evidence in <design_context>; prefer references that fit, and flag any that would require departing from the project's system.",
-        "9. After curating the strongest options, use ask_user_question to ask the user which reference direction they prefer. Offer 2-4 concise choices drawn from the best references/directions and include a clear `None of these fit` choice when appropriate.",
-        "10. If the user says none of the discovered references align with their preference, ask them to provide a reference image, screenshot, URL, or local file path for best results, and include that request and any answer in the final brief.",
-        "11. If `playwright-cli` is unavailable or a site blocks automation, fall back to web search / page fetch to reach the actual design pages, and clearly mark any reference you could not capture with a recording or full-page screenshot.",
-        "12. Never fabricate references or visual claims; if a gallery yielded nothing usable, say so.",
+        "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",
       [
-        "Markdown sections:",
+        "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: which curated direction/reference the user preferred, or that none aligned and a reference image/screenshot/URL/path was requested for best results.",
-        "3. Synthesis: the 3-5 strongest directions to emulate for THIS design, ranked by fit, calling out motion/animation worth reproducing.",
-        "4. What to avoid (anti-references observed on the real pages).",
-        "5. Verification notes (which references have a scroll-through recording and/or full-page screenshot of the actual design page vs search-only).",
+        "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"),
     ],
   ]);
 }
 
-/** 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)
 // ---------------------------------------------------------------------------
@@ -231,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
     ? [
@@ -250,23 +298,83 @@ export function buildLivePreviewDisplayPrompt(args: {
         "`next_action_hint`",
       ].join("\n");
   return taggedPrompt([
+    ["preview_path", args.previewPath],
+    ["preview_file_url", args.previewFileUrl],
+    ["browser_use_guidelines", args.browserBootstrapRules],
     [
       "role",
-      "You are an opinionated staff design engineer running interactive `live` QA so the user can iterate on the design in a real browser.",
+      "You are an opinionated staff design engineer running interactive `live` QA in a real browser.",
     ],
     ["objective", objective],
-    ["preview_path", args.previewPath],
-    ["preview_file_url", args.previewFileUrl],
-    ["browser_use_guidelines", args.browserBootstrapRules],
     ["interactive_live_qa", interactiveQa],
     [
       "graceful_degradation",
       [
-        `If \`/skill:impeccable live\` cannot boot (no dev server/HMR for the static file, missing config, or sandbox limits), fall back to opening the preview directly: \`playwright-cli open ${args.previewFileUrl}\`, then \`playwright-cli snapshot\`${isFinal ? "" : " and `playwright-cli show --annotate` so the user can draw/type notes on the page"}. If a \`playwright-cli\` command reports a missing browser executable, follow the bootstrap rules and retry once.`,
-        `If \`playwright-cli\` is also unavailable, print a clear instruction block telling the user to open the file manually at ${args.previewPath} (or ${args.previewFileUrl}).`,
-        "Never block the workflow on unavailable tooling; always exit with a non-empty status string.",
+        `If \`/skill:impeccable live\` cannot boot, open the preview with \`playwright-cli open ${args.previewFileUrl}\`, then run \`playwright-cli snapshot\`${isFinal ? "" : " and `playwright-cli show --annotate` for user notes"}. If the browser executable is missing, follow the bootstrap rules and retry once.`,
+        `If \`playwright-cli\` is unavailable, tell the user to open ${args.previewPath} or ${args.previewFileUrl} manually.`,
+        "Unavailable tooling must not block the workflow; return a non-empty status.",
       ].join("\n"),
     ],
-    ["output_format", outputFormat],
+    ["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/builtin/open-claude-design-utils.ts

@@ -176,23 +176,23 @@ export function prepareArtifactDir(cwd = process.cwd()): {
 }
 
 export const HTML_PREVIEW_RULES = [
-  "Produce a single self-contained HTML document. Inline all CSS in a <style> block and inline any JS in a <script> block; no external network requests except Google Fonts when explicitly required.",
-  "Embed realistic content that respects the design brief — no Lorem ipsum, no obvious placeholders.",
-  "Implement responsive behavior with sensible breakpoints (use container queries or media queries) so the file renders well from 360px up to 1440px.",
-  "Cover at minimum: default state, hover/focus state for every interactive element, empty state if relevant, loading state if relevant, error state if relevant.",
-  "Use accessible markup: semantic landmarks, labeled form controls, sufficient contrast (WCAG AA), visible focus styles, prefers-reduced-motion respected.",
-  "Annotate the file with HTML comments that mark sections, states, and design-system token references so engineers can read the intent quickly.",
+  "Produce one self-contained HTML document: inline CSS in <style> and JS in <script>; make no external requests except explicitly required Google Fonts.",
+  "Use realistic brief-specific content, not Lorem ipsum or obvious placeholders.",
+  "Render well from 360px to 1440px with sensible container or media-query breakpoints.",
+  "Include default and hover/focus states for every interactive element, plus empty, loading, and error states where relevant.",
+  "Use semantic landmarks, labeled controls, WCAG AA contrast, visible focus, and prefers-reduced-motion.",
+  "Add HTML comments marking sections, states, and design-system token references for engineering handoff.",
 ].join("\n");
 
 export const ANTI_SLOP_RULES = [
-  "Do not produce generic AI-slop palettes (purple/indigo gradients, blue-to-pink, neon glassmorphism stacks, nested card grids).",
-  "Avoid the AI design clichés impeccable's anti-pattern catalog calls out: gradient text for emphasis, side-tab borders, three-font headers, decorative shadows on flat-by-default systems.",
-  "Commit to a specific aesthetic direction; do not hedge with generic SaaS defaults.",
+  "Avoid generic AI palettes and structures: purple/indigo or blue-to-pink gradients, neon glassmorphism stacks, and nested card grids.",
+  "Avoid impeccable catalog clichés: gradient emphasis text, side-tab borders, three-font headers, and decorative shadows in flat-by-default systems.",
+  "Commit to a specific aesthetic rather than generic SaaS defaults.",
 ].join("\n");
 
 /** Reference-import precedence note shared by import, generation, and refinement. */
 export const REFERENCE_PRECEDENCE =
-  "User-provided references in <reference_context> are the PRIMARY visual authority: when they conflict with DESIGN.md/PRODUCT.md, follow the references. DESIGN.md governs decisions the references do not cover; PRODUCT.md still governs strategic register/voice.";
+  "User references in <reference_context> are the PRIMARY visual authority and override conflicting DESIGN.md/PRODUCT.md guidance. DESIGN.md governs uncovered design decisions; PRODUCT.md still governs strategic register/voice.";
 
 export type PlaywrightCliStatus = {
   /** Whether the `playwright-cli` command is expected to be available to downstream stages. */
@@ -299,21 +299,16 @@ export function ensurePlaywrightCli(): PlaywrightCliStatus {
   }
 }
 
-/**
- * Build the per-run browser bootstrap guidance injected into stage prompts.
- * When the deterministic setup step already ensured `playwright-cli` is installed,
- * the guidance tells stages to assume availability and not waste turns
- * reinstalling; otherwise it retains the original probe-and-install fallback.
- */
+/** Build browser guidance for downstream stage prompts. */
 export function buildPlaywrightCliBootstrapRules(status: PlaywrightCliStatus): string {
   const probeRule = status.available
-    ? "The workflow's deterministic setup step already ensured the playwright-cli skill's `playwright-cli` command is installed and on PATH; assume it is available and do NOT reinstall it. Only if a `playwright-cli` command reports it is missing should you re-probe with `which playwright-cli` (or `npx --no-install playwright-cli --version`) and run `npm install -g @playwright/cli@latest` once before retrying. Do not add project dependencies."
-    : `The workflow's deterministic setup step attempted to install the playwright-cli skill's \`playwright-cli\` command but it FAILED with: "${status.error ?? "unknown error"}". Treat this as a known starting condition to work around, not a hard blocker. Probe with \`which playwright-cli\` (or \`npx --no-install playwright-cli --version\`) and retry once with \`npm install -g @playwright/cli@latest\`; if it still fails, use the error above to diagnose a workaround (for example: EACCES/permission errors → retry with a user-writable global prefix; missing npm/Node → report it plainly; network/registry errors → surface them). If the command still cannot be made available, degrade gracefully and surface the manual file path / URL. Do not add project dependencies.`;
+    ? "The playwright-cli skill's `playwright-cli` command is on PATH. Do not reinstall it unless a command reports it missing; then probe with `which playwright-cli` (or `npx --no-install playwright-cli --version`), run `npm install -g @playwright/cli@latest` once, and retry. Do not add project dependencies."
+    : `The playwright-cli skill's \`playwright-cli\` command failed setup: "${status.error ?? "unknown error"}". Probe with \`which playwright-cli\` (or \`npx --no-install playwright-cli --version\`) and retry once with \`npm install -g @playwright/cli@latest\`. For permission errors, use a user-writable global prefix; report missing npm/Node or network/registry errors plainly. If still unavailable, surface the manual file path / URL. Do not add project dependencies.`;
   return [
     probeRule,
-    "Use `playwright-cli open <url>` when a generated local preview should be visible to the user, and use `playwright-cli snapshot` plus `playwright-cli screenshot --filename=<file>` for review evidence.",
-    "If a `playwright-cli` command reports a missing browser executable, install the browser once with `npx playwright install chromium` and retry.",
-    "If `playwright-cli` is unavailable after three attempts or the browser runtime still fails, degrade gracefully and surface the manual file path / URL.",
+    "Use `playwright-cli open <url>` to show a local preview; use `playwright-cli snapshot` and `playwright-cli screenshot --filename=<file>` for review evidence.",
+    "If a `playwright-cli` command reports a missing browser executable, run `npx playwright install chromium` once and retry.",
+    "If `playwright-cli` is unavailable after three attempts or the browser runtime still fails, surface the manual file path / URL.",
   ].join("\n");
 }
 

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

@@ -18,6 +18,7 @@
 
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runOpenClaudeDesignWorkflow } from "./open-claude-design-runner.js";
 import {
   DEFAULT_MAX_REFINEMENTS,
@@ -56,5 +57,5 @@ export default workflow({
     spec_file_url: Type.Optional(Type.String({ description: "file:// URL for the generated spec.html file." })),
     playwright_cli_status: Type.Optional(Type.String({ description: "Outcome of the initial deterministic step that ensures the playwright-cli skill's `playwright-cli` command is installed." })),
   },
-  run: async (ctx) => await runOpenClaudeDesignWorkflow(ctx),
+  run: async (ctx) => await runOpenClaudeDesignWorkflow(withSteeringPropagationContext(ctx)),
 });

package/dist/builtin/workflows/builtin/ralph-core.ts

@@ -1,9 +1,12 @@
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { Type } from "typebox";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
-import { LITERAL_OBJECTIVE_CONTRACT } from "./shared-prompts.js";
+import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
+import {
+  E2E_VERIFICATION_GUIDANCE,
+  LITERAL_OBJECTIVE_CONTRACT,
+} from "./shared-prompts.js";
 import type { ReviewDecision, ReviewFinding } from "./ralph-review-gate.js";
 import { reviewDecisionApproved } from "./ralph-review-gate.js";
 import {
@@ -167,8 +170,8 @@ export function defaultResearchPath(prompt: string, now = new Date()): string {
   return join(DEFAULT_RESEARCH_DIR, `${date}-${slugifyResearchTopic(prompt)}.md`);
 }
 
-export async function createImplementationNotesFile(prompt: string): Promise<string> {
-  const notesDir = await mkdtemp(join(tmpdir(), "atomic-ralph-notes-"));
+export async function createImplementationNotesFile(prompt: string, runId?: string): Promise<string> {
+  const notesDir = await createWorkflowArtifactDirectory(runId);
   const notesPath = join(notesDir, IMPLEMENTATION_NOTES_FILENAME);
   const initialNotes = [
     "# Implementation Notes",
@@ -177,7 +180,8 @@ export async function createImplementationNotesFile(prompt: string): Promise<str
     "",
     "## Running Notes",
     "",
-    "- Record implementation decisions, deviations from the research findings, tradeoffs, blockers, validation notes, and anything else the user should know.",
+    "- Record implementation decisions, deviations from research, tradeoffs, blockers, validation outcomes, and user-relevant facts. Keep entries concise and readable.",
+    "- 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.",
   ].join("\n");
   await writeFile(notesPath, `${initialNotes}\n`, {
     encoding: "utf8",
@@ -191,19 +195,17 @@ export async function createImplementationNotesFile(prompt: string): Promise<str
 // write to it; the video file itself is produced by the orchestrator's QA pass
 // (and overwritten each iteration so it always reflects the latest state). The
 // final pull-request stage attaches it when it exists.
-export async function createQaEvidenceVideoPath(): Promise<string> {
-  const qaDir = await mkdtemp(join(tmpdir(), "atomic-ralph-qa-"));
+export async function createQaEvidenceVideoPath(runId?: string): Promise<string> {
+  const qaDir = await createWorkflowArtifactDirectory(runId);
   return join(qaDir, QA_E2E_VIDEO_FILENAME);
 }
 
 export function renderQaE2eVideoGuidance(qaVideoPath: string): string {
   return [
-    "QA the change end-to-end whenever it touches user-visible UI behavior, including full-stack changes whose UI correctness depends on backend/API behavior. Use the `playwright-cli` skill (or delegate to a subagent with `skill: \"playwright-cli\"`) to drive the running application like a user and prove the implemented scenario actually works.",
-    `Record that QA E2E pass as a reviewable video so the user can watch the feature working. After \`playwright-cli open\`, start recording with \`playwright-cli video-start ${qaVideoPath}\`, annotate the scenario with \`playwright-cli video-chapter\` / \`playwright-cli video-show-actions\`, exercise the full user scenario, then \`playwright-cli video-stop\`. Write the video to exactly this path and overwrite any prior recording so it always reflects the latest implemented state: ${qaVideoPath}`,
-    `After recording, add the video to the implementation notes as a reference: include a \`## QA E2E Video\` entry with the absolute path ${qaVideoPath} and a one-line description of the proven scenario, so the user can review the proof when this stage finishes.`,
-    "If the change has no user-visible UI scenario (pure refactor, docs, infra, or non-UI library code), do not fabricate a video; record in the implementation notes that no QA E2E video applies and why.",
-    "Assume credentials, auth, and browser environment access exist until a concrete attempt proves otherwise. Before declaring the QA E2E video impractical, check credential/auth state with non-destructive commands, attempt to launch the app/flow, and record the exact command(s) plus observed failure output.",
-    "If `playwright-cli` or a browser runtime is unavailable, install it once per the skill (`npm install -g @playwright/cli@latest`, then `npx playwright install chromium` for a missing browser executable). If it still cannot run, record the smallest validation actually performed and note that the QA E2E video could not be produced — never claim a video exists when it does not.",
+    E2E_VERIFICATION_GUIDANCE,
+    `For a user-visible UI scenario, record the QA pass for review. After \`playwright-cli open\`, use \`playwright-cli video-start ${qaVideoPath}\`, annotate with \`playwright-cli video-chapter\` / \`playwright-cli video-show-actions\`, exercise the complete scenario, then run \`playwright-cli video-stop\`. Write to exactly ${qaVideoPath}, overwriting stale evidence.`,
+    `Add a \`## QA E2E Video\` entry to the implementation notes with the absolute path ${qaVideoPath} and one sentence naming the proven scenario. For changes without a user-visible UI scenario, record why video does not apply; never fabricate one.`,
+    "If `playwright-cli` or its browser runtime is unavailable, install it once per the skill (`npm install -g @playwright/cli@latest`, then `npx playwright install chromium` when needed). If a concrete attempt still fails, record the commands, observed failure output, smallest validation performed, and that no video was produced.",
   ].join("\n");
 }
 
@@ -333,29 +335,29 @@ export function renderResearchPromptRefinementPrompt(args: {
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
 }): string {
-  const basePrompt = `/skill:prompt-engineer Transform the following user request into a codebase and online research question which can be thoroughly explored: ${args.request}`;
-  return [
-    basePrompt,
-    taggedPrompt([
-      ["objective", `Research the full requested task: ${args.request}`],
-      ["acceptance_criteria", args.acceptanceCriteria],
-      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
-      args.workflowCwdContext,
-      [
-        "review_findings",
-        args.latestReviewReportPath === undefined
-          ? "No prior review artifact is available."
-          : [
-              `Latest review round artifact: ${args.latestReviewReportPath}`,
-              "Read this JSON artifact and include unresolved reviewer findings in the transformed research question only when they are consistent with the literal objective and acceptance criteria.",
-            ].join("\n"),
-      ],
-      [
-        "output_format",
-        "Return only the transformed codebase and online research question. Do not implement code changes and do not write an RFC/spec.",
-      ],
-    ]),
-  ].join("\n\n");
+  return taggedPrompt([
+    ["acceptance_criteria", args.acceptanceCriteria],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined
+        ? "No prior review artifact is available."
+        : [
+            `Latest review round artifact: ${args.latestReviewReportPath}`,
+            "Include unresolved reviewer findings in the transformed research question only when consistent with the literal objective and acceptance criteria.",
+          ].join("\n"),
+    ],
+    ["objective", `Research the full requested task: ${args.request}`],
+    [
+      "output",
+      "Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.",
+    ],
+    [
+      "instruction",
+      `/skill:prompt-engineer Transform this request into a codebase and online research question that covers the full requested task: ${args.request}`,
+    ],
+  ]);
 }
 
 
@@ -365,35 +367,35 @@ export function renderResearchPrompt(args: {
   readonly acceptanceCriteria: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
-  readonly researchPath: string;
 }): string {
-  const basePrompt = `/skill:research-codebase ${args.transformedResearchQuestion}`;
-  return [
-    basePrompt,
-    taggedPrompt([
-      ["objective", `Research implementation requirements for: ${args.prompt}`],
-      ["acceptance_criteria", args.acceptanceCriteria],
-      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
-      args.workflowCwdContext,
-      [
-        "review_findings",
-        args.latestReviewReportPath === undefined
-          ? "No prior review artifact is available."
-          : [
-              `Latest review round artifact: ${args.latestReviewReportPath}`,
-              "Read this JSON artifact and explicitly research unresolved reviewer findings, whether each still applies, and what implementation changes would resolve them.",
-            ].join("\n"),
-      ],
+  return taggedPrompt([
+    ["acceptance_criteria", args.acceptanceCriteria],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined
+        ? "No prior review artifact is available."
+        : [
+            `Latest review round artifact: ${args.latestReviewReportPath}`,
+            "Research whether each unresolved finding still applies and what objective-aligned implementation change would resolve it.",
+          ].join("\n"),
+    ],
+    ["objective", `Research implementation requirements for: ${args.prompt}`],
+    [
+      "research_artifact",
       [
-        "research_artifact",
-        [
-          `Write research findings for this workflow run to: ${args.researchPath}`,
-          "Return a complete Markdown research report with codebase findings, online/contextual findings when useful, concrete implementation guidance, relevant files/tests/docs, unresolved reviewer finding analysis, and validation recommendations.",
-          "Do not author an RFC/spec and do not implement code changes in this stage.",
-        ].join("\n"),
-      ],
-    ]),
-  ].join("\n\n");
+        "Return the complete research report as your final message. Downstream implementation and review stages read it from there.",
+        "Produce a complete Markdown report with codebase and useful online/contextual findings, implementation guidance, relevant files/tests/docs, unresolved-finding analysis, and validation recommendations. Lead with conclusions; keep facts, caveats, and implementation-relevant next steps; drop background and repetition.",
+        "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.",
+        "Do not author an RFC/spec or implement code changes.",
+      ].join("\n"),
+    ],
+    [
+      "instruction",
+      `/skill:research-codebase ${args.transformedResearchQuestion}`,
+    ],
+  ]);
 }
 
 
@@ -413,6 +415,7 @@ export type RalphWorkflowOptions = {
   readonly comparisonBaseBranch: string;
   readonly workflowStartCwd: string;
   readonly createPr: boolean;
+  readonly runId?: string;
 };
 
 export type RalphWorkflowResult = {