@asrunjs/asrun 0.9.0 → 0.11.0

package/docs/cases.md

@@ -31,6 +31,9 @@ suites: [smoke, regression]
 ## Goal
 Why this case exists, in one or two sentences.
 
+## Rules
+- Before step 1: dismiss the cookie banner; it covers the header.
+
 ## Steps
 1. Open `/`.
     - Ready when: the header has rendered its menu.
@@ -63,8 +66,8 @@ example-staging:
 Anything a reviewer should know.
 ````
 
-The headings are fixed English tokens (`Goal`, `Steps`, `Expected`, `Values`, `Visual checks`, `Targets`, `Notes`,
-and `Source` when the case was made from raw notes). A project language never translates them.
+The headings are fixed English tokens (`Goal`, `Rules`, `Steps`, `Expected`, `Values`, `Visual checks`, `Targets`,
+`Notes`, and `Source` when the case was made from raw notes). A project language never translates them.
 
 ## Front matter
 
@@ -80,6 +83,21 @@ and `Source` when the case was made from raw notes). A project language never tr
 
 `priority: <level>` is the old name of `suites`; it is read as `suites: [<level>]`. Do not use both.
 
+## Rules
+
+Optional, case-local instructions for the AI agents that explore, generate and heal this case: **how** to run it, never
+**what it proves**. One bullet per rule. A bullet may start with `Step 3:`, `Before step 3:` or `After step 3:` to tie
+it to that step; `pnpm case:check` fails when the step does not exist. A rule without a prefix applies to the whole case.
+
+- Use it for a page quirk, a mandatory read-only preparation (dismiss a cookie banner), a control to avoid, or a
+  waiting/attention hint.
+- Do not put an expectation, a literal or a target here: those stay in `## Expected`, `## Values` and `## Targets`.
+- A rule never allows creating, changing or deleting data, sending email or doing a person's step. Those stay tagged
+  steps with a recipe.
+- A rule that conflicts with the rest of the case is a blocking question, not an override. `/explore-case` re-checks
+  each rule against the page and never deletes one silently.
+- The framework baseline's `R1`–`R4` define exactly what a rule may say.
+
 ## Steps
 
 Numbered lines. Keep them short and in plain language: the spec uses each step's text verbatim in `test.step`, so the
@@ -97,8 +115,13 @@ report and the trace read like the case.
   generated: `/gen-spec` stops with `needs-input`.
 - **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about,
   with the agent's suggestion written above and a last line `- ✍️ Answer:`. Accepting a question means deleting the
-  whole block; answering means writing after `Answer:`. The marker `🔍 to be confirmed by QA` / `👁️ not observed`
-  marks something seen but not settled.
+  whole block; answering means writing after `Answer:`. Hang the block under the sentence that makes the claim, not
+  under a broader one above it, and one claim gets one block.
+- **What the AI saw** is marked by what happens if it is wrong: `(seen on <profile>)` is a plain note the run checks by
+  itself, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` is a line that would pass even
+  if it were wrong, so a person settles it. A marker may name a screenshot (`evidence: .explore/.../x.png`) so nobody
+  has to open the page again. Never put a marker inside a TODO block, on the sentence a block hangs under, or inside
+  the `## Values` yaml: one claim carries one signal. `pnpm case:check` fails on the first two.
 
 ## Expected
 
@@ -174,6 +197,7 @@ It reads every case (or the ids you pass) and prints one line per case. It **fai
 - a target card without its required fields (`What`, `Where`, `Identified by`), or a reference image outside
   `.explore/targets/<case-id>/`;
 - a `[T<n>]` reference with no card;
