@asrunjs/asrun 0.9.0 → 0.10.0

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

@@ -6,8 +6,8 @@ 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] [--profiles a,b]`. The case id is the path below cases/ without `.md` (it may include a group
+(Project rules). F1–F6 and R2 always win.
+Arguments: `<case-id> <env> [--attended] [--profiles a,b] [--hints <file>]`. 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
@@ -15,8 +15,13 @@ recipe under the step it belongs to (`- Recipe:` lines). Without `--attended`, n
 `--profiles a,b` explores only those profiles (comma-separated ids from profiles.yaml); without it, at least one
 logged-in profile per domain. A profile the list leaves out is not opened and nothing is written about it: runs add up,
 so a later run covers the rest.
-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.
+`--hints <file>` (or free text after the arguments) is what I know or want checked; read it first. After the work, a
+reusable instruction goes into `## Rules` by the gate in `references/case-rules.md`; a one-off clue stays in the report.
+Read `## Rules` before the steps and apply it. Follow `case-rules.md` (a rule says how to run the case, never what it
+proves; never delete or rewrite one), `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. If you are not allowed to write files at all (a plan-mode
-run, a read-only sandbox), say what blocked you and end with `RESULT: needs-input`.
+file as the skill describes, and end with the `RESULT:` line as plain text on the last line, never in a code fence or in
+emphasis. If you are not allowed to write files at all (a plan-mode run, a read-only sandbox), say what blocked you and
+end with `RESULT: needs-input`.

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

@@ -6,14 +6,18 @@ 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.
+(Project rules). F1–F6 and R2 always win.
+Arguments: `<case-id> [<env>] [--force] [--hints <file>]`. 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.
+left alone unless `--force` is given; with `--force` it is regenerated and overwritten. `--hints <file>` (or free text
+after the arguments) is what I know or want changed; read it first. A reusable instruction goes into `## Rules` by the
+gate in `references/case-rules.md`; a one-off clue stays in the report.
 There is no profile option: the spec is generated for every profile the case holds information for (its `## Values`
 keys, its target cards and its observations), not for a chosen subset and not only for the profiles that are logged in.
-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
+Follow the skill's procedure exactly, including `case-rules.md` (read `## Rules` before the steps; a rule says how to
+run the case, never what it proves), `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. If you are not allowed to write
-files at all (a plan-mode run, a read-only sandbox), say what blocked you and end with `RESULT: needs-input`.
+write the remaining questions into the case file), and end with the `RESULT:` line as plain text on the last line,
+never in a code fence or in emphasis. If you are not allowed to write files at all (a plan-mode run, a read-only
+sandbox), say what blocked you and end with `RESULT: needs-input`.

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

@@ -6,7 +6,7 @@ Load the `generating-specs` skill, section "Healing and refining a spec", and fo
 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.
+(Project rules). F1–F6 and R2 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
@@ -14,22 +14,26 @@ Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`,
 - `--profiles`: the profiles to run when evidence is needed. 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 wants repaired or improved, with any evidence. Read it first. Any free
-  text after the arguments is the same kind of request. Both are optional.
+  text after the arguments is the same kind of request. Both are optional. Read `## Rules` before the steps and apply
+  it; after the work, a reusable method instruction goes into `## Rules` by the gate in `references/case-rules.md`,
+  while a one-off clue stays in the report.
 A passing run is not a reason to refuse a request: healing also refines a case and its spec. Never lower the bar for a
 product finding to make a test pass.
 
 Do not ask me questions in the chat: this may run unattended. Resolve what the report, the case and the page can
-resolve, and write what still needs a person into the case as a `[blocking]` question. End with the `RESULT:` line:
-`ready` when the healing or the refinement is finished, `needs-input` when something is still open. If you could not
-write files at all (a plan-mode run, a read-only sandbox, a refused permission), say in one sentence what blocked you
-and end with `RESULT: needs-input`: never answer with a plan and a question instead.
+resolve, and write what still needs a person into the case as a `[blocking]` question. End with the `RESULT:` line as
+plain text on the last line, never in a code fence or in emphasis: `ready` when the healing or the refinement is
+finished, `needs-input` when something is still open. If you could not write files at all (a plan-mode run, a read-only
+sandbox, a refused permission), say in one sentence what blocked you and end with `RESULT: needs-input`: never answer
+with a plan and a question instead.
 
 Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see step 5
 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`. If the change leaves an open question or an unconfirmed marker
-in the case, stop there, tell me to review the case and run `/explore-case`, and end with `RESULT: needs-input`.
-Otherwise tell me whether it is a test problem or a product finding.
+skill says it is needed. Always run with `--logged-in`. If the change leaves an open question or a `🔍 to be confirmed` marker
+in the case, stop there, tell me to review the case and run `/explore-case` (or `pnpm markers:confirm` after a passing
+run), and end with `RESULT: needs-input`. A marker inside `## Rules` does not stop the spec unless the rule covers a
+literal the spec asserts. Otherwise 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

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

