@bastani/atomic 0.9.18 → 0.9.19-alpha.10

package/docs/workflows/reliable-design.md

@@ -2,7 +2,7 @@
 
 Use this guide to turn an objective into an acyclic, evidence-producing workflow with explicit contracts, context boundaries, verification, and stop conditions. Read [Custom Workflow Authoring](/workflows/authoring) first if you have not built a workflow definition yet.
 
-First honor the user's task-scoped [execution-mode choice](/workflows/verification#execution-mode). Explicit inline/no-workflow requests override the routing rubric below, including complex tasks and review loops; preserve the same safety and verification bar without creating a hidden workflow. For workflow authoring, carry the [domain/environment verification and media evidence contract](/workflows/verification) into worker, reviewer and final handoff prompts.
+First honor the user's task-scoped [execution-mode choice](/workflows/verification#execution-mode). Requests to do the task "quickly" or "inline", or not to use a workflow, override the routing rubric below, including complex tasks and review loops. Preserve the same safety and verification bar without creating a hidden workflow. Descriptions of software that should run quickly are not execution-mode instructions. For workflow authoring, carry the [domain/environment verification and media evidence contract](/workflows/verification) into worker, reviewer and final handoff prompts.
 
 ## Choosing an Execution Shape
 
@@ -67,16 +67,47 @@ A first named workflow launch commits the selected execution shape for the turn.
 
 Choose the cheapest complete graph. Routing cues are not a reason to add decorative stages: avoid duplicated research and review loops. Before launch, state the selected graph, why one broad builtin is sufficient or insufficient, the evidence each major stage produces, and the stop/repair conditions. A simple direct match can be one sentence; a composed graph should briefly name its children and task-specific gates.
 
+### Runtime-aware scheduling and estimates
+
+Treat workflow runtime as a dependency-constrained task-scheduling problem. Optimize elapsed time while preserving the evidence and approval contract, not by deleting gates or minimizing node count.
+
+During the short architecture pass, inspect project scripts and available historical runtimes from comparable CI jobs, test-suite reports, and prior workflow stages. For GitHub projects, recent run/job timings and uploaded test-duration reports can provide evidence. Record the source links or artifact paths, sample size and range, runner/cache differences, and missing data. Do not run the full suite just to collect an estimate or turn timing reconnaissance into a separate research project.
+
+Use a compact schedule alongside the coverage matrix:
+
+```text
+node | prerequisites | duration range and source | shared resources | evidence needed by
+```
+
+- Estimate the critical path, the longest dependency path, rather than adding all parallel node durations. Account for bounded concurrency, runner queues, environment setup, model variability, retries, and resource contention. More parallel jobs can be slower when they compete for the same resources.
+- Put focused tests and necessary build/type/contract checks at each implementation slice. When repeated full-suite runs add no required evidence, run the full suite once on the final candidate instead of after every stage. Preserve mandatory per-slice checks, required CI contexts, approval gates, and repair reruns. Each slice must still pass its own gates before dependent work starts.
+- Start long CI/check waits when their candidate is ready and overlap independent review, documentation, or handoff preparation that neither mutates that candidate nor needs its check results. Use supported concurrency, keep workflow-owned CI launch/wait/result checks in durable `ctx.tool` nodes with finite timeouts and cancellation, and join required results before acceptance, merge, or publication. Background admission is not check completion.
+- Record the checked commit or artifact identity. Later edits invalidate affected results, so rerun those checks for the new candidate. Never reuse a green check from an older commit as proof for a changed head. Do not alter repository protections, required checks, or concurrency limits to shorten the estimate.
+
+Before launching a workflow, give the user an estimated wall-clock completion range without confidence labels or scores. Cite available timing sources and distinguish measured checks from estimated model work, queue/repair uncertainty, and human wait time. If history is missing, state that briefly rather than inventing metrics. An estimate is not a `budget` override or a promise.
+
+Proceed with inherited budget limits without asking the user to choose a budget before each launch; preserve existing budget limits and approval gates. Omit `budget` unless the user specified a limit, inheriting the workflow declaration and config. When the user does state a limit, pass only the fields they named, leave every other field inherited, and use `0` only for a field the user asked to disable. Never convert an estimate into a cap.
+
+For example, with hypothetical timings, 6 minutes of implementation followed by independent 12-minute CI and 4-minute read-only review branches, then a 1-minute handoff, has a 19-minute critical path, not a 23-minute sum. Queue delays, repairs, and human approval can extend that. Real launch estimates must cite actual project evidence rather than reuse these illustrative numbers.
+
+Revise the remaining-time estimate at lifecycle updates only when new evidence materially changes the path. Keep the normal heartbeat cadence and end-turn/no-polling rules. At completion, report actual elapsed time against the estimate and identify the main bottleneck to improve the next schedule. These are agent design/reporting instructions, not an automatic scheduler or ETA feature.
+
+### Questions and approvals
+
+When `ask_user_question` or an equivalent question tool is available, all agent-authored questions to the user must use that tool instead of plain text, including clarification, confirmation, and permission to proceed. Prefer `ask_user_question` when available; otherwise follow the equivalent tool's supported schema. In these sessions, do not append a prose-only "Proceed?" to a status update. Ask only for needed decisions, not repeat approval of already-authorized work. See the [question tool guidance and confirmation example](/tools#ask_user_question).
+
+Workflow-authored `ctx.ui` gates remain supported. `workflow answer` relays an actual user response to a pending prompt; it does not grant authority to choose an approval on the user's behalf. Intercom questions are for agents, not a substitute for user approval. If no usable question tool is available, continue autonomously using best judgment and record evidence-backed assumptions. Tool unavailability alone is not a blocker. Preserve safety, authorization, explicit approval gates, and budget limits. A cancelled or unanswered question is not approval.
+
 ### Stage model and thinking-level assignment
 