+- a `## Rules` bullet that names `Step <n>`, `Before step <n>` or `After step <n>` when the case has no such step;
 - an invalid `## Values` block (bad YAML, an unknown profile, a non-map entry).
 
 It **warns** (usable, but something to settle) on: a reference image missing on this machine (`.explore/` is
@@ -183,7 +207,7 @@ that cannot be answered in place.
 
 ## Rename or move a case
 
-Use the Cases page (click the file name or the pencil icon). The spec and the baseline images move with it and the
-spec is rewritten to match. By hand, move the three things together (`cases/...md`, `tests/...spec.ts`, its
-`*-snapshots/`), and keep the spec's `// case:` line and its imports unchanged: specs import the framework by package
-name, so their folder depth does not change the imports.
+Use the Cases page (open the case, then **Rename or move** in the **⋯** menu at the end of the tab strip). The spec
+and the baseline images move with it and the spec is rewritten to match. By hand, move the three things together
+(`cases/...md`, `tests/...spec.ts`, its `*-snapshots/`), and keep the spec's `// case:` line and its imports
+unchanged: specs import the framework by package name, so their folder depth does not change the imports.

package/docs/commands.md

@@ -18,9 +18,11 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | Run tests | `pnpm asrun --env <env> [filters]` |
 | Open the last report | `pnpm report` |
 | Look around a page as a profile | `pnpm explore <profile-id> [path]` |
+| See or validate what an exploration recorded for a case | `pnpm explore:notes <case-id> [--profile <id>] [--json] [--check]` |
 | Read what the last report says about a case | `pnpm heal:evidence --case <case-id> --env <env>` |
 | List or forget test data that could not be removed | `pnpm cleanup --env <env> [--forget]` |
 | Create or validate a case | `pnpm case:new <id>`, `pnpm case:check [case-id]` |
+| Settle the "to be confirmed" lines of a case from a passing run | `pnpm markers:confirm --case <case-id> --env <env> [--dry-run]` |
 | Check a spec | `pnpm spec:lint [case-id]`, `pnpm baselines:review [case-id] [--new]` |
 | Look at a PDF | `pnpm pdf:render <file.pdf> --out <dir> [--pages all] [--corner top-left]` |
 | Type-check the workspace | `pnpm typecheck` |
@@ -125,7 +127,11 @@ pnpm pdf:render report.pdf --out .explore/targets/header-logo --corner top-left
 ```
 
 - `case:new` creates the case from the template. One optional group folder, created on demand.
-- `case:check` validates front matter, values and target cards; see [cases.md](./cases.md).
+- `case:check` validates front matter, values and target cards; it fails on a marker inside a question block, a marker
+  on the line a question hangs under, and a marker inside the `## Values` yaml. See [cases.md](./cases.md).
+- `markers:confirm` reads the newest run report (or `--report <run-id|file>`) and removes the `🔍 to be confirmed`
+  markers whose line the spec carries as `// unconfirmed: ...`, but only when every test of the case passed. It answers
+  "does the page still say this?", never "is this the right expectation".
 - `spec:lint` is a static check of the specs: it fails on sleeps, `networkidle`, image checks without a target,
   `.first()` on images, raw download events, a magic-number-only PDF check. `pnpm spec:lint <case-id>` limits it.
 - `baselines:review` opens nothing; it lists every baseline next to the target card that says what it must show.
@@ -136,6 +142,9 @@ pnpm pdf:render report.pdf --out .explore/targets/header-logo --corner top-left
 
 ```bash
 pnpm explore example-staging /app/home
+pnpm explore:notes conduit/header-navigation
+pnpm explore:notes conduit/header-navigation --profile example-staging --json
+pnpm explore:notes conduit/header-navigation --check
 pnpm heal:evidence --case header-logo --env staging
 ```
 
@@ -144,6 +153,13 @@ are saved to `~/Downloads` and never overwrite an existing file. `heal:evidence`
 step, error, call log and screenshots for a case, and whether the report is stale; it is what `/heal-spec` reads
 first.
 
+`explore:notes` reads the **exploration note** that `/explore-case` writes for a case under
+`.explore/notes/<case-id>/<profile-id>.json`. It prints one line per profile (fresh or stale, the steps and targets it
+covers) and `--json` prints the parsed notes for a run that reads them. A note is local, git-ignored and optional:
+`/gen-spec` uses a fresh one to verify the locators and request patterns instead of rediscovering them, and replays the
+case when it is missing or stale. `--check` fails on a malformed note and warns about a stale one (it prints the current
+`caseSha256`); `--hash` prints that hash. Deleting `.explore/notes/` is always safe.
+
 ## Cleanup
 
 ```bash

package/docs/theme-guide.html

@@ -330,6 +330,7 @@
     <a href="#icons">Icons</a>
     <a href="#tooltips">Tooltips</a>
     <a href="#editor">Markdown editor</a>
+    <a href="#document-tabs">Document tabs</a>
     <a href="#surfaces">Surfaces</a>
     <a href="#sections">Sidebar sections</a>
     <a href="#checklist">Checklist</a>
@@ -959,6 +960,61 @@ import {FilterChips} from '../components/filter-chips';
       <li><b>Every expand/collapse animates.</b> Use <code>Collapse</code> from <code>components/collapse.tsx</code> (height and fade, 200ms, <code>ease-out</code>) for content that appears and disappears, and rotate the chevron with <code>transition-transform duration-200</code> instead of swapping two icons. Always add <code>motion-reduce:transition-none</code>. Turn transitions off while the user drags a resize handle.</li>
     </ul>
 
+    <h2 id="document-tabs">Document tabs</h2>
+    <p class="muted">
+      A page that holds more than one file of the same thing puts them in a tab strip: <code>DocumentTabs</code> in
+      <code>pages/cases.tsx</code>, where <b>Case</b> is the source a person writes and <b>Spec</b> what a run
+      generated from it. The strip is the only place the file names appear. The bar under it carries the tools of the
+      file on screen (<code>WorkbenchControls</code>, the layout and pane switches), never a second copy of the name,
+      and <b>Save</b> / <b>Discard</b> always sit at the same end of the strip and act on the file on screen.
+    </p>
+    <div class="demo" style="align-items:flex-end;gap:16px;padding:12px 16px 0;background:var(--warm);border-bottom:1px solid var(--line-mid)">
+      <span style="display:flex;align-items:center;gap:8px;margin-bottom:-1px;padding:6px 12px;border-bottom:2px solid var(--theme-btn);border-radius:6px 6px 0 0;background:var(--card);font-size:14px">
+        <span style="font-size:12px;font-weight:500;letter-spacing:.05em;color:var(--theme-ink)">Case</span>
+        <span class="mono">favorite-article.md</span>
+        <span title="Unsaved changes" style="width:6px;height:6px;border-radius:9999px;background:var(--gold-deep)"></span>
+      </span>
+      <span style="display:flex;align-items:center;gap:8px;padding:6px 12px;border-bottom:2px solid transparent;border-radius:6px 6px 0 0;font-size:14px;color:var(--ink-2)">
+        <span style="font-size:12px;font-weight:500;letter-spacing:.05em;color:var(--ink-3)">Spec</span>
+        <span class="mono">favorite-article.spec.ts</span>
+      </span>
+      <span style="display:flex;align-items:center;gap:8px;margin-left:auto;padding-bottom:8px">
+        <span class="btn btn-secondary">Discard</span>
+        <span class="btn btn-primary">Save</span>
+        <span class="btn btn-secondary">...</span>
+      </span>
+    </div>
+    <div class="demo" style="gap:16px;background:var(--card);border-bottom:1px solid var(--line-mid);padding:8px 16px">
+      <span style="display:flex;align-items:center;gap:6px">
+        <span style="font-size:12px;color:var(--ink-3)">Layout</span>
+        <span style="display:flex;overflow:hidden;border-radius:4px;box-shadow:0 0 0 1px var(--line-mid)">
+          <span style="padding:4px 10px;font-size:14px;background:var(--card);color:var(--ink-2)">Split</span>
+          <span style="padding:4px 10px;font-size:14px;background:var(--theme-btn);color:#fff">Single</span>
+        </span>
+      </span>
+      <span style="display:flex;align-items:center;gap:6px">
+        <span style="font-size:12px;color:var(--ink-3)">Pane</span>
+        <span style="display:flex;overflow:hidden;border-radius:4px;box-shadow:0 0 0 1px var(--line-mid)">
+          <span style="padding:4px 10px;font-size:14px;background:var(--theme-btn);color:#fff">Panel</span>
+          <span style="padding:4px 10px;font-size:14px;background:var(--card);color:var(--ink-2)">Editor</span>
+          <span style="padding:4px 10px;font-size:14px;background:var(--card);color:var(--ink-2)">Doc</span>
+        </span>
+      </span>
+    </div>
+    <ul class="tight">
+      <li>The active tab is <code>bg-card</code> with a <code>border-b-2 border-theme-btn</code> underline; the others are
+        <code>text-ink-2</code> on the warm strip. The name is <code>font-mono</code>; the kind in front of it is
+        <code>text-xs tracking-wider</code>, <code>text-theme-ink</code> when active and <code>text-ink-3</code> otherwise.</li>
+      <li>Unsaved changes are a 6px <code>bg-gold-deep</code> dot on the tab, never a badge in the page header. A file
+        that does not exist yet keeps its tab, disabled at 45% opacity, with a tooltip that says how to create it.</li>
+      <li>The switches of the bar under the tabs are a segmented control, not buttons: active <code>bg-theme-btn</code>
+        with white text, the others <code>bg-card</code>, the whole group ringed with <code>ring-1 ring-line-mid</code>, and
+        a <code>text-xs text-ink-3</code> label in front (<code>Layout</code>, <code>Pane</code>). A switch group without a
+        label is not discoverable; never ship one.</li>
+      <li>Switching tabs keeps the other tab's draft, so <b>Save</b> and <b>Discard</b> take the active file; the tab
+        dot is what says another file still has unsaved changes.</li>
+    </ul>
+
     <h2 id="sections">Sidebar sections and selection</h2>
     <div class="row" style="align-items:flex-start">
       <div class="side">

package/docs/troubleshooting.md

@@ -57,6 +57,11 @@ and regenerate the spec.
 `Identified by`), refers to a reference image outside `.explore/targets/<case-id>/`, or a check refers to a `[T<n>]`
 that has no card. A blocking question (`🚫 TODO [blocking]`) is the normal way to wait for a person's answer.
 
+**`pnpm case:check` fails on a marker** — the same claim carries two signals: a marker word inside a question block, a
+marker on the line a question hangs under, or a marker inside the `## Values` yaml (where it would become part of the
+expected value). Keep one of the two, and move a `## Values` marker to the prose line above the block. A marker without
+a reason is only a warning: write `🔍 to be confirmed: <what a person must decide>`.
+
 **`pnpm spec:lint` fails** — read the rule name in the message: `no-sleep` (`waitForTimeout`), `no-networkidle`,
 download handling, a screenshot or image check without `// target: T<n>`, a PDF check on a magic number alone. The
 fixes are in the framework's `generating-specs` conventions; do not silence the rule.
