@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

package/dist/builtin/workflows/README.md

@@ -54,7 +54,7 @@ Workflow lifecycle notices are enabled by default. They send steer prompts into
 }
 ```
 
-Set `enabled` to `false` to disable all lifecycle notices, or narrow `notifyOn` to a non-empty list of selected events. Completion, failure, and blocked lifecycle notices are emitted for top-level workflow runs, use steer delivery, and wake an idle model so the lifecycle update enters the model context when it happens. Nested child workflow completion/failure is reflected inside the expanded parent graph instead of producing separate top-level completion cards. Awaiting-input states are tracked for dedupe/restore, but workflows do not enqueue main-chat `/workflow connect` cards for them; prompt state remains visible through workflow status/connect surfaces, avoiding stale actionable cards if a prompt resolves while the main chat is streaming.
+Set `enabled` to `false` to disable all lifecycle notices, or narrow `notifyOn` to a non-empty list of selected events. Completion, failure, and blocked lifecycle notices are emitted for top-level workflow runs, use steer delivery, and wake an idle model so the lifecycle update enters the model context when it happens. When a fulfilled workflow body leaves admitted tool failures, the engine promotes the first admission and persists that exact tool origin for the failed notice. Ordinary body rejections retain their original error and failed graph nodes without claiming a tool origin because transparent native promises do not expose the source promise; this prevents a caught tool rejection from being misattributed when body code later throws the same object or primitive. Nested child workflow completion/failure is reflected inside the expanded parent graph instead of producing separate top-level completion cards. Awaiting-input states are tracked for dedupe/restore, but workflows do not enqueue main-chat `/workflow connect` cards for them; prompt state remains visible through workflow status/connect surfaces, avoiding stale actionable cards if a prompt resolves while the main chat is streaming.
 
 When a stage human-in-the-loop prompt is answered from the workflow TUI/stage chat, workflows also emits a separate display-only `workflows:hil-answer-notice` custom message. It records the answer for user-visible audit, but it does not wake the main agent, enter LLM context, or authorize answering later workflow prompts. Answers sent by the main-chat `workflow` tool do not emit this notice because the tool result already tells the main agent what happened.
 
@@ -62,9 +62,23 @@ When a stage human-in-the-loop prompt is answered from the workflow TUI/stage ch
 
 ## Authoring API
 
+### Dynamic topology is DAG-only
+
+Atomic `workflow({ run })` definitions are imperative, dynamic TypeScript. Discovery loads modules and validates imports and definition shape, but it does not compile every `run` path into a complete graph or prove acyclicity. Runtime inputs, branches, loops, external data, model or human output, helpers, and nested workflows determine the materialized topology during execution.
+
+**Cyclic workflow graphs are unsupported. Authors and coding agents MUST NOT create a self-edge or a dependency edge from the current frontier to an existing ancestor. Every materialized execution topology must remain a DAG. Redesign or stop before launch if a cycle cannot be removed.**
+
+Sketch branches, loops, and nested boundaries before launch. Bounded loops must create distinct tracked work per iteration with stable identity and call order; never reopen an ancestor beneath its downstream work. Compose children through `ctx.workflow(...)` boundaries rather than recursive `run` invocation. Keep retained-session follow-up that creates no dependency work as activity, not a back-edge.
+
+Execution, replay, and DBOS hydration are the authoritative topology-validation points. Runtime topology changes should add incremental edge checks and DBOS hydration validation; prompt guidance and TypeScript types cannot replace these checks.
+
 ### Workflow-owned side effects
 
-Prefer `ctx.tool(name, args, fn)` for workflow-owned TypeScript operations with side effects, including filesystem writes, network mutations, external API actions, and similar deterministic operations orchestrated directly by the workflow definition. Atomic durably caches a completed call's serializable result, so resume returns that result without rerunning `fn` or repeating the side effect. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately.
+Prefer `ctx.tool(name, args, fn)` for workflow-owned TypeScript operations with side effects, including filesystem writes, network mutations, external API actions, and similar deterministic operations orchestrated directly by the workflow definition. Each invocation creates a non-chat, non-attachable durable graph node before `fn` runs; it may appear before, between, after, or without model stages. Atomic durably caches a completed call's serializable result, so resume returns that result without rerunning `fn` or repeating the side effect. Tool-only workflows are valid tracked execution, while a normal return with no stage, child, tool, or explicit exit remains invalid. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately. The executor closes tool admission before publishing any terminal outcome; calling a retained `ctx.tool` function afterward returns a rejected native promise and creates no callback, retry, graph node, or checkpoint.
+
+Checks that may fail as part of a repair loop can opt into `failureMode: "return"`. That overload returns a typed `{ ok: true, value, attempts, cached } | { ok: false, error, attempts, cached }` outcome after configured retries. Failure details preserve exposed `exitCode`, `stdout`, and `stderr`; persisted text is best-effort secret-redacted and limited to 16 KiB per field. A recoverable failure keeps its tool node failed but lets author code continue. Replay returns the same durable outcome with `cached: true` and does not rerun the callback. Cancellation and storage faults still throw. Atomic never injects this evidence into a later prompt: pass the needed fields to a repair stage or artifact explicitly, and use distinct serializable arguments for each bounded rerun.
+
+New tool checkpoints retain stable graph identity, invocation order, parents, and timing. A current-format checkpoint created before tool topology was added still replays safely: its cached output remains authoritative and the callback is never rerun. Root inspection derives deterministic fallback identity/order from checkpoint identity and record order; replay inside a child attempts to append topology metadata with the current child/boundary ownership without replacing the original output checkpoint. That additive migration write is best-effort: a storage rejection leaves the live replay cached in its inferred child, does not poison a later durable flush, and is retried by a later replay. Until one retry succeeds, a fresh completed inspection can only show the legacy record through the deterministic root fallback with topology unavailable; historical child ownership cannot be reconstructed from the old record alone. Fresh completed inspection reconstructs available tool topology but does not persist a workflow's declared root output; that existing limitation is separate from live `run()` output and graph correctness.
 
 ### Example 1 — Single task
 
@@ -186,36 +200,43 @@ Prefer regular TypeScript module imports for reusable child workflows: import th
 ```typescript
 import { workflow } from "@bastani/workflows";
 import { Type } from "typebox";
