@asrunjs/asrun 0.8.0 → 0.10.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. Healing (repairing a failing spec, or refining a case and its spec on request) is the exception. Use when asked to generate, update, fix, heal or refine a spec, or for /gen-spec or /heal-spec.
 ---
 
 # Generating specs from case documents
@@ -8,31 +8,47 @@ description: Turns a human-written test case (cases/<id>.md, the id may include
 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/case-rules.md` (how a case's `## Rules` are read, applied and maintained),
 `../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.
+`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts). All four 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`.
+`claude -p` / `opencode run`). This holds whatever mode or agent the run is in: plan mode changes what you may write,
+never how you end. If you are not allowed to write files (plan mode, a read-only sandbox, a refused permission), say
+what blocked you in one sentence and end with `RESULT: needs-input` instead of answering with a plan and a question.
+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.
 
+The profile scope is the case's, not a selection. It is every profile id that appears in the case — the keys of
+`## Values`, a target card's `Reference <profile-id>:` line, a step observation — plus the `default` entry. There is no
+`--profiles` here: never narrow the scope to the profiles that are logged in, and never ask for a subset. The spec runs
+once per profile in the environment, so it must cover every profile the case says something about. A profile the case
+says nothing about runs on `default` alone; name those in the report. Runs of `/explore-case` add up, so a case explored
+with A and B first and C later generates a spec for all three.
+
 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.
+spec afterwards (see the report). Healing (below) is the exception: it reads the last report first, may edit the case
+and the spec, 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.
+`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.
 
 ## 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".
+- Optionally `--hints <file>` (or free text after the arguments): what the person knows, or a change they want. Read it
+  before validating the case. It guides this run; after the work, a reusable instruction is written into `## Rules`
+  by the gate in `../exploring-cases/references/case-rules.md`, and a one-off clue stays in the report.
+- No profile selection: the profile scope is the case's (see above). A case id and an environment are all this command
+  takes besides `--force` and `--hints`.
 
 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
@@ -68,14 +84,21 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
 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:
+   - **Apply the rule pass (`R1`–`R4`).** Read `## Rules` before the steps. A rule that states an expectation, a
+     literal, a target or a real step belongs in that section: move it there (or ask). A rule that conflicts with the
+     case or the page is a `[blocking]` question, never an override. A rule that would write, send email or do a
+     person's step is never followed. Details: `case-rules.md`.
    - **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.
+   - Facts the page can answer and that the case does not hold yet are read in step 4 and written into the case. Mark
+     them by the gate in `open-questions.md` ("Which sentences carry a marker"): a locator, a flow or a request is
+     `(seen on <profile>)`; a literal the spec asserts gets
+     `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`, and that is the only thing a person
+     has to settle. 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.
@@ -94,40 +117,52 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    - 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`.
+   user to run `pnpm signin <profile-id>` and continue with the profiles that are ready. A profile the case holds
+   information for is never dropped because it is not logged in: write its part from the case and mark it
+   `not verified on the page` in the report. 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. Read `../exploring-cases/references/tools.md`
+   first: that MCP lists tools it cannot run, and a call that answers `Tool "<name>" not found` means exactly that (the
+   server is up; use the substitute). If its tools are not registered in this session at all (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
+   `project=<profile-id>` (for example `example-staging`), `seedFile=tests/seed.spec.ts` and `plan=""`, 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
+   Do the read-only steps as written, and follow the `## Rules` that say how to prepare, wait or which control to
+   avoid. **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. A rule never
+   authorizes one of those steps. 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.
+   leave the first run of the spec (or `/heal-spec`) to confirm them. Do this for at least one logged-in profile
+   per domain (example.com and exampleshop.com differ in markup). A profile the case holds information for that is
+   not logged in is skipped and named in the report; its part is written from the case and marked `not verified` in
+   the assertion table. Use this exploration to answer the open points of step 2, and read each profile's value from
+   the case's `## Values`: open that profile's page only when a value or a behavior still has to be resolved for it.
    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.