@@ -6,6 +6,6 @@ Load the `making-cases` skill and turn this input into case documents: $ARGUMENT
 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.
+(Project rules). F1–F6 and R2 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/skills/exploring-cases/SKILL.md

@@ -5,7 +5,8 @@ description: Explores the real pages for one case document (cases/<id>.md) befor
 
 # 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
+Read the workspace `AGENTS.md` (hard rules and project rules), `cases/_template.md` (the target format), `references/case-rules.md`
+(how a case's `## Rules` are read, applied and maintained), `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
@@ -14,8 +15,8 @@ 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.
+`AGENTS.md` §2, which wins over both (the baseline, "Precedence"). F1–F6 and R2 always win. This is not a stop
+condition: continue with the procedure below.
 
 ## Where this skill sits
 Three steps, each learns one thing:
@@ -50,10 +51,15 @@ one exception is a handoff in an attended run, where waiting for the person is t
   least one logged-in profile per domain. The selection is never widened: a profile it leaves out is not opened and
   nothing about it is written into the case. Runs add up: a later run with other profiles adds their observations and
   `## Values` entries next to the ones recorded before.
+- Optionally `--hints <file>` (or free text after the arguments): what the person knows or wants checked. Read it
+  before the static review. It guides this run; after the work, a reusable instruction is written into `## Rules` by
+  the gate in `references/case-rules.md`, and a one-off clue stays in the report.
 
 ## 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.
+1. **Read** the case, `profiles.yaml` and `cases/_template.md`. Read `## Rules` before the steps: it says how to run
+   this case. Apply the rule pass of `references/case-rules.md` (apply what holds, move what belongs in another
+   section, turn a conflict into a `[blocking]` question, never delete or rewrite a rule a person wrote). 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` (with `--profiles`, only those ids: the rest belong to a run of their own). A missing
@@ -65,28 +71,33 @@ one exception is a handoff in an attended run, where waiting for the person is t
      `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).
+     too broad (screenshot a small element);
+   - rules that conflict with a step, an expectation, a value or a target, rules that state an expectation or a
+     literal instead of a method, and rules that no longer look true.
 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`.
+4. **Explore**. The exploration runs through the `playwright-test` MCP only. Read `references/tools.md` before the
+   first browser call: that MCP lists many tools it cannot run, and a call that answers `Tool "<name>" not found`
+   means exactly that — the server is up, use the substitute in that file, do not stop and do not report a missing
+   MCP server. If the tools are not registered in this session at all (no `browser_*` / `generator_*` tool) or the
+   server 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 each profile `--profiles` names that is
    logged in, and, without `--profiles`, 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`). Never explore a profile the selection leaves out, and never add a profile to fill
+   (`generator_setup_page` with `project=<profile-id>`, `seedFile=tests/seed.spec.ts` and `plan=""`). Never explore a
+   profile the selection leaves out, and never add a profile to fill
    a gap. Profiles that are selected but 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.
+     name the finish condition, run the wait loop (the card records what the person does), then write down what
+     happened from its `recorded` result. 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`).
@@ -94,16 +105,25 @@ one exception is a handoff in an attended run, where waiting for the person is t
      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>, ...)`.
+   - **Apply the `## Rules` while you explore.** A rule that says how to prepare, how to wait or which control to
+     avoid is followed on every profile. Re-check each rule against the page: one that no longer holds gets a TODO
+     with evidence under it, never silent deletion or rewriting. A rule never lets you write data or do a person's
+     step.
+   - **Ready before you read** (`references/readiness.md`): note the highest number of
+     `browser_network_requests` (`static: false`) before an action that loads something, then the action, then wait for
+     its key requests (the numbers above that mark) and for the content signal, and only then take the snapshot.
+     `browser_network_clear` is not runnable in this MCP: the marker replaces it (`references/tools.md`). When the
+     first read is empty or missing something, wait and read again before you record or ask anything. Record the
+     signal as a plain note, `(seen on <profile>, after <signal>)`: the spec waits for it, so no person has to confirm
+     it.
    - **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`.
+     screenshot or repeated text, list ALL candidates, outline the one that is meant (`locator.highlight()` through
+     `browser_run_code_unsafe`, see `references/tools.md`), take the screenshot to `.explore/targets/<case-id>/`,
+     **open that screenshot and look at it**, then clear it with `page.hideHighlight()`, 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 name the element in the handoff
+     card, then outline what they named (`browser_annotate` is not runnable here).
    - **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
@@ -127,25 +147,39 @@ one exception is a handoff in an attended run, where waiting for the person is t
    `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
