@asrunjs/asrun 0.0.0-stage → 0.5.2

package/.claude/skills/exploring-cases/references/readiness.md

@@ -0,0 +1,146 @@
+# Readiness: look at the result only after the content is there
+
+Shared by `exploring-cases`, `generating-specs` and healing. It is binding in all three.
+
+A page that has just reacted is not ready. Dialogs, composers, previews, lists and PDFs show a frame first and fill
+in later. Reading it too early gives a false "missing", "empty" or "wrong", and exploration then writes the false fact
+into the case, the spec encodes it, and healing believes it.
+
+**The rule: after every action that loads something, wait for its key requests to finish and for the content itself
+to be visible, before reading, asserting or recording anything.**
+
+## What "ready" is
+All of these, in this order:
+1. **The key requests finished** with a success status. The key requests are the data calls the action starts
+   (the composer's content, the list query, the PDF render), not images, fonts or analytics.
+2. **Nothing says it is still loading**: no spinner, progress bar, skeleton, `aria-busy="true"`, "Loading..." text.
+3. **The content itself is visible**: a positive signal that only exists when the data is there (a field with its value, the
+   first row, an image whose `naturalWidth` is above 0), never "the frame is open".
+4. **Stable**: for exploration, two snapshots one second apart say the same.
+
+A check for something **missing, empty or hidden** is only valid after a positive ready signal. "The list has no X"
+means: the list finished loading and has rows, and none is X.
+
+## Exploring
+- Know the key requests: after the action, call `browser_network_requests`, pick the data calls (XHR/fetch to the
+  app's API, the ones that return the content). Wait until they are finished; use `browser_network_clear` before the
+  action so the list only holds what the action started.
+- Then wait for the content signal (`browser_wait_for` with text, or `browser_find` that the content is there), and
+  take the snapshot only then. A snapshot taken right after a click is a frame, not a fact.
+- Observations record the ready signal: `(observed after <signal>, ...)`. A fact with no signal is not recorded.
+- When the first read shows less than expected (empty, a missing field, a logo not there), do not record it yet and do
+  not raise a question yet. Wait for readiness, read again, and only then decide. Mention in the report that the first
+  read was too early, with what was missing.
+- Do it for every profile: loading time differs between profiles and environments.
+
+## In the case
+Steps and targets state their ready signal: `Ready when: <signal>` under the step, or the target card's `Ready when`.
+Example: `Ready when: the composer's "To" field is visible and the logo image has loaded.` It is what `/gen-spec` turns into
+`ready` and `responses`.
+
+**A ready signal is when to look, `## Expected` is what must hold.** Write the shortest positive signal that proves the
+content arrived (one element, one image, one first row): no counts, no negatives, no "and everything else is right". The
+requirement itself lives in `## Expected`, and a check may repeat the same element the signal names — one is the wait,
+the other the assertion. A ready signal is never the only place where a required behaviour is written down.
+
+A step that loads something and has no `Ready when` is read too early by whoever replays it: `/gen-spec` then waits for
+the step's text alone, and a check on what only appears later fails or records a false "empty". Add one to every step
+whose action opens a page, a dialog, a tab, a list or a preview.
+
+## Generating (spec code)
+Use `actAndWait` and `expectNotBusy` from `@asrunjs/asrun/ready`, and `verifyDownload` from `@asrunjs/asrun/downloads`:
+
+```ts
+// ready: the composer shows its recipient field and the logo image has loaded
+const composer = page.getByRole('dialog', {name: 'Email PDF'});
+await actAndWait(page, () => option.click(), {
+  responses: [/\/api\/documents\/[^/]+\/email-preview/],
+  ready: [composer.getByRole('textbox', {name: 'To'}), logo],
+});
+await expectImageLoaded(logo);
+```
+
+- Register the response wait **before** the action (`actAndWait` does).
+- Every action that opens a dialog, a tab, a menu with data, a list or a preview waits for its key requests and its content
+  signal. The request URL patterns come from `browser_network_requests` during exploration, not from guesses; if none was
+  seen (the action was not run), say "not verified on the page" in the report.
+- Never `waitForTimeout`, never `networkidle`. They wait for time or for silence, not for the content. `pnpm spec:lint` fails both.
+- Never `if (await x.isVisible()) ...` to decide something that may not have loaded yet. Wait for a ready signal, then branch.
+  Where an element is genuinely optional, say what proves the page finished (`// ready: ...`) before looking for it.
+- `locator.isVisible()` and `isHidden()` answer for this instant only. Their `timeout` option is deprecated and ignored:
+  `isVisible({timeout: 3_000})` does not wait 3 seconds. Never write it, and never use `.catch(() => false)` to make it
+  look like a wait. `pnpm spec:lint` fails both.
+- An optional confirmation (see below) is handled with `clickOptionalUntilHidden`, not with `isVisible`.
+
+### Optional confirmations (a dialog that may or may not show up)
+Closing a composer, leaving an editor or deleting something can raise "Discard draft?", "Are you sure?" or nothing at all,
+and the dialog can show up a second or two after the click. A check made right after the click sees "no dialog" and skips
+it, then the next check (the composer is closed) races a dialog that appears later and fails.
+
+The click on the confirmation and the check that the action finished go into **one retry loop**:
+
+```ts
+await composer.getByRole('button', {name: 'close', exact: true}).click();
+await clickOptionalUntilHidden(page.getByRole('button', {name: 'Discard', exact: true}), composer, {
+  message: 'The email composer did not close',
+});
+```
+
+- Each round: click the confirmation if it is visible now, then check that the target is hidden. A late dialog is clicked
+  in a later round; no dialog passes in the first round.
+- Never decide "there is no dialog" from one look, and never wait a fixed time for it.
+- The same holds for any other optional modal (for example "Add to Business Tracker" after publishing): when the case says
+  it opens, assert it with a waiting `expect(...).toBeVisible({timeout})`; when it may or may not open, use a loop that
+  also checks the next page state, or wait for the signal that proves the action finished (URL, heading), then look.
+- A check for absence needs a positive ready signal in front of it (`// ready: <signal>`).
+- A new tab: wait for the page event first (`context.waitForEvent('page')`), then for its URL, then for its content signal.
+- A download is verified with `verifyDownload` (below), never with a bare `waitForEvent('download')`.
+
+## Downloads
+Any download (PDF, image, CSV, ZIP), in exploration and in the spec, is verified in five parts, and the verification
+step fails as a whole when any part fails or times out:
+1. wait for the download to start after the click;
+2. wait for the download to finish;
+3. check that the file exists and has content;
+4. check that the file is valid for its kind (an image has the right signature; a ZIP/CSV likewise; a PDF starts with `%PDF-`,
+   ends with `%%EOF` and **opens with at least one page**), and run the case's own validation if there is one;
+5. any failure or timeout of 1 to 4 fails the verification with a message that names the stage.
+
+`verifyDownload(page, trigger, {kind, fileName?, minBytes?, validate?})` does exactly this. Name the file type in the
+case (`kind`), and describe in a target card what the file must contain.
+
+### PDF content: read it like a person (rendered images and extracted text)
+A PDF check never stops at "it is a PDF". `verifyDownload(..., {kind: 'pdf'})` returns `file.pdf`, and
+`expectPdf(file.pdf!, {...})` from `@asrunjs/asrun/pdf` then:
+- **renders the pages to images** (scale 2, white background) and, for every region check, fails when the region is blank
+  and compares it with the profile's baseline image (2% tolerance; the first run with `--update-snapshots` creates the
+  baseline and a person looks at it, like any other baseline);
+- **extracts the text** of every page and checks `textContains` / `textNotContains` (the names of the other profiles, for
+  example).
+Regions are fractions of the page from the top-left corner; `corner('top-left')` is the usual logo corner.
+
+**Which pages are checked is the case's decision, case by case:**
+- The case says ONLY certain pages in strong words (a requirement: "only", "exactly", "must be on the first page", "the
+  logo is on the first and last page and nowhere else"): check just those (`pages: 'first' | 'last' | [1, 3]`), and put
+  `// pages: <the case's words>` above the check so a reviewer can see where the limit comes from.
+- The case names pages softly ("should", "always", "usually", "typically", "normally", "e.g.") or names no page: check
+  **every page** (`pages: 'all'`, the default). The named page is then only the place where the check was first seen.
+- A page limit that comes from the agent's own reading of the case is not allowed. When it is unclear whether a wording is
+  a strong requirement, check all pages and put the doubt in a `[non-blocking]` TODO.
+
+**While exploring, the agent looks at the PDF too:** save the downloaded file under `.explore/` (`download.saveAs(...)`
+in the same `browser_run_code_unsafe` call that waits for the download), run
+`pnpm pdf:render <file> --out .explore/targets/<case-id>/<name> --pages all --corner top-left`, then **open the page
+images** and say in the card where the logo really is on each page, which pages have it and which do not, and what the
+text shows. The rendered pages are the card's `Reference`. If the logo is not where the case says, that is a question.
+
+While exploring, do the same by hand: click, wait for the download event, see the file finish, read its size and its first
+bytes. Record "(observed: <file name>, <size>, valid <kind>)".
+
+## Healing
+A failure of the kind "missing", "empty", "not visible", "wrong count", "timeout waiting for X" is first a suspected
+readiness problem, then a suspected product problem:
+1. Read the failure screenshot and video: was the page still loading (a spinner, a skeleton, an empty frame)?
+2. Run the failing step by hand with the readiness protocol above and compare.
+3. Only when the content is complete and still not what the case says is it a test-expectation or product matter.
+4. A readiness fix goes into the spec as `actAndWait` / a ready signal, never as a longer timeout alone and never as a sleep.

package/.claude/skills/exploring-cases/references/user-handoff.md

@@ -0,0 +1,157 @@
+# User handoff: a person works in the browser, the agent waits
+
+Used by `exploring-cases` (and by `making-cases` never: it does not open a browser). `generating-specs` never hands
+off; it replays the step recipes that an exploration recorded.
+
+## The rule
+**An agent never writes data.** Not in staging, not in production. Every step that creates, edits, publishes, shares,
+deletes or otherwise changes data, and every step that needs a human's choice (an existing document, items, a contact
+name), is done by the user in the browser window that Playwright opened. Writing is rare (only while preparing a
+case) and a person succeeds where an agent guesses. The agent drives only what is read-only: open, look, read,
+hover, switch tabs, open and close dialogs and menus.
+
+The runtime permission is a different thing and stays as it is: `writes: [<env>, ...]` in the case front matter says
+where the finished spec may write, and a human confirms a run in any environment except staging.
+
+## When a handoff happens
+Only in an attended run (`--attended`, a person is at the machine, the browser window is visible). A step is a
+handoff when it is marked `[input]` or `[writes]` in the case, or when the agent finds out while exploring that the
+next action would write data or needs a choice.
+
+Without `--attended` the agent does not wait. It writes a `TODO [blocking]` under that step ("a person has to
+perform this step; run /explore-case with --attended") and goes on with the rest. Never wait for a person in a run
+that nobody watches.
+
+## Before the handoff
+1. Say what the user has to do and when it is finished, in one or two sentences ("Fill in the form, pick two
+   items, then press Done"). Name the finish condition first (below).
+2. Put every text the user has to type into `copy` (the `[asrun] ...` name of a document, a title), so it can be
+   copied with one click.
+3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
+   profile). Never ask for login or 2FA. Name everything the user creates `[asrun] <something>`.
+4. Start recording with `browser_start_recording` (see "Recording").
+
+## The wait loop
+Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
+timeout), so no polling from outside is needed. The loop:
+
+- **Shows a small floating card, not a bar.** It sits in the bottom-left corner and only the card takes clicks, so
+  nothing of the page is covered or blocked. The user can **drag** it by its title bar and **minimize** it to a small
+  pill that still has a Done button. Position and minimized state survive a page reload (kept in `sessionStorage`).
+- **Click to copy.** Every text in `copy` (for example the `[asrun] ...` name the user has to type) is shown on its
+  own line with a copy icon; one click puts it on the clipboard and the icon shows "Copied". Pass only text that the
+  case says to type; leave `copy` empty when there is none.
+- **Resets the flag first**: `window.__handoff = null` on every page it paints. A flag left over from an earlier
+  handoff ends the wait at once.
+- **Paints the card on every open tab** and repaints after navigation (a new page has no card). The document
+  editor opens in a new tab, so the loop looks at `context.pages()`, not only at the first page.
+- **Stops** when one of these happens, whichever is first: the user presses Done or "Cannot do this" on the card
+  (`window.__handoff` is `'done'` or `'skip'`), or the finish condition holds, or the time is up (default 10 minutes).
+- **Ends visibly**: the card turns green and says control is back for two seconds, then it is removed, and the tab
+  titles are restored.
+- The card lives in a Shadow DOM (the site's CSS cannot change it), does not take keyboard focus (the user can keep
+  typing in the page) and works even when the page locks all clicks behind a modal. The icons are inline SVG because
+  the card is injected into the page under test; the web UI's react-feather rule does not apply to it.
+
+**Never write this code yourself and never shorten it.** It lives in `references/handoff-card.js` (next to this
+file) and a rewritten, simplified card has already gone wrong once: it had no drag handle, no minimize button and
+no copy icon. Load that file in two calls:
+
+**Two calls, every time.** Set the options with their own call and only then run the card, for every handoff,
+including a second one later in the same run. Never reuse the options of an earlier handoff and never change them
+inside the call that runs the card: OpenCode reports a tool call only when it ends, so the options call is the only
+way the web UI can see that a person is needed while the card waits. With the card alone there is no "Your turn"
+badge, no count in the tab title and no notification (a HINT in the job log says so).
+
+1. Set the options on the browser context (this call only sets data):
+   ```js
+   async (page) => {
+     page.context().__handoffCfg = {
+       message: '<what the user does, one sentence>',
+       copy: [],                  // texts to type, e.g. ['[asrun] published document']
+       doneText: null,            // text that appears when finished, or null
+       maxMs: 600000,
+     };
+     return 'cfg set';
+   }
+   ```
+2. Run the card and wait: `browser_run_code_unsafe` with `filename` set to the absolute path of
+   `<framework>/.claude/skills/exploring-cases/references/handoff-card.js` (use the absolute path of the repository, a
+   relative one is resolved against the workspace root, which may be the parent folder). It returns `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs}`.
+
+Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
+chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. If not, stop and report
+it; do not hand off with a broken card.
+
+Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
+Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
+UI, the UI notices the handoff by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call, whether the
+browser tool is called directly or through the CLI's code mode, as OpenCode's `execute` tool does) and shows the
+"Your turn" badge, a count in the tab title and, if the person switched notifications on, a browser notification;
+this is why the message in `__handoffCfg` must be a plain string literal. A macOS notification is a bonus and may
+fail in a sandbox: `osascript -e 'display notification "<task>" with title "AsRun" sound name "Glass"'`. If it
+fails, go on.
+
+## Finish condition
+Pick one that the page can show, before the handoff, and write it into the message of the card:
+- a text that appears (a "Saved" toast, the title of the next step) or one that goes away;
+- a URL that the page reaches;
+- an element that appears or disappears (an editor that closes).
+
+The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give up a step.
+
+## After the handoff
+- The card turns green and says control is back ("Done: control is back with Playwright. Do not touch the page.")
+  for two seconds before it is removed, so the user knows when they may let go.
+- `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
+  not depend on it.
+- Take a snapshot and write down what the user did (see "Recording"), then continue read-only.
+- At the end of the exploration hand off once more when the user created data: "Delete the [asrun] items you
+  created, then press Done". The case must clean up after itself, and so must the exploration.
+
+## Recording
+Between the start and the end of a handoff the agent records what the user does (`browser_start_recording`,
+`browser_stop_recording`). The recorded Playwright code is **raw material, never saved as it is**. It is turned into
+a general recipe and written under the step as `- Recipe (phase): ...` lines (format below). The recipe holds what the
+user did in words, plus the **labels and roles of the controls** they used ("the textbox 'Title'", "the button
+'Next'"), because `/gen-spec` cannot write data and so cannot see those controls itself. It never holds selectors,
+ids or the names of data that can change.
+
+Make the recipe as general as possible, because lists and data change:
+- **A choice from a list that can change** (items, search results, a contact list): record the position, never the
+  name or id. "Select items #1 to #3 from the list."
+- **Random is allowed only when the user asks for it** ("pick any 3"). The default is the position, because it can be
+  repeated. A random pick must be written into the test's annotations when the spec runs.
+- **Text the case creates**: `[asrun] <something>`.
+- **A value that has to exist** (an existing name, a search term): write what it must be like ("a name that
+  returns a result") and the observed value as `(observed "<value>", 🔍 to be confirmed by QA)` plus a
+  `[non-blocking]` TODO block. Do not put a brittle literal in as the only truth.
+- **Nothing that depends on the pick** may become an assertion (a total changes with the items). Say so in a
+  TODO when a check would.
+- Settings that the user changed on purpose (a toggle, a template) are recorded as they were set, by label.
+
+If the recording tool fails or returns nothing, describe what the user did from before/after snapshots instead.
+
+## Recipe lines under a step
+One or more `- Recipe (phase): ...` lines directly under the `[input]` or `[writes]` step they belong to, indented by
+four spaces. The phase is optional (`start`, `items`, `finish`, ...). The step is the key; there is no step number to
+keep in sync.
+
+```
+3. Select an existing document and pick 3 items. [input]
+    - Recipe (start): search for an existing document and pick result #1 (observed search term "...", 🔍 to be confirmed by QA).
+      - ❓ TODO [non-blocking]: Is any result that opens fine as the starting point? (seen on example-staging)
+        - ✍️ Answer:
+    - Recipe (items): select 3 items by position (#1 to #3) from the list.
+    - Recipe (finish): press "Next" until the "Publish" button shows, then publish.
+```
+
+A step that is marked `[input]` or `[writes]` and has no `- Recipe:` line has never been explored. `generating-specs`
+stops on it, and `pnpm case:check` warns about it.
+
+## Hard rules
+- Never write data yourself, never press a button that writes. In production the same, with no exception.
+- Never wait in an unattended run.
+- Never ask a person to log in, pass 2FA or send email through the handoff.
+- Never save selectors, ids or the names of changing data into a case. Control labels and roles are fine.
+- Never read or print anything under `.auth/`.

package/.claude/skills/generating-specs/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: generating-specs
+description: Turns a human-written test case (cases/<id>.md, the id may include a group folder such as documents/landing-page) into a Playwright spec (tests/<id>.spec.ts) for the multi-profile test suite, explores the real pages to learn the locators and values, and completes the case's own "## Values" block. It only generates: it never runs the tests. Use when asked to generate, update, fix or heal a spec, or for /gen-spec.
+---
+
+# Generating specs from case documents
+
+Read `references/conventions.md` first. It defines the spec shape, fixtures, assertion layers and
+the read-only rules. Read the workspace `AGENTS.md` for the hard rules and the project rules. Read `../exploring-cases/references/open-questions.md`: it
+defines how open questions are written into the case file, resolved and reported. Also read
+`../exploring-cases/references/assertion-targets.md` (the exact thing each check looks at) and
+`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts). All three are binding here.
+
+This skill never stops to ask the user in the chat, because it may run without anybody present (a one-shot
+`claude -p` / `opencode run`). Questions go into the case file; the final line is `RESULT: ready` or
+`RESULT: needs-input`.
+
+This skill trusts the case. What the pages show, what a person has to enter, and what the open questions are is
+settled by `/explore-case` and recorded in the case (`(observed, ...)` marks, the step recipes). Generating
+only finds locators and writes code: it replays the case and does not judge the case again.
+
+Generating a spec and running it are separate processes. This skill only writes files: it does not run
+`pnpm asrun`, does not create screenshot baselines and does not judge whether the spec passes. The user runs the
+spec afterwards (see the report). Healing a failing spec (below) is the exception: it reads the last report first and runs only the profiles that are logged in, and only when the report is not enough.
+
+## Before you start
+Read the workspace `AGENTS.md`: its §2 holds the project rules, and it points at the framework baseline. If
+`.claude/skills/generating-specs.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.
+
+## Inputs
+- The case id and the environment to explore in (`staging` or `production`). There is no default. If the
+  environment is missing, stop before exploring and report `RESULT: needs-input` ("pass the environment").
+- Optionally `--force`: regenerate the spec from scratch and overwrite the existing one. See "An existing spec".
+
+A case id is its path below `cases/` without `.md`: `hub-landing`, or `documents/landing-page` when the case is in a
+folder (one level only). The spec is at the same path below `tests/` (`tests/documents/landing-page.spec.ts`); both import
+the framework through the `@asrunjs/asrun/*` alias, so the folder depth does not change the imports.
+
+- `cases/<id>.md` (front matter: `id`, `login: required|none` (`none` = public page; the login page itself is not a valid case), `suites: [<name>, ...]` (the old `priority: <level>` means one suite), `writes: [<env>, ...]` (omitted = read-only; the environments the spec may write in, e.g. `[staging]`) + `writes-note`, optional `envs: [...]`; sections Steps (with a step's `- Recipe:` lines) / Expected / Values / Visual checks / Targets; an old `## Inputs` section may still hold recipes). `## Values` holds one fenced yaml block keyed by `default` and by profile id, with the exact literals the spec asserts. The case document is the only place where expected values live.
+- `profiles.yaml` (profiles: id, name, env, baseURL, account, tags, email). It holds no expected values.
+
+## An existing spec
+Decide this first, before exploring anything. The spec path is `tests/<id>.spec.ts`.
+- **No spec yet:** generate it (the procedure below).
+- **A spec exists and `--force` was not given:** do not touch it. Do not edit the spec, the case values or any baseline.
+  Report that the spec already exists, say that `--force` regenerates and overwrites it, and give the id and
+  environment to run it again with. End with `RESULT: ready` (the spec that exists is not in question). Nothing else
+  is written, not even the case file.
+- **A spec exists and `--force` was given:** the user chose to overwrite it. Regenerate it from the case with the
+  procedure below, and write the new file over the old one (do not merge with it: the case file is the source of
+  truth). Do not read the old spec as a starting point and do not keep it just because the result looks the same:
+  write the file from the case and the exploration. If it ends up identical, say so in the report. Keep the `## Values`
+  of other cases untouched; only this case's `## Values` is yours. Leave the
+  baseline images in `tests/<id>.spec.ts-snapshots/` alone: a changed visual check needs a person to update them,
+  so list in the report which baselines may now be out of date. Say in the report that an existing spec was
+  overwritten.
+
+## Procedure
+1. **Make sure the case uses the artifact language.** `AGENTS.md` §2 sets it (English by default), and spec step
+   titles copy the case's step text. If `cases/<id>.md` is written in another language, translate it into that
+   language and rewrite the file BEFORE anything else: keep the front matter keys and values, the section headings,
+   the `## Values` entries and the step numbering as they are, and keep quoted UI text exactly as it appears
+   on the page (do not translate strings the page shows). Do not add, drop or reinterpret any step or
+   expectation; if a sentence is unclear, translate it literally and raise it as a question in the next step.
+   Tell the user in the report that the case file was translated. Skip this when the case already uses that language.
+2. **Validate the case.** Collect everything that is ambiguous, every check without an expected value and every
+   missing per-profile value, including the `TODO` items already in the case. Resolve them in the order of
+   `open-questions.md`; do not stop here:
+   - **Steps that write or need a choice (`[input]`, `[writes]`) need a recipe.** Each must have at least one
+     `- Recipe (phase): ...` line under it in the case (written by `/explore-case`). An old case may still hold the
+     same recipe in `## Inputs`: use that line until it is moved under the step. If one has none, the case was
+     never explored with a person: stop before opening a browser, do not write the spec, and report `RESULT:
+     needs-input` with exactly this: "step <n> has no recorded input; run `/explore-case <id> <env> --attended`
+     first". Nothing else is written.
+   - Facts the page can answer and that the case does not hold yet are read in step 4 and written into the case as
+     `(observed, 🔍 to be confirmed by QA)`. A spec is generated from observed values.
+   - Safe defaults are applied: the suggestion is the sentence above the TODO block, and the block stays in the case
+     as `❓ TODO [non-blocking]` with an empty `✍️ Answer:`. A sentence with no TODO block under it is confirmed text.
+   - A non-empty `Answer:` is the user's answer: it wins over the sentence above it. Fold it into the case.
+   - Only what is always-blocking in `open-questions.md` blocks. Generate everything else; for a blocked check
+     (a `[blocking]` block), write `test.fixme(true, '<the question>')` inside its step (or skip that profile), never
+     an invented value and never a check built from the sentence above a `[blocking]` block.
+   - **Every check on a logo, image, icon, file, PDF, screenshot or repeated text needs a target card** (`## Targets`,
+     referenced as `[T<n>]`) that was observed (`Reference <profile-id>:` is a screenshot, not `none`) and has no open
+     `[blocking]` block. A check that has no card, or whose card is not observed, is not guessed here. Do not pick
+     an element yourself: report `RESULT: needs-input` with "check <text> has no observed target; run `/explore-case
+     <id> <env>` first" (or, when the card has a `[blocking]` TODO, write `test.fixme(true, '<the question>')` for that check as
+     the rule above says and go on with the rest).
+   - **Evidence gate:** a hard assertion (one that decides pass or fail) on something nobody has seen on a page is not
+     written. "Not verified on the page" is allowed for a locator of a page that only exists after a write step, but
+     never for what the check asserts about it: that goes to `test.fixme` with the reason, or `needs-input`.
+   - Do not invent expected values. If the case's `## Values` and the spec disagree, the case wins: fix the spec and
+     mention the change in the report.
+3. **Check sessions** if `login: required`: run `pnpm status --env <env>`. If a profile needs login, tell the
+   user to run `pnpm signin <profile-id>` and continue with the profiles that are ready. If `pnpm status`
+   cannot run (a sandbox error such as `listen EPERM` or a Chromium start failure), judge by the page instead: a page
+   that lands on the login page means the profile is not logged in.
+4. **Replay the case on the real page** with the `playwright-test` MCP. 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: stop, tell the user which MCP server is missing and to run `pnpm asrun doctor`, write no spec,
+   and end with `RESULT: needs-input`.
+   Call `generator_setup_page` with
+   `project=<profile-id>` (for example `example-staging`) and `seedFile=tests/seed.spec.ts`, then perform the
+   steps in the environment you were given (never ask for it; there is no default) to learn the locators.
+   Do the read-only steps as written. **Never perform a step that writes or needs a choice**: the agent does not write
+   data, in staging or in production, and it does not hand off to a person here or wait for one. Write those steps
+   of the spec from the `- Recipe:` lines under the step (positions, `[asrun]` names, control labels and roles that
+   `/explore-case` recorded). Pages that only exist after such a step cannot be seen from here: write their locators
+   from what the recipe and the exploration notes say, mark them in the report as "not verified on the page", and
+   leave the first run of the spec (or `/heal-spec`) to confirm them. Do this for at least one profile
+   per domain (example.com and exampleshop.com differ in markup). Profiles that are not logged in are skipped and
+   named in the report. Use this exploration to answer the open points of step 2, and look at every profile that has
+   an entry in `## Values` to read its value.
+   Keep every browser call short (one action, about 60 s at most, a snapshot between steps, `{timeout: 5000}` when
+   something may not appear, no third retry): see "Keep every browser call short" in `../exploring-cases/SKILL.md`.
+   **Ready before you read, here too** (`readiness.md`): `browser_network_clear`, act, wait for the key requests
+   (`browser_network_requests`) and the content signal, then snapshot. The request URL patterns for `actAndWait` and the
+   `Ready when` signals of the case are taken from what you see here.
+   **Check every target on the page:** for each target card, find its `Identified by` locator, confirm that it matches
+   exactly one element and that this element is what `What` says (highlight it and read the screenshot). A locator that
+   matches several elements or the wrong one is fixed or becomes a question, never `.first()`.
+   Prefer `getByTestId` (the project uses `data-tn`), then role/label locators. No CSS chains or XPath.
+   Update the case file with what you learned: fold observations into the right section marked
+   `(observed, 🔍 to be confirmed by QA)`, remove the TODO blocks they answer (rewrite the sentence above the block),
+   and narrow the ones that remain. Keep the shape of `open-questions.md` for every block. Edit the case
+   with targeted edits; never touch its `## Source` table.
+5. **Complete the case's `## Values`**: for every profile the spec runs for, add the entry with the literals the spec
+   asserts (the same keys as `default`, only what differs). Do not move values into `profiles.yaml`; it holds connection
+   settings only. Mention every value you added or corrected in the report.
+6. **Write `tests/<id>.spec.ts`** (inside the group folder if the id has one, creating it if needed) following the conventions. One `test()` per outcome, and every
+   case step wrapped in `test.step()` with the case's step text as the title, and the top-level
+   `test.describe` tagged with `caseTags('<id>')`. The spec must
+   contain no profile-specific literals: everything profile-specific comes from `requireValues('<id>', profile)`
+   (`@asrunjs/asrun/values`), which merges `default` with the running profile's entry.
+   Every action that loads something goes through `actAndWait` (`@asrunjs/asrun/ready`) with the key requests and the ready
+   signal; every download goes through `verifyDownload` (`@asrunjs/asrun/downloads`); every check on a target has
+   `// target: T<n>` on the line before it; every absence check has a `// ready: <signal>` before it. Never
+   `waitForTimeout`, `networkidle` or `.first()` to pick an image. A confirmation or modal that may or may not appear is
+   never decided by one `isVisible()` look (its `timeout` option is ignored): use `clickOptionalUntilHidden`
+   (`@asrunjs/asrun/ready`) or a waiting `expect(...).toBeVisible({timeout})`; see `readiness.md`, "Optional confirmations".
+7. **Check the files**: run `pnpm typecheck`, `pnpm spec:lint <id>` and `pnpm case:check` (or `node --import tsx <framework>/scripts/check-cases.ts` if
+   it fails with a sandbox error such as `listen EPERM`). Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
+   into a question). Every lint `WARN` is handled too: fix it, or name it in the report with the reason it is acceptable.
+   Then do the **self-review**: for each assertion answer in writing "if the product were broken, would this fail?"
+   and "if the product is right, could this fail by timing?" (a check that cannot fail, or that races the page, is rewritten).
+   For every branch that depends on something possibly not there yet (`if`, `.count()`, `.catch(() => false)`), ask "what
+   if it shows up a second later?"; the answer must be a retry loop or a waiting assertion, never a single look.
+   Do NOT run `pnpm asrun`, do not use
+   `--update-snapshots` and do not create baselines: the first run of the spec does that, and a person reviews them.
+8. **Report** in the user's language: spec path, **an assertion table** (step, what is asserted, target card, ready signal, and
+   `observed on the page` or `not verified`; no row may be missing), profiles explored, profiles skipped (and why), whether the case file was
+   translated, what was added to the case file as observed, checks generated from observations (QA must confirm
+   them), visual checks that need a baseline on the first run, and the remaining TODO blocks (`[blocking]` ones with
+   the sentence that deleting the block would confirm). State that the spec was not run and give the command to run it:
+   `pnpm asrun --env <env> --profile <ids> --grep <id>` (with `--update-snapshots` once if the spec has visual
+   checks, then run `pnpm baselines:review <id> --new` and open every new image: it must show what its target card says). The last line is `RESULT: ready` (no `[blocking]` question left, spec
+   written and the checks above pass) or `RESULT: needs-input`, as defined in `open-questions.md`.
+
+## Cases that write data
+Only when the case front matter lists environments under `writes` (for example `writes: [staging]`). Never add
+`--allow-writes` or set `ASRUN_ALLOW_WRITES`. Use the `records` fixture, `configureCase` and `emailStepAllowed` as
+described in `references/conventions.md`. The agent does not perform write steps while generating (see step 4); the
+spec does, when a person runs it in an environment that `writes` lists. Elsewhere the runner skips the case with a
+notice. Never send email in production; in other environments only if `profile.email` is true, otherwise skip that step and say so
+in the report.
+
+## Healing a failing spec
+Inputs: the case id and the environment (both required, there is no default: without an environment stop and say so),
+optionally `--profiles a,b`, `--report <run-id>` and `--hints <file>` (or free text after the arguments). Healing is
+the one case where this skill runs specs, and only in the environment given.
+
+Heal from evidence, not from a habit of rerunning. A report that already exists says what failed.
+
+1. **Read the user's clues first** (the `--hints` file, or the free text). They say what to look at and may hold
+   evidence the report lacks. They guide the diagnosis and nothing else: they never lower the bar for a product
+   finding and never allow an expectation to be changed just to make a test pass. Quote the clue you used, or say that
+   it did not hold up, in the report.
+2. **Read the existing report**: run `pnpm heal:evidence --case <case-id> --env <env>` (add `--profile a,b` when `--profiles`
+   was given). It reads `reports/*/summary.json` and prints, per profile, the status, the failed step, the error, the call
+   log, the screenshots and videos, and ends with `EVIDENCE: fresh | stale | no-failure | none`. With `--report <run-id>`,
+   read `reports/<run-id>/summary.json` instead. Look at the screenshot when the error alone does not explain it. A profile
+   that failed only because it was not logged in is no evidence about the spec.
+3. **Decide whether to rerun the case**. Do not rerun when the report is `fresh`, names the failing step and the error,
+   and that is enough to tell whether the product changed or the test is wrong. Rerun when:
+   - there is no report (`none`), or it is `stale` (the spec, the case or `profiles.yaml` changed after it);
+   - the report does not explain the failure (a bare timeout with no locator, a failure before any step, a truncated log);
+   - a clue from the user has to be checked against the real page;
+   - a profile that must be healed has no result in the report (for example it was not logged in then).
+   Rerun with one plain command, as few profiles as possible, and say why in the report:
+   `pnpm asrun --env <env> --logged-in --profile <ids> --grep <case-id>` (optionally piped to `tail`; do not chain it
+   with other commands, or it runs inside Claude's sandbox and fails with `listen EPERM`). Always add `--logged-in`: it
+   leaves out the profiles that are not logged in instead of failing them. A profile that is not logged in is never healed:
+   name it in the report with `pnpm signin <profile-id>`.
+4. **Audit the assertion before you blame anyone.** Read the `assertion-targets.md` and `readiness.md` sections on healing.
+   - Is the locator still what the target card says (`What`, `Identified by`)? Open the failure screenshot and the
+     baseline (`pnpm baselines:review <case-id>`) and look at each: a baseline that shows something other than the card
+     (a content image instead of a logo) is a wrong test, and passing runs on it prove nothing. Delete it and report it; a
+     person creates the new baseline after the spec is fixed. Note: other profiles that pass on the same wrong target are also suspect.
+   - Is the failure a "missing / empty / not visible / timeout" kind? Then it is first a readiness suspect: was the page
+     still loading in the screenshot or video? Fix with `actAndWait` and a ready signal, never with a longer timeout alone or a sleep.
+   - Is the spec weak in the ways the lint knows? Run `pnpm spec:lint <case-id>` and fix every `FAIL` while you are there.
+   - A download that fails says which stage failed (start, finish, exists, valid): fix the stage, do not loosen the check.
+   - Doubt about which element is meant: write the question into the case (a `[blocking]` TODO naming the exact image,
+     text, place or UI) instead of choosing; do not rewrite the card quietly.
+5. **Decide whether the PRODUCT changed or the TEST is wrong.**
+   - Locator/timing problem: fix the spec.
+   - A real product difference (wrong logo, wrong name): do NOT change the expectation to make it
+     pass. Report it as a finding with the trace/screenshot path.
+6. **After editing the spec, run it once to confirm** (same command as in step 3, for the profiles you healed). That rerun
+   is the only one that is always allowed. Run `pnpm typecheck` too.
+7. **Report** in the user's language: which report was read (or that there was none) and whether it was fresh or stale,
+   whether the case was run again and why (or why not), what was changed, what is a product finding (with paths),
+   which assertions were wrong or raced the page, which baselines are wrong and were deleted, what the user's clues contributed, which profiles were left out because they are not logged in, and the result of the
+   confirming run.
+
+A case that writes data in `production` needs a person's confirmation at run time, so the rerun is refused there:
+use the report, or heal in staging, and never add `--allow-writes`.