-Before launching an authored workflow, assign every model stage a **role**, **failure cost**, **primary model**, **thinking level**, and **fallback policy**. Read [Model Selection](/models/model-selection) for the role defaults and [Evals](/models/evals) for the measured per-evaluation scores — its task-type picker maps each stage type (terminal debugging, knowledge-work planning, tool-calling loops, document research, code-reading review) to the eval that measures it and the models that lead it — but treat thinking levels in benchmark rows as measurement configurations, not production defaults. Reserve `max` for high-cost-of-error roles or an explicit user request; use `high` for demanding mapping, lifecycle analysis, compatibility, planning, synthesis, triage, and repair; use `medium` for user-impact review and final reporting; and keep deterministic checks as tool nodes with no model call.
+Before launching an authored workflow, assign every model stage a **role**, **failure cost**, **primary model**, **thinking level**, and **fallback policy**. Read [Model Selection](/models/model-selection) for the role defaults and [Evals](/models/evals) for the measured per-evaluation scores — its task-type picker maps each stage type (terminal debugging, knowledge-work planning, tool-calling loops, document research, code-reading review) to the eval that measures it and the models that lead it — but treat thinking levels in benchmark rows as measurement configurations, not production defaults. Use `low` or `medium` for implementation and routine fixes, and `high` or `xhigh` for code review, test design, failure analysis, and approval decisions when supported. Use `high` for demanding mapping, lifecycle analysis, compatibility, planning, synthesis, and triage, and `medium` for user-impact review and final reporting. `max` is an exception justified by task-specific evidence or an explicit user request, not a role default. Keep deterministic checks as tool nodes with no model call.
 
 Print this compact assignment before launch, with a short cost/quality rationale for each model stage:
 
 ```text
 Stage | Model | Thinking | Role
 map | <catalog fullId> | high | codebase mapping
-approve | <catalog fullId> | max | final approval
+approve | <catalog fullId> | high | final approval
 report | <catalog fullId> | medium | final reporting
 tests | — | — | deterministic check (tool node)
 ```
@@ -143,7 +174,7 @@ Interpretation:
 - **7+ total, or Iteration = 2, or Verifiability = 2 with a review/approval gate:** a real workflow. Prefer a named workflow when one fits the whole task; otherwise author a custom graph, nesting proven children where sub-problems overlap.
 - **Any single hard signal overrides the arithmetic:** an explicit loop/stop condition, an approval or evidence gate, or a request for durable/background execution puts the task in workflow territory regardless of total score.
 
-When workflow execution is permitted, use the rubric to select tracked implementation/review loops and transfer bounded reconnaissance through `reads`. It does not override an explicit inline request. In either mode, stop unbounded reconnaissance by recording findings and taking the next concrete in-scope action.
+When workflow execution is permitted, use the rubric to select tracked implementation/review loops and transfer bounded reconnaissance through `reads`. It does not override a request to do the task quickly or inline. In either mode, stop unbounded reconnaissance by recording findings and taking the next concrete in-scope action.
 
 ### Task queues and software factories
 
@@ -374,12 +405,12 @@ The factory self-prompt is: **enumerate → inspect and classify dependencies
 
 Humans can steer the shape directly:
 
-- **Name the shape or installed workflow.** "Do this inline", "use subagents to investigate", or "write a custom workflow for this" overrides automatic scoring.
+- **Name the shape or installed workflow.** "Do this quickly", "do this inline", "use subagents to investigate", or "write a custom workflow for this" overrides automatic scoring.
 - **State acceptance criteria.** Verbatim criteria make the objective provable and define reviewer and reducer contracts.
 - **State the loop.** "Iterate until tests pass" or "review and fix until approved" defines a hard workflow stop condition.
 - **State the evidence.** A QA video, test output, generated artifact, or reviewer sign-off tells the graph which gates it needs.
 - **State the boundary.** "Work in a separate worktree", "do not create a PR", or "stop after implementation" separates implementation from final actions.