-import goal from "@bastani/workflows/builtin/goal";
-import sharedResearch from "./shared-research.js";
+import { adversarialVerification, fanOutAndSynthesize } from "@bastani/workflows/builtin";
 
 export default workflow({
-  name: "research-and-synthesize",
-  description: "Run shared research, implement from it, then synthesize the result.",
-  inputs: {
-    topic: Type.String(),
-  },
+  name: "research-and-verify",
+  description: "Map repository slices, synthesize cited evidence, then verify the report.",
+  inputs: { topic: Type.String() },
   outputs: {
-    final: Type.String({ description: "Synthesis of the child research and implementation." }),
+    report_path: Type.String(),
+    approved: Type.Boolean(),
   },
   run: async (ctx) => {
-    const child = await ctx.workflow(sharedResearch, {
-      inputs: { topic: ctx.inputs.topic },
+    const research = await ctx.workflow(fanOutAndSynthesize, {
+      inputs: {
+        prompt: `Partition repository research for: ${ctx.inputs.topic}. Save cited findings per slice and synthesize conflicts.`,
+        max_branches: 6,
+      },
     });
+    if (research.exited) return ctx.exit({ status: research.status, reason: research.exitReason ?? "research stopped early" });
 
-    const implementation = await ctx.workflow(goal, {
-      inputs: { objective: `Implement improvements based on: ${String(child.outputs.summary)}` },
+    const verification = await ctx.workflow(adversarialVerification, {
+      inputs: { task: `Verify the cited report at ${research.outputs.synthesis_path}` },
     });
+    if (verification.exited) return ctx.exit({ status: verification.status, reason: verification.exitReason ?? "verification stopped early" });
 
-    const final = await ctx.task("synthesize", {
-      prompt: `Synthesize this research and implementation:\n\n${String(child.outputs.summary)}\n\n${String(implementation.outputs.result)}`,
-    });
-    return { final: final.text };
+    return {
+      report_path: research.outputs.synthesis_path,
+      approved: verification.outputs.approved,
+    };
   },
 });
 ```
 
-The child executes as a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default, but user-facing status and graph views flatten it into the parent run. In practice it should feel like inlining the child workflow code: child stages, HIL prompt nodes, and deeper imported children appear in one expanded parent graph, while implementation-owned child run ids stay hidden from top-level `/workflow status` lists. The child still has a run id internally so the graph can attach to, pause, interrupt, or resume live child stages correctly. Inputs are strictly validated against the child workflow before it starts: unknown keys, missing required values, type mismatches, and invalid `select` choices fail before the child body runs. The parent receives the child's declared `outputs` on `child.outputs` after those outputs pass their declared runtime type checks.
+The child executes as a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default, but user-facing status and graph views recursively replace that boundary with a valid, non-empty child graph whose run reciprocally identifies the parent run and boundary stage. Every boundary parent connects to every child root, and every child terminal connects to each downstream dependent. Repeated or sibling children keep distinct virtual node ids and exact `{ runId, stageId }` control targets even when local stage ids or names collide, so attach, send, pause, interrupt, resume, stage selection, and post-mortem chat reach the true owning run and stage. Implementation-owned child runs stay out of top-level `/workflow status` lists.
+
+For durable runs, Atomic writes and awaits a versioned boundary-start identity before child code can run. That record fixes the boundary id, child run id, owning root/parent, source order and parents, replay scope, alias, workflow, and a deterministic fingerprint of the child definition plus exact validated inputs across pause, process restart, cached replay, and completed inspection. Distinct-input parallel calls therefore keep their own cache even when restart reverses dispatch order; repeated identical calls share the fingerprint but retain a per-invocation ordinal. A completed child boundary and its `ctx.tool` side effects replay exactly once from the root's scoped checkpoints; only incomplete work continues.
+
+If no valid child graph can stand in for the boundary—including a failed or skipped boundary, a missing or empty child graph, stale or mismatched ownership metadata, or a recursive link that cannot produce a valid expansion—the expanded graph keeps the boundary summary instead of flattening an unrelated or invalid child. Exact expanded ids resolve first; a local id, prefix, or stage name is accepted only when it identifies one visible stage. Inputs are strictly validated against the child workflow before it starts: unknown keys, missing required values, type mismatches, and invalid `select` choices fail before the child body runs. The parent receives the child's declared `outputs` on `child.outputs` after those outputs pass their declared runtime type checks.
 
 For workflows intended to be called as children, declare an `outputs` entry for every non-default field a parent should rely on. `outputs` is only the schema/contract: use normal TypeScript in `run()` to gather values from any stage/task/child workflow and return those keys.
 
@@ -249,11 +270,19 @@ Builtin workflows are also callable as modules for reuse:
 
 ```typescript
 import {
-  adversarialVerification, classifyAndAct, deepResearchCodebase,
-  fanOutAndSynthesize, generateAndFilter, goal, loopUntilDone,
-  openClaudeDesign, ralph, tournament,
+  adversarialVerification,
+  classifyAndAct,
+  fanOutAndSynthesize,
+  generateAndFilter,
+  goal,
+  loopUntilDone,
+  openClaudeDesign,
+  ralph,
+  tournament,
 } from "@bastani/workflows/builtin";
+import fanOutAndSynthesizeWorkflow from "@bastani/workflows/builtin/fan-out-and-synthesize";
 import goalWorkflow from "@bastani/workflows/builtin/goal";
+import ralphWorkflow from "@bastani/workflows/builtin/ralph";
 import openClaudeDesignWorkflow from "@bastani/workflows/builtin/open-claude-design";
 ```
 
@@ -546,7 +575,7 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 | `/workflow list`                      | List all registered workflows with descriptions          |
 | `/workflow status [run-id]`           | Show active plus retained terminal/current-session runs, or details for one run |
 | `/workflow connect [run-id]`          | Open a workflow run graph                                |
-| `/workflow attach [run-id] [stage]`   | Open the attach/chat pane for a run or stage             |
+| `/workflow attach [run-id] [stage]`   | Open live stage chat or explicit terminal post-mortem chat |
 | `/workflow pause [run-id] [stage]`    | Pause a live run or stage                                |
 | `/workflow interrupt [run-id\|--all]` | Pause active/named/all active runs so they can resume    |
 | `/workflow quit [run-id\|--all]`      | Gracefully pause live workflow runs so they can resume later          |
@@ -560,15 +589,15 @@ Named workflow launches always run as **background tasks** in interactive sessio
 
 Named launches return only after startup admission, while the admitted workflow body and stages remain background work. Pre-body setup failures (including invalid input-bound reusable worktrees) are returned immediately from the original tool call as structured failed results with the concrete error and allocated run id; Atomic does not first claim that the workflow started, and it removes the unadmitted run so corrected inputs can be retried immediately. Failures after admission continue to use normal background status and lifecycle notices.
 
-Graceful quit is idempotent for already-paused runs and preserves unresolved `ctx.ui` prompts in DBOS. Stable author-callsite-and-composed-nested-scope reservations are created before prompting and released by exact current-format token generation after answer checkpoint, rejection, or abort. Answering while quit/paused cannot advance workflow code until explicit resume.
+Graceful quit is idempotent for already-paused runs and preserves unresolved `ctx.ui` prompts in DBOS. Pausing or interrupting a stage also holds every queued steering and follow-up item in place: no queued turn, late context-bearing delivery, or workflow continuation starts while the stage is paused, and the existing `resume` action releases the items once in their existing per-queue order without queue release itself starting a provider turn. Stable author-callsite-and-composed-nested-scope reservations are created before prompting and released by exact current-format token generation after answer checkpoint, rejection, or abort. Answering while quit/paused cannot advance workflow code until explicit resume.
 
 Workflow durability requires DBOS/Postgres. Atomic configures and launches DBOS lazily on the first workflow action, reuses that process-wide instance, and awaits readiness before durable execution or control. Initialization or persistence failures fail the workflow action; no alternate backend is selected. `DBOS_SYSTEM_DATABASE_URL` selects an existing database when supplied; otherwise Atomic runs DBOS against its own embedded Postgres (npm-distributed binaries, detached `pg_ctl` daemon under `~/.atomic/postgres` on port 5439, shared across sessions and never stopped by Atomic), with DBOS's `dbos-db` Docker container only as a platform fallback. Concurrent Atomic sessions safely share one database: unique per-process executor ids, owner/heartbeat metadata on running workflows, and first-writer-wins claims on contended status transitions prevent double dispatch. Running workflows never appear as resume targets in any session; stale-heartbeat (crashed) ones surface as red `crashed` rows, paused rows render yellow, failed/blocked red, completed green, and the open picker live-updates on local changes plus a bounded cross-session poll.
 
-DBOS is the only durable catalog for resume, completed inspection, deletion, and targeted lookup. Session JSONL files remain chat transcripts only. Atomic reads and writes one current format; prior local workflow state and older DBOS records are not converted or discovered.
+DBOS is the only durable catalog for resume, completed inspection, deletion, and targeted lookup. Session JSONL files remain chat transcripts only. Atomic reads one current durable format and does not convert prior local state or pre-current DBOS records. A completed current-format child checkpoint created before boundary-start or invocation-fingerprint identity existed is shown only when its child checkpoints reciprocally prove the same root, parent run, boundary, child owner, and scope. Active checkpoints without a provable invocation fingerprint, and malformed, duplicate, stale, nonreciprocal, mixed, aliased, cyclic, orphaned, or unsupported topology, fail closed before cache exposure or child/control dispatch: Atomic does not invent a child link or execute child code to repair it.
 
-Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. The run-level `quit` action targets the selected top-level run or all live top-level runs. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `quit`, `resume`, `reload`, and `inputs`.)
+Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. After a fresh process starts, active and completed graphs retain source stage ids, order, parent edges, lifecycle status, boundary ownership, and exact `{ runId, stageId }` control targets. The `workflow` tool's `stages`, `stage`, `transcript`, `pause`, `interrupt`, and `resume` actions route a uniquely identified visible child stage to that nested owner; `send` uses the same routing only while the root is nonterminal, and ambiguous local ids or names are rejected. Run-level `quit` still targets the selected top-level run or all live top-level runs. Completed graph inspection is read-only even when no stage transcript remains. `/workflow attach <root-run> <nested-stage>` remains the explicit user-driven path for retained post-mortem chat and routes to the true child owner without resuming or mutating execution. Programmatic `workflow send` rejects terminal roots before nested-owner routing or session probing. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `quit`, `resume`, `reload`, and `inputs`.)
 
-Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, custom prompt identity hash, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node. Arbitrary custom-widget answers cannot be supplied with `workflow send`; focus the `custom` awaiting-input node in the interactive graph instead.
+Raw stage-chat prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a raw stage-chat answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Durable `ctx.ui` responses are separate DBOS checkpoints: resume returns those cached responses without asking again, and graph-backed UI re-materializes the answered prompt node from metadata. Replay keys include prompt kind, message text, select choices, input/editor initial value, custom prompt identity hash, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node. Arbitrary custom-widget answers cannot be supplied with `workflow send`; focus the `custom` awaiting-input node in the interactive graph instead.
 
 ### `workflow` tool (LLM-callable)
 
@@ -577,7 +606,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 ```json
 {
   "name": "workflow",
-  "description": "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/quit runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.",
+  "description": "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.",
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
@@ -603,7 +632,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 - **`renderCall`** — renders a compact workflow call summary in the chat scroll.
 - **`renderResult`** — renders the result or dispatch banner; live progress continues through the widget and graph viewer. Named workflow runs are background-oriented.
 - **`transcript`** — path-only by default when a transcript file exists: use `status`, `stages`, or `stage` to identify the stage and its `sessionFile`/`transcriptPath`, quote the exact path without changing platform separators (for example, preserve Windows backslashes), then search that file with `rg`/`grep` for targeted terms and read only small surrounding ranges. Default text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals plus a `lazyReadPrompt`, with `entries: not inlined` so transcript bodies and tool outputs stay out of model context. Passing explicit `tail` or `limit` opts into a bounded inline preview for quick context checks. If no transcript path is available, the action falls back to a bounded preview of up to 5 recent entries with a `fallbackNote`. A registered live stage handle is used when one exists, even before live messages arrive; otherwise the action falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies only to inlined snapshot previews or no-path fallback previews; live session transcripts may not expose tool output.
-- **`send`** — answers pending primitive/structured stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. Follow-ups to eligible terminal agent stages revive an interactive **post-mortem chat** through the shared resolver: on a live-handle miss the stage's retained `sessionFile` is validated (existing, readable, context-bearing) and reopened as a detached, single-flight handle so the message is delivered as a conversational follow-up appended in place — the same path used by `/workflow attach`, restored/replayed durable snapshots, and completed-workflow inspection — without resuming, retrying, or re-dispatching workflow execution. If no valid retained session exists, the follow-up is refused (`No live handle for stage.`) instead of silently resetting or exposing a handle-less non-terminal session. Arbitrary `ctx.ui.custom<T>` widget prompts require the interactive workflow graph and return a clear unsupported message when targeted through `send`. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
+- **`send`** — operates only while the authoritative root workflow is nonterminal. It answers pending primitive/structured stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or starts/queues the eligible live turn. Terminal `completed`, `failed`, `skipped`, `cancelled`, `killed`, and terminal `blocked` roots fail closed with `status: "failed"`, `code: "WORKFLOW_TERMINAL"`, `delivery: "rejected"`, the requested root id/status, and guidance to start a new workflow (or proceed inline only for small, deterministic, low-risk work). The preflight guard rejects already-terminal roots before stage resolution, nested-owner routing, prompt inspection, retained-session probing/revival, handle lookup, message admission, or delivery selection, so it creates no session/handle/model/tool/file work, appends no transcript, answers no input, and mutates no workflow/stage snapshot. Missing or malformed retained sessions receive the same error without probing. A second check against the same shared authority runs at final synchronous SDK admission: if a live root terminates while retained-session creation is pending, Atomic rejects the send, disposes its unclaimed provisional session/handle, and starts no prompt, model, tool/file, transcript, or workflow-state work. Concurrent explicit `/workflow attach` or Intercom claims remain independent. Use `/workflow attach <run-id> <stage>` as the user-driven post-mortem path; that chat can append to a valid retained session but never resumes or changes workflow execution state.
 - **`reload`** — refreshes workflow resources directly in-process instead of queuing a literal `/workflow reload` chat follow-up.
 - **`models`** — returns safe model-catalog metadata from the configured registry. Each entry contains `provider` (e.g. `openai`), `id` (e.g. `gpt-4`), `fullId` (e.g. `openai/gpt-4`), `isCurrent` (whether this is the active model), and `availableThinkingLevels`, canonically derived from the registry model's `reasoning` and `thinkingLevelMap` metadata. The result is a configured-auth snapshot: it shows which models are present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. No secrets, tokens, or authentication details are returned.
 
@@ -647,6 +676,8 @@ For large handoffs, prefer artifact paths over prompt injection: write stage out
 
 Workflow stage sessions follow Atomic SDK directory defaults: `DefaultResourceLoader` is initialized with the project `cwd` and the Atomic default `~/.atomic/agent` directory, while legacy `.pi` paths remain readable where the SDK supports multiple config directories. A stage-supplied `agentDir` is treated as an explicit user override; a stage-supplied `resourceLoader` owns discovery, with `cwd`/`agentDir` left for session naming and tool path resolution.
 
+Custom `AgentSessionAdapter` runtimes may optionally expose `queuedMessagesPaused`, `pauseQueuedMessages()`, and `resumeQueuedMessages()` on public `StageSessionRuntime`. Existing adapters that omit them retain the prior fallback pause behavior: the active call is aborted and runner-admitted public deliveries stay deferred until explicit resume. When both methods are present, Atomic uses the stronger native hold so raw queued steer/follow-up work is gated before abort settles and released without starting a provider turn. Atomic's official runtime implements this optional capability.
+
 To inspect a workflow's input schema inside pi, use `/workflow inputs <name>` or `/workflow <name> --help`.
 
 ---
@@ -692,68 +723,39 @@ const convergence = await ctx.workflow(loopUntilDone, {
 
 The parent can consume `fixes.outputs`, `verification.outputs`, and `convergence.outputs` directly, and can repeat the verification child per patch when its own typed input lists individual patch artifacts.
 
-### `deep-research-codebase`
+### Repository-wide research
 
-Heavy research for tasks requiring comprehensive, whole-repository context.
+For broad repository uncertainty, compose `fan-out-and-synthesize` with a partition prompt that produces distinct subsystem slices, writes each branch to an artifact, and requires the synthesis barrier to cite concrete paths and resolve conflicting findings. Use `/skill:research-codebase` when one focused subsystem or question is enough.
 
 ```text
-/workflow deep-research-codebase prompt="How does session persistence work?"
+/workflow fan-out-and-synthesize prompt="Partition session persistence by subsystem, save cited findings per branch, and synthesize the end-to-end flow"
 ```
 
-| Input             | Type     | Required | Default | Description                                               |
-| ----------------- | -------- | -------- | ------- | --------------------------------------------------------- |
-| `prompt`          | `text`   | ✓        | —       | Research question or topic to investigate.                |
-| `max_partitions`  | `number` | —        | `100`   | Maximum number of codebase partitions to explore.         |
-| `max_concurrency` | `number` | —        | `100`   | Maximum number of workflow stages to run concurrently.    |
+### Task-specific implementation and review
 
-Final Markdown research documents are written to dated `research/` paths relative to the current working directory, with a numeric suffix if needed to avoid overwriting an existing document. Hidden run artifacts are written under `research/.deep-research-<run-id>/`.
-
-Child workflow outputs: `result`, `findings`, `research_doc_path`, `artifact_dir`, `manifest_path`, `partitions`, `explorer_count`, `specialist_count`, `max_concurrency`, and `history`.
+Domain-specific implementation should use a custom worker → fresh verifier → reducer graph when no installed pattern covers the complete contract. Keep literal acceptance criteria visible to each reviewer, execute deterministic checks through workflow-owned tools, consolidate evidence-backed findings into bounded repair rounds, and stop on explicit approval, blocked evidence, or iteration exhaustion. Keep PR/MR creation, release, deployment, and publication as separately authorized post-approval actions.
 
 ### `goal`
 
-Goal Runner workflow: initialize a persisted goal ledger with a per-run goal id, immutable `acceptance_criteria`, and lifecycle events, render goal-continuation context, run bounded worker LM turns, append receipts, run three independent reviewers with objective-alignment findings and clause-by-clause requirements traceability, let a TypeScript reducer decide `complete`, `continue`, `blocked`, or `needs_human`, and optionally run a final-stage PR handoff after approval. All three reviewers start in clean, non-forked contexts like Ralph's reviewers and use Ralph's exact `reviewer-a` model chain, led by Claude Fable 5. At review start, every concurrent reviewer checks Intercom, discovers sibling reviewers in the same run, communicates its validation plan, and coordinates ownership and serialization of expensive, lock-prone, or conflicting shared-checkout/shared-environment commands. Reviewers announce coordinated check starts and finishes, release claimed resources, and share reusable execution evidence while still independently inspecting the patch and producing their own verdicts. Workers begin from an observable acceptance/contract matrix derived from the literal objective/acceptance criteria and are prompted to model states, transitions, and invariants explicitly for stateful work; each review round's findings are consolidated into a deduplicated cross-reviewer batch (`consolidated_findings` in the round artifact) that the next worker turn repairs together, with durable regression evidence required for reproduced findings. Reviewers independently derive adversarial checks from the literal contract before relying on the worker receipt or worker-authored tests. Workers and reviewers are prompted to verify user-visible behavior end-to-end when practical with `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios; they must assume credentials/auth/environment access exists until concrete checks plus an actual app/flow launch attempt prove otherwise, and skipped E2E must cite exact attempted commands and observed failure output. Reviewers also look for any QA E2E video referenced by the ledger or receipt and inspect the actual video before treating it as proof. Token budget behavior is intentionally excluded. Goal skips PR creation by default; prompt text alone does not opt in. Pass `create_pr=true` to authorize only the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation after Goal reaches `complete` within the turn budget.
-
-Resource release is itself a coordinated update: after releasing a claim, the reviewer explicitly notifies its siblings through Intercom rather than treating release as a silent local action.
+Goal runs a bounded autonomous implementation loop with a durable objective ledger, immutable acceptance criteria, sub-agent orchestration receipts, parallel reviewers, and a deterministic reducer. It returns `complete`, `blocked`, or `needs_human`; set `create_pr=true` only to authorize the final PR/MR/review stage after approval.
 
 ```text
-/workflow goal objective="Migrate the database layer to Drizzle ORM" base_branch=develop
-/workflow goal objective="Migrate the database layer to Drizzle ORM and open a PR when complete" base_branch=develop create_pr=true
+/workflow goal objective="Update CLI docs, add one example, and validate the docs build"
 ```
 
-| Input         | Type     | Required | Default       | Description                                                   |
-| ------------- | -------- | -------- | ------------- | ------------------------------------------------------------- |
-| `objective`   | `text`   | ✓        | —             | Goal-runner objective or delta.                               |
-| `acceptance_criteria` | `text` | — | objective | Original immutable task contract; pass the original task text when launching follow-up Goal runs from reviewer findings. |
-| `max_turns`   | `number` | —        | `10`          | Maximum worker/review turns before human follow-up is needed. |
-| `base_branch` | `string` | —        | `origin/main` | Branch reviewers and the optional final stage compare the current delta with. |
-| `create_pr`    | `boolean` | —        | `false`       | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation after Goal reaches `complete`. |
-
-`goal` defaults to 10 worker/review turns. Reviewer quorum is fixed internally at 2 reviewer `complete` votes, and approval is deterministic on each reviewer's self-reported `stop_review_loop` boolean: a reviewer approves exactly when it returns `stop_review_loop=true` with no `reviewer_error` (parse failures count as non-approval), and the reducer completes the run when quorum of those booleans is met. Findings and `requirements_traceability` remain required audit evidence and drive the reviewer prompts that derive the flag (`required_by_objective` findings mean `false` at any priority, P3 included; `consistent_with_objective` P3 nice-to-haves, out-of-scope observations, the quorum process itself, and the authorized post-approval PR final action must not hold the flag at `false`), but the harness does not recompute approval from those arrays. Without quorum, the decision reason records the reviewers' remaining work, and the bounded loop stops inspectably at `max_turns` as `needs_human`. The repeated-blocker threshold defaults to 3 consecutive same-blocker turns and is clamped to `max_turns` when you run fewer than 3 turns.
-
-Child workflow outputs: `result`, `status`, `approved`, `goal_id`, `objective`, `acceptance_criteria`, `ledger_path`, `turns_completed`, `iterations_completed`, `receipts`, `remaining_work`, `review_report`, and `review_report_path`. `pr_report` is included only when `create_pr=true`, Goal reaches `complete`, and the final `pull-request` stage runs.
+Inputs: required `objective`; optional `acceptance_criteria`, `max_turns=10`, `base_branch=origin/main`, `git_worktree_dir=""`, and `create_pr=false`.
 
 ### `ralph`
 
-Raw prompt → prompt-engineering research → orchestrate → review workflow with optional final-stage PR handoff: use the raw prompt as the operative objective, keep optional `acceptance_criteria` as the immutable original task contract (defaulting to `prompt`), transform the prompt into a codebase and online research question with `/skill:prompt-engineer`, run `/skill:research-codebase` against it, write findings under `research/`, delegate implementation through sub-agents from that research, run parallel reviewers across Claude Fable 5 and GPT-5.5 Codex model families, and iterate until approval or the loop limit. At review start, each concurrent Ralph reviewer checks Intercom, discovers same-run sibling reviewers, communicates its validation plan, claims expensive or lock-prone checks, and coordinates serialization of conflicting shared-checkout/shared-environment commands. Reviewers announce coordinated check starts and finishes, release claimed resources, and share reusable command evidence, but each still independently inspects the patch and returns its own verdict. Ralph's research, orchestrator, and reviewer prompts receive the objective next to the literal acceptance contract; when launching follow-up Ralph runs from reviewer findings, pass the ORIGINAL task text as `acceptance_criteria` so deltas cannot drift from the contract. The orchestrator begins from an observable acceptance/contract matrix derived from the literal prompt/acceptance criteria, models states/transitions/invariants explicitly for stateful work, and repairs unresolved reviewer findings as one consolidated batch (the round artifact carries a deduplicated cross-reviewer `consolidated_findings` list) with durable regression evidence for reproduced findings. Reviewers independently derive adversarial checks from the literal contract before relying on the implementation notes, orchestrator report, or worker-authored tests, and each reviewer derives a single authoritative `stop_review_loop` boolean from that evidence (`required_by_objective` findings mean `false` at any priority, P3 included, while `consistent_with_objective` P3 nice-to-haves stay non-blocking); the loop gate approves deterministically on that boolean plus a null `reviewer_error` without recomputing approval from the findings arrays. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical with `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. They must assume credentials/auth/environment access exists until concrete non-destructive checks plus an actual launch/flow attempt prove otherwise; skipped E2E is valid only when exact attempted commands and observed failure output are recorded. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video, references it in the implementation notes, and exposes it as the `qa_video_path` output; reviewers receive that path and inspect the actual video before treating it as proof. Review decisions include `requirements_traceability`, a non-empty clause-by-clause map over every prompt/acceptance-criteria requirement kept as audit evidence for deriving the flag; worker-authored tests/snapshots passing are circular evidence unless tied to independent current-state proof, and process-only clauses (reviewer quorum, the authorized post-approval PR final action) must never hold `stop_review_loop` at `false`. When `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. Follow-up iterations pass unresolved review artifacts into prompt-engineering/research and fork research from prior research session data when available. Ralph skips PR creation by default; prompt text alone does not opt in. Pass `create_pr=true` to authorize only the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation (for example GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling). Ralph's own PR-creation instructions live in that final stage. Reviewers inspect repository infrastructure directly as needed; Ralph no longer runs separate `infra-*` discovery stages.
-
-Resource release is itself a coordinated update: after releasing a claim, the reviewer explicitly notifies its sibling through Intercom rather than treating release as a silent local action.
+Ralph runs prompt refinement, codebase research, delegated implementation, and independent multi-model review in a bounded loop. It can start from a task, issue, or spec path; set `create_pr=true` only to authorize the post-approval final stage.
 
 ```text
-/workflow ralph prompt="Migrate the database layer to Drizzle ORM" max_loops=3 base_branch=develop
-/workflow ralph prompt="Migrate the database layer to Drizzle ORM" max_loops=3 base_branch=develop create_pr=true
+/workflow ralph prompt="Implement specs/rate-limit.md and validate burst traffic" max_loops=3
 ```
 
-| Input                 | Type      | Required | Default       | Description                                                   |
-| --------------------- | --------- | -------- | ------------- | ------------------------------------------------------------- |
-| `prompt`              | `text`    | ✓        | —             | Task, feature request, issue summary, or spec path to research, execute, refine, and review. |
-| `acceptance_criteria` | `text`    | —        | prompt        | Original immutable task contract; pass the original task text when launching follow-up Ralph runs from reviewer findings. |
-| `max_loops`           | `number`  | —        | `10`          | Maximum research/orchestrate/review iterations before completion or optional final handoff. |
-| `base_branch`         | `string`  | —        | `origin/main` | Branch reviewers and the optional final stage compare the current delta with; also used to create a missing worktree. |
-| `git_worktree_dir`    | `string`  | —        | `""`          | Optional reusable Git worktree root. Empty runs in the invoking checkout; non-empty values run Ralph stages in the created/reused worktree. |
-| `create_pr`           | `boolean` | —        | `false`       | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation. |
+Inputs: required `prompt`; optional `acceptance_criteria`, `max_loops=10`, `base_branch=origin/main`, `git_worktree_dir=""`, and `create_pr=false`.
 
-Child workflow outputs: `result`, `plan` (latest transformed research question), `plan_path` (compatibility alias for `research_path`), `research`, `research_path`, `implementation_notes_path`, `qa_video_path` (reviewable QA end-to-end proof video recorded with `playwright-cli` for UI-applicable changes, when produced), `approved`, `iterations_completed`, `review_report`, and `review_report_path`. `pr_report` is included only when `create_pr=true` and the final `pull-request` stage runs.
+For either workflow, keep PR/MR creation out of the task text and pass the original task as `acceptance_criteria` on follow-up runs to prevent contract drift.
 
 ### `open-claude-design`
 

package/dist/builtin/workflows/ambient.d.ts

@@ -25,11 +25,6 @@ declare module "@bastani/workflows/builtin/classify-and-act" {
 	export { default } from "@bastani/atomic/workflows/builtin/classify-and-act";
 }
 
-declare module "@bastani/workflows/builtin/deep-research-codebase" {
-	export * from "@bastani/atomic/workflows/builtin/deep-research-codebase";
-	export { default } from "@bastani/atomic/workflows/builtin/deep-research-codebase";
-}
-
 declare module "@bastani/workflows/builtin/fan-out-and-synthesize" {
 	export * from "@bastani/atomic/workflows/builtin/fan-out-and-synthesize";
 	export { default } from "@bastani/atomic/workflows/builtin/fan-out-and-synthesize";

package/dist/builtin/workflows/builtin/adversarial-verification-prompts.ts

@@ -1,15 +1,18 @@
+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 READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
+
 export function renderWorkerPrompt(task: string): string {
-  return `<role>\nYou produce a candidate solution for independent verification.\n</role>\n\n<objective>\n${task}\n</objective>\n\n<requirements>\nComplete the task, preserve concrete evidence, and state every validation performed. Do not claim success without observable support.\n</requirements>\n\n<output_format>\nA self-contained candidate with actions taken, evidence, validation, and remaining risks.\n</output_format>`;
+  return `<role>\nYou produce a candidate solution for independent verification.\n</role>\n\n<success_criteria>\nThe task is complete and important claims have observable support. Preserve concrete evidence and state every validation performed.\n</success_criteria>\n\n<stop_rules>\nStop when the candidate is complete and validated where practical, or state the evidence still missing.\n</stop_rules>\n\n<output_format>\nA self-contained candidate with actions taken, evidence, validation, and remaining risks. ${READABLE_REPORT}\n${GROUNDED_REPORTING}\n</output_format>\n\n<objective>\n${task}\n</objective>`;
 }
 
 export function renderVerifierPrompt(task: string, candidatePath: string, rubricPath: string): string {
-  return `<role>\nYou are an independent adversarial verifier. Find blockers; do not rewrite the candidate.\n</role>\n\n<objective>\nVerify the candidate against the task and rubric. Task: ${task}\n</objective>\n\n<artifacts>\nRead the complete candidate at ${candidatePath} and rubric at ${rubricPath}.\n</artifacts>\n\n<requirements>\nTest important claims where practical. A pass requires concrete evidence for every rubric item. Report precise blocking findings; absence of evidence is not evidence of correctness.\n</requirements>\n\n<output_format>\nCall structured_output with verdict (pass or fail), evidence, and blocking_findings.\n</output_format>`;
+  return `<artifacts>\nRead the complete candidate at ${candidatePath} and rubric at ${rubricPath}.\n</artifacts>\n\n<role>\nYou are an independent adversarial verifier. Find blockers; do not rewrite the candidate.\n</role>\n\n<success_criteria>\nA pass requires concrete evidence for every rubric item; absence of evidence is not evidence of correctness.\n</success_criteria>\n\n<evidence_rules>\nTest important claims where practical. For each conclusion, report the command run, observed output, and file:line evidence where applicable. Report precise blocking findings. ${GROUNDED_REPORTING}\n</evidence_rules>\n\n<stop_rules>\nStop after every rubric item has pass evidence or a precise blocking finding.\n</stop_rules>\n\n<output_format>\nCall structured_output with verdict (pass or fail), concise evidence, and blocking_findings. ${READABLE_REPORT}\n</output_format>\n\n<objective>\nVerify the candidate against the task and rubric. Task: ${task}\n</objective>`;
 }
 
 export function renderReducerPrompt(task: string, candidatePath: string, verifierPaths: readonly string[], repairsCompleted: number, maxRepairs: number): string {
-  return `<role>\nYou reduce independent verification reports into one deterministic next action.\n</role>\n\n<objective>\nDecide whether the candidate for ${task} is accepted, rejected, or needs repair.\n</objective>\n\n<artifacts>\nCandidate: ${candidatePath}\nVerifier reports: ${verifierPaths.join(", ")}\n</artifacts>\n\n<decision_rules>\nAccept only when all material rubric requirements have pass evidence. Request repair when findings are actionable and repair budget remains (${repairsCompleted}/${maxRepairs}). Reject when evidence proves the candidate cannot satisfy the task or the repair budget is exhausted. Preserve unresolved blockers verbatim.\n</decision_rules>\n\n<output_format>\nCall structured_output with decision (accept, reject, or repair), rationale, and remaining_work.\n</output_format>`;
+  return `<artifacts>\nCandidate: ${candidatePath}\nVerifier reports: ${verifierPaths.join(", ")}\n</artifacts>\n\n<role>\nYou reduce independent verification reports into one deterministic next action.\n</role>\n\n<decision_rules>\nAccept only when all material rubric requirements have pass evidence. Request repair when findings are actionable and repair budget remains (${repairsCompleted}/${maxRepairs}). Reject when evidence proves the candidate cannot satisfy the task or the repair budget is exhausted. Preserve unresolved blockers verbatim.\n</decision_rules>\n\n<success_criteria>\nThe decision follows the evidence and repair bound, with every unresolved blocker preserved.\n</success_criteria>\n\n<stop_rules>\nStop after selecting exactly one decision: accept, reject, or repair.\n</stop_rules>\n\n<output_format>\nCall structured_output with decision (accept, reject, or repair), a concise evidence-based rationale, and remaining_work. ${READABLE_REPORT}\n${GROUNDED_REPORTING}\n</output_format>\n\n<objective>\nDecide whether the candidate for ${task} is accepted, rejected, or needs repair.\n</objective>`;
 }
 
 export function renderRepairPrompt(task: string, candidatePath: string, reviewPath: string): string {
-  return `<role>\nYou repair a candidate using independent blocking findings.\n</role>\n\n<objective>\nRepair the candidate for: ${task}\n</objective>\n\n<artifacts>\nRead the current candidate at ${candidatePath} and reducer report at ${reviewPath}.\n</artifacts>\n\n<requirements>\nAddress every actionable blocker, rerun relevant validation, and retain valid prior work. Do not dismiss a finding without contrary evidence.\n</requirements>\n\n<output_format>\nA complete replacement candidate with repair summary, evidence, validation, and remaining risks.\n</output_format>`;
+  return `<artifacts>\nRead the current candidate at ${candidatePath} and reducer report at ${reviewPath}.\n</artifacts>\n\n<role>\nYou repair a candidate using independent blocking findings.\n</role>\n\n<success_criteria>\nEvery actionable blocker is addressed, relevant validation is rerun, and valid prior work is retained.\n</success_criteria>\n\n<evidence_rules>\nDo not dismiss a finding without contrary evidence. Report commands run, observed output, and file:line evidence where applicable. ${GROUNDED_REPORTING}\n</evidence_rules>\n\n<stop_rules>\nStop when all actionable blockers are repaired and validated, or list any blocker that remains with the missing evidence.\n</stop_rules>\n\n<output_format>\nA complete replacement candidate with repair summary, evidence, validation, and remaining risks. ${READABLE_REPORT}\n</output_format>\n\n<objective>\nRepair the candidate for: ${task}\n</objective>`;
 }

package/dist/builtin/workflows/builtin/adversarial-verification-runner.ts

@@ -47,7 +47,7 @@ export async function runAdversarialVerification(ctx: WorkflowRunContext<Inputs>
   const root = await stableArtifactRoot(ctx, "adversarial-verification");
   const rubricPath = join(root, "rubric.md");
   const candidatePath = join(root, "candidate.md");
-  await writeFile(rubricPath, ["# Verification rubric", "- The candidate satisfies the literal task.", "- Important claims cite observable evidence.", "- Relevant validation is executed and reported.", "- No blocking correctness, safety, or completeness gap remains."].join("\n"));
+  await writeFile(rubricPath, ["# Verification rubric", "- The candidate satisfies the literal task.", "- Important claims cite observable evidence.", "- Relevant validation is executed and reported with commands run and observed output.", "- File findings cite file:line evidence where applicable.", "- No blocking correctness, safety, or completeness gap remains."].join("\n"));
   await ctx.task("worker", { prompt: renderWorkerPrompt(ctx.inputs.task), context: "fresh", output: candidatePath, outputMode: "file-only" });
 
   let repairsCompleted = 0;

package/dist/builtin/workflows/builtin/adversarial-verification.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runAdversarialVerification } from "./adversarial-verification-runner.js";
 
 export default workflow({
@@ -20,5 +21,5 @@ export default workflow({
     artifact_dir: Type.String({ description: "Directory containing run artifacts." }),
     remaining_work: Type.Array(Type.String(), { description: "Unresolved blocking findings when not approved." }),
   },
-  run: runAdversarialVerification,
+  run: async (ctx) => await runAdversarialVerification(withSteeringPropagationContext(ctx)),
 });

package/dist/builtin/workflows/builtin/classify-and-act-prompts.ts

@@ -1,5 +1,8 @@
+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 READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
+
 export function classifierPrompt(prompt: string, categories: readonly string[]): string {
-  return `<role>\nYou route a task to exactly one declared action category.\n</role>\n\n<objective>\nClassify this task: ${prompt}\n</objective>\n\n<categories>\n${categories.map((category) => `- ${category}`).join("\n")}\n</categories>\n\n<requirements>\nChoose a category verbatim from the list. Base confidence on concrete wording in the task. Use low confidence when the task is ambiguous or spans categories. Provide a concise evidence-based rationale. Return only the structured result requested by the schema.\n</requirements>`;
+  return `<categories>\n${categories.map((category) => `- ${category}`).join("\n")}\n</categories>\n\n<role>\nYou route a task to exactly one declared action category.\n</role>\n\n<success_criteria>\nThe selected category is copied verbatim and supported by the task's concrete wording.\n</success_criteria>\n\n<decision_rules>\nChoose exactly one listed category. Use low confidence when the task is ambiguous or spans categories. Stop after making that single classification.\n</decision_rules>\n\n<output_format>\nReturn only the structured result requested by the schema: category, confidence, and a concise evidence-based rationale in complete sentences.\n</output_format>\n\n<objective>\nClassify this task: ${prompt}\n</objective>`;
 }
 
 export function actionPrompt(input: {
@@ -7,5 +10,5 @@ export function actionPrompt(input: {
   readonly category: string;
   readonly classificationPath: string;
 }): string {
-  return `<role>\nYou are the isolated action agent for category "${input.category}".\n</role>\n\n<objective>\n${input.prompt}\n</objective>\n\n<evidence>\nRead the classification artifact at ${input.classificationPath}. Use only relevant evidence available to this stage; do not assume access to classifier conversation context.\n</evidence>\n\n<success_criteria>\nComplete the requested action for this category, distinguish verified facts from assumptions, and report concrete evidence, validation, and remaining risks.\n</success_criteria>\n\n<output_format>\nMarkdown with Outcome, Evidence, Validation, and Remaining risks headings.\n</output_format>`;
+  return `<evidence>\nRead the classification artifact at ${input.classificationPath}. Use only relevant evidence available to this stage; do not assume access to classifier conversation context.\n</evidence>\n\n<role>\nYou are the isolated action agent for category "${input.category}".\n</role>\n\n<success_criteria>\nComplete the requested action for this category, distinguish verified facts from assumptions, and report concrete evidence, validation, and remaining risks.\n</success_criteria>\n\n<stop_rules>\nStop when the category-specific action is complete or a remaining blocker is stated with its missing evidence.\n</stop_rules>\n\n<output_format>\nMarkdown with Outcome, Evidence, Validation, and Remaining risks headings. ${READABLE_REPORT}\n${GROUNDED_REPORTING}\n</output_format>\n\n<objective>\n${input.prompt}\n</objective>`;
 }

package/dist/builtin/workflows/builtin/classify-and-act-runner.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Type } from "typebox";
 import type { WorkflowRunContext, WorkflowSerializableValue } from "../src/shared/types.js";
@@ -40,11 +40,6 @@ function actionTools(category: string): readonly string[] {
   return ["read"];
 }
 
-
-async function artifactText(path: string, fallback: string): Promise<string> {
-  try { return await readFile(path, "utf8"); } catch { return fallback; }
-}
-
 /**
  * Resolve a low-confidence or unlisted classification. Interactive runs ask the
  * user; headless/non-interactive runs (where ctx.ui rejects) deterministically
@@ -105,6 +100,9 @@ export async function runClassifyAndAct(ctx: WorkflowRunContext<Inputs>): Promis
     output: actionPath,
     outputMode: "file-only",
   });
-  const result = await artifactText(actionPath, action.text);
+  // `file-only` already returns a compact artifact reference. Reading the file
+  // back here would defeat that and push the whole report into the caller's
+  // context; `action_path` is returned for callers that want the contents.
+  const result = action.text;
   return { result, category, confidence, action: action.stageName, classification_path: classificationPath, action_path: actionPath, artifact_dir: artifactDir };
 }

package/dist/builtin/workflows/builtin/classify-and-act.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runClassifyAndAct } from "./classify-and-act-runner.js";
 
 export const DEFAULT_ACTION_CATEGORIES = ["analysis", "implementation", "research"] as const;
@@ -23,7 +24,7 @@ export default workflow({
     }),
   },
   outputs: {
-    result: Type.String({ description: "Category-specific action report." }),
+    result: Type.String({ description: "Compact reference to the category-specific action report artifact; read `action_path` for the full report." }),
     category: Type.String({ description: "Selected category, including any human fallback selection." }),
     confidence: Type.Number({ minimum: 0, maximum: 1, description: "Classifier confidence before fallback." }),
     action: Type.String({ description: "Executed category-specific action stage name." }),
@@ -31,5 +32,5 @@ export default workflow({
     action_path: Type.String({ description: "Category action report artifact path." }),
     artifact_dir: Type.String({ description: "Per-run artifact directory." }),
   },
-  run: async (ctx) => await runClassifyAndAct(ctx),
+  run: async (ctx) => await runClassifyAndAct(withSteeringPropagationContext(ctx)),
 });

package/dist/builtin/workflows/builtin/fan-out-and-synthesize-prompts.ts

@@ -1,11 +1,14 @@
+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 READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
+
 export function partitionPrompt(prompt: string, maxBranches: number): string {
-  return `<role>\nYou partition work into independent evidence-producing branches.\n</role>\n\n<objective>\nPartition this task: ${prompt}\n</objective>\n\n<requirements>\nReturn between 1 and ${maxBranches} non-overlapping partitions. Split by files, sources, claims, candidates, or work items that can be evaluated independently. Give each partition a concise label and a self-contained objective. Avoid duplicate scope and identify boundaries explicitly. Return only the structured result requested by the schema.\n</requirements>`;
+  return `<role>\nYou partition work into independent evidence-producing branches.\n</role>\n\n<success_criteria>\nThe plan has between 1 and ${maxBranches} non-overlapping partitions whose labels and objectives are self-contained.\n</success_criteria>\n\n<decision_rules>\nSplit by files, sources, claims, candidates, or work items that can be evaluated independently. Avoid duplicate scope and identify boundaries explicitly. Stop when every required part of the task belongs to one partition.\n</decision_rules>\n\n<output_format>\nReturn only the structured result requested by the schema, with concise labels and self-contained objectives.\n</output_format>\n\n<objective>\nPartition this task: ${prompt}\n</objective>`;
 }
 
 export function branchPrompt(input: { readonly prompt: string; readonly label: string; readonly objective: string }): string {
-  return `<role>\nYou own one independent branch of a larger task.\n</role>\n\n<overall_task>\n${input.prompt}\n</overall_task>\n\n<branch>\n${input.label}: ${input.objective}\n</branch>\n\n<success_criteria>\nInvestigate only this branch, cite concrete files/sources/commands or other observable evidence, distinguish findings from uncertainty, and produce a standalone artifact that a synthesizer can audit.\n</success_criteria>\n\n<output_format>\nMarkdown with Scope, Findings, Evidence, Conflicts or uncertainty, and Recommendations headings.\n</output_format>`;
+  return `<overall_task>\n${input.prompt}\n</overall_task>\n\n<role>\nYou own one independent branch of a larger task. Your artifact lets a synthesizer audit this branch without its conversation context.\n</role>\n\n<success_criteria>\nCite concrete files, sources, commands, or other observable evidence, distinguish findings from uncertainty, and produce a standalone artifact.\n</success_criteria>\n\n<stop_rules>\nStop when the branch objective is supported or when unresolved uncertainty and the evidence needed to resolve it are explicit.\n</stop_rules>\n\n<output_format>\nMarkdown with Scope, Findings, Evidence, Conflicts or uncertainty, and Recommendations headings. ${READABLE_REPORT}\n${GROUNDED_REPORTING}\n</output_format>\n\n<branch>\nInvestigate only ${input.label}: ${input.objective}\n</branch>`;
 }
 
 export function synthesisPrompt(prompt: string, manifestPath: string): string {
-  return `<role>\nYou synthesize independent branch artifacts at a strict barrier.\n</role>\n\n<objective>\nProduce the final answer for: ${prompt}\n</objective>\n\n<artifact_contract>\nRead ${manifestPath} first, then read every branch artifact listed there. Do not omit a completed branch and do not assume access to branch conversations.\n</artifact_contract>\n\n<success_criteria>\nDeduplicate overlapping findings, explicitly resolve or preserve conflicting claims, retain material uncertainty, and cite branch labels and artifact paths for important conclusions. The answer must be traceable to evidence rather than majority vote.\n</success_criteria>\n\n<output_format>\nMarkdown with Executive synthesis, Consolidated findings, Conflicts and resolutions, Evidence index, and Remaining uncertainty headings.\n</output_format>`;
+  return `<artifact_contract>\nRead ${manifestPath} first, then read every branch artifact listed there. Do not omit a completed branch and do not assume access to branch conversations.\n</artifact_contract>\n\n<role>\nYou synthesize independent branch artifacts at a strict barrier. The final reader needs conclusions traceable to branch evidence rather than majority vote.\n</role>\n\n<success_criteria>\nDeduplicate overlapping findings, explicitly resolve or preserve conflicting claims, retain material uncertainty, and cite branch labels and artifact paths for important conclusions.\n</success_criteria>\n\n<stop_rules>\nStop after every completed branch is accounted for and each material conflict is resolved or preserved as uncertainty.\n</stop_rules>\n\n<output_format>\nMarkdown with Executive synthesis, Consolidated findings, Conflicts and resolutions, Evidence index, and Remaining uncertainty headings. ${READABLE_REPORT}\n${GROUNDED_REPORTING}\n</output_format>\n\n<objective>\nProduce the final answer for: ${prompt}\n</objective>`;
 }

package/dist/builtin/workflows/builtin/fan-out-and-synthesize-runner.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Type } from "typebox";
 import type { WorkflowRunContext, WorkflowSerializableValue, WorkflowTaskStep } from "../src/shared/types.js";
@@ -31,9 +31,6 @@ function safeName(value: string, index: number): string {
   const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
   return `${String(index + 1).padStart(2, "0")}-${normalized || "branch"}`;
 }
-async function artifactText(path: string, fallback: string): Promise<string> {
-  try { return await readFile(path, "utf8"); } catch { return fallback; }
-}
 function parsedPartitions(value: WorkflowSerializableValue | undefined, limit: number, prompt: string): Partition[] {
   if (typeof value !== "object" || value === null || !("partitions" in value) || !Array.isArray(value.partitions)) {
     return [{ label: "whole-task", objective: prompt }];
@@ -86,7 +83,10 @@ export async function runFanOutAndSynthesize(ctx: WorkflowRunContext<Inputs>): P
     outputMode: "file-only",
   });
   return {
-    result: await artifactText(synthesisPath, synthesis.text),
+    // `file-only` already returns a compact artifact reference. Reading the file
+    // back here would defeat that and push the whole report into the caller's
+    // context; `synthesis_path` is returned for callers that want the contents.
+    result: synthesis.text,
     partitions: partitions.map((partition) => partition.label),
     branch_artifact_paths: branchPaths,
     synthesis_path: synthesisPath,

package/dist/builtin/workflows/builtin/fan-out-and-synthesize.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runFanOutAndSynthesize } from "./fan-out-and-synthesize-runner.js";
 
 export default workflow({
@@ -21,12 +22,12 @@ export default workflow({
     }),
   },
   outputs: {
-    result: Type.String({ description: "Evidence-citing synthesized report." }),
+    result: Type.String({ description: "Compact reference to the evidence-citing synthesis artifact; read `synthesis_path` for the full report." }),
     partitions: Type.Array(Type.String(), { description: "Ordered labels for executed partitions." }),
     branch_artifact_paths: Type.Array(Type.String(), { description: "Ordered branch artifact paths consumed by synthesis." }),
     synthesis_path: Type.String({ description: "Final synthesis artifact path." }),
     artifact_dir: Type.String({ description: "Per-run artifact directory." }),
     manifest_path: Type.String({ description: "Barrier manifest linking partitions to branch artifacts." }),
   },
-  run: async (ctx) => await runFanOutAndSynthesize(ctx),
+  run: async (ctx) => await runFanOutAndSynthesize(withSteeringPropagationContext(ctx)),
 });