@asrunjs/asrun 0.9.0 → 0.11.0

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

@@ -8,8 +8,11 @@ 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/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/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),
+`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts),
+`../exploring-cases/references/notes.md` (the local exploration note this run reads first) and
+`../exploring-cases/references/tools.md` (the browser tools this MCP can run). All six 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`). This holds whatever mode or agent the run is in: plan mode changes what you may write,
@@ -36,15 +39,18 @@ and the spec, and runs only the profiles that are logged in, and only when the r
 ## 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`.
+  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
@@ -80,14 +86,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.
@@ -105,41 +118,47 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
      never for what the check asserts about it: that goes to `test.fixme` with the reason, or `needs-input`.
    - Do not invent expected values. If the case's `## Values` and the spec disagree, the case wins: fix the spec and
      mention the change in the report.
-3. **Check sessions** if `login: required`: run `pnpm status --env <env>`. If a profile needs login, tell the
-   user to run `pnpm signin <profile-id>` and continue with the profiles that are ready. 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. If its tools are not registered in this
-   session (no `browser_*` / `generator_*` tool) or it reports that it failed to start, do not fall back to ad-hoc
-   Playwright scripts: stop, tell the user which MCP server is missing and to run `pnpm asrun doctor`, write no spec,
-   and end with `RESULT: needs-input`.
-   Call `generator_setup_page` with
-   `project=<profile-id>` (for example `example-staging`) and `seedFile=tests/seed.spec.ts`, then perform the
-   steps in the environment you were given (never ask for it; there is no default) to learn the locators.
-   Do the read-only steps as written. **Never perform a step that writes or needs a choice**: the agent does not write
-   data, in staging or in production, and it does not hand off to a person here or wait for one. Write those steps
+3. **Check sessions** if `login: required`: follow `../exploring-cases/references/tools.md`, "Starting a session". A
+   profile that needs login is named with `pnpm signin <profile-id>`, and the run continues 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.
+4. **Replay the case on the real page** with the `playwright-test` MCP, following
+   `../exploring-cases/references/tools.md` ("Starting a session", "Short calls") and `readiness.md` ("Exploring"). 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`.
+   **Read each profile's exploration note first** (`../exploring-cases/references/notes.md`): run
+   `pnpm asrun explore:notes <case-id> --json`. A fresh note (its `caseSha256` matches the case) supplies the locator,
+   the request pattern and the target's match count for a step; confirm each on the page instead of rediscovering it,
+   and skip what it does not hold. A missing or stale note means the plain replay below. After confirming an entry of
+   a fresh note, you may write the verified locator or request back into that file (`updatedAt` gets the time); never
+   add a step or a target, and never touch a stale note. Say in the report what came from a note and what was
+   refreshed. Perform the steps in the environment you were given (never ask for it; there is no default).
+   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 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.
-   **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
+   from a fresh note first, then from the recipe, and mark them in the report as "observed by explore on <profile>" or
+   "not verified on the page"; leave the first run of the spec (or `/heal-spec`) to confirm the latter. 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.
+   **Ready before you read, here too**: follow `readiness.md`. The request URL patterns for `actAndWait` come from a
+   fresh note or from `browser_network_requests` during this replay, never from a guess; the `Ready when` signal comes
+   from the case.
+   **Check every target on the page:** follow `../exploring-cases/references/assertion-targets.md`, "What the spec does
+   with a card (generating)". Confirm that the card's `Identified by` matches 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 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
@@ -154,12 +173,16 @@ 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".
 7. **Check the files**: run `pnpm typecheck`, `pnpm spec:lint <id>` and `pnpm case:check` (or `node --import tsx <framework>/scripts/check-cases.ts` if
-   it fails with a sandbox error such as `listen EPERM`). Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
+   it fails with a sandbox error such as `listen EPERM`). When you wrote an exploration note back, also run
+   `pnpm asrun explore:notes <id> --check --profile <profile-id>` for each profile you refreshed. Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
    into a question). Every lint `WARN` is handled too: fix it, or name it in the report with the reason it is acceptable.
    Then do the **self-review**: for each assertion answer in writing "if the product were broken, would this fail?"
    and "if the product is right, could this fail by timing?" (a check that cannot fail, or that races the page, is rewritten).
@@ -168,14 +191,19 @@ 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),
+   `observed on the page` or `not verified`; no row may be missing), profiles explored, which steps were written from a
+   fresh exploration note and which notes were refreshed (or that there were none), 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 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:
+   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
@@ -197,7 +225,8 @@ 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 request first** (the `--hints` file, or the free text). It says what to repair or improve and may
-   hold evidence the report lacks. Decide which kind of work it is:
+   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;
@@ -225,10 +254,15 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    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. **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
+   improvement request with no failure behind it. Use the `playwright-test` MCP exactly as `/gen-spec` step 4 describes,
+   following `../exploring-cases/references/tools.md` ("Starting a session", "Short calls"), `readiness.md` and the
+   exploration note (`../exploring-cases/references/notes.md`). 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 as `(observed, 🔍 to be confirmed by QA)`, so the person can confirm it in the review gate below.
+   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. If the note was stale, edit the case
+   as usual; if it was fresh, a verified locator may be written back
+   (`../exploring-cases/references/notes.md`).
 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
@@ -250,12 +284,22 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
      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 by QA` or `👁️ not observed` marker, do not edit 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). 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.
+   `/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
@@ -264,8 +308,9 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    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, 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)
+   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.

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
 
@@ -144,15 +184,16 @@ Three steps, each learns one thing: the intent, the facts and inputs, the implem
 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] [--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. 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).
+   case. It edits that case file: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
+   of the steps that write or need a choice, and it writes a local note under `.explore/notes/` with the locators and
+   data-call paths it saw. `--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, its
+   step recipes and the exploration note, and `## Values`, writes the spec (values stay in the case document), but never
+   runs the tests, never 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

package/README.md

@@ -99,11 +99,12 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
 3. **Write a case.** `pnpm case:new header-logo` creates `cases/header-logo.md` from the template; or start from raw
    notes with `/make-case notes.md`. Fill in the steps, what is expected and the exact values.
 4. **Check it against the real pages.** `/explore-case header-logo staging` opens the pages (with your saved session),
-   writes what they show into the case and turns what it cannot know into questions. Answer them in the case file, or
-   in the UI's **Answer** sheet, and run it again. With many profiles, `--profiles a,b` opens only those; a later run
-   with the others adds theirs, and the case keeps both.
-5. **Generate, run, read.** `/gen-spec header-logo staging` writes `tests/header-logo.spec.ts` and fills the case's
-   `## Values`. Then:
+   writes what they show into the case and turns what it cannot know into questions. It also saves a local note of the
+   locators and data calls it saw. Answer the questions in the case file, or in the UI's **Answer** sheet, and run it
+   again. With many profiles, `--profiles a,b` opens only those; a later run with the others adds theirs, and the case
+   keeps both.
+5. **Generate, run, read.** `/gen-spec header-logo staging` reads those notes, writes `tests/header-logo.spec.ts` and
+   fills the case's `## Values`. Then:
 
    ```bash
    pnpm asrun --env staging --grep header-logo
@@ -133,12 +134,13 @@ It is read after the framework skill and before your project rules. Write only w
 
 Rules combine in this order, and a later layer wins where they conflict:
 
-1. `F1`–`F6` of the framework baseline (safety, in every project). They cannot be changed.
+1. `F1`–`F6` and `R2` of the framework baseline (safety, in every project). They cannot be changed.
 2. The framework baseline, `node_modules/@asrunjs/asrun/AGENTS.md`.
 3. The framework skill.
 4. Your override, `.claude/skills/<skill>.md`.
-5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`) with `narrows` or `replaces`, for example the artifact
-   language.
+5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`, `R1`, `R3`, `R4`) with `narrows` or `replaces`, for example
+   the artifact language.
+6. A case's `## Rules`: how to run that one case, never what is true.
 
 `pnpm asrun doctor` validates the table and lists the overrides it sees. An update never rewrites your rules:
 `init --force` refuses `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` without `--reset-rules`. Never edit the

package/bin/asrun.mjs

@@ -23,9 +23,11 @@ const SCRIPTS = {
   status: 'status.js',
   report: 'report.js',
   explore: 'explore.js',
+  'explore:notes': 'explore-notes.js',
   cleanup: 'cleanup.js',
   'case:new': 'new-case.js',
   'case:check': 'check-cases.js',
+  'markers:confirm': 'markers-confirm.js',
   'spec:lint': 'lint-specs.js',
   'baselines:review': 'review-baselines.js',
   'pdf:render': 'render-pdf.js',