-- **State the queue policy.** Say how to split, order, isolate, and bound queued items; otherwise Atomic runs the [dependency-triage and bounded-dispatch playbook](#task-queues-and-software-factories) before implementation. Ordinary list order and per-item "create a PR after" wording do not create a cross-item dependency.
+- **State the queue policy.** Say how to split, order, isolate, and bound queued items; otherwise Atomic runs the [dependency-triage and bounded-dispatch playbook](/workflows/reliable-design#task-queues-and-software-factories) before implementation. Ordinary list order and per-item "create a PR after" wording do not create a cross-item dependency.
 
 Absent these controls, Atomic applies the self-prompt and rubric above; a prompt that names none of them delegates the shape decision rather than avoiding it.
 
@@ -1004,7 +1035,7 @@ Pass file references, not content. This is the strongly encouraged default for e
 
 Three rules make that work in practice:
 
-1. **One owner per artifact.** The runner writes the stage's final assistant message to `output` after the stage ends, automatically writes the companion transcript outside the repository tree, and appends one instruction telling the model that its final message becomes the artifact. Your prompt does not need to restate any of that — describe the deliverable, not the plumbing. If a late admitted turn displaces the intended content, search the transcript with `rg` rather than assuming the curated artifact holds every later turn. A prompt may write other files freely; only the declared `output` path is runner-owned and overwritten at stage end.
+1. **One owner per artifact.** The runner writes the stage's completed answer to `output` and appends later completed answers from the same generation as numbered supplements. This preserves a report when an admitted clarification arrives before generation close, without copying tool progress or earlier history into the artifact. Completed handoffs are immutable under later chat. State corrections explicitly, and use a new tracked stage and output path for an intentional replacement. The runner also writes the companion transcript outside the repository and tells the model the output contract. Describe the deliverable in your prompt, not the plumbing. Search the transcript with `rg` for supporting details that belong outside the curated artifact.
 2. **Do not read an artifact back just to return it.** `outputMode: "file-only"` exists so the parent receives a compact reference. Calling `readFile` on that artifact and returning its text as a workflow output cancels the saving and drops the whole report into the caller's context window. Return the reference and a `*_path` output instead.
 3. **Return paths from the workflow.** Declared outputs are consumed by the calling session, so a workflow's `result` should be a reference plus explicit `*_path` outputs. Callers that need the body read the path; callers that only need the outcome pay nothing for it. When a detail is missing from the curated artifact, search its companion transcript with `rg` and inspect a narrow range.
 
@@ -1137,7 +1168,7 @@ Good workflows are information-flow systems, not just prompt sequences. Keep sta
 - Do not rely on undeclared child outputs; returning a key that is not declared in `outputs` fails the run. Declare every child-workflow field you expose in `outputs` — including `result` — and return values matching those schemas from `run` (see [Outputs](/workflows/authoring#outputs)).
 - Do not expect to select or rename child outputs at the call site; parent workflows receive the child's declared output contract as `child.outputs` after checking `child.exited === false`, and a partial declared-output map when `child.exited === true`.
 - Do not expect named workflow runs to block the chat turn; they are background tasks.
-- Use `interrupt` or `pause` when the user asks to pause specific live work resumably; use `quit` for a graceful run-level process boundary.
+- Use `pause` when the user asks to pause specific live work resumably; use `quit` for a graceful run-level process boundary.
 - Keep stage names readable because they appear in workflow status and UI.
 - Do not ask a stage to reason from workflow or stage names that are only orchestration labels. Model stages see their local prompt, artifacts, tools, and reads; describe the concrete action and evidence instead of referring to an implementation-specific nickname.
 - Do not write stage prompts that depend on hidden workflow-wide awareness; make each model stage locally scoped and self-described ([Locally Scoped Stage Prompts](#locally-scoped-stage-prompts)).
@@ -1317,7 +1348,9 @@ A failed test becomes the next objective.
 Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.
 ```
 
-#### 8. Interrupt stale or wrong work
+<a id="8-interrupt-stale-or-wrong-work" />
+
+#### 8. Pause stale or wrong work
 
 If a run is solving the wrong problem, based on outdated assumptions, or duplicating another run, stop it. Continuing usually creates more cleanup.
 
@@ -1364,6 +1397,8 @@ Constructive quorum relies on existing Intercom mechanics: every workflow invoca
 
 #### Pattern diagrams
 
+<a id="1-classify-and-act"></a>
+
 ##### 1. Classify-and-act
 
 Builtin definition and contracts: [Six composable pattern builtins](/workflows/builtins#six-composable-pattern-builtins).
@@ -1389,6 +1424,8 @@ Best practices:
 - Keep each action branch isolated with the minimum tools and context it needs.
 - Add a fallback or human-input branch for low-confidence classifications.
 
+<a id="2-fan-out-and-synthesize"></a>
+
 ##### 2. Fan-out-and-synthesize
 
 Builtin definition and contracts: [Six composable pattern builtins](/workflows/builtins#six-composable-pattern-builtins).
@@ -1417,6 +1454,8 @@ Best practices:
 - Save each branch to a separate artifact and pass paths with `reads` instead of inlining all branch output.
 - Treat synthesis as a barrier: it waits for every branch, deduplicates, resolves conflicts, and cites evidence.
 
+<a id="3-adversarial-verification" />
+
 ##### 3. Adversarial verification
 
 Builtin definition and contracts: [Six composable pattern builtins](/workflows/builtins#six-composable-pattern-builtins).
@@ -1455,6 +1494,8 @@ Best practices:
 - Invalid criterion reports are written as invalid artifacts and re-asked in bounded waves up to `reask_limit`; an invalid or missing report is counted in `invalidCount` only and is never converted into a fail vote or included in the mean. If the required quorum is still missing after the re-asks, the round is `indeterminate` rather than silently narrowing the decision.
 - `score_table_path` names the durable `verification-summary-<round>.json` for the final round. Its object contains `scores` (`criterion_id`, integer `score`, `evidence`, and `findings` with `finding` plus `severity`), `mean`, `invalidCount`, the `decision` (`accept`, `repair`, or `indeterminate` with its corresponding mean/findings or missing count), and folded `usage`; `review_report_path` carries repair guidance or quorum evidence.
 
+<a id="4-generate-and-filter"></a>
+
 ##### 4. Generate-and-filter
 
 Builtin definition and contracts: [Six composable pattern builtins](/workflows/builtins#six-composable-pattern-builtins).
@@ -1483,6 +1524,8 @@ Best practices:
 - When the filter ranks candidates rather than applying a threshold, use the same judge guidance as Tournament: graded per-criterion integer scores rather than binary keep/drop, a Bradley–Terry preference from the score gap so near-ties stay near-ties, and K repeats with candidates swapped between the A and B slots. See [Verification scaling](#verification-scaling).
 - For a custom ranking filter, reuse the shared `verification-criteria` module and its `criteria.md` parser rather than inventing a binary keep/drop rubric; stable criterion ids let the judge select the same criteria in each comparison. See [Adversarial verification](#3-adversarial-verification) for the accepted shapes and score decision.
 
+<a id="5-tournament" />
+
 ##### 5. Tournament
 
 Builtin definition and contracts: [Six composable pattern builtins](/workflows/builtins#six-composable-pattern-builtins).
@@ -1516,6 +1559,8 @@ Best practices:
 - The shipped tournament inputs use `num_attempts=4` and `max_concurrency=4`; `n_evaluations=2` repeats each criterion/directed pair, `pivots=1` selects the second comparison phase's pivot candidates, and `seed=0` drives the deterministic schedule. `criteria` is optional and accepts a markdown rubric, a string-to-description record, a string list, or a `CriterionInput` list; omission uses the shipped three-criterion Correctness, Completeness, and Evidence and task fit rubric. Optional ordered `models` ids are assigned round-robin to attempt slots.
 - `comparisons_path` points to `comparisons.json`, whose ledger records the task and seed, `params` (`n`, `pivots`, `n_evaluations`, and normalized `criteria`), per-job `comparisons` rows (`a`, `b`, phase, criterion id, repeat, slot-swap flag, scores or an `invalid` marker, preference, and judge artifact path), aggregate `pairs`, weights/counts, the complete `ranking`, and optional model assignment. Its `budget` records planned versus executed judge stages, including re-asks; invalid reports remain auditable rows and an all-invalid pair remains marked invalid rather than becoming a score.
 
+<a id="6-loop-until-done" />
+
 ##### 6. Loop until done
 
 Builtin definition and contracts: [Six composable pattern builtins](/workflows/builtins#six-composable-pattern-builtins).
@@ -1546,6 +1591,8 @@ Best practices:
 - Progress scores use the anchored 1–20 scale and average valid repeat scores per checkpoint. `classify_trend` uses `window=3`, `riseDelta=1.5`, and `fallDelta=-1.5`; it compares equal leading/trailing halves of the trailing two windows, drops an odd middle sample, and classifies inclusive threshold crossings as `rising`, `flat`, or `regressing`. A short series is `flat` evidence.
 - The trend is monitoring and escalation evidence only: it never kills, terminates, or approves a loop, and the explicit evaluator stop condition remains authoritative. `progress_curve`, `final_trend`, and `progress_disclaimer` are advisory outputs, not alternate closure signals.
 
+<a id="7-constructive-quorum"></a>
+
 ##### 7. Constructive quorum
 
 This prompt-level reviewer pattern is used by the `goal` and `ralph` builtins; it does not add a reducer or quorum mechanism.
@@ -1577,6 +1624,8 @@ Best practices:
 - Change a verdict only through evidence, never deference. Each reviewer emits its own final structured verdict and records whether deliberation changed it and which evidence caused the change.
 - Let the existing deterministic reducer count the final votes; deliberation shapes votes but does not replace quorum counts or the `stop_review_loop` contract.
 
+<a id="stacked-implementation-slices-starter-pattern" />
+
 ##### Stacked implementation slices starter pattern
 
 Use this authoring pattern when one implementation objective should land as a stack of small, independently verified changes. It is not a queue dispatcher: the slices belong to one dependency chain, so slice N+1 starts only after slice N is verified.
@@ -2062,7 +2111,7 @@ These anti-patterns target run prompts; [Common Mistakes](#common-mistakes) cove
 | `Fix this.` | `Fix [specific failure]; done means [test command] passes.` |
 | No validation step | Require tests, smoke checks, typecheck, or explicit manual verification. |
 | Broad refactors | Constrain the run to the files needed for the objective. |
-| Letting a wrong stage continue | Redirect or interrupt as soon as the agent follows the wrong signal. |
+| Letting a wrong stage continue | Redirect or pause as soon as the agent follows the wrong signal. |
 | Accepting unverified summaries | Ask for changed files, commands run, results, and remaining risks. |
 | Mixing investigation and implementation too early | Ask for root cause and proposed fix before code changes. |
 | Ignoring blocked stages | Answer directly with one decision and any constraints. |

package/docs/workflows/verification.md

@@ -1,62 +1,146 @@
 # Verification and evidence
 
-Use executable verification appropriate to the changed behavior. Workflow authors should put the same evidence contract in worker, reviewer and final handoff prompts. Goal and Ralph share this guidance. Reviewers inspect actual artifacts and results, not claims or filenames.
+Verify the behavior that changed, then give the reviewer enough evidence to understand the result. A small fix may need a focused test and a short explanation. An interactive change usually needs a real user scenario as well. A video is useful when it shows something a test log or screenshot cannot; it is not required for every PR.
 
-## Execution mode
+For tool installation, automation techniques, platform permissions, and general work in applications, read [Computer use](/computer-use). That guide covers Herdr for terminals, playwright-cli for browsers, and PyAutoGUI with uv for desktop CUA on macOS, Linux, and Windows. It also covers native accessibility and application tools when they are easier or more reliable.
 
-An explicit request to work `inline`, `do this directly`, `don't use a workflow`, or equivalent overrides workflow-first defaults for that task, including complex implementation and review loops. Do not create or launch a hidden or nested replacement workflow, or ask the user to reapprove the choice. Keep appropriate testing, review and evidence inline. Safety and authorization requirements do not change.
+<a id="select-the-verification-environment" />
 
-Apply the preference only to its stated task. Quoted examples and questions about inline code are not execution-mode instructions. Without an opt-out, normal workflow fit defaults apply.
+## Choose checks that answer the question
 
-If the user switches during an active workflow, safely hold or stop the affected run using its available lifecycle controls. Reconcile completed work and in-flight side effects before continuing inline so commands and external writes are not duplicated. Stages notify the controlling session rather than launching a replacement. Already-completed work remains completed; do not claim it was undone.
+Start with the project's existing tests, build, typecheck, and lint commands. Add an interactive scenario when the change affects what a user sees or does. Do not replace required checks with a recording, or create a UI solely to demonstrate a non-UI change.
 
-## Select the verification environment
+| Changed behavior | Preferred mechanism | What to check |
+| --- | --- | --- |
+| Interactive terminal or TUI | **Herdr**, under its explicit-request and managed-pane requirements; tmux or native Windows psmux as fallbacks | Actual input, rendered output, navigation, resizing, and exit behavior relevant to the change. |
+| Browser/frontend | **playwright-cli** | The user flow and its visible result, with DOM or network assertions where useful. |
+| Desktop app, simulator, or emulator | **PyAutoGUI with uv**, supplemented by native/app APIs | The visible app scenario and its saved or exported result. |
+| API, library, script, or other non-UI behavior | Existing test runner and shell commands | Inputs, outputs, error handling, and relevant build/type contracts. |
+| Documentation | Documentation checks and example review | Links, navigation, command accuracy, and whether a reader can follow the instructions. |
 
-Inspect installed tools, cached runtimes, existing sessions and safe test configuration first. Install missing tools/plugins when online access and permissions permit. Known offline or restricted installation is enough reason not to attempt a prohibited download. Otherwise make a reasonable capability check or one bounded setup attempt, not an endless installation retry loop.
+See [tool selection](/computer-use#choose-the-right-tool) before operating a session. Herdr is the terminal priority, but the preference does not authorize control from outside a Herdr-managed pane. Install missing tools when permitted; otherwise use the available fallback and describe any coverage gap.
 
-When a mechanism cannot run, continue available authoritative repository checks, retain useful local evidence, and record the constraint, attempted commands and observed output, narrower validation and missing coverage. Do not require production credentials or take unsafe actions to satisfy a generic verification suggestion. An unavailable optional mechanism is not failed implementation, but it does not waive a required project check.
+## Define a reproducible scenario
 
-| Changed behavior | Verification and evidence |
-| --- | --- |
-| Browser/frontend, including API-dependent flows | Use the playwright-cli skill. Exercise the real user flow and assert its result. Retain current screenshots, video, DOM snapshots or network evidence as appropriate. |
-| TUI/terminal | Use tmux on supported hosts, native Windows psmux, or herdr where available and appropriate. Exercise actual interactive input and inspect pane output or a terminal recording. These tools do not have interchangeable CLIs. |
-| Desktop/simulator/emulator | Use suitable PyAutoGUI or native platform tools against a real visible app scenario. Capture screenshots/video from that environment, not a browser recording labeled as desktop or iOS proof. |
-| Non-UI | Run relevant unit, integration, build, type or command-line scenarios. Do not manufacture a UI or video requirement. |
+Before running it, write down:
 
-### Terminal contracts
+- The behavior being verified and the expected result.
+- The commit or artifact under test, plus any uncommitted changes.
+- The environment that matters, such as OS, app/browser version, terminal dimensions, display scaling, and test fixtures.
+- The actions and assertions, including a relevant failure or edge case.
 
-[psmux](https://github.com/psmux/psmux) is a native Windows ConPTY multiplexer using tmux-style commands. Its [scripting guide](https://github.com/psmux/psmux/blob/master/docs/scripting.md) documents `psmux capture-pane -p -t %0` for stdout capture. Verify installed help and use the actual pane identifier rather than assuming `%0` belongs to the test.
+Use dedicated sessions and non-production data. Wait for observable completion with a deadline instead of assuming that a submitted command or a fixed delay means success. Preserve useful failure output before cleanup.
 
-[herdr's CLI](https://herdr.dev/docs/cli-reference/) talks to a running server. Discover your isolated test pane with `herdr pane list`. `herdr pane run <pane_id> <command>` submits a command with Enter; `herdr pane send-text` alone does not submit. `herdr pane read <pane_id> --source visible` returns the screen text. For bounded waits use `herdr pane wait-output <pane_id> --match <text> --timeout 10000`. Do not confuse pane output with an agent lifecycle status or infer success from `idle`. Check installed version/help and host support before use. Do not take over unrelated panes.
+After a repair, rerun the affected checks on the new candidate. Label before/after evidence and keep it clear which commit produced each result. Do not present an earlier passing run as verification of later edits.
 
-### Desktop safety
+## Capture evidence appropriate to the change
 
-The [OpenAI CUA sample](https://github.com/openai/openai-cua-sample-app#first-run) distinguishes JavaScript Playwright browser control from Python PyAutoGUI desktop input. It is an optional sample requiring API/model access, not a prerequisite for every GUI test. Follow its [Python quickstart and interruption guidance](https://github.com/openai/openai-cua-sample-app/blob/main/python-app/README.md).
+### Browser changes
 
-Use a dedicated desktop/session with controlled fixtures. macOS needs Accessibility and Screen Recording permissions for the launching app; Linux PyAutoGUI needs an appropriate X11 desktop and dependencies; Windows needs a graphical session. Screenshots may include other windows and PyAutoGUI controls real mouse and keyboard input. Keep failsafes enabled, inspect privacy before saving/sharing, release held keys/buttons after interruption, and check for leftover processes before restarting. Do not install the sample's pnpm dependencies into an npm repository.
+Use playwright-cli to exercise the actual flow. A screenshot can show layout; a DOM snapshot can show control state; console and network output can help establish why a flow failed. Pair captures with assertions about the result, such as a saved record appearing after reload.
 
-A visible simulator/emulator or suitable native automation/mirroring setup is required for mobile UI. PyAutoGUI does not directly control an arbitrary physical iPhone. Use native platform tooling where it provides better assertions or safer input.
+For a named browser session you own, the CLI supports captures such as:
 
-## qlty setup and fallback
+```sh
+playwright-cli -s=pr-check snapshot --filename=after.yaml
+playwright-cli -s=pr-check screenshot --filename=after.png
+```
+
+For behavior best shown in motion, check the installed CLI's help, start recording before the relevant actions, and stop afterward:
+
+```sh
+playwright-cli -s=pr-check video-start flow.webm
+# Exercise the scenario here.
+playwright-cli -s=pr-check video-stop
+```
+
+Open the saved artifact and confirm it includes the final state. Keep recordings short and focused. Inspect traces, authentication state, and network output for secrets before sharing. See [browser setup and best practices](/computer-use#browser-automation-with-playwright-cli).
+
+<a id="terminal-contracts" />
+
+### Terminal changes
+
+Use Herdr to send real interactive input and inspect the resulting pane, or use tmux/psmux when Herdr cannot be used. Keep the terminal dimensions and shell relevant to the change. Test narrow layouts or modified keys when those are affected.
+
+Retain screen captures or transcripts that show the input and result. For cursor movement, redraws, colors, or timing, a terminal recording or video may explain more than plain text. Capture important states during the run; alternate-screen content may not remain in scrollback. Check exit status or explicit assertions rather than treating an agent's `idle` indicator as a passing result.
+
+See [terminal setup and capture commands](/computer-use#terminal-automation-with-herdr). A browser rendering of terminal text is not proof that the real TUI accepted input. WSL tmux does not establish native Windows terminal coverage.
+
+<a id="reproduce-stage-skill-terminal-evidence" />
+
+<a id="desktop-safety" />
+
+### Desktop, simulator, and emulator changes
+
+Run PyAutoGUI through uv in a dedicated graphical session, using [the desktop guide](/computer-use#desktop-automation-with-pyautogui-and-uv). Native accessibility tools or application APIs can give more reliable assertions than pixel matching. For example, check a saved document through the app API after exercising the visible Save flow.
+
+Capture the actual application or simulator. A browser recording is not desktop or iOS evidence. PyAutoGUI can interact with a visible simulator/emulator window, but does not directly control an arbitrary physical phone. Use supported native tooling where needed, and name the device or emulator actually exercised.
+
+Keep failsafes enabled and release held keys/buttons after interruption. Inspect saved files and exports rather than assuming a completed click means a completed operation. Screenshots show appearance, not necessarily persistence or correctness.
 
-Use the qlty skill to choose reliable, low-noise checks and useful metrics based on user priorities and repository evidence. Preserve existing `.qlty/qlty.toml`, the project's chosen tools such as Biome, and authoritative package/CI checks. Do not add competing formatters or run wholesale formatting by habit. Record command/output, scope and a relevant baseline; numbers without a decision are not useful verification.
+## Use evidence in a workflow
 
-During authorized coding, absent config permits `qlty init --no` or a hand-authored `.qlty/qlty.toml`; inspect generated suggestions. Missing config alone is not a blocker. For offline/restricted installation or a missing binary, use the skill's bundled manual-configuration reference to prepare TOML without network when configuration edits are in scope. Use source-backed options, omit unknown optional plugin versions rather than inventing them, and validate syntax/schema with available tools. Read-only tasks stay read-only or use isolated scratch config.
+Give workers, reviewers, and the final handoff the same scenario and success criteria. A verification stage should produce commands, observed results, and artifact paths. The reviewer should inspect those results, not just accept the worker's summary or a filename.
 
-Installed built-in metrics/smells may work offline. Cached plugins may work too, but uncached source/plugin/runtime resolution can require downloads. Report configuration prepared separately from lint/security/metrics actually run. TOML parsing is not proof of plugin availability or a passing quality check. Continue available repository checks without making optional qlty installation a universal blocker.
+For workflow-owned checks, use durable `ctx.tool` calls with finite timeouts and cancellation. Pass scripts and larger evidence through files. After a failed check, send the actual failure to a bounded repair step and rerun the affected checks. Keep implementation acceptance separate from later PR creation, upload, or publication. See [workflow authoring](/workflows/authoring) and [reliable design](/workflows/reliable-design).
 
-## Native GitHub media
+### Execution mode
 
-Only publish to an authorized target. Detect the provider first and inspect/redact artifacts for secrets, personal information and unrelated windows. Name the verified commit and scenario in the accompanying evidence. Collection alone is not upload authorization.
+The same verification standard applies inline. A task-scoped request such as `quickly`, `inline`, or `don't use a workflow` means no workflow creation or launch, including hidden replacements. If switching an active run to inline, stop or hold it safely and reconcile completed work and in-flight effects before continuing. See [when to use workflows](/workflows#when-to-use-workflows).
 
-[GitHub CLI >=2.99.0](https://github.blog/changelog/2026-09-01-github-cli-media-in-issues-pull-requests-and-comments/) supports repeatable `--attach` on `gh issue create`, `edit`, `comment` and `gh pr create`, `edit`, `comment`. Check `gh --version` and the specific command's `--help` before using it. For an authorized PR comment:
+## When a tool or environment is unavailable
+
+Inspect installed tools and cached runtimes first. Install missing tools or plugins when network access and permissions allow. If installation is restricted, or no suitable graphical session is available, continue the checks that can run and record:
+
+- What was unavailable and the observed error or known restriction.
+- Any setup attempt and the narrower checks that actually ran.
+- What still needs verification, including missing platform coverage.
+
+Do not require production credentials or bypass permissions to satisfy a generic verification suggestion. An optional tool being unavailable is not an implementation failure, but a required project check remains required. Do not label skipped, mocked, or simulated coverage as a real platform run.
+
+### qlty setup and fallback
+
+Use the qlty skill when it adds useful lint, security, or complexity checks. Preserve the repository's existing tools and `.qlty/qlty.toml`; do not introduce a competing formatter or wholesale formatting changes.
+
+When configuration changes are in scope, missing config can be initialized with `qlty init --no` or prepared manually using the skill's bundled configuration reference. Review generated suggestions. Read-only tasks should remain read-only or use isolated scratch configuration.
+
+Cached plugins and built-in metrics may work offline; uncached plugins or runtimes may need downloads. Report prepared configuration separately from checks actually executed. Valid TOML is not proof that a plugin ran. Optional qlty setup should not block available repository checks.
+
+## Include evidence in a PR
+
+Give the reviewer a short summary before linking logs or media. For example, replace the placeholders in this template with observed results:
+
+```markdown
+## Verification
+
+- Candidate: <commit SHA; note any uncommitted changes>
+- Environment: <OS, app/tool versions, relevant dimensions>
+- Checks: <command and result>
+- Scenario: <starting state, actions, expected and observed result>
+- Evidence: <hosted links or attached artifacts>
+- Limits: <checks/platforms not exercised>
+```
+
+Attach a screenshot for a visual state, a short recording for an interaction, or logs for command behavior. Include reproduction steps even when media is available. Label local-only paths as local; reviewers cannot open a file on your machine. CI artifact links are useful when readers have access, but note retention limits where relevant.
+
+Only upload to an authorized repository or destination. Inspect and redact secrets, personal information, private source content, and unrelated windows before attaching files. Permission to collect local evidence is not permission to publish it.
+
+### Native GitHub media
+
+[GitHub CLI 2.99.0 and newer](https://github.blog/changelog/2026-09-01-github-cli-media-in-issues-pull-requests-and-comments/) supports repeatable `--attach` on issue and PR `create`, `edit`, and `comment` commands. Check `gh --version`, the specific command's `--help`, and the host's [attachment support and limits](https://docs.github.com/en/github-cli/github-cli/attaching-files-with-github-cli).
+
+For an authorized PR comment, replace the target and file paths:
 
 ```sh
-gh pr comment 123 --repo owner/repo --body-file evidence.md --attach proof.mp4
+gh pr comment 123 --repo owner/repo --body-file evidence.md \
+  --attach 'after.png#Settings panel after saving' \
+  --attach flow.webm
 ```
 
-Use actual target and file values. Attach each file once. A body-local path reference is rewritten to the hosted URL; other attachments append in flag order. Images can use `--attach 'screen.png#Image alt text'`; videos do not support alt text. A standalone `![](proof.mp4)` paragraph is rewritten to an embedded player. See [official attachment documentation](https://docs.github.com/en/github-cli/github-cli/attaching-files-with-github-cli).
+The backslashes above are POSIX shell continuations. In PowerShell, use a single line or PowerShell continuation syntax.
+
+Attach each file once. The CLI rewrites body-local attachment references to hosted URLs; otherwise it appends attachments in flag order. Images support `#Image alt text`; videos do not support alt text. A standalone `![](flow.webm)` paragraph in the body becomes an embedded player. These are CLI attachment features, not support for arbitrary local paths in GitHub Markdown.
 
-Supported media include PNG, JPEG, GIF, WebP, SVG, MP4, MOV and WebM. Images/GIFs have a 10 MB limit; video limits are 10 MB on Free and 100 MB on paid plans. Repository write access and supported OAuth/classic PAT authentication are required; this release does not support GitHub Enterprise Server. Recheck current limits for the chosen host/account.
+Supported media include PNG, JPEG, GIF, WebP, SVG, MP4, MOV, and WebM. Uploads require repository push access and supported authentication. Recheck current size limits and authentication support for the target account and host. The 2.99.0 release does not support GitHub Enterprise Server.
 
-Read back the created or edited issue/PR/comment and confirm usable GitHub-hosted links before reporting success. Unsupported versions, hosts, providers, auth or sizes require a truthful fallback: retain the local artifact and explain authorized manual attachment or supported provider tooling. Do not claim a `file://` reference is uploaded evidence or send artifacts to unrelated third-party hosts.
+Read back the created or edited PR/comment and confirm usable hosted links before reporting an upload as successful. If the CLI, provider, authentication, or file size is unsupported, retain the local artifact and explain the manual attachment path or supported provider tooling. Do not upload to an unrelated host to work around a limitation.

package/docs/workflows.md

@@ -11,7 +11,7 @@ Default to a workflow for non-trivial work with a verifiable objective — see [
 - **Parallel branches** - Run independent research, review, or implementation branches concurrently
 - **Context handoffs** - Pass summaries, artifacts, files, and schema-backed structured results between stages
 - **Human input** - Pause for `ctx.ui.input`, `confirm`, `select`, `editor`, or custom TUI widget decisions during a run
-- **Resumable control** - Interrupt, pause, quit, resume, or connect to workflow runs
+- **Resumable control** - Pause, quit, resume, or connect to workflow runs
 - **Intercom run notifications** - Deliver async run results and control notices (long-running, needs-attention, completed, failed) to a parent session over [Intercom](/intercom)
 - **Artifacts** - Save large outputs to files instead of pushing everything through model context
 - **Verification and gates** - Preserve evidence, run checks, and stop for human approval where reliability matters
@@ -40,9 +40,11 @@ Prefer composing builtin definitions with `ctx.workflow(...)` over copying or re
 4. [Operations](/workflows/operations) — run, inspect, steer, pause, resume, and configure workflows.
 5. [API reference](/workflows/api-reference) — look up definitions, contexts, options, results, and programmatic APIs.
 
+For checking changes and sharing results in PRs, see [Verification and evidence](/workflows/verification). For general desktop, browser, and terminal work, including creative workflows, see [Computer use](/computer-use).
+
 ## When to Use Workflows
 
-Unless the user explicitly chooses inline execution, workflows are the default for non-trivial requests or structured work with a verifiable objective. Requests such as `inline`, `do this directly`, and `don't use a workflow` override that default for the specified task, even when complex. Do not launch a hidden/nested replacement or ask the user to reapprove the choice. Preserve testing, review, evidence, safety and authorization inline. Quoted examples and questions about inline code are not mode instructions. For an active switch, safely hold/stop the affected run and reconcile completed work and in-flight effects before continuing without duplicates; completed work is not undone. See [Verification and evidence](/workflows/verification).
+Unless the user explicitly chooses inline execution, workflows are the default for non-trivial requests or structured work with a verifiable objective. Requests such as `quickly`, `inline`, `do this directly`, and `don't use a workflow` override that default for the specified task, even when complex. Treat "quickly" as an inline execution choice, not a request for a faster workflow. Do not launch a hidden/nested replacement or ask the user to reapprove the choice. Preserve testing, review, evidence, safety and authorization inline. Quoted examples, questions about inline code, and descriptions of software that should run quickly are not mode instructions. For an active switch, safely hold/stop the affected run and reconcile completed work and in-flight effects before continuing without duplicates; completed work is not undone. See [Verification and evidence](/workflows/verification).
 
 When no opt-out was given, workflow signals include:
 
@@ -60,11 +62,13 @@ Workflow-first does not require builtins, monolithic workflows, or a force-fit b
 
 Rich custom workflows can compose the [common workflow patterns](/workflows/reliable-design#common-workflow-patterns): classify and branch at runtime, fan out and synthesize artifacts, run worker/verifier/reducer repair cycles, generate and filter or tournament-rank candidates, and loop until explicit evidence says the work is done. Workflow definitions are composable TypeScript modules — see [Workflow Composition](/workflows/authoring#workflow-composition). Atomic can write the definition, reload workflow resources, and run it for the current task; the workflow tool has no create action.
 
+Design for elapsed time using [runtime-aware scheduling and estimates](/workflows/reliable-design#runtime-aware-scheduling-and-estimates). Use available CI/test history to place focused checks at slice boundaries, defer redundant full-suite runs to the final candidate, and overlap independent work with CI without bypassing required gates. Before launch, report a completion range without confidence labels or scores. Inherit existing budget limits without asking for a budget choice before each launch, and override only limits the user explicitly requests. Preserve existing approval gates. An estimate is not a budget. At completion, compare the estimate with actual elapsed time.
+
 If exploration drifts without progress, save findings and choose a concrete next action. Transfer them through `reads` to a fitting workflow when permitted; continue directly with appropriate validation when inline was requested.
 
 | User need | Use |
 |-----------|-----|
-| Run, inspect, connect to, pause, interrupt, quit, resume, or check status for an existing workflow | `/workflow ...` or `workflow({ action: ... })` |
+| Run, inspect, connect to, pause, quit, resume, or check status for an existing workflow | `/workflow ...` or `workflow({ action: ... })` |
 | Run repository-wide research | Compose `fan-out-and-synthesize` with repository-focused branches, artifact outputs, and a synthesis barrier, or author a smaller task-specific research workflow. |
 | Run an implementation/review loop | Author a task-specific worker → fresh verifier → reducer loop with explicit evidence, repair bounds, and stop conditions. |
 | Create or edit reusable automation | A TypeScript workflow definition exported from `workflow({...})` |