@asrunjs/asrun 0.9.0 → 0.10.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

package/docs/commands.md

@@ -21,6 +21,7 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | 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 +126,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.

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

@@ -62,14 +62,15 @@ Single, between **Panel**, **Editor** and **Doc**.
 - **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,6 +79,11 @@ 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.
+- **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). **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
@@ -121,6 +127,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 +149,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 +177,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.10.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",
@@ -55,6 +55,7 @@
     "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

@@ -17,6 +17,7 @@
     "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",