+6. **Write the recipe lines** for every `[input]` or `[writes]` step that was handed off, from the card's `recorded`
+   result, 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
+   outcome into the case, every block with an empty `Answer:` line. Then mark the facts you wrote: a fact the run
+   checks gets `(seen on <profile>)`, only a fact that would pass while wrong gets
+   `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`, with `evidence: <path>` when a
+   screenshot says it better (the gate is "Which sentences carry a marker" in `references/open-questions.md`; never
+   mark a locator, a flow, a request or a readiness signal, and never put a marker inside a TODO block). This includes
+   the rules: apply what holds, move what belongs in another section, and leave a question under a rule that conflicts
+   or is obsolete. Then apply the `--hints` gate of `references/case-rules.md`: a reusable, general instruction goes
+   into `## Rules` (with a marker only when it changes what is asserted); a one-off clue stays in the report.
+8. **Check**: run `pnpm case:check` (it fails on an incomplete target card, a rule that names a missing step, 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 profiles `--profiles` left out (and that a run with them covers the rest),
    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.
+   the steps that could not be observed (and why), the questions that remain
+   with the sentence that deleting each block would confirm, the markers with their reason and whether each changes an
+   assertion (that is the short list a person has to look at), and findings that look
+   like product bugs. Add the rule table of `references/case-rules.md` (every rule, where it was applied, or why
+   not) and say which rules were added from `--hints`. End with the `RESULT:` line as `references/open-questions.md`
+   requires: plain text on the last line, never inside a code fence or in emphasis.
 
 ## Hard rules
 - Edit `cases/<id>.md` only. Do not touch the `## Source` table.
+- A `## Rules` bullet is a person's instruction: never delete it or change what it says, and never treat it as
+  permission to write data, send email or do a person's step (`R1`–`R4`, `references/case-rules.md`).
 - 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

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

@@ -38,7 +38,8 @@ Fields:
   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`.
+  (`tools.md`, "Outlining a target": `locator.highlight()` through `browser_run_code_unsafe`, then
+  `browser_take_screenshot` with `scale: "css"`), 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.
 
@@ -74,14 +75,17 @@ as evidence, so the person answers by pointing:
 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).
+In an **attended** run, do not write the question first: ask the person in the handoff card to name the element
+("the image with the logo, top-right of the header") or to point at it, then outline what they mean with
+`locator.highlight()` (`tools.md`, "Outlining a target"; `browser_annotate` cannot run in this MCP) and write the card
+from that screenshot, which becomes 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`.
+3. Outline the target (`locator.highlight()` via `browser_run_code_unsafe`, see `tools.md`), take the screenshot to
+   `.explore/targets/...`, then `page.hideHighlight()`.
 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.

package/.claude/skills/exploring-cases/references/case-rules.md

@@ -0,0 +1,110 @@
+# Case rules (`## Rules`): read, apply, maintain
+
+Shared by `exploring-cases`, `generating-specs` and `making-cases`. The binding rules are `R1`–`R4` of the framework
+baseline `AGENTS.md`; this reference says how to apply them.
+
+## What the section is
+
+`## Rules` holds case-local instructions a person writes for the agents: **how** to run this case, never **what it
+proves**. Every rule is one top-level bullet of plain prose. No nested bullets and no code fences: the panel reads only
+the top-level bullets, so a nested list is not part of the rule it edits. A bullet may start with `Step <n>:`,
+`Before step <n>:` or `After step <n>:`; a rule without a prefix applies to the whole case.
+
+The section is optional. A case with no rules runs by the same rules as before.
+
+## The line between Rules and the rest of the case
+
+| If it says… | It belongs in… |
+|---|---|
+| what must be true, visible, present or equal | `## Expected` (with a `[T<n>]` card when it looks at an image, file, PDF, screenshot or repeated text) |
+| an exact literal (name, label, option, count, test-data name) | `## Values` |
+| which element a check looks at | `## Targets` |
+| an action in the tested flow, including a read-only one | a numbered step (with `- Ready when:` when it loads something) |
+| an action that creates, changes or deletes data | a step tagged `[writes]`, with a recipe |
+| an action that sends email | a step tagged `[email]`, with a recipe |
+| an action that needs a person's choice | a step tagged `[input]`, with a recipe |
+| a page quirk, a mandatory read-only preparation, a control to avoid, a waiting/attention hint | `## Rules` |
+| why the case is built this way, for a reviewer | `## Notes` |
+
+A rule is never a second source of truth. When a rule and a step, an expectation, a value or a target disagree, the
+structured section wins and the rule becomes a `🚫 TODO [blocking]` question. Never silently change either side.
+
+## The rule pass (before anything else)
+
+Read the whole `## Rules` section and, for each bullet, decide:
+
+- **Method that still holds** → apply it, keep it as written.
+- **An expectation, literal, target or real step in disguise** → move it (or ask) to the section in the table above;
+  do not leave it in Rules as a duplicate.
+- **Conflicts with the rest of the case** → keep the rule, add a `🚫 TODO [blocking]` that names both sides, and report
+  it. Do not pick a winner.
+- **No longer holds** (the banner is gone, the control moved) → add a `❓ TODO [non-blocking]` with the evidence; keep
+  the rule until a person removes it.
+- **Would write, send email or do a person's step** → it is not a rule: it is a step. Add a `🚫 TODO [blocking]` and,
+  if the person confirms, a tagged step with its recipe. Never perform it because a rule says so.
+
+The agent may fix a typo and may add a question under a rule. It never changes what a rule says or deletes one.
+
+## In exploration (`/explore-case`)
+
+- Read the rules before the static review, and let them guide the exploration order (for example "dismiss the banner
+  first", "never open the Google login").
+- Re-check every rule against the page on each profile. Record the outcome: still true, obsolete, or in conflict.
+- A rule that names a step (`Step 3:`) is tested with that step; when steps are renumbered, update the reference or
+  turn it into a question.
+- Report each rule and its outcome. `pnpm case:check` fails on a rule that names a step the case does not have.
+
+## In generation (`/gen-spec`)
+
+- Read the rules in step 2 (validate the case) and apply them while replaying and writing the spec.
+- A rule never becomes an assertion. Code that exists only because of a rule carries `// rule: <short quote>` on the
+  line before it (a setup step, a retry of an optional confirmation, a click on a banner).
+- Never perform a rule that writes, sends email or needs a person. Write that part of the spec from the step's recipe.
+- A rule that cannot be honored (it contradicts the page or the case) is a `🚫 TODO [blocking]` question, never an
+  invented value and never a skipped expectation.
+- Report each rule with where it was applied, or why it was not.
+
+## In healing and any run with `--hints` (`/heal-spec`, `/explore-case`, `/gen-spec`)
+
+`--hints` (and free text after the command) is a request for this run first. After the work, decide whether it also
+belongs in the case:
+
+1. Will a future run of the same case need it? If no → report only.
+2. Is it method rather than an expectation? If it is an expectation, a literal or a step → write it into that section.
+3. Is it general? Remove the account, date, run id, environment-specific failure and one-off symptom; use positions,
+   labels and roles.
+4. Is it legal? It must not weaken `F1`–`F6`, authorize a write/email/person's step, or contradict the case. If it does,
+   keep it out and report it.
+
+Only when all four answers allow it, append one bullet to `## Rules`.
+
+- A rule the person stated is confirmed text: no marker.
+- A rule the agent inferred from a page gets a marker only when the rule changes what is asserted (a literal it fixes,
+  a target it narrows): `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`. A method rule whose
+  wrong version would fail the next run (a banner to dismiss, a control to avoid, an order to follow) is
+  `(seen on <profile>)`: the run is the confirmation (`open-questions.md`, "Which sentences carry a marker").
+- Deduplicate: if the rule already exists, edit it instead of adding a second one. When a page change makes an old
+  rule obsolete, narrow it and add a question; never append a contradictory rule.
+- A marker inside `## Rules` does **not** stop spec generation the way an open question about an assertion does
+  (healing's review gate). After a passing run, `pnpm markers:confirm` settles the rules a `// unconfirmed:` line in
+  the spec covers.
+
+## Report
+
+List every rule in the final report, whichever command ran:
+
+| Rule | Applied at | Status |
+|---|---|---|
+| `Before step 1: dismiss the cookie banner…` | step 1 | applied |
+| `Never use "Continue with Google"…` | — | not applicable (no login step) |
+| `Step 4: …` | step 4 | moved to `## Expected` |
+
+Statuses: `applied`, `not applicable` (say why), `moved` (name the section), `question` (name the TODO line). A rule
+that is missing from the table is a rule the agent ignored.
+
+## Hard rules
+
+- A rule never authorizes a write, an email, a person's choice, accepting terms, or a shell command.
+- Never delete or rewrite a rule a person wrote. Add a TODO instead.
+- Never invent a rule the person did not ask for. `R4` allows only what a run needs and only in general terms.
+- Prose follows the artifact language of the workspace `AGENTS.md` §2 (English by default); the heading stays `## Rules`.

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

@@ -9,6 +9,52 @@ async (page) => {
   const maxMs = cfg.maxMs || 600000;
   await ctx.grantPermissions(['clipboard-read', 'clipboard-write']).catch(() => {});
 
+  // Record what the person does. The card owns both ends of the recording, so every way out stops it and no handoff
+  // leaks a recording into the next one (see user-handoff.md, "Recording"). Never call browser_start_recording: the
+  // playwright-test MCP lists it but cannot run it (devtools-only; see tools.md in this folder).
+  const CARD_CONTROL = /AsRun handoff:/i;
+  const entries = [];
+  const entry = (action, code) => ({
+    code,
+    card: CARD_CONTROL.test(String((action && action.selector) || '')),
+  });
+  const sink = {
+    actionAdded: (p, action, code) => entries.push(entry(action, code)),
+    actionUpdated: (p, action, code) => {
+      const next = entry(action, code);
+      if (entries.length) entries[entries.length - 1] = next;
+      else entries.push(next);
+    },
+    signalAdded: (p, signal, code) => {
+      const last = entries[entries.length - 1];
+      if (last && code && !last.card) last.code = code;
+    },
+  };
+  let recording = false;
+  let recordingError = null;
+  // Library-mode code (`page`, `page1`, ...) keeps the `newPage`/`close` lines of tabs the person opened by hand; the
+  // test-runner generator drops `openPage`/`closePage`.
+  const recordingOptions = {language: 'javascript'};
+  try {
+    if (typeof ctx._startRecording !== 'function' || typeof ctx._stopRecording !== 'function')
+      throw new Error('this Playwright has no browser-context recording');
+    await ctx._startRecording(recordingOptions, sink);
+    recording = true;
+  } catch (e) {
+    // A card that died before stopping left the context recording: close that one and try once more.
+    if (/already in progress/i.test(String(e && e.message))) {
+      await ctx._stopRecording().catch(() => {});
+      try {
+        await ctx._startRecording(recordingOptions, sink);
+        recording = true;
+      } catch (e2) {
+        recordingError = String((e2 && e2.message) || e2);
+      }
+    } else {
+      recordingError = String((e && e.message) || e);
+    }
+  }
+
   const paint = (p) => p.evaluate(({message, copy}) => {
     if (document.getElementById('__ASRUN_panel')) return;
     const KEY = '__ASRUN_panel_state';
@@ -41,9 +87,9 @@ async (page) => {
       '.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>' +
+      '<button class="mini-done" data-a="done" aria-label="AsRun handoff: done">Done</button><button id="toggle" title="Minimize or expand" aria-label="AsRun handoff: 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>';
+      '<button class="primary" data-a="done" aria-label="AsRun handoff: done">Done</button><button data-a="skip" aria-label="AsRun handoff: cannot do this">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');
@@ -51,7 +97,7 @@ async (page) => {
     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.innerHTML = '<span></span><button aria-label="AsRun handoff: copy to clipboard" title="Copy">' + ICON.copy + '</button>';
       chip.firstChild.textContent = text;
       const btn = chip.lastChild;
       btn.addEventListener('click', async () => {
@@ -107,14 +153,18 @@ async (page) => {
   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';
+  try {
+    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);
     }
-    if (!outcome) await page.waitForTimeout(500);
+  } finally {
+    if (recording) await ctx._stopRecording().catch(() => {});
   }
   for (const p of ctx.pages()) {
     await p.evaluate(() => {
@@ -124,5 +174,17 @@ async (page) => {
   }
   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};
+  const dedent = (text) => {
+    const lines = text.split('\n');
+    const indents = lines.filter((line) => line.trim()).map((line) => line.length - line.trimStart().length);
+    const indent = indents.length ? Math.min(...indents) : 0;
+    return lines.map((line) => line.substring(indent)).join('\n');
+  };
+  return {
+    outcome: outcome || 'timeout',
+    waitedMs: Date.now() - started,
+    recording,
+    recorded: entries.filter((e) => e.code && e.code.trim() && !e.card).map((e) => dedent(e.code)),
+    ...(recordingError ? {recordingError} : {}),
+  };
 }