@asrunjs/asrun 0.0.0-stage → 0.5.2

package/.claude/commands/explore-case.md

@@ -0,0 +1,18 @@
+---
+description: Explore the real pages for one case (optionally attended: you do the steps that write data), before generating the spec
+---
+
+Load the `exploring-cases` skill and explore: $ARGUMENTS
+In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
+Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
+framework skill, `.claude/skills/exploring-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
+(Project rules). F1–F6 always win.
+Arguments: `<case-id> <env> [--attended]`. The case id is the path below cases/ without `.md` (it may include a group
+folder, e.g. documents/landing-page) and is required. `<env>` is `staging` or `production`; it is required and there is no
+default (without one, stop and say so). With `--attended` I am at the machine and the browser window is visible: when a step
+writes data or needs a choice, hand it to me as the skill describes, wait for me, and record what I did as a general
+recipe under the step it belongs to (`- Recipe:` lines). Without `--attended`, never wait for me.
+Follow `assertion-targets.md` (list the candidates, never pick when in doubt, ask for the exact image/text/place/UI)
+and `readiness.md` (wait for the key requests and the content before you read anything) of the skill.
+This command edits cases/<case-id>.md only (plus screenshots under `.explore/targets/`). Do not ask me questions in the chat: write open questions into the case
+file as the skill describes, and end with the `RESULT:` line.

package/.claude/commands/gen-spec.md

@@ -0,0 +1,16 @@
+---
+description: Generate or update tests/<id>.spec.ts from cases/<id>.md (the id may be <group>/<name>)
+---
+
+Load the `generating-specs` skill and generate the spec for: $ARGUMENTS
+In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
+Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
+framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
+(Project rules). F1–F6 always win.
+Arguments: `<case-id> [<env>] [--force]`. The case file is cases/<case-id>.md (the id may include one group folder, e.g.
+documents/landing-page). `<env>` is the environment to explore in (`staging` or `production`); there is no default. If the spec already exists, it is
+left alone unless `--force` is given; with `--force` it is regenerated and overwritten.
+Follow the skill's procedure exactly, including `assertion-targets.md` and `readiness.md`; run `pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
+process), and do not create baselines.
+Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for QA,
+write the remaining questions into the case file), and end with the `RESULT:` line.

package/.claude/commands/heal-spec.md

@@ -0,0 +1,26 @@
+---
+description: Diagnose and fix a failing spec from its last report (without hiding real product regressions)
+---
+
+Load the `generating-specs` skill, section "Healing a failing spec", and follow it exactly.
+In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
+Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
+framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
+(Project rules). F1–F6 always win.
+Arguments: $ARGUMENTS
+Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`, with optional free text after them.
+- `<case-id>` and `<env>` (`staging` or `production`) are required. There is no default environment. Without one, stop
+  and say so.
+- `--profiles`: the profiles to heal. Without it, every profile that is logged in in `<env>`.
+- `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
+- `--hints <file>`: a file with what the user knows (what to heal, evidence, clues). Read it first. Any free text
+  after the arguments is the same kind of clue. Both are optional.
+Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see steps 4
+of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
+Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when the
+skill says it is needed. Always run with `--logged-in`. Tell me whether it is a test problem or a product finding.
+
+Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and `pnpm status ...` as plain commands, optionally piped to `tail` or
+`head`, and do not chain other commands with them (`;` or `&&`). Only these exact forms run outside Claude Code's
+sandbox, which tsx and the browser need. If a command still fails with `listen EPERM` or a sandbox error, stop and
+report it. Do not ask to disable the sandbox, and never add `--allow-writes` or set `ASRUN_ALLOW_WRITES`.

package/.claude/commands/make-case.md