+   **Ready before you read, here too** (`readiness.md`): take a marker on `browser_network_requests`
+   (`static: false`), act, wait for the key requests above that mark 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()`.
+   exactly one element and that this element is what `What` says (outline it with `locator.highlight()` and look at the
+   screenshot, see `tools.md`). 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
+   Update the case file with what you learned: fold observations into the right section, marked `(seen on <profile>)`
+   or, for a literal the spec asserts, `(observed on <profile>, 🔍 to be confirmed: <what to decide>)`; 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, and never put a marker inside one. 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
+5. **Complete the case's `## Values`**: for every profile the case holds information for, add the entry with the
+   literals the spec asserts (the same keys as `default`, only what differs); put a literal that holds for every profile
+   in `default`. Do not add an entry for a profile the case says nothing about, and never invent a value to fill one: a
+   profile without an entry runs on `default` alone, and a literal the case does not hold is a question in the case.
+   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
@@ -136,7 +171,10 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    (`@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
+   `// target: T<n>` on the line before it; every absence check has a `// ready: <signal>` before it; code that exists
+   only because of a `## Rules` bullet carries `// rule: <short quote>` before it; an assertion whose literal comes
+   from a `🔍 to be confirmed` line carries `// unconfirmed: <that case sentence>` before it, so
+   `pnpm markers:confirm` can settle it from a passing run. 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".
@@ -150,13 +188,18 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    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:
+   `observed on the page` or `not verified`; no row may be missing), profiles explored, profiles skipped (and why),
+   the profiles of `profiles.yaml` the case holds no information for (they run on `default` alone), whether the case file was
+   translated, what was added to the case file as `(seen on <profile>)` and which lines still need a person
+   (`🔍 to be confirmed`, with the reason), checks generated from observations, 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). Add the rule table of `case-rules.md`: every `## Rules`
+   bullet, where it was applied or why it was not, and which rules were added from `--hints`. 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`.
+   written and the checks above pass) or `RESULT: needs-input`, as defined in `open-questions.md`: plain text on the
+   last line, never inside a code fence or in emphasis.
 
 ## Cases that write data
 Only when the case front matter lists environments under `writes` (for example `writes: [staging]`). Never add
@@ -166,34 +209,54 @@ spec does, when a person runs it in an environment that `writes` lists. Elsewher
 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
+## Healing and refining a 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.
 
+Healing has two jobs, and the same command does both: **repair** a spec that fails, and **refine** a case and its spec
+when the user asks for a change. A passing run is never a reason to refuse a request, and "nothing failed" is never a
+reason to do nothing when the user asked for something.
+
 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`
+1. **Read the user's request first** (the `--hints` file, or the free text). It says what to repair or improve and may
+   hold evidence the report lacks. Read the case's `## Rules` before the steps and apply the rule pass (`R1`–`R4`,
+   `../exploring-cases/references/case-rules.md`). Decide which kind of work it is:
+   - a failure to repair (the last run failed, or the user names one);
+   - an improvement, even when the last run passed: a check that is too loose, a step, expectation, value or target
+     that no longer matches the page, wording a person cannot follow;
+   - both.
+   Quote the request you used, or say that it did not hold up, in the report. It guides the work and nothing else: it
+   never lowers the bar for a product finding and never allows an expectation to be changed just to make a test pass.
+   - **No report and no request:** do not invent work. Say that nothing asks for a change, list what
+     `pnpm spec:lint <case-id>` and the last report call weak (as suggestions, not edits), and end with `RESULT: ready`.
+   - **A passing report and no request:** the same. Do not start an improvement of your own.
+2. **Read the existing report** if there is one: 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.
+   that failed only because it was not logged in is no evidence about the spec. `EVIDENCE: none` or `no-failure` with an
+   improvement request is a starting point, not a stop.
 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 clue or a requested improvement has to be checked against the real page, and no recent report shows it;
    - 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.
+4. **Look at the pages when the change depends on them.** Reading a page is not a run and is always allowed, also for an
+   improvement request with no failure behind it. Use the `playwright-test` MCP exactly as `/gen-spec` step 4 describes
+   (`generator_setup_page` with `project=<profile-id>`, one action per call, ready before you read). Do the read-only
+   steps only: **never perform a step that writes or needs a choice**, in any environment. What you see goes into the
+   case by the gate in `open-questions.md` ("Which sentences carry a marker"): `(seen on <profile>)` for a locator, a
+   flow or a request, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` only for a
+   literal the spec asserts, so the person settles that in the review gate below.
+5. **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
@@ -204,16 +267,46 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    - 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.**
+6. **Decide what the change belongs to, and change the case first.**
    - 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 request the case can settle: the case is the source of truth, so write the change into `cases/<case-id>.md`
+     first, then into the spec. That covers a step, an expectation, a value in `## Values`, a target card, a ready
+     signal and a recipe. The spec follows the case (its step titles copy the case's step text). When the case changed
+     more than a sentence (a new or removed step, different expected values, another target), regenerate the spec from
+     the case as "## Procedure" steps 5–6 describes instead of patching it; otherwise edit it in place. Say in the
+     report which of the two you did.
+   - A reusable instruction that is method, not an expectation: append it to `## Rules` under the four-question gate
+     of `case-rules.md`, in general terms, after checking that it is not already there. An agent-inferred rule
+     carries a marker only when it changes what is asserted; a method rule is `(seen on <profile>)` and a rule the
+     person stated carries nothing. A one-off request (this failure, this
+     account, this run) stays in the report. Never put a write, an email, a person's step, an expectation or a literal
+     into `## Rules`.
+7. **Stop at the review gate.** After editing the case, read it back. If **this run** left a `🚫 TODO [blocking]` or
+   `❓ TODO [non-blocking]` block, or a `🔍 to be confirmed` or `👁️ not observed` marker, do not edit or
+   regenerate the spec any further: a case that still asks something is not a source for a spec. Report exactly what
+   to review, that answering or deleting those blocks comes first, and that the next command is
+   `/explore-case <case-id> <env>` (with `--attended` when a step writes data), or
+   `pnpm markers:confirm --case <case-id> --env <env>` when a passing run already checks those lines. End with
+   `RESULT: needs-input`. Blocks and markers that were already in the case before this run and that it did not touch do
+   not stop it. A plain `(seen on <profile>)` note never stops it. One exception:
+   a `🔍 to be confirmed` marker inside `## Rules` does not stop the spec work unless the rule covers a literal the
+   spec asserts (a `🚫`/`❓` TODO block under a rule still does).
+8. **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`, `pnpm spec:lint <case-id>` and `pnpm case:check`, and
+   fix every failure of the checks you touched. An improvement may make the run fail on purpose: a tightened check that
+   now fails is evidence about the product, so report it as a finding instead of loosening it again.
+9. **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 the request asked for and what came of it, what was
+   changed in the case and in the spec (and whether the spec was regenerated), 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 request
+   contributed, the rule table of `case-rules.md` (every `## Rules` bullet, where it was applied or why it was not,
+   and which rules this run added or changed), which profiles were left out because they are not logged in, and the
+   result of the confirming run. The last line is `RESULT: ready` (nothing left for a person, the spec changed and its checks pass)
+   or `RESULT: needs-input` (the case waits for a review, as in step 7, or a person has to decide something). A run
+   that could not write files at all (plan mode, a read-only sandbox, a refused permission) is `needs-input` too:
+   never end with a plan and a question instead.
 
 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`.

package/.claude/skills/generating-specs/references/conventions.md

@@ -108,6 +108,10 @@ Binding rules are in `../exploring-cases/references/readiness.md` and `.../asser
 - A check on a logo, image, file or screenshot has `// target: T<n>` on the line before it (a card in the case's
   `## Targets`). The element is found by the card's `Identified by` (role and name, test id, alt/title), never `.first()` or
   a bare `img`/`svg`. Semantic assertion first (name/alt/src, where it is), pixels second, on that element only.
+- An assertion whose literal comes from a `🔍 to be confirmed` line in the case carries
+  `// unconfirmed: <that case sentence>` before it (one line, the sentence without its marker). It is what
+  `pnpm markers:confirm --case <id> --env <env>` reads after a passing run to settle the marker, so the line must be
+  the case's own wording, not a paraphrase.
 - A check for absence ("no", "missing", "empty", "hidden") has `// ready: <signal>` in front of it and a positive wait
   before it. The page must have loaded before "nothing" means anything.
 - A download is `await verifyDownload(page, () => option.click(), {kind: 'pdf'})`. It checks, and fails the step on

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

@@ -10,14 +10,16 @@ Read the workspace `AGENTS.md` (hard rules and project rules) and `cases/_templa
 - `references/writes-and-email.md`: how to classify steps that write data or send email, and the data rules.
 - `references/gaps.md`: what to ask, and the default to suggest for each question.
 - `references/splitting.md`: how many cases to make.
+- `../exploring-cases/references/case-rules.md`: what belongs in `## Rules` (a method constraint), and what stays in
+  Steps, Expected, Values or Targets.
 
 This skill writes `cases/*.md` only. It never writes specs, `profiles.yaml`, or anything under `tests/`.
 
 ## Before you start
 Read the workspace `AGENTS.md`: its §2 holds the project rules, and it points at the framework baseline. If
 `.claude/skills/making-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.
+§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.
 
 ## Inputs
 - Raw notes: pasted text or a file path. Any language, any quality.
@@ -34,10 +36,11 @@ the procedure below.
    creates, edits, publishes, shares, deletes or sends is not read-only, even if the notes do not say so.
 4. **Find the gaps** (`references/gaps.md`): missing expected results, unknown values a spec must assert, unclear starting
    state, steps that need data that may not exist, ordering that is not linear. Never invent an expected value.
-   Unknown values are written as the suggested default sentence with a `❓ TODO` block under it (see `gaps.md`), or as an
-   `Observed, 🔍 to be confirmed by QA` bullet. Every marker starts with its emoji. A literal nobody knows yet goes into
-   the case's `## Values` as `TODO` (the spec then fails with a clear message until it is filled), never into
-   `profiles.yaml`.
+   Unknown values are written as the suggested default sentence with a `❓ TODO` block under it (see `gaps.md`). A fact
+   from the notes that nobody questions is a plain note `(seen on <profile>)`; only a literal the spec will assert and
+   that would pass while wrong gets `(observed on <profile>, 🔍 to be confirmed: <what to decide>)`. A marker never
+   goes inside a TODO block. A literal nobody knows yet goes into the case's `## Values` as `TODO` (the spec then fails
+   with a clear message until it is filled), never into `profiles.yaml`.
 5. **Ask before writing.** Show the user a short plan and the open questions in one message: the proposed split
    into cases, the classification (which steps write, which send email), and the gaps with your suggested default
    for each. Wait for answers. Do not write case files before that.
@@ -48,10 +51,14 @@ the procedure below.
      ask in step 5. The group does not repeat in the name: `documents/landing-page`, not `documents/documents-landing-page`.
    - Front matter: `id`, `title`, `login`, `suites`, `writes`, `writes-note` (required when `writes` is not `none`),
      `envs` when a case must not run everywhere. When unsure: `suites: [regression]`, no `writes` (read-only), or `writes: [staging]` when a step writes.
-   - Fill the sections that apply (Goal, Steps, Expected, Values, Visual checks, Source, Notes).
+   - Fill the sections that apply (Goal, Steps, Expected, Rules, Values, Visual checks, Source, Notes).
      Remove template placeholders you do not use. Use `## Values` only for the literals a spec asserts; `default`
      applies to every profile, and a profile id entry holds only what differs. Do not add `- Recipe:` lines: a person
      records them during `/explore-case --attended`.
+   - Put a note in `## Rules` only when it states a **method** constraint (dismiss a banner before step 1, never use
+     an entry that needs 2FA). A constraint that is part of the tested flow is a step; one that creates, changes or
+     deletes data is a tagged step with a later recipe. Never invent a rule, and never put an expectation or a literal
+     there: those go to `## Expected` or `## Values`. The note that became a rule is listed in its `## Source` row.
    - Case ids are lowercase kebab-case and name the thing, not the ticket: `landing-page`.
    - Existing case files: do not overwrite. If a new case overlaps one (for example another case about the same page), say so,
      propose "keep", "merge" or "replace", and wait for the user.

package/.claude/skills/making-cases/references/gaps.md

@@ -17,7 +17,7 @@ single lines. Never ask a question whose answer is already in the notes, `AGENTS
 | Environments | Must this case run in production, or only staging? | All environments; production writes need the usual confirmation |
 | Suites | Smoke, regression, or both? | A read-only landing check: `[smoke, regression]`; a flow that writes: `[regression]` |
 | Profiles | Do all profiles see the same UI? | Yes; the exact literals that differ go in `## Values`, never in the steps |
-| Unclear words | What does "collaborator button" / "..." button open? | Describe only what is observed; mark `(observed, 🔍 to be confirmed by QA)` |
+| Unclear words | What does "collaborator button" / "..." button open? | Describe the safest reading and hang a TODO under it; a detail nobody questions is a plain note `(seen on <profile>)` |
 | Unused lines | A statement that fits no case | Ask where it belongs; never drop it silently |
 
 ## Marking unknowns in a case
@@ -26,11 +26,14 @@ single lines. Never ask a question whose answer is already in the notes, `AGENTS
 
   ```
   - The preview header shows the product logo, visible and not empty.
-    - ❓ TODO [non-blocking]: Which logo must it be? (👁️ not observed)
+    - ❓ TODO [non-blocking]: Which logo must it be? (the notes say only "the logo")
       - ✍️ Answer:
   ```
 
   The user accepts the default by deleting the block, or types an answer. Never write a bare `TODO: ...` line, a
-  question as the only text, or `Suggested:`.
-- Seen on a page during exploration but not stated in the notes: `- <observation> (observed, 🔍 to be confirmed by QA)`.
+  question as the only text, or `Suggested:`. Never put a marker word inside the block: one claim carries one signal.
+- Seen on a page during exploration but not stated in the notes: `- <observation> (seen on <profile>)`. A literal the
+  spec will assert is different: `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`, and only
+  when a wrong reading would still pass. The gate is "Which sentences carry a marker" in
+  `exploring-cases/references/open-questions.md`.
 - Never turn an observation into a hard requirement on your own.

package/.claude/skills/making-cases/references/normalizing.md

@@ -34,6 +34,6 @@ Original notes, verbatim. Do not edit this table; it only exists so a reviewer c
 ```
 
 - The original text is copied character by character, in a code span, in its original language.
-- "Became" points at step numbers, or says "Expected", "Visual checks", "Not used: <reason>".
+- "Became" points at step numbers, or says "Expected", "Rules", "Visual checks", "Not used: <reason>".
 - A statement used by two cases appears in both tables.
 - A statement that is not used anywhere is a gap: ask about it, do not silently drop it.

package/AGENTS.md

@@ -11,7 +11,7 @@ project that uses asrun, the framework files are in `node_modules/@asrunjs/asrun
 ## Precedence
 
 Rules are applied in this order; a later layer wins where they conflict.
-1. **F1–F6: safety.** Nothing overrides them, in any project. They are enforced in code as well
+1. **F1–F6 and R2: safety.** Nothing overrides them, in any project. They are enforced in code as well
    (`lib/write-gate.ts`, `lib/session.ts`, the run filters), so a rule file cannot weaken them.
 2. **This file.** The generic facts and defaults.
 3. **The framework skills** (`<framework>/.claude/skills/**`).
@@ -20,8 +20,11 @@ Rules are applied in this order; a later layer wins where they conflict.
 5. **The project's `AGENTS.md` §2 (Project rules).** It states the project's intent and wins over layers 2–4.
 
 A project writes §2 only for what differs from the defaults here, names the rule id, and says whether it `narrows` or
-`replaces` the rule. `replaces` is refused for F1–F6; `pnpm asrun doctor` checks the table. A rule file never renames
-the structural tokens under "Fixed tokens".
+`replaces` the rule. `replaces` is refused for F1–F6 and R2; `pnpm asrun doctor` checks the table. A rule file never
+renames the structural tokens under "Fixed tokens".
+
+Inside a case, `## Rules` is a case-local layer below this file and the project's §2: it says how to run that case,
+never what is true (`R1`), and a rule that conflicts with the rest of the case is a question, not an override.
 
 ## Hard rules
 - **F1 — Read-only by default.** [non-negotiable] Tests never create, edit, delete, submit forms that change data,
@@ -62,8 +65,12 @@ These apply to every agent that drives a browser to explore pages for cases or s
   Everything that writes is the person's (see F3).
 - **B2 — Waiting for a person.** Only in an attended run. Announce the task in the browser window (a small draggable
   card with a Done button and click-to-copy for texts to type), name the finish condition, wait, and tell the person
-  when control is back. Record what they did as a general recipe under the step (`- Recipe (phase): ...`): positions
-  instead of names of data that can change.
+  when control is back. The card starts and stops the recording itself and returns `recorded`; never call
+  `browser_start_recording` or `browser_stop_recording`: the `playwright-test` MCP lists many browser tools it cannot
+  run (`devtools`, `storage`, `network`, `pdf`, `vision`, and the `skillOnly` ones such as `browser_network_clear`),
+  and the substitutes for each are in `<framework>/.claude/skills/exploring-cases/references/tools.md`. Record what
+  they did as a general recipe under the step (`- Recipe (phase): ...`): positions instead of names of data that can
+  change.
 - **B3 — Closing an email composer.** When closing an email composer makes a confirm dialog appear (for example
   "Discard draft?"), choose "Discard" and continue. Never choose "Save" or "Send"; closing the composer must not keep
   or send anything. The dialog can show up late: in a spec, clicking "Discard" and checking that the composer is
@@ -104,27 +111,60 @@ Details: `<framework>/.claude/skills/exploring-cases/references/assertion-target
 - **A6 — Observe first, delete last.** Everything that needs the data (preview, share menus, composers, downloads) is
   observed before the person deletes it.
 
+## Case rules (`R`, binding for exploring, generating, healing and making cases)
+A case document may hold a `## Rules` section: case-local instructions a person writes for the agents. They say **how**
+to run that case, never **what is true**. Details: `<framework>/.claude/skills/exploring-cases/references/case-rules.md`.
+- **R1 — Rules describe the method, not the outcome.** `## Steps`, `## Expected`, `## Values` and `## Targets` stay the
+  only place for behaviour, expectations and literals. A rule that contradicts them is a `🚫 TODO [blocking]` question,
+  never a silent override. A sentence that says something must be true belongs in `## Expected` (with a target card when
+  it looks at an image, file, PDF, screenshot or repeated text).
+- **R2 — Rules never authorize what F1–F6 forbid.** [non-negotiable] A rule cannot allow creating, changing or
+  deleting data, sending email, accepting terms, or doing a person's step. Those stay tagged steps (`[writes]`,
+  `[email]`, `[input]`) with their `- Recipe:` lines and the front-matter `writes`/`writes-note` the case needs. The
+  agent never performs them while exploring or generating, whatever a rule says.
+- **R3 — Every AI step reads every rule and accounts for it.** `/explore-case`, `/gen-spec` and `/heal-spec` (and
+  `/make-case` when it edits an existing case) read the whole `## Rules` section before they start, apply it, and list
+  each rule in the final report with where it was applied or why it was not. Exploration re-checks each rule against
+  the page: a rule that no longer holds gets a TODO with evidence, never silent deletion or rewriting. The agent may fix
+  a typo and may add a question under a rule; it never changes what a rule says.
+- **R4 — Only reusable method is written back.** When a person supplies instructions before or during a run (`--hints`,
+  free text, an answer in the case), the agent appends to `## Rules` only what a future run of the same case needs,
+  stated in general terms (no account, date, run id or one-off failure), and only when it is method rather than an
+  expectation. A rule the agent inferred from a page carries a marker only when the rule changes what is asserted
+  (`(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`); a method rule whose wrong version would
+  fail the next run is a plain note `(seen on <profile>)`, and a rule the person stated carries nothing. Run-specific
+  information stays in the report. A marker inside `## Rules` does not stop spec generation the way an open question
+  about an assertion does.
+
 ## Fixed tokens
 `lib/case-doc.ts`, the scripts and the web panel parse these literals. A project language never translates them, and
 a project rule never renames them.
-- Section headings: `## Goal`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`, `## Notes`,
-  `## Source` (only when the case was made from notes).
+- Section headings: `## Goal`, `## Rules`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`,
+  `## Notes`, `## Source` (only when the case was made from notes).
 - A step's recipe lines: `- Recipe (phase): ...` under the step it belongs to.
 - `### T<n>` target cards and the `[T<n>]` references to them.
 - Question blocks: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:` (with its emoji), and the markers
-  `🔍 to be confirmed by QA` / `👁️ not observed`.
+  `🔍 to be confirmed` and `👁️ not observed`. A marker may carry its reason and a screenshot in the same
+  parentheses: `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>, evidence: <path>)`.
+  `(seen on <profile>)` is not a token: it is an ordinary note.
 - Step tags `[input]`, `[writes]`, `[email]`, and the last line `RESULT: ready` / `RESULT: needs-input`.
+  The RESULT line stands on its own: nothing in front of it on that line (no label, in any language), nothing after
+  it but closing punctuation, and plain text: never inside a code fence or in emphasis.
 - Front-matter keys: `id`, `title`, `login`, `suites`, `writes`, `writes-note`, `envs`.
 
 ## Where the details are
 This file holds the rules. The exact shape those rules apply to is documented once, and not repeated here:
-- `docs/agents/case-format.md`: the case document contract (front matter, steps, `## Values`, target cards, the
-  spec's consumption of them, the write gate). Read it before editing a case document or a generated spec.
+- `docs/agents/case-format.md`: the case document contract (front matter, steps, `## Rules`, `## Values`, target cards,
+  the spec's consumption of them, the write gate). Read it before editing a case document or a generated spec.
+- `.claude/skills/exploring-cases/references/case-rules.md`: how a case's `## Rules` are read, applied and maintained.
+- `.claude/skills/exploring-cases/references/tools.md`: which browser tools the `playwright-test` MCP can run, the
+  substitute for each one it only lists, and the arguments every call has to carry. Read it before the first browser
+  call of a run.
 - `docs/commands.md`: every command and flag.
 - `docs/cases.md`: the same case format for the people who write cases by hand.
 - `docs/agents/framework-dev.md`: the framework's own layout and how to change it.
 The project's own `AGENTS.md` §2 (project rules) and §3 (project facts) still win over the documentation where they
-differ, and `F1`–`F6` win over everything.
+differ, and `F1`–`F6` and `R2` win over everything.
 
 ## Layout
 
@@ -143,14 +183,16 @@ The framework folder is read-only in a project: never edit it. Its own layout an
 Three steps, each learns one thing: the intent, the facts and inputs, the implementation.
 1. `making-cases` (or `/make-case <notes>`) turns raw notes into case documents. It writes `cases/*.md` only and
    never opens a browser. Check them with `pnpm case:check`.
-2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended]`) explores the real pages for one case. It
-   edits that case file only: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines of
-   the steps that write or need a choice.
+2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended] [--profiles a,b]`) explores the real pages for one
+   case. It edits that case file only: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
+   of the steps that write or need a choice. `--profiles` narrows the run to those profiles; runs add up, so the case
+   can be explored in passes.
 3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case and its
    step recipes and `## Values`, writes the spec (values stay in the case document), but never runs the tests, never
-   writes data and never creates baselines. A tagged step with no `- Recipe:` line (an old `## Inputs` line counts
-   until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs is a separate step
-   (`pnpm asrun`, or the Run page).
+   writes data and never creates baselines. There is no profile selection here: it covers every profile the case names,
+   which is why a case explored in passes generates one spec for all of them. A tagged step with no `- Recipe:` line
+   (an old `## Inputs` line counts until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs
+   is a separate step (`pnpm asrun`, or the Run page).
 Workspace maintenance is separate from the AI steps: `pnpm asrun upgrade` installs the newest framework, refreshes the
 generated files and applies the release's workspace migrations (it checks the target release for breaking changes
 before installing), `pnpm asrun init [--update] [--force]` writes or refreshes the workspace files, `pnpm asrun
@@ -161,9 +203,15 @@ Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec p
 Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
 case's own steps (see the skill's `references/conventions.md`).
 Every AI command needs an environment (`--env`/`<env>`); there is no default and no "no environment" mode.
-`/heal-spec <case-id> <env>` reads the existing report first (`pnpm heal:evidence --case <id> --env <env>`), reads the
-user's optional clues (`--hints <file>`), runs only the profiles that are logged in (`--logged-in`) and runs the case
-again only when the report is missing, stale or not enough.
+A one-shot AI run is a build run: it writes the case or the spec, never a plan. AsRun starts OpenCode with
+`--agent build`, because OpenCode keeps the agent (build or plan) on the session and a plan session would only propose
+changes and ask a question nobody can answer. Whatever mode or sandbox a run finds itself in, it still ends with the
+`RESULT:` line: a run that was not allowed to write files is `needs-input`, never a plan and a question.
+`/heal-spec <case-id> <env>` repairs one failing spec or refines a case and its spec on request (a passing run is not
+a reason to refuse): it reads the existing report first (`pnpm heal:evidence --case <id> --env <env>`), the user's
+request (`--hints <file>`), runs only the profiles that are logged in (`--logged-in`) and runs the case again only
+when the report is missing, stale or not enough. A change that leaves an open question or an unconfirmed observation
+in the case stops before the spec: the person reviews the case and runs `/explore-case` again.
 Run `pnpm typecheck`, `pnpm spec:lint <case-id>` and `pnpm case:check` before reporting that a spec was generated. Run
 `pnpm asrun --env <env> --profile <id> --grep <case-id>` only when healing a spec or when asked to.
 Pick `--env staging` while developing. A case that does not list `production` under `writes` is skipped in