@@ -117,6 +122,41 @@ cases, specs, `profiles.yaml` and `package.json` stay. Then run `pnpm dlx @asrun
 `claude mcp list`; `failed: ... path specified` means the `playwright` path in that file does not resolve (repair it
 with `pnpm asrun init --force <file>`).
 
+**A `browser_*` tool says `Tool "<name>" not found`** — expected for part of them: the `playwright-test` MCP
+(`run-test-mcp-server`) lists every browser tool Playwright has, but a call runs in a paused test whose backend installs
+only the `core` and `testing` capabilities, plus it never installs the `skillOnly` tools. The server is up and the other
+tools work: use the substitute in `.claude/skills/exploring-cases/references/tools.md` and do not report a missing MCP
+server. `browser_highlight` / `browser_hide_highlight` become `locator.highlight()` / `page.hideHighlight()` through
+`browser_run_code_unsafe`, `browser_network_clear` becomes a marker on the request list,
+`browser_start_recording` / `browser_stop_recording` are never called (the handoff card,
+`.claude/skills/exploring-cases/references/handoff-card.js`, starts and stops the recording itself and returns
+`recorded`). `browser_annotate` cannot run either: the person names the element in the handoff card. `pnpm asrun doctor`
+prints how many tools the installed Playwright runs and warns when `tools.md` names one it cannot.
+
+**An AI run stops answering and never finishes** — the log keeps repeating `... still waiting for <tool call> (running
+5m 30s)` or `... no output from the agent for 5m`, and nothing else arrives. A workspace has exactly one
+`playwright-test` MCP server (the `run-test-mcp-server` child process OpenCode starts from `opencode.jsonc`), shared by
+every session in that workspace, and Playwright runs one paused test in it at a time. One interrupted browser call —
+closing the browser window by hand, cancelling a run while a call is in flight, or a second AI run using the same
+server — leaves that queue wedged: the call never returns and every later run hangs on its first
+`generator_setup_page` until the process is replaced. `pnpm asrun doctor` cannot see it, because it starts a fresh
+server of its own. Cancel the stuck run, quit and restart OpenCode (that ends its MCP processes), then start the run
+again. From the UI this is bounded: only one AI run at a time runs per workspace (the `ai` job lock, whatever case it is
+on), and a run that says nothing for 10 minutes — 15 while a handoff card waits for a person — is stopped with this
+instruction in its log.
+
+**The UI server restarted while an AI run was going** — the job is still in the Jobs drawer, marked **Interrupted**,
+and its log stops where the server died. If the agent (and the `playwright-test` MCP server below it) is still running,
+the job offers **Stop the leftover process**; stop it before starting another AI run, or both agents share one MCP
+server and wedge it. A job that had already written `RESULT: needs-input` is recovered as **Succeeded**, so its answers
+can still be sent. Every finished job has **Run again**, which reuses the inputs it was started with.
+
+**A call fails with `Missing key`** — the published schema requires two things that are easy to leave out: `intent` on
+every action, input and assertion tool (`browser_click`, `browser_type`, `browser_evaluate`, `browser_run_code_unsafe`,
+`browser_wait_for`, ...), and the fields that have a default (`browser_take_screenshot` needs `scale: "css"`,
+`browser_network_requests` needs `static: false`, `generator_setup_page` needs `plan`). The full list is in
+`.claude/skills/exploring-cases/references/tools.md`.
+
 **An AI job runs but uses a slow or limited model** — the top bar's **Model** picker sets the model for UI runs;
 without one, a one-shot OpenCode run uses its built-in free model, which has a daily usage limit. Set `"model"` in
 `opencode.jsonc` to stop depending on the browser's choice. For Claude Code, the picker lists what its settings,

package/docs/web-ui.md

@@ -55,21 +55,39 @@ One row per profile, with the same login check as `pnpm status`.
 
 ## Cases
 
-The case list is grouped by folder and collapses. The editor opens in **Single** with the **Panel** full width; the
-toolbar switches to **Split** (source left, one pane right; drag the divider to resize, double-click to reset) or, in
-Single, between **Panel**, **Editor** and **Doc**.
+The case list is grouped by folder and collapses. A case opens on the **Case** tab, with the **Spec** tab beside it:
+
+- **Case** (`favorite-article.md`) is the source a person writes: the steps, values, rules and questions.
+- **Spec** (`favorite-article.spec.ts`) is what a generate or heal run wrote from it. It stays visible but disabled
+  until the case has a spec, and its tooltip says how to make one.
+
+The tab is the page's state: it lives in the URL (`?view=spec`), so a reload, a shared link and the Back button land on
+the same file, and every other link opens the case. Each tab keeps its own unsaved draft while you switch between them;
+an amber dot on a tab means that file has unsaved changes, and **Save** (`Ctrl/Cmd+S`) and **Discard** always sit at the
+right of the tab strip and act on the file on screen.
+
+Under the tabs, the first row is the AI toolbar (command, environment, profiles, attended, **Run AI**, copy the shell
+command, AI guide). It is the same on both tabs, because every AI command acts on the case. The row below holds the
+tools of the file on screen: on **Case** the **Layout** (Split / Single) and **Pane** (Panel / Editor / Doc) switches
+and the previous / next of an outstanding mark; on **Spec** the line that says the file is generated from the case
+(with a link back to it), **Open in editor**, **Copy path** and copy the spec. **Rename or move** and **Delete** live
+in the **⋯** menu at the end of the tab strip.
+
+The editor opens in **Single** with the **Panel** full width; **Split** puts the source on the left and one pane on the
+right (drag the divider to resize, double-click to reset).
 
 - **Source and preview** scroll together, the preview block at the caret is shaded, and a click in the preview puts
   the caret on that line. `Ctrl/Cmd+S` saves.
 - **What needs a person is highlighted** in both: `TODO` in any spelling (red for `🚫 TODO [blocking]`, gold
-  otherwise), `🔍 to be confirmed by QA` / `👁️ not observed` / `TBC` / `TBD` in blue, and your `✍️ Answer:` lines in
+  otherwise), `🔍 to be confirmed` / `👁️ not observed` / `TBC` / `TBD` in blue, and your `✍️ Answer:` lines in
   green. Hover for a tooltip; the small X after a marker removes it (or the whole question block for a `TODO`) in one
   step, with Undo; the file is saved when you save it.
 - **New case** takes an optional folder and runs `pnpm case:new`.
 - **The Panel** shows the case as a form, with the open questions first (accept one to delete the question, or write an
   answer and the AI folds it in). Then the front matter (title, login, suites, writes and its note, environments), the
-  steps (sentence, `[writes]` / `[input]` / `[email]` tags, `- Ready when:` lines, `- Recipe:` lines), the
-  `## Expected` and `## Visual checks` bullets (drag to reorder), the `## Values` table (one column per profile; an
+  `## Rules` bullets, the steps (sentence, `[writes]` / `[input]` / `[email]` tags, `- Ready when:` lines,
+  `- Recipe:` lines), the `## Expected` and `## Visual checks` bullets (drag to reorder), the `## Values` table (one
+  column per profile; an
   empty cell inherits `default`), and the `## Targets` cards read-only, with what each is missing. With two or more
   profiles the Values section offers a **Rows: Keys / Profiles** switch, and from four profiles on it also adds a
   search and environment chips. With more profiles than keys it starts as one row per profile, so every name and
