@asrunjs/asrun 0.2.0 → 0.5.3

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

@@ -1,207 +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 `AGENTS.md` for hard 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 `## Inputs` section). 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.
-
-## 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 / Expected / Values / Visual checks / Targets / Inputs). `## 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 is in English.** All files in this repo are English (see `AGENTS.md`), and spec step titles
-   copy the case's step text. If `cases/<id>.md` is written in another language, translate it to English 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 is already English.
-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 a bullet in the case's
-     `## Inputs` section (written by `/explore-case`). 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: 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 `## Inputs` recipe (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`.
+---
+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`.