@@ -0,0 +1,11 @@
+---
+description: Turn raw test notes (pasted text or a file) into case documents in cases/
+---
+
+Load the `making-cases` skill and turn this input into case documents: $ARGUMENTS
+In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
+Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
+framework skill, `.claude/skills/making-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
+(Project rules). F1–F6 always win.
+The input is either text or a path to a file with the notes. Follow the skill's procedure exactly.
+Ask me the open questions before writing any case file. Do not generate specs; that is `/gen-spec`.

package/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "sandbox": {
+    "excludedCommands": ["pnpm asrun *", "pnpm status *", "pnpm heal:evidence *", "tail *", "head *"]
+  }
+}

package/.claude/skills/exploring-cases/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: exploring-cases
+description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
+---
+
+# Exploring a case document
+
+Read the workspace `AGENTS.md` (hard rules and project rules), `cases/_template.md` (the target format), `references/open-questions.md` (how
+questions are written, resolved and reported), `references/assertion-targets.md` (which exact image, text, file or
+place a check looks at, and when to ask instead of picking), `references/readiness.md` (wait for the content before
+you read it) and `references/user-handoff.md` (how a person works in the browser while the agent waits, and how it is
+recorded). All but the last are binding for `/gen-spec` and healing too.
+
+## Before you start
+Read the workspace `AGENTS.md`: its §2 holds the project rules, and it points at the framework baseline. If
+`.claude/skills/exploring-cases.md` exists in the workspace, read it and apply it after this skill. Then apply
+`AGENTS.md` §2, which wins over both (the baseline, "Precedence"). F1–F6 always win. This is not a stop condition:
+continue with the procedure below.
+
+## Where this skill sits
+Three steps, each learns one thing:
+1. `/make-case` (making-cases): the **intent**. Turns raw notes into case documents. No browser.
+2. `/explore-case` (this skill): the **facts and the inputs**. What the pages really show, and what a person has to
+   do for the steps that write or need a choice. The only step where a person and the agent work together.
+3. `/gen-spec` (generating-specs): the **implementation**. Replays the case and its step recipes to find locators and
+   writes the spec. It does not judge the case again.
+
+The purpose of this skill is to leave a case that can be replayed without anybody: no ambiguity, every fact marked
+as observed, every input step described as a general recipe.
+
+This skill edits `cases/<id>.md` only. It never edits `profiles.yaml`, `tests/`, the framework folder or anything
+under `.auth/`.
+**The agent never writes data**, in staging or in production: a person does every step that writes or needs a
+choice (see `references/user-handoff.md`).
+
+It never stops to ask in the chat. A question that cannot be answered from the page goes into the case file, where
+the user answers it by editing the file, and the report says `RESULT: needs-input`. The one exception is a handoff in
+an attended run, where waiting for the person is the point.
+
+## Inputs
+- A case id (path below `cases/` without `.md`, e.g. `documents/landing-page`). It is required: an attended exploration of
+  every case at once is not a thing. Without an id, stop and say so.
+- An environment to explore (`staging` or `production`). It is required and there is no default. Without one, stop
+  before exploring and report `RESULT: needs-input` ("pass the environment").
+- Optionally `--attended`: a person is at the machine and the browser window is visible, so handoffs may happen.
+  Without it nothing waits, and a step that needs a person becomes a `[blocking]` TODO.
+
+## Procedure
+1. **Read** the case, `profiles.yaml` and `cases/_template.md`. Apply uncommitted user edits as they are: they are the
+   newest wording. Use targeted edits, never rewrite a whole file.
+2. **Static review.** Find:
+   - missing values for a profile: compare the entries of `## Values` (keyed by `default` and profile ids) with the
+     ids in `profiles.yaml`. A missing entry is a gap, not something to invent: leave it to the observations and
+     `/gen-spec`. The case's `## Values` is the only place for expected values; never copy them into `profiles.yaml`;
+   - ambiguous steps and checks without an expected result;
+   - steps that write data or need a choice: mark them `[writes]` / `[input]`. The front matter must list the
+     environments the finished spec may write in (`writes: [staging]`, or `[staging, production]`) with a
+     `writes-note`, the data must be named `[asrun] ...` and cleaned up, and a step that sends email is never
+     allowed in production and only in other environments when the profile has `email: true`;
+   - missing or doubtful `suites`/`envs`, a `writes` environment that `envs` excludes, and visual checks that are
+     too broad (screenshot a small element).
+3. **Repair the wording** (edit the file). Fix typos and grammar, make steps one action or one check each, put
+   assumptions in `## Notes` (not in `## Expected`), remove duplicates and template placeholders, make paths relative
+   to the app. Do not add checks the case did not ask for and do not drop any. Never edit the `## Source` table.
+4. **Explore**. The exploration runs through the `playwright-test` MCP only. If its tools are not registered in this
+   session (no `browser_*` / `generator_*` tool) or it reports that it failed to start, do not fall back to ad-hoc
+   Playwright scripts: they see a different browser and their network view does not count as
+   `browser_network_requests` (A2). Stop, tell the user which MCP server is missing and to run `pnpm asrun doctor`
+   (it names the broken `.mcp.json` / `opencode.jsonc` and the fix), make no observations, and end with
+   `RESULT: needs-input`.
+   Run `pnpm status --env <env>`. If it cannot run (a sandbox error such as
+   `listen EPERM` or a Chromium start failure), do not give up: open the profile's page through the MCP, and a page
+   that lands on the login page means the profile is not logged in. Explore at least one logged-in profile per
+   domain with the `playwright-test` MCP (`generator_setup_page` with `project=<profile-id>` and
+   `seedFile=tests/seed.spec.ts`). Profiles that are not logged in are skipped and named in the report; a human runs
+   `pnpm signin <profile-id>`.
+   - Do the read-only steps yourself: open, look, read, hover, switch tabs, open and close dialogs and menus.
+   - **A step that writes or needs a choice is done by the person**, per `references/user-handoff.md`: announce it,
+     name the finish condition, start recording, run the wait loop, then write down what happened. In a run that
+     is not attended, write a `TODO [blocking]` under the step instead.
+   - Close any modal that opens by itself without confirming it (for example the follow-up modal that opens after
+     publishing: close it and confirm nothing).
+   - When a confirm dialog appears while closing an email composer, choose "Discard" (see `AGENTS.md`).
+   - **Plan the order before you start: observe, then let the person delete.** Every read-only observation that
+     needs the data (preview, share menu, email composers, downloads, menus, the dialogs) is done while the data
+     exists, and the handoff that deletes it comes last. If the data is gone before a step was observed, that step
+     is not observed: say so, do not fill it in from memory.
+   - **Ready before you read** (`references/readiness.md`): `browser_network_clear` before an action that loads
+     something, then the action, then wait for its key requests (`browser_network_requests`) and for the content
+     signal, and only then take the snapshot. When the first read is empty or missing something, wait and read
+     again before you record or ask anything. Record the signal as `(observed after <signal>, ...)`.
+   - **Targets, not guesses** (`references/assertion-targets.md`): for every check on a logo, image, icon, file, PDF,
+     screenshot or repeated text, list ALL candidates, outline the one that is meant, take the highlighted screenshot to
+     `.explore/targets/<case-id>/`, **open that screenshot and look at it**, and write the card under `## Targets`.
+     If there are several candidates, only a position to tell them apart, a generic locator, dynamic data in the area,
+     or the page differs from the case: write a `[blocking]` TODO that names the exact image, text, place or UI wanted
+     and lists the candidates. In an attended run let the person outline the target with `browser_annotate`.
+   - **Downloads and email composers are opened for real** (the composer is closed with "Discard"). A download is
+     verified in five parts: starts, finishes, file exists, file valid, and a failure or timeout fails the check
+     (see `references/readiness.md`). Record the file name, size and kind as observed. A downloaded PDF is rendered
+     (`pnpm pdf:render`) and its page images are opened and looked at: record which pages show the target, where, and
+     the text. Which pages the check covers follows the case: every page unless the case says ONLY (strong wording).
+   - Compare every step with what is really there.
+
+   **Keep every browser call short, so nothing hangs** (`generating-specs` follows the same rules):
+   - One `browser_run_code_unsafe` call does one thing and should finish within about 60 seconds. Do not close a tab,
+     click, wait for a dialog and read it in one call: split it, and read the page (`browser_snapshot`) between the
+     steps. Only the handoff wait loop may take minutes.
+   - The browser times out an action or a lookup after 15 s (the config sets it). Pass a shorter `{timeout: 5000}` when
+     you wait for something that may not appear, and use `.catch()` or `isVisible()` for a one-time look while exploring only.
+      `isVisible()` answers for this instant and ignores any `timeout` passed to it, so after an action take a snapshot or
+      wait for a signal first. Never copy this pattern into a spec (see `references/readiness.md`, "Optional confirmations").
+   - After a click that should open something, take a snapshot and see what opened before you wait for it by role. A
+     dialog that did not appear is a finding (what did open instead?), not something to wait for or retry.
+   - A step that fails or times out twice is not tried a third time: write what you saw, add a `TODO [blocking]` under
+     the step and go on with the next one.
+5. **Write the `## Targets` section and the ready signals.** One card per target, in the format of
+   `references/assertion-targets.md`, and a `[T<n>]` reference in each check that uses it. Add `Ready when:` to every
+   step or target whose content loads after an action. A check with no card or a card with open doubts is a
+   `[blocking]` TODO, never a guess. Check the screenshots you saved: each must show what its card says.
+6. **Write the recipe lines** for every `[input]` or `[writes]` step that was handed off, from the recording, as a
+   general recipe under that step: one `- Recipe (phase): ...` line per phase. Format and rules are in
+   `references/user-handoff.md`. A step that was not handed off gets no recipe line and a `[blocking]` TODO. A case
+   that still has the old `## Inputs` section: move the lines of the steps you touch under those steps as
+   `- Recipe:`; `pnpm case:check` names the rest.
+7. **Resolve every open point** in the order of `references/open-questions.md`: answer it from the page, else apply
+   the safe default as the sentence above a `[non-blocking]` TODO block, else keep a `[blocking]` block. Write the
+   outcome into the case, every block with an empty `Answer:` line.
+8. **Check**: run `pnpm case:check` (it fails on an incomplete target card and warns on a check that has none) and fix every FAIL. If it fails with a sandbox error (`listen EPERM`), run
+   `node --import tsx <framework>/scripts/check-cases.ts` instead; it checks the same thing.
+9. **Report** in the user's language: what was changed (wording fixes, observations added, TODOs closed or narrowed),
+   what was explored (profile ids), which steps the person did and what was recorded for them, what was skipped and
+   why, the target cards written (and which ones are still questions), the steps whose first read was too early,
+   the steps that could not be observed (and why), the questions that remain with the sentence that deleting each block would confirm, and findings that look
+   like product bugs. End with the `RESULT:` line.
+
+## Hard rules
+- Edit `cases/<id>.md` only. Do not touch the `## Source` table.
+- The agent never writes data (see above). Never add `--allow-writes`, never set `ASRUN_ALLOW_WRITES`.
+- Never wait for a person in a run that is not attended.
+- Never invent expected values, profile names, counts or UI texts. Observations are marked as such. Values that a
+  check asserts are written into the case's `## Values` under the profile id (or `default` when they hold for every
+  profile), and never into `profiles.yaml`.
+- Never pick a target when in doubt, and never record a fact that was read before the content finished loading.
+- Never read or print anything under `.auth/`. Never automate login or 2FA.
+- Prose follows the artifact language of the workspace `AGENTS.md` §2 (English by default); structural tokens stay English.

package/.claude/skills/exploring-cases/references/assertion-targets.md

@@ -0,0 +1,103 @@
+# Assertion targets: never guess what a check looks at
+
+Shared by `exploring-cases`, `generating-specs` and healing. It is binding in all three.
+
+A check that looks at an image, a logo, a file, a piece of text or a place on the page must say **exactly which one**.
+"The logo", "the header", "the first image" are not targets. A spec built on a guessed target passes or fails for
+the wrong reason: a baseline once saved a content image instead of a logo, and a composer check once looked at a
+close icon instead of the logo.
+
+**When in doubt, ask. Never pick.** A wrong guess that passes is worse than a question.
+
+## The target card
+Every such check gets a card in the case, under `## Targets` (after `## Visual checks`). The checks refer to it as
+`[T1]`, `[T2]`, ... (in "Expected", "Visual checks" and in steps).
+
+```
+## Targets
+### T1 Preview logo
+- What: the product logo (the ACME wordmark), not the avatar or a content image.
+- Where: top-right corner of the preview page (`/preview/view/documents/...`).
+- Identified by: the image with alt text "<observed alt>" inside the page header region (role and name, or test id; never `.first()`).
+- Not: any element that shows item data (images, amounts, "Content #1").
+- Ready when: the image is visible and its natural width is above 0.
+- Reference example-staging: .explore/targets/documents/published-flow/T1-example-staging.png
+- Reference example-production: .explore/targets/documents/published-flow/T1-example-production.png
+```
+
+Fields:
+- `What` (required): the thing itself, in words a QA person agrees with. Say what it is and, when a look-alike
+  exists on the page, what it is not.
+- `Where` (required): the region of the page, dialog, tab or file page.
+- `Identified by` (required): how it is told apart from every look-alike: role and accessible name, test id (`data-tn`),
+  alt text, `title`, or an anchor element and a relation to it. Never a position (`.first()`, `.nth()`, "the first
+  image") unless the case's author wrote that exact rule (then quote them).
+- `Not` (recommended): the look-alikes that must not be matched. It is what `/gen-spec` and a reviewer check a baseline against.
+- `Ready when` (required when the content loads after an action): see `readiness.md`.
+- For a PDF or another multi-page file, also `Pages` (`all`, `first`, `last`, `1, 3`, plus the case's own words when it limits
+  the pages: see "Which pages are checked" in `readiness.md`; the default is every page) and `Region` (a corner or a box,
+  as fractions of the page: `top-left 30% x 12%`). Text that must or must not appear goes under `What` / `Not`.
+- `Reference <profile-id>` (one per profile explored): a screenshot of the page with the target outlined
+  (`browser_highlight`, then `browser_take_screenshot`), saved under `.explore/targets/<case-id>/T<n>-<profile-id>.png`.
+  `.explore/` is git-ignored, because the pages are logged in. Write `none: <reason>` when it could not be taken.
+  A reference is evidence for the reader; it is never a test baseline.
+
+`pnpm case:check` fails on a card without What/Where/Identified by and warns on a check about an image, logo, file,
+screenshot or PDF that has no `[T<n>]`.
+
+## Which checks need a card
+Any check whose words include logo, image, icon, photo, screenshot, PDF, file, download, color, or "shows <profile>", and
+every check that gets a screenshot baseline or an image/hash comparison. Text checks need a card when the text can
+occur more than once on the page (a product name in a header and in a footer).
+
+## When to ask (a `🚫 TODO [blocking]` block, not a guess)
+Ask instead of choosing when ANY of these is true:
+1. **More than one candidate** matches the description (two logos, a logo and a watermark, several images with alt text).
+2. **The only way to find it is by position** (`.first()`, `.nth()`, "the image at the top").
+3. **The only locator is generic**: `img`, `svg`, `img, svg`, `[alt]`, a CSS class chain.
+4. **The area contains dynamic data**: rows, prices, dates, avatars, counts. A screenshot of it is never stable.
+5. **It has no stable identity**: no alt, title, name or test id, so a rename or a reorder silently changes what is checked.
+6. **The case says something different from the page** (the case says "top-right corner", the page has the logo top-left).
+7. **It could not be opened or seen** in this run (a dialog, a file, a tab that needs data that is gone).
+8. **A value is unknown** for a profile (no entry in the case's `## Values`), or the profiles differ where the case
+   says "same".
+
+The question names the exact thing wanted: image, text, place or UI element. Write it like this, with the candidates
+as evidence, so the person answers by pointing:
+
+```
+- The preview shows the product logo in its top-right corner [T1].
+  - 🚫 TODO [blocking]: Which element is the logo? Candidates on example-staging: (a) the image with alt "Example" in the page header, (b) the first content image "Content #1", (c) the avatar. (candidates highlighted in .explore/targets/documents/published-flow/T1-candidates-example-staging.png)
+    - ✍️ Answer:
+```
+
+The parent sentence is the guess, so a `[blocking]` card is never turned into a check. `/gen-spec` writes
+`test.fixme(true, '<the question>')` for it.
+
+In an **attended** run, do not write the question first: ask the person to outline the target in the browser with
+`browser_annotate`, then write the card from the annotation (the annotated screenshot is the Reference).
+
+## How a card is made (exploring)
+1. Find every candidate: `browser_find` / `browser_snapshot`, and count them. Do not stop at the first match.
+2. Decide with the rules above: exactly one candidate with a stable identity and no dynamic data means a card;
+   anything else means a question.
+3. Outline the target with `browser_highlight`, take the screenshot to `.explore/targets/...`, then `browser_hide_highlight`.
+4. **Look at the screenshot** (read the image file) and say in the card what it shows. If it shows something other than
+   the card's `What` (a content image instead of a logo), the card is wrong: fix it before going on. This is the step that
+   would have caught the wrong baseline.
+5. Do this for every profile that has an entry in the case's `## Values`. A target that differs between profiles is not
+   settled: write a `[blocking]` question instead of encoding one profile's locator as if it held for all.
+
+## What the spec does with a card (generating)
+- The check is written against `Identified by`, and the line before it is `// target: T<n>`. `pnpm spec:lint` fails a
+  screenshot, a logo/image locator or a position pick that has no target comment.
+- A semantic assertion always comes before a pixel one: the element's alt/title/src or role matches, and it is where
+  `Where` says, then `toHaveScreenshot` on that element only.
+- A card with `Not:` gets a check that the matched element is not one of those (for example it shows no item text).
+- Screenshot only elements without dynamic data. If the target card cannot give such an element, it is a question.
+
+## What healing does with a card
+Before deciding "product changed" or "test is wrong", check **the assertion itself**: does the locator still point to
+what the card's `What` says? Open the baseline and the failure screenshot and compare each with the card. A baseline
+that shows something else is a test bug: delete it and report it (a person creates the new one). A card that no longer
+matches the page is a question for the person, not something to rewrite quietly.

package/.claude/skills/exploring-cases/references/handoff-card.js

@@ -0,0 +1,128 @@
+async (page) => {
+  // Floating "YOUR TURN" card for a handoff to a person. Do not copy, shorten or rewrite this file: load it with
+  // browser_run_code_unsafe({filename}) after setting the options (see user-handoff.md, "The wait loop").
+  const ctx = page.context();
+  const cfg = ctx.__handoffCfg || {};
+  const message = cfg.message || 'Do the step, then press Done';
+  const copy = Array.isArray(cfg.copy) ? cfg.copy : [];
+  const doneText = cfg.doneText || null;
+  const maxMs = cfg.maxMs || 600000;
+  await ctx.grantPermissions(['clipboard-read', 'clipboard-write']).catch(() => {});
+
+  const paint = (p) => p.evaluate(({message, copy}) => {
+    if (document.getElementById('__ASRUN_panel')) return;
+    const KEY = '__ASRUN_panel_state';
+    let state = {minimized: false, left: null, top: null};
+    try { state = {...state, ...JSON.parse(sessionStorage.getItem(KEY) || '{}')}; } catch (e) {}
+    const save = () => { try { sessionStorage.setItem(KEY, JSON.stringify(state)); } catch (e) {} };
+    const icon = (body) => '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' + body + '</svg>';
+    const ICON = {
+      copy: icon('<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>'),
+      check: icon('<polyline points="20 6 9 17 4 12"/>'),
+      up: icon('<polyline points="18 15 12 9 6 15"/>'),
+      down: icon('<polyline points="6 9 12 15 18 9"/>'),
+      move: icon('<polyline points="5 9 2 12 5 15"/><polyline points="9 5 12 2 15 5"/><polyline points="15 19 12 22 9 19"/><polyline points="19 9 22 12 19 15"/><line x1="2" y1="12" x2="22" y2="12"/><line x1="12" y1="2" x2="12" y2="22"/>'),
+    };
+    const host = document.createElement('div');
+    host.id = '__ASRUN_panel';
+    host.style.cssText = 'all:initial;position:fixed;z-index:2147483647;left:16px;bottom:16px';
+    const root = host.attachShadow({mode: 'open'});
+    root.innerHTML = '<style>' +
+      '.card{width:300px;max-width:calc(100vw - 32px);background:#1e3340;color:#fff;font:13px/1.4 system-ui,sans-serif;border-radius:8px;box-shadow:0 6px 20px rgba(0,0,0,.35);overflow:hidden}' +
+      '.card.min{width:auto}.card.ok{background:#15803d}' +
+      '.bar{display:flex;align-items:center;gap:8px;padding:7px 8px 7px 12px;background:#b45309;cursor:grab;user-select:none;touch-action:none}' +
+      '.ok .bar{background:#166534;align-items:flex-start;padding-top:9px}.bar b{flex:1;min-width:0;font-size:12px;letter-spacing:.04em;white-space:nowrap}.ok .bar b{white-space:normal;line-height:1.35}.grip{display:inline-flex;opacity:.8}' +
+      'button{all:unset;box-sizing:border-box;cursor:pointer;display:inline-flex;align-items:center;justify-content:center;gap:4px;padding:3px 8px;border-radius:4px;background:rgba(255,255,255,.18);color:#fff;font:600 12px system-ui,sans-serif}' +
+      'button:hover{background:rgba(255,255,255,.3)}' +
+      '.body{padding:10px 12px 12px;display:flex;flex-direction:column;gap:8px}.min .body,.ok .body{display:none}' +
+      '.mini-done{display:none}.min .mini-done{display:inline-flex}' +
+      '.chip{display:flex;align-items:center;gap:6px;background:rgba(0,0,0,.28);padding:4px 4px 4px 8px;border-radius:4px}' +
+      '.chip span{flex:1;font:12px ui-monospace,Menlo,monospace;word-break:break-all;user-select:all}' +
+      '.row{display:flex;gap:8px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}' +
+      '</style>' +
+      '<div class="card" id="card"><div class="bar" id="bar" title="Drag to move"><span class="grip">' + ICON.move + '</span><b id="title">YOUR TURN</b>' +
+      '<button class="mini-done" data-a="done">Done</button><button id="toggle" title="Minimize or expand" aria-label="Minimize or expand"></button></div>' +
+      '<div class="body"><div id="msg"></div><div id="chips"></div><div class="row">' +
+      '<button class="primary" data-a="done">Done</button><button data-a="skip">Cannot do this</button></div></div></div>';
+    const card = root.getElementById('card'), bar = root.getElementById('bar'), toggle = root.getElementById('toggle');
+    root.getElementById('msg').textContent = message;
+    const chips = root.getElementById('chips');
+    chips.style.cssText = 'display:' + (copy.length ? 'flex' : 'none') + ';flex-direction:column;gap:6px';
+    for (const text of copy) {
+      const chip = document.createElement('div');
+      chip.className = 'chip';
+      chip.innerHTML = '<span></span><button aria-label="Copy to clipboard" title="Copy">' + ICON.copy + '</button>';
+      chip.firstChild.textContent = text;
+      const btn = chip.lastChild;
+      btn.addEventListener('click', async () => {
+        try { await navigator.clipboard.writeText(text); } catch (e) {
+          const area = document.createElement('textarea');
+          area.value = text; area.style.cssText = 'position:fixed;opacity:0';
+          document.body.appendChild(area); area.select(); document.execCommand('copy'); area.remove();
+        }
+        btn.innerHTML = ICON.check + 'Copied';
+        setTimeout(() => { btn.innerHTML = ICON.copy; }, 1200);
+      });
+      chips.appendChild(chip);
+    }
+    const apply = () => {
+      card.classList.toggle('min', state.minimized);
+      toggle.innerHTML = state.minimized ? ICON.up : ICON.down;
+      root.getElementById('title').textContent = state.minimized ? 'YOUR TURN' : 'YOUR TURN: control is yours';
+    };
+    const place = () => {
+      if (state.left === null) return;
+      const r = host.getBoundingClientRect();
+      const left = Math.max(0, Math.min(innerWidth - Math.min(r.width, 80), state.left));
+      const top = Math.max(0, Math.min(innerHeight - 36, state.top));
+      host.style.left = left + 'px'; host.style.top = top + 'px'; host.style.bottom = 'auto';
+    };
+    root.addEventListener('mousedown', (e) => { if (e.target.closest('button')) e.preventDefault(); });
+    root.addEventListener('click', (e) => { const a = e.target.closest('[data-a]'); if (a) window.__handoff = a.dataset.a; });
+    toggle.addEventListener('click', () => { state.minimized = !state.minimized; save(); apply(); place(); });
+    let drag = null;
+    bar.addEventListener('pointerdown', (e) => {
+      if (e.target.closest('button')) return;
+      const r = host.getBoundingClientRect();
+      drag = {dx: e.clientX - r.left, dy: e.clientY - r.top};
+      bar.setPointerCapture(e.pointerId); bar.style.cursor = 'grabbing';
+    });
+    bar.addEventListener('pointermove', (e) => {
+      if (!drag) return;
+      state.left = e.clientX - drag.dx; state.top = e.clientY - drag.dy; place();
+    });
+    bar.addEventListener('pointerup', () => { drag = null; bar.style.cursor = 'grab'; save(); });
+    host.__finish = () => {
+      card.classList.remove('min'); card.classList.add('ok');
+      toggle.style.display = 'none';
+      root.getElementById('title').textContent = 'Done: control is back with Playwright. Do not touch the page.';
+      setTimeout(() => host.remove(), 2000);
+    };
+    apply();
+    document.documentElement.appendChild(host);
+    place();
+    if (!document.title.startsWith('YOUR TURN | ')) document.title = 'YOUR TURN | ' + document.title;
+  }, {message, copy}).catch(() => {});
+
+  for (const p of ctx.pages()) await p.evaluate(() => { window.__handoff = null; }).catch(() => {});
+  const started = Date.now();
+  let outcome = null;
+  while (!outcome && Date.now() - started < maxMs) {
+    for (const p of ctx.pages()) {
+      await paint(p);
+      const flag = await p.evaluate(() => window.__handoff || null).catch(() => null);
+      if (flag) outcome = flag;
+      else if (doneText && await p.getByText(doneText).first().isVisible().catch(() => false)) outcome = 'condition';
+    }
+    if (!outcome) await page.waitForTimeout(500);
+  }
+  for (const p of ctx.pages()) {
+    await p.evaluate(() => {
+      document.getElementById('__ASRUN_panel')?.__finish();
+      document.title = document.title.replace(/^YOUR TURN \| /, '');
+    }).catch(() => {});
+  }
+  await page.waitForTimeout(2300);
+  for (const p of ctx.pages()) await p.evaluate(() => sessionStorage.removeItem('__ASRUN_panel_state')).catch(() => {});
+  return {outcome: outcome || 'timeout', waitedMs: Date.now() - started};
+}

package/.claude/skills/exploring-cases/references/open-questions.md

@@ -0,0 +1,116 @@
+# Open questions: write, resolve, report
+
+Shared by `exploring-cases` and `generating-specs`. The agent never waits for an answer in the chat: it may run
+without anybody present (a one-shot `claude -p` / `opencode run`). The case file is where the agent and the user
+talk to each other, so nothing is lost between runs, tools or sessions.
+
+## How a question is written in the case file
+Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed by QA` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it.
+Every question is a small block that hangs under a normal sentence. The sentence is the agent's suggestion, written
+exactly as it should read in the final case. The block holds the question and an empty answer slot:
+
+```
+- <the suggested statement, a complete sentence that can stand in the case as it is>
+  - ❓ TODO [non-blocking]: <the question, one sentence>? (<evidence, e.g. seen on example-staging>)
+    - ✍️ Answer:
+```
+
+The same shape is used under a step, under a bullet of "Expected" and under the yaml block of "Values":
+
+```
+11. Delete the document with the "Delete" option of its "..." menu on the list page. [writes]
+    - 🚫 TODO [blocking]: How is the document deleted? (the same path was observed for drafts on example-staging)
+      - ✍️ Answer:
+```
+
+Rules for writing it:
+- **The suggestion is a statement, never a question or a half sentence.** "The logo is visible and not empty." is
+  right. "Suggested: visible." and "what is the logo?" are wrong. When no value is known, state the safest reading
+  (visible and not empty, the spec accepts both, no screenshot baseline is taken, ...). Never invent a concrete
+  value such as a text, a count or a color.
+- **The suggestion is always the parent line**, so deleting the TODO block leaves a finished case. Do not put the
+  suggestion inside the TODO line, and do not write `Suggested:`.
+- **Always leave the empty `Answer:` line** as the last line of the block, one level deeper than the `TODO` line.
+  Nothing goes after it, and there is exactly one per block.
+- **Both the suggestion and the question may wrap.** A wrapped line is plain text (no bullet): the block ends at the
+  first blank line or at a line that is not indented deeper than the `TODO` line. Indent the block by 4 spaces under a
+  numbered step (2 under a `-` bullet) so Markdown renders it inside that step; `pnpm case:check` warns otherwise.
+- The TODO line has the question and, when the page showed something, the evidence in parentheses. Nothing else.
+- `[blocking]`: the spec cannot be written correctly without the answer. `[non-blocking]`: the suggestion is safe;
+  QA should confirm it later but nothing waits for it.
+- One question per block; narrow broad questions down instead of copying them ("which profile elements?" becomes
+  "is the logo the only per-profile element in the left side bar?").
+- A value read from a page is not a question: write it as a statement marked `(observed, 🔍 to be confirmed by QA)`.
+  It needs no TODO block; the reviewer confirms it by deleting the marker.
+
+## How the user answers
+Two ways, and the agent must understand both on the next run:
+- **The suggestion is fine:** delete the whole TODO block (the `TODO` line and the `Answer:` line). The parent
+  sentence is now confirmed text.
+- **Own answer:** write it after `Answer:`. The answer replaces the parent sentence where they disagree. The user
+  may delete the rest of the block, or leave it.
+- An `Answer:` with no text is not an answer. A block that was left untouched stays open.
+- An old `TODO: ...` line without a tag or without a parent suggestion (written before this format) counts as
+  `[blocking]` until it is rewritten into the shape above.
+
+The agent folds an answer into plain text in the right place (the parent sentence, an expected bullet, an entry of
+`## Values`, a step) and removes the `TODO` line and the `Answer:` line. If an answer contradicts the page, it keeps the
+answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It never overrides the user.
+
+## What an open block means for the agent
+- No TODO block under a sentence: the sentence is confirmed. Use it.
+- `[non-blocking]` block: use the parent sentence as the expectation; keep the block for QA.
+- `[blocking]` block: the parent sentence is only a guess. Do not generate a check from it: write
+  `test.fixme(true, '<the question>')` inside the step (or skip that profile).
+- Every run re-evaluates the blocks that are already in the file against the rules below, including their tag: a
+  `[blocking]` question that now has an observation or a safe default is downgraded or closed in the file, and the
+  edit is part of the report. Do not carry old tags over.
+
+## Resolution order (no question goes to the user while a better step exists)
+1. **The page answers it.** Facts such as exact labels, which controls exist, where the logo is, what a menu holds
+   are answered by exploration (`/explore-case`; needs an environment and a logged-in profile; the agent only reads, a person does the steps that write). Rewrite the parent sentence
+   with the fact, mark it `(observed, 🔍 to be confirmed by QA)` and remove the block.
+   - A check with no expected value ("check X", "can see Y") becomes: the observed behaviour, marked as observed.
+     A spec may be generated from it.
+   - Values that a check asserts (logo name, label, option list) are observed per profile and written into the case's
+     `## Values`, under the profile id (or `default` when they hold for every profile).
+2. **A default is safe.** Use the default of `gaps.md` in the `making-cases` skill (visible and not empty, all
+   environments, `suites: [regression]`, ...) as the parent sentence and keep the block as `[non-blocking]`.
+   Implementation questions are in this group: whether "visible" is enough, how long to wait, which of two equally
+   good locators for the SAME element to use. Pick the most robust option the page offers, state it, and do not
+   block on it. **Not in this group: which element a check looks at.** That is a target (`assertion-targets.md`):
+   one clear candidate becomes a card, anything else blocks.
+3. **Otherwise it blocks.** Keep the block as `[blocking]`, narrowed as far as the page allows, with the best guess
+   as the parent sentence.
+
+## What is always blocking (never guess, never generate around it)
+- A step that would write data or send email while the front matter has no `writes` list (or no `writes-note`), or for an environment that `writes` does not list.
+- A step that writes data or needs a choice, in a run that is not attended: no person can do it, so there is nothing to
+  record as a `- Recipe:` line under it.
+- A step that cannot be performed after exploring: the path 404s, the control does not exist for any profile, or it
+  needs data that does not exist and the case does not create it.
+- Observed behaviour that contradicts what the case states, or a profile that deviates from the others where the case
+  says "same for every profile". This may be a product bug: record it (`(observed: <what>, on <profile-id>)`),
+  do not encode the deviating value as the expectation, and say it in the report.
+- **An assertion target that is in doubt** (`assertion-targets.md`): several candidates, only a position or a generic
+  locator to find it, dynamic data in its area, no stable identity, or the page differs from the case. The question
+  names the exact image, text, place or UI wanted and lists the candidates. Never a safe default, because a wrong
+  guess passes silently.
+- An intent question the page cannot answer ("should this also work for agents?").
+- No environment was given, or no profile is logged in, so a fact that needs the page cannot be observed.
+
+## Final report
+Report in the user's language. List every open block with its question and the parent sentence it would confirm, so
+the user can see what deleting it accepts. The last line of the final message is exactly one of:
+
+```
+RESULT: ready
+RESULT: needs-input
+```
+
+- `ready`: no `[blocking]` question remains. Non-blocking ones may remain; list them so QA can confirm them.
+- `needs-input`: at least one `[blocking]` question remains in the case file (list each with its parent sentence),
+  or the work could not be done (no environment, nobody logged in). Say what the user should edit in the case file,
+  then re-run.
+
+Do not write anything after the `RESULT:` line.