@asrunjs/asrun 0.9.0 → 0.10.0

package/.claude/skills/exploring-cases/references/open-questions.md

@@ -5,7 +5,7 @@ without anybody present (a one-shot `claude -p` / `opencode run`). The case file
 talk to each other, so nothing is lost between runs, tools or sessions.
 
 ## How a question is written in the case file
-Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed by QA` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it.
+Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it. `(seen on <profile>)` is not a marker: it is a plain note, shown as ordinary text.
 Every question is a small block that hangs under a normal sentence. The sentence is the agent's suggestion, written
 exactly as it should read in the final case. The block holds the question and an empty answer slot:
 
@@ -15,7 +15,7 @@ exactly as it should read in the final case. The block holds the question and an
     - ✍️ Answer:
 ```
 
-The same shape is used under a step, under a bullet of "Expected" and under the yaml block of "Values":
+The same shape is used under a step, under a bullet of "Expected" and on the prose line above the `## Values` block:
 
 ```
 11. Delete the document with the "Delete" option of its "..." menu on the list page. [writes]
@@ -40,8 +40,52 @@ Rules for writing it:
   QA should confirm it later but nothing waits for it.
 - One question per block; narrow broad questions down instead of copying them ("which profile elements?" becomes
   "is the logo the only per-profile element in the left side bar?").
-- A value read from a page is not a question: write it as a statement marked `(observed, 🔍 to be confirmed by QA)`.
-  It needs no TODO block; the reviewer confirms it by deleting the marker.
+- A fact read from a page is not a question: either say it as a plain note `(seen on <profile>)`, or mark it
+  `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` when a wrong reading would still pass.
+  It needs no TODO block. See "Marker or question, never both" below.
+
+## Where the block hangs
+The parent line is the sentence the question is about: the panel shows it on its own, next to "The text above this
+question", so it has to make sense without the rest of the document.
+- **The immediate line, not an ancestor.** Hang the block under the one sentence that makes the claim. Under a
+  nested bullet, indent it under that bullet, not under the top-level one above it; when the claim only makes sense
+  with an umbrella sentence, write the claim itself as a top-level bullet and hang the block there.
+- **One claim, one block.** Several bullets raising one question get one block, under the closest of them, with the
+  others' evidence in that block. Never end a long list with a single question that covers all of it.
+- **A sentence that stands alone.** No "see above", no pronoun whose referent is in a sibling bullet.
+- **Never inside the `## Values` yaml block.** A marker or a question there becomes part of the expected value: put
+  it on the prose line above the block.
+
+## Marker or question, never both
+A sentence carries at most one "not settled yet" signal, and the two marks are alternatives:
+- `🚫/❓ TODO`: there **is** a question. The parent sentence is a suggestion, the block says what to decide.
+- `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`: there is **no** question, only a check
+  somebody has to make later. The part after the colon is required: "to be confirmed by QA" alone tells a person
+  nothing, and the panel shows that part as "why it needs you".
+- `(observed on <profile>, evidence: .explore/observations/<case-id>/<image>.png)`: the same, with a screenshot the
+  reviewer opens instead of going back to the page. Save it while exploring.
+- `(seen on <profile>)`: a plain note. The run checks it, so nobody has to; it gets no colour and no panel row.
+
+- Never put a marker inside a TODO block: not in the question, not in the evidence, not in a wrapped line. The words
+  "to be confirmed", "TBC", "TBD" and "not observed" are marker words even in prose there, and `pnpm case:check` fails
+  on them.
+- Never put a marker on the sentence a block hangs under: keep the question and drop the marker.
+- `👁️ not observed` is for an expectation that came from the notes and was never seen on a page. It is never the
+  evidence of a question.
+
+## Which sentences carry a marker
+A marker is for exactly one thing: a fact a person must settle because a wrong reading would still pass. Ask yourself:
+**if this line were read wrong, would the generated spec fail?**
+- **It would fail** → no marker. Locators, the flow of a step, navigation, request URLs, readiness signals, whether an
+  element exists. The run is the confirmation. Leave `(seen on <profile>)` when where it was seen matters.
+- **It would pass anyway** → marker, with the reason. The literals a check asserts (a `## Values` entry, the wording of
+  an `## Expected` bullet) and the identity of a `[T<n>]` target. This is the class that hides a wrong expectation
+  forever; `assertion-targets.md` records two real incidents of it.
+- A `## Rules` bullet the agent inferred from a page carries a marker only when the rule changes what is asserted;
+  otherwise it is `(seen on <profile>)`. A rule a person stated never carries one.
+
+After a passing run, `pnpm markers:confirm --case <id> --env <env>` settles the markers whose line the spec checks
+(`// unconfirmed: <the sentence>`), so a person does not have to open the page again to see whether it is still true.
 
 ## How the user answers
 Two ways, and the agent must understand both on the next run:
@@ -69,7 +113,9 @@ answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It
 ## Resolution order (no question goes to the user while a better step exists)
 1. **The page answers it.** Facts such as exact labels, which controls exist, where the logo is, what a menu holds
    are answered by exploration (`/explore-case`; needs an environment and a logged-in profile; the agent only reads, a person does the steps that write). Rewrite the parent sentence
-   with the fact, mark it `(observed, 🔍 to be confirmed by QA)` and remove the block.
+   with the fact and remove the block. Then decide the mark by "Which sentences carry a marker": a fact the run checks
+   gets `(seen on <profile>)`, a fact that would pass while wrong gets
+   `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`.
    - A check with no expected value ("check X", "can see Y") becomes: the observed behaviour, marked as observed.
      A spec may be generated from it.
    - Values that a check asserts (logo name, label, option list) are observed per profile and written into the case's
@@ -101,13 +147,19 @@ answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It
 
 ## Final report
 Report in the user's language. List every open block with its question and the parent sentence it would confirm, so
-the user can see what deleting it accepts. The last line of the final message is exactly one of:
+the user can see what deleting it accepts. List the markers separately, each with its reason and whether it changes an
+assertion: that is the short list a person actually has to look at. The last line of the final message is plain text
+and nothing else, exactly one of:
 
 ```
 RESULT: ready
 RESULT: needs-input
 ```
 
+Never put that line in a code fence or inline code, never make it bold, a heading or a list item, and put no label,
+number or emoji in front of it: the panel reads it to show how the run ended. (The block above only lists the two
+tokens; write the one that applies as the last line of your message, not the block.)
+
 - `ready`: no `[blocking]` question remains. Non-blocking ones may remain; list them so QA can confirm them.
 - `needs-input`: at least one `[blocking]` question remains in the case file (list each with its parent sentence),
   or the work could not be done (no environment, nobody logged in, or no permission to write files: a plan-mode run,

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

@@ -22,9 +22,10 @@ A check for something **missing, empty or hidden** is only valid after a positiv
 means: the list finished loading and has rows, and none is X.
 
 ## Exploring
-- Know the key requests: after the action, call `browser_network_requests`, pick the data calls (XHR/fetch to the
-  app's API, the ones that return the content). Wait until they are finished; use `browser_network_clear` before the
-  action so the list only holds what the action started.
+- Know the key requests: after the action, call `browser_network_requests` (`static: false`), pick the data calls
+  (XHR/fetch to the app's API, the ones that return the content). Wait until they are finished. `browser_network_clear`
+  is not runnable in this MCP, so take a marker instead: read the list before the action, keep the highest number, and
+  after the action only the entries above it belong to it (`tools.md`, "Network requests without a clear").
 - Then wait for the content signal (`browser_wait_for` with text, or `browser_find` that the content is there), and
   take the snapshot only then. A snapshot taken right after a click is a frame, not a fact.
 - Observations record the ready signal: `(observed after <signal>, ...)`. A fact with no signal is not recorded.

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

@@ -0,0 +1,117 @@
+# The browser tools this MCP can run, and the ones it only lists
+
+Shared by `exploring-cases`, `generating-specs` and healing. It is binding in all three: read it before the first
+browser call of a run.
+
+`playwright run-test-mcp-server` answers `tools/list` with **every** browser tool Playwright has, but a call runs
+inside a paused test, and that backend installs one capability set:
+
+```js
+const config = { capabilities: ["testing"] };   // playwright/lib/mcp/test/browserBackend.js
+const toolList = tools.filteredTools(config);   // core* + testing, minus `skillOnly`
+```
+
+Everything outside that set is listed and still cannot run: it answers `Tool "<name>" not found`. Two groups:
+- a capability other than `core`/`testing` (`devtools`, `storage`, `network`, `pdf`, `vision`, `config`);
+- `skillOnly: true` tools, which the backend never installs (`browser_network_clear`, `browser_console_clear`).
+
+**`Tool "<name>" not found` is not a broken MCP server.** The server is up and every other tool works. Never stop
+with `RESULT: needs-input` for it, never report a missing MCP server, and never fall back to an ad-hoc Playwright
+script (it sees a different browser and its network view is not `browser_network_requests`, see A2). Use the
+substitute below instead, and say in the report which substitute you used.
+
+`pnpm asrun doctor` prints how many tools the installed Playwright actually runs and warns when this file names one
+it cannot (it happens when Playwright changes the filter; the file then needs the same edit).
+
+## Runnable
+
+Navigation and reading:
+`browser_navigate`, `browser_navigate_back`, `browser_snapshot`, `browser_find`, `browser_evaluate`,
+`browser_run_code_unsafe`, `browser_tabs`, `browser_resize`, `browser_close`, `browser_handle_dialog`,
+`browser_console_messages`, `browser_emulate_media`, `browser_wait_for`.
+
+Interaction: `browser_click`, `browser_type`, `browser_fill_form`, `browser_press_key`, `browser_hover`,
+`browser_drag`, `browser_drop`, `browser_select_option`, `browser_file_upload`.
+
+Screenshots: `browser_take_screenshot`.
+
+Network: `browser_network_requests`, `browser_network_request`.
+
+Test helpers: `browser_generate_locator`, `browser_verify_element_visible`, `browser_verify_text_visible`,
+`browser_verify_list_visible`, `browser_verify_value`.
+
+`browser_run_code_unsafe` takes Playwright's own API (a `page`, `context`, `expect` are in scope), which is what
+every substitute below uses.
+
+## Listed but not runnable
+
+| Tool | Why | Do this instead |
+|---|---|---|
+| `browser_highlight`, `browser_hide_highlight` | `devtools` | [Outline a target](#outlining-a-target-without-browser_highlight) |
+| `browser_network_clear` | `skillOnly` | [Network requests without a clear](#network-requests-without-a-clear) |
+| `browser_console_clear` | `skillOnly` | read `browser_console_messages` and note the messages you already saw |
+| `browser_start_recording`, `browser_stop_recording` | `devtools` | the handoff card (`user-handoff.md`, "Recording") |
+| `browser_annotate` | `devtools` | let the person name the element in the handoff card, then outline it yourself |
+| `browser_start/stop_tracing`, `browser_start/stop_video`, `browser_video_*`, `browser_resume` | `devtools` | not needed by a case |
+| `browser_cookie_*`, `browser_localstorage_*`, `browser_sessionstorage_*`, `browser_storage_state`, `browser_set_storage_state` | `storage` | never: saved logins are passwords (F5) |
+| `browser_route`, `browser_unroute`, `browser_route_list`, `browser_network_state_set` | `network` | never: a case checks the real page |
+| `browser_pdf_save` | `pdf` | a page that serves a PDF is downloaded and rendered (`pnpm pdf:render`) |
+| `browser_mouse_move_xy`, `browser_mouse_down`, `browser_mouse_up`, `browser_mouse_wheel`, `browser_mouse_click_xy`, `browser_mouse_drag_xy` | `vision` | `browser_click` with a locator |
+| `browser_get_config` | `config` | `pnpm status --env <env>` |
+
+## Arguments the schema requires
+
+A call that looks complete still fails when one of these is missing. Both come from the MCP's own schema, and both
+answer `Missing key`:
+
+1. **`intent` on every action, input and assertion tool.** The test runner adds it so the recorded step has a name.
+   One short sentence, imperative, about what this call is for: `intent: "open the article preview"`. It belongs on
+   `browser_navigate`, `browser_navigate_back`, `browser_click`, `browser_type`, `browser_fill_form`,
+   `browser_press_key`, `browser_hover`, `browser_drag`, `browser_drop`, `browser_select_option`,
+   `browser_file_upload`, `browser_evaluate`, `browser_run_code_unsafe`, `browser_tabs`, `browser_close`,
+   `browser_resize`, `browser_handle_dialog`, `browser_emulate_media`, and on `browser_wait_for` and every
+   `browser_verify_*`. The read-only tools (`browser_snapshot`, `browser_find`, `browser_take_screenshot`,
+   `browser_console_messages`, `browser_network_requests`, `browser_network_request`, `browser_generate_locator`) take
+   none.
+2. **A field with a default is published as required:**
+   - `browser_take_screenshot` → `scale: "css"` (CSS pixels, the size baselines expect).
+   - `browser_network_requests` → `static: false` (data calls only).
+   - `browser_network_request` → `index` (from the numbered list).
+   - `browser_tabs` → `action` (`"list"`, `"new"`, `"select"` or `"close"`).
+   - `browser_console_messages` → `level` (`"error"` is enough).
+   - `browser_handle_dialog` → `accept` (`true` to accept, `false` to dismiss).
+   - `generator_setup_page` → `project`, `seedFile` and `plan` (`plan: ""` when there is no plan).
+
+## Outlining a target without `browser_highlight`
+
+`browser_highlight` is a one-line wrapper over `locator.highlight()`, and that method is public Playwright API. The
+overlay is the real one, not an approximation, and nothing of the page is changed.
+
+1. Outline (one call, one element, the card's `Identified by` as the locator):
+   ```js
+   // browser_run_code_unsafe({intent: 'outline the target for the reference screenshot', code: ...})
+   async (page) => {
+     const target = page.getByRole('img', {name: '<the Identified by value of the card>'});
+     await target.highlight({style: 'outline: 3px solid #e11d48; outline-offset: 2px'});
+     return await target.toString();
+   }
+   ```
+2. Screenshot the page (not the element) so the reader sees where it sits:
+   `browser_take_screenshot({scale: 'css', filename: '.explore/targets/<case-id>/T<n>-<profile-id>.png'})`
+3. Remove it before the next step: `browser_run_code_unsafe` with `intent: 'remove the highlight overlay'` and
+   `async (page) => { await page.hideHighlight(); }`.
+
+A highlight overlay is not page state: it never appears in a snapshot, it is not part of what the case checks, and
+`page.hideHighlight()` clears all of them. Do this for every candidate when several elements are compared, and say in
+the card what the screenshot shows.
+
+## Network requests without a clear
+
+`browser_network_requests` returns a numbered list that only grows while the page stays open, so a marker works:
+
+1. Before the action: `browser_network_requests({static: false})`, note the highest number in the list (`mark`).
+2. Do the action.
+3. Read `browser_network_requests({static: false})` again and take the entries above `mark`: those, and only those,
+   were started by the action. `browser_network_request({index})` gives one request's detail and status.
+
+Record the marker as a plain note in the report (`after 12 new requests; the data call was 7`), never in the case.

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

@@ -29,7 +29,9 @@ that nobody watches.
    copied with one click.
 3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
    profile). Never ask for login or 2FA. Name everything the user creates `[asrun] <something>`.
-4. Start recording with `browser_start_recording` (see "Recording").
+4. Do not start a recording yourself: the card starts and stops it (see "Recording"). Never call
+   `browser_start_recording` or `browser_stop_recording`: the `playwright-test` MCP lists them but cannot run them
+   (`devtools` tools; see `tools.md`).
 
 ## The wait loop
 Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
@@ -63,8 +65,9 @@ inside the call that runs the card: OpenCode reports a tool call only when it en
 way the web UI can see that a person is needed while the card waits. With the card alone there is no "Your turn"
 badge, no count in the tab title and no notification (a HINT in the job log says so).
 
-1. Set the options on the browser context (this call only sets data):
+1. Set the options on the browser context (this call only sets data; `browser_run_code_unsafe` needs `intent`):
    ```js
+   // browser_run_code_unsafe({intent: 'set the handoff card options', code: ...})
    async (page) => {
      page.context().__handoffCfg = {
        message: '<what the user does, one sentence>',
@@ -77,11 +80,16 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    ```
 2. Run the card and wait: `browser_run_code_unsafe` with `filename` set to the absolute path of
    `<framework>/.claude/skills/exploring-cases/references/handoff-card.js` (use the absolute path of the repository, a
-   relative one is resolved against the workspace root, which may be the parent folder). It returns `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs}`.
+   relative one is resolved against the workspace root, which may be the parent folder) and an `intent` such as
+   `'hand off step 5 to the person'`. It returns
+   `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs, recording, recorded}`: `recorded` holds the
+   actions the person performed, one Playwright line each, across every tab (`page`, `page1`, ...), and is empty when
+   the recording was unavailable (`recording: false`; `recordingError` says why).
 
 Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
-chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. If not, stop and report
-it; do not hand off with a broken card.
+chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. Playwright's own recording
+toolbar at the top of the page is expected and is not part of the card. If the card is not right, stop and report it;
+do not hand off with a broken card.
 
 Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
 Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
@@ -105,17 +113,21 @@ The Done button is always there (also on the minimized card) as the fallback, an
   for two seconds before it is removed, so the user knows when they may let go.
 - `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
   not depend on it.
-- Take a snapshot and write down what the user did (see "Recording"), then continue read-only.
+- Take a snapshot, write down what the user did from the card's `recorded` (see "Recording"), then continue read-only.
 - At the end of the exploration hand off once more when the user created data: "Delete the [asrun] items you
   created, then press Done". The case must clean up after itself, and so must the exploration.
 
 ## Recording
-Between the start and the end of a handoff the agent records what the user does (`browser_start_recording`,
-`browser_stop_recording`). The recorded Playwright code is **raw material, never saved as it is**. It is turned into
-a general recipe and written under the step as `- Recipe (phase): ...` lines (format below). The recipe holds what the
-user did in words, plus the **labels and roles of the controls** they used ("the textbox 'Title'", "the button
-'Next'"), because `/gen-spec` cannot write data and so cannot see those controls itself. It never holds selectors,
-ids or the names of data that can change.
+The card records what the person does: it starts the recording when it shows and stops it on every way out (Done,
+"Cannot do this", the finish condition, the timeout, an error), in the same `browser_run_code_unsafe` call. The agent
+neither starts nor stops it. The result is the card's `recorded`: one Playwright line per action, `page` for the first
+tab that acted and `page1`, `page2`, ... for the others. The aliases follow the order in which actions first appear,
+not the order in which the tabs were opened, so read the actions before you describe tabs.
+
+The recorded Playwright code is **raw material, never saved as it is**. It is turned into a general recipe and written
+under the step as `- Recipe (phase): ...` lines (format below). The recipe holds what the user did in words, plus the
+**labels and roles of the controls** they used ("the textbox 'Title'", "the button 'Next'"), because `/gen-spec` cannot
+write data and so cannot see those controls itself. It never holds selectors, ids or the names of data that can change.
 
 Make the recipe as general as possible, because lists and data change:
 - **A choice from a list that can change** (items, search results, a contact list): record the position, never the
@@ -123,14 +135,31 @@ Make the recipe as general as possible, because lists and data change:
 - **Random is allowed only when the user asks for it** ("pick any 3"). The default is the position, because it can be
   repeated. A random pick must be written into the test's annotations when the spec runs.
 - **Text the case creates**: `[asrun] <something>`.
-- **A value that has to exist** (an existing name, a search term): write what it must be like ("a name that
-  returns a result") and the observed value as `(observed "<value>", 🔍 to be confirmed by QA)` plus a
-  `[non-blocking]` TODO block. Do not put a brittle literal in as the only truth.
+- **A value that has to exist** (an existing name, a search term): the recipe says what it must be like ("a name
+  that returns a result") and notes the observed value as plain text `(seen on <profile>: "<value>")`. Do not put a
+  brittle literal in as the only truth. One claim carries one signal: when a `[non-blocking]` TODO under the recipe
+  asks whether any such value is acceptable, the observed value gets **no** marker (`open-questions.md`, "Marker or
+  question, never both").
 - **Nothing that depends on the pick** may become an assertion (a total changes with the items). Say so in a
   TODO when a check would.
 - Settings that the user changed on purpose (a toggle, a template) are recorded as they were set, by label.
 
-If the recording tool fails or returns nothing, describe what the user did from before/after snapshots instead.
+The recording is raw: merge and prune it before you write the recipe.
+- **The same action can appear twice**, and clicking a checkbox or its label can give both a `click` and a `check`.
+  Write it once ("check 'Agree'").
+- **Side products**: clicking a textbox to focus it, `Cmd+C`, `Scroll`, `Escape`. Keep only actions that change data
+  or the page's state.
+- **The card's own buttons are filtered out** of `recorded`. A click on the card's text (not a button) can still show
+  up; ignore it.
+- **Not recorded at all**: drag and drop, native file pickers, OS dialogs. Describe those from before/after snapshots.
+
+If `recording` is `false` or `recorded` is empty, do not silently write a recipe from snapshots: write a
+`🚫 TODO [blocking]` under the step that says the step was not recorded (and why, from `recordingError` when there is
+one). A recipe from before/after snapshots may be added next to that block only, and must say that it came from
+snapshots, not from a recording.
+
+If Playwright's own recording toolbar shows at the top of the page while the card waits, it is not AsRun's: leave it
+alone.
 
 ## Recipe lines under a step
 One or more `- Recipe (phase): ...` lines directly under the `[input]` or `[writes]` step they belong to, indented by
@@ -139,7 +168,7 @@ keep in sync.
 
 ```
 3. Select an existing document and pick 3 items. [input]
-    - Recipe (start): search for an existing document and pick result #1 (observed search term "...", 🔍 to be confirmed by QA).
+    - Recipe (start): search for an existing document and pick result #1 (seen on example-staging: "quarterly report").
       - ❓ TODO [non-blocking]: Is any result that opens fine as the starting point? (seen on example-staging)
         - ✍️ Answer:
     - Recipe (items): select 3 items by position (#1 to #3) from the list.

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

@@ -8,8 +8,9 @@ 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`). This holds whatever mode or agent the run is in: plan mode changes what you may write,
@@ -36,15 +37,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 +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.
@@ -111,15 +122,19 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    `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`.
+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
@@ -130,16 +145,18 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    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 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,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".
@@ -170,12 +190,16 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
 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),
    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 +221,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;
@@ -228,7 +253,9 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    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 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.
 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 +277,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 +301,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