@@ -78,15 +96,24 @@ Single, between **Panel**, **Editor** and **Doc**.
   the card: what it is, where, how it is identified, what it must not be, and its reference screenshots. Every section
   collapses and has a **?** with a short help card. Panel edits land in the same draft as the source editor, so one
   save covers both, and **Discard** throws them away together.
-- **Spec view** is editable too (`Ctrl/Cmd+S`; refused when the file changed on disk meanwhile). **Open in editor**
-  opens it in the default application for `.spec.ts`, **Copy path** copies its absolute path.
-- Click the file name (or the pencil icon) to **rename** or move the case: the spec and the baselines move with it and
-  the spec is rewritten. **Delete** (type the id, or fill it in with the feather icon) removes the case, its spec and
-  its baselines; both dialogs list exactly what they touch, and are refused while an AI or test run is in progress.
-- **Toolbar:** command (explore / generate / heal, explore by default), **Environment** (required, no default),
+- **The To confirm section** lists every line the AI marked: the sentence, where it is (`## Values · line 42`), **why it
+  needs you** (the reason the AI wrote after the marker's colon), **what it feeds** (an assertion or only a note) and,
+  when it saved one, the **screenshot** from the exploration, so you look at the image instead of opening the page
+  again. Rows that change an assertion are highlighted; **Confirm** settles one line and **Confirm all** settles the
+  list in one undo step. None of this blocks generating a spec; healing stops until the case is settled.
+- **Spec view** is editable too (`Ctrl/Cmd+S`; refused when the file changed on disk meanwhile), and its tab links back
+  to the case it was generated from. **Open in editor** opens it in the default application for `.spec.ts`, **Copy
+  path** copies its absolute path.
+- **Rename or move** (in the **⋯** menu) keeps the spec and the baselines with the case and rewrites the spec;
+  **Delete** (type the id, or fill it in with the feather icon) removes the case, its spec and its baselines. Both
+  dialogs list exactly what they touch, and are refused while an AI or test run is in progress or while a draft is
+  unsaved.
+- **AI toolbar:** command (explore / generate / heal, explore by default), **Environment** (required, no default),
   **Profiles** (explore only: every profile that is logged in is ticked, the choice is remembered per environment, and
   only the ticked ones are opened), **Attended** (only for explore, ticked by default), **Run AI**, copy the shell
   command, open the AI guide.
+- **Writes in …** is one line under the toolbar, in red: the environments whose data the case writes, then its note,
+  with the full note in its tooltip. A case that only runs in some environments shows that line instead.
 - **From memo** opens a Markdown editor with a preview for raw notes. **Make cases** saves them to `.tmp/memos/` and
   runs `/make-case` one-shot (defaults for gaps, `TODO` for unknown values, no page exploration, existing cases never
   overwritten); **Copy /make-case** copies the memo for the interactive dialogue. When the run ends, **What to do
@@ -121,6 +148,21 @@ One entry per run, with a PRODUCTION or STAGING badge (runs from before environm
 The bottom bar shows every command started from the UI with live stdout/stderr and the exit code; a job can be
 cancelled there. Opening it shrinks the page instead of covering it.
 
+- Jobs are recorded under `.tmp/ui-jobs/<id>/` (`record.json`, `chunks.jsonl`, `output.log`), kept for 7 days and the
+  newest 50. A UI server restart does not forget them. A job that was running is shown as **Interrupted**: its output
+  stops at the last line the server received (the UI replays the last 4 MB of structured output; `output.log` keeps the
+  whole text). If its process is still alive, the page offers **Stop the leftover process** (the agent, its browser and
+  its MCP server), and a new AI run or test run is refused until it is stopped: one agent per workspace, as above. A
+  job that had already written `RESULT: needs-input` is recovered as **Succeeded**, so its answers can still be sent.
+- **Run again** starts a finished job with the inputs it was started with. A heal keeps its hints, model, profiles and
+  report, so nothing has to be typed again. It is a new job with a new conversation and report; write cases, baseline
+  overwrites and an existing spec are confirmed again.
+
+- Only one AI job runs at a time per workspace: `/explore-case`, `/gen-spec` and `/heal-spec` all drive the workspace's
+  single `playwright-test` MCP server, and two at once wedge it. Starting a second one is refused with the name of the
+  job it clashes with. A run that says nothing for 10 minutes — 15 while a handoff card waits for a person — is stopped
+  and its log says why; see [troubleshooting](./troubleshooting.md#ai-steps).
+
 - An AI job's log is structured: a timestamp, one line per tool call (name, what it touched, how long it took), the
   first lines of what it returned with the colors the command printed, the agent's thinking dimmed while **Thinking**
   is ticked, and its messages rendered as Markdown. Long output is a preview with a count. The same text is kept in
@@ -128,8 +170,10 @@ cancelled there. Opening it shrinks the page instead of covering it.
 - When an AI job ends, a thin **What to do next** bar appears under the log (or **Details** opens it in a sheet):
   open questions with an answer box and **Use the suggested defaults**, the confirmations the exploration marked, and
   the next action (**Generate spec**, **Open Run tests**, **View spec**, **Re-explore**). A run that ends with
-  `needs-input` gets an amber *Needs your input* badge; sending answers continues the same conversation, once per turn
-  and only while the UI server has not restarted. After a restart, answer in the case file and run the command again.
+  `needs-input` gets an amber *Needs your input* badge; sending answers continues the same conversation, once per turn.
+  The record survives a UI server restart, so a run that had already written its questions can still be answered and a
+  finished job can be started again with **Run again**; after a restart, a job that did not get that far is answered in
+  the case file and run again.
 - A run that ends without its `RESULT:` line gets an amber *No result* badge and a banner under the command instead of
   a "what to do next" bar: nothing is known about what it did, so read the log before trusting the case or the spec.
   A run that is not allowed to write files (plan mode, a read-only sandbox) ends that way; the framework starts
@@ -154,7 +198,7 @@ cancelled there. Opening it shrinks the page instead of covering it.
 
 | Path | What |
 |---|---|
-| `.tmp/ui-jobs/` | the log of every job started from the UI (git-ignored) |
+| `.tmp/ui-jobs/` | the record, chunks and log of every job started from the UI (git-ignored); 7 days, newest 50 |
 | `.tmp/hints/` | the text you type in the Heal dialog, passed to the agent as `--hints` |
 | `.explore/` | reference screenshots of the target cards (git-ignored) |
 | `reports/` | one folder per run, `reports/latest` points at the newest |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asrunjs/asrun",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Multi-profile end-to-end test suite: plain-language cases, AI-written Playwright specs, evidence for every run.",
   "license": "UNLICENSED",
   "author": "Zoro Chen",
@@ -52,9 +52,11 @@
     "report": "tsx scripts/report.ts",
     "heal:evidence": "node scripts/heal-evidence.mjs",
     "explore": "tsx scripts/explore.ts",
+    "explore:notes": "tsx scripts/explore-notes.ts",
     "cleanup": "tsx scripts/cleanup.ts",
     "case:new": "tsx scripts/new-case.ts",
     "case:check": "tsx scripts/check-cases.ts",
+    "markers:confirm": "tsx scripts/markers-confirm.ts",
     "spec:lint": "tsx scripts/lint-specs.ts",
     "baselines:review": "tsx scripts/review-baselines.ts",
     "pdf:render": "tsx scripts/render-pdf.ts",

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

@@ -6,9 +6,9 @@ Load the framework skill `{{framework}}/.claude/skills/exploring-cases/SKILL.md`
 
 Rules combine in this order, and a later one wins where they conflict: the framework baseline
 `{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/exploring-cases.md` if it exists, then the workspace
-`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+`AGENTS.md` §2 (Project rules). F1–F6 and R2 always win. Project facts are in `AGENTS.md` §3.
 
-Arguments: `<case-id> <env> [--attended] [--profiles a,b]`. The case id is the path below `cases/` without `.md` (it may include a
+Arguments: `<case-id> <env> [--attended] [--profiles a,b] [--hints <file>]`. The case id is the path below `cases/` without `.md` (it may include a
 group folder, e.g. `documents/landing-page`) and is required. `<env>` is `staging` or `production`; it is required and there
 is no default (without one, stop and say so). With `--attended` I am at the machine and the browser window is
 visible: when a step writes data or needs a choice, hand it to me as the skill describes, wait for me, and record
@@ -16,12 +16,17 @@ what I did as a general recipe under the step it belongs to (`- Recipe:` lines).
 `--profiles a,b` explores only those profiles (comma-separated ids from `profiles.yaml`); without it, at least one
 logged-in profile per domain. A profile the list leaves out is not opened and nothing is written about it: runs add up,
 so a later run covers the rest.
+`--hints <file>` (or free text after the arguments) is what I know or want checked; read it first. After the work, a
+reusable instruction goes into `## Rules` by the gate in
+`{{framework}}/.claude/skills/exploring-cases/references/case-rules.md`; a one-off clue stays in the report.
 
-Follow `{{framework}}/.claude/skills/exploring-cases/references/assertion-targets.md` (list the candidates, never
+Read `## Rules` before the steps and apply it. Follow
+`{{framework}}/.claude/skills/exploring-cases/references/case-rules.md` (a rule says how to run the case, never what it
+proves; never delete or rewrite one), `assertion-targets.md` (list the candidates, never
 pick when in doubt, ask for the exact image/text/place/UI) and `readiness.md` (wait for the key requests and the
 content before you read anything) of the skill.
 
 This command edits `cases/<case-id>.md` only (plus screenshots under `.explore/targets/`). Do not ask me questions in
-the chat: write open questions into the case file as the skill describes, and end with the `RESULT:` line. If you are
-not allowed to write files at all (a plan-mode run, a read-only sandbox), say what blocked you and end with
-`RESULT: needs-input`.
+the chat: write open questions into the case file as the skill describes, and end with the `RESULT:` line as plain text
+on the last line, never in a code fence or in emphasis. If you are not allowed to write files at all (a plan-mode run,
+a read-only sandbox), say what blocked you and end with `RESULT: needs-input`.

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

@@ -7,18 +7,23 @@ $ARGUMENTS
 
 Rules combine in this order, and a later one wins where they conflict: the framework baseline
 `{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace
-`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+`AGENTS.md` §2 (Project rules). F1–F6 and R2 always win. Project facts are in `AGENTS.md` §3.
 
-Arguments: `<case-id> [<env>] [--force]`. The case file is `cases/<case-id>.md` (the id may include one group folder,
+Arguments: `<case-id> [<env>] [--force] [--hints <file>]`. The case file is `cases/<case-id>.md` (the id may include one group folder,
 e.g. `documents/landing-page`). `<env>` is the environment to explore in (`staging` or `production`); there is no default. If
 the spec already exists, it is left alone unless `--force` is given; with `--force` it is regenerated and overwritten.
+`--hints <file>` (or free text after the arguments) is what I know or want changed; read it first. A reusable
+instruction goes into `## Rules` by the gate in
+`{{framework}}/.claude/skills/exploring-cases/references/case-rules.md`; a one-off clue stays in the report.
 There is no profile option: the spec is generated for every profile the case holds information for (its `## Values`
 keys, its target cards and its observations), not for a chosen subset and not only for the profiles that are logged in.
 
-Follow the skill's procedure exactly, including its `assertion-targets.md` and `readiness.md`; run
+Follow the skill's procedure exactly, including `case-rules.md` (read `## Rules` before the steps; a rule says how to
+run the case, never what it proves), its `assertion-targets.md` and `readiness.md`; run
 `pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
 process), and do not create baselines.
 
 Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for
-QA, write the remaining questions into the case file), and end with the `RESULT:` line. If you are not allowed to write
-files at all (a plan-mode run, a read-only sandbox), say what blocked you and end with `RESULT: needs-input`.
+QA, write the remaining questions into the case file), and end with the `RESULT:` line as plain text on the last line,
+never in a code fence or in emphasis. If you are not allowed to write files at all (a plan-mode run, a read-only
+sandbox), say what blocked you and end with `RESULT: needs-input`.

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

@@ -7,7 +7,7 @@ spec", and follow it exactly.
 
 Rules combine in this order, and a later one wins where they conflict: the framework baseline
 `{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace
-`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+`AGENTS.md` §2 (Project rules). F1–F6 and R2 always win. Project facts are in `AGENTS.md` §3.
 
 Arguments: $ARGUMENTS
 Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`, with optional free text after them.
@@ -16,23 +16,27 @@ Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`,
 - `--profiles`: the profiles to run when evidence is needed. Without it, every profile that is logged in in `<env>`.
 - `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
 - `--hints <file>`: a file with what the user wants repaired or improved, with any evidence. Read it first. Any free
-  text after the arguments is the same kind of request. Both are optional.
+  text after the arguments is the same kind of request. Both are optional. Read `## Rules` before the steps and apply
+  it; after the work, a reusable method instruction goes into `## Rules` by the gate in
+  `{{framework}}/.claude/skills/exploring-cases/references/case-rules.md`, while a one-off clue stays in the report.
 
 A passing run is not a reason to refuse a request: healing also refines a case and its spec. Never lower the bar for a
 product finding to make a test pass.
 
 Do not ask me questions in the chat: this may run unattended. Resolve what the report, the case and the page can
-resolve, and write what still needs a person into the case as a `[blocking]` question. End with the `RESULT:` line:
-`ready` when the healing or the refinement is finished, `needs-input` when something is still open. If you could not
-write files at all (a plan-mode run, a read-only sandbox, a refused permission), say in one sentence what blocked you
-and end with `RESULT: needs-input`: never answer with a plan and a question instead.
+resolve, and write what still needs a person into the case as a `[blocking]` question. End with the `RESULT:` line as
+plain text on the last line, never in a code fence or in emphasis: `ready` when the healing or the refinement is
+finished, `needs-input` when something is still open. If you could not write files at all (a plan-mode run, a read-only
+sandbox, a refused permission), say in one sentence what blocked you and end with `RESULT: needs-input`: never answer
+with a plan and a question instead.
 
 Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see step 5
 of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
 Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when
 the skill says it is needed. Always run with `--logged-in`. If the change leaves an open question or an unconfirmed
 marker in the case, stop there, tell me to review the case and run `/explore-case`, and end with
-`RESULT: needs-input`. Otherwise tell me whether it is a test problem or a product finding.
+`RESULT: needs-input`. A marker inside `## Rules` does not stop the spec unless the rule covers a literal the spec
+asserts. Otherwise tell me whether it is a test problem or a product finding.
 
 Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and
 `pnpm status ...` as plain commands, optionally piped to `tail` or `head`, and do not chain other commands with them

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

@@ -7,7 +7,7 @@ documents: $ARGUMENTS
 
 Rules combine in this order, and a later one wins where they conflict: the framework baseline
 `{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/making-cases.md` if it exists, then the workspace
-`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+`AGENTS.md` §2 (Project rules). F1–F6 and R2 always win. Project facts are in `AGENTS.md` §3.
 
 The input is either text or a path to a file with the notes. Follow the skill's procedure exactly. Ask me the open
 questions before writing any case file. Do not generate specs; that is `/gen-spec`.

package/templates/AGENTS.md

@@ -9,11 +9,13 @@ Read this file and the framework baseline it points at, before any AI step.
 
 Rules are applied in this order, and a later layer wins where they conflict (the framework baseline, "Precedence"):
 
-1. `F1`–`F6` of the framework baseline: safety, in every project. Nothing here can change them.
+1. `F1`–`F6` and `R2` of the framework baseline: safety, in every project. Nothing here can change them.
 2. The framework baseline, `{{framework}}/AGENTS.md`.
 3. The framework skill (`{{framework}}/.claude/skills/<skill>/SKILL.md`).
 4. A project skill override, `.claude/skills/<skill>.md` (optional; the command and the skill read it).
 5. This file, §2 below: what this project does differently.
+6. A case's `## Rules`: how to run that one case, never what is true. It is below §2 and cannot weaken `F1`–`F6` or
+   `R2`.
 
 The framework skills are loaded by the commands in `.claude/commands/` (Claude Code) and `.opencode/commands/`
 (OpenCode). The skills live in the framework package; §3 holds this project's facts.
@@ -21,8 +23,8 @@ The framework skills are loaded by the commands in `.claude/commands/` (Claude C
 ## 2. Project rules
 
 Only what differs from the baseline: name the rule id, and whether it `narrows` (stricter) or `replaces` (a different
-default, for example the artifact language) the baseline rule. `replaces` is refused for `F1`–`F6`. Rows whose first
-cell is not a rule id are ignored, so the placeholder below can stay until you need it.
+default, for example the artifact language) the baseline rule. `replaces` is refused for `F1`–`F6` and `R2`. Rows
+whose first cell is not a rule id are ignored, so the placeholder below can stay until you need it.
 
 | Rule | Project rule | Effect |
 |---|---|---|
@@ -39,9 +41,10 @@ Examples (delete what you do not use; the fenced block is an example, not a rule
 `pnpm asrun doctor` fails when this table names a `[non-negotiable]` rule, an unknown rule id, or an `Effect` that is
 not `narrows` or `replaces`.
 
-The structural tokens are fixed English whatever the project language: the section headings (`## Values`, `## Targets`,
-...), a step's `- Recipe (phase): ...` lines, `### T<n>`, the `TODO` blocks with their `Answer:` line,
-`[input]`/`[writes]`/`[email]`, `RESULT:`, and the front-matter keys. See "Fixed tokens" in the framework baseline.
+The structural tokens are fixed English whatever the project language: the section headings (`## Values`, `## Rules`,
+`## Targets`, ...), a step's `- Recipe (phase): ...` lines, `### T<n>`, the `TODO` blocks with their `Answer:` line,
+`[input]`/`[writes]`/`[email]`, `RESULT:` (plain text on the last line, never inside a code fence or in emphasis),
+and the front-matter keys. See "Fixed tokens" in the framework baseline.
 
 ## 3. Project facts
 

package/templates/cases/_template.md

@@ -11,6 +11,13 @@ suites: [smoke, regression]   # a case may be in several suites; filter with `pn
 ## Goal
 Why this case exists, in one or two sentences.
 
+## Rules
+Optional instructions for the AI on how to run this case (a page quirk, a mandatory read-only preparation, a control
+to avoid). They never state what the case expects and never allow writing data or acting for a person. One bullet per
+rule; a bullet may start with `Step 3:`, `Before step 3:` or `After step 3:`. Delete this paragraph when the case needs
+none.
+- <e.g. Before step 1: dismiss the cookie banner; it covers the header.>
+
 ## Steps
 1. Open <page or path, e.g. /account/>.
     - Ready when: <the one positive signal that what this step loads is really there, e.g. the list shows its first

package/templates/package.json

@@ -14,9 +14,11 @@
     "report": "asrun report",
     "heal:evidence": "asrun heal:evidence",
     "explore": "asrun explore",
+    "explore:notes": "asrun explore:notes",
     "cleanup": "asrun cleanup",
     "case:new": "asrun case:new",
     "case:check": "asrun case:check",
+    "markers:confirm": "asrun markers:confirm",
     "spec:lint": "asrun spec:lint",
     "baselines:review": "asrun baselines:review",
     "pdf:render": "asrun pdf:render",