@asrunjs/asrun 0.9.0 → 0.10.0

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

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

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

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

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

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

package/AGENTS.md

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

package/README.md

@@ -133,12 +133,13 @@ It is read after the framework skill and before your project rules. Write only w
 
 Rules combine in this order, and a later layer wins where they conflict:
 
-1. `F1`–`F6` of the framework baseline (safety, in every project). They cannot be changed.
+1. `F1`–`F6` and `R2` of the framework baseline (safety, in every project). They cannot be changed.
 2. The framework baseline, `node_modules/@asrunjs/asrun/AGENTS.md`.
 3. The framework skill.
 4. Your override, `.claude/skills/<skill>.md`.
-5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`) with `narrows` or `replaces`, for example the artifact
-   language.
+5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`, `R1`, `R3`, `R4`) with `narrows` or `replaces`, for example
+   the artifact language.
+6. A case's `## Rules`: how to run that one case, never what is true.
 
 `pnpm asrun doctor` validates the table and lists the overrides it sees. An update never rewrites your rules:
 `init --force` refuses `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` without `--reset-rules`. Never edit the

package/bin/asrun.mjs

@@ -26,6 +26,7 @@ const SCRIPTS = {
   cleanup: 'cleanup.js',
   'case:new': 'new-case.js',
   'case:check': 'check-cases.js',
+  'markers:confirm': 'markers-confirm.js',
   'spec:lint': 'lint-specs.js',
   'baselines:review': 'review-baselines.js',
   'pdf:render': 'render-pdf.js',

package/dist/lib/case-doc.d.ts

@@ -183,7 +183,7 @@ export interface CaseQuestion {
     region: TextRange;
 }
 export type MarkerKind = 'confirm' | 'unseen';
-/** `🔍 to be confirmed by QA` and `👁️ not observed`: markers of what was seen but not checked by a person. */
+/** `🔍 to be confirmed` and `👁️ not observed`: markers of what was seen but not checked by a person. */
 export interface CaseMarker {
     kind: MarkerKind;
     /** The marker as written, including its emoji. */
@@ -193,6 +193,21 @@ export interface CaseMarker {
     sentence: string;
     section: string;
     line: number;
+    /**
+     * What a person has to decide, written after the marker's colon inside the same parentheses
+     * (`🔍 to be confirmed: is this the label users see?`). Null in the old form, which only says "shown by QA".
+     */
+    detail: string | null;
+    /** A screenshot a person can look at instead of opening the page again: a `.explore/` image path. */
+    evidence: string | null;
+    /** The marker plus its `: <reason>` and `evidence: <path>` parts: what deleting the marker removes. */
+    removeRange: TextRange;
+}
+/** What a marked line feeds: an assertion, the wording of a step, a method rule, or only context. */
+export interface CaseMarkerFeed {
+    kind: 'assertion' | 'step' | 'rule' | 'note';
+    /** Short text for the panel, e.g. `## Expected` or `a step (the run checks it)`. */
+    label: string;
 }
 export type CaseValues = Record<string, Record<string, unknown>>;
 export interface CaseValuesBlock {
@@ -225,6 +240,12 @@ export interface CaseDocument {
     frontMatter: CaseFrontMatter | null;
     sections: CaseSection[];
     steps: CaseStep[];
+    /**
+     * The top-level bullets of `## Rules`: case-local instructions on *how* to run the case (a page quirk, a mandatory
+     * read-only preparation, a control to avoid). They never define what is true: that stays in Steps, Expected, Values
+     * and Targets (framework baseline `R1`).
+     */
+    rules: CaseBullet[];
     questions: CaseQuestion[];
     markers: CaseMarker[];
     values: CaseValuesBlock | null;
@@ -243,6 +264,18 @@ export declare function endWithBreak(text: string, end: number): number;
 export declare const afterLine: (text: string, line: CaseLine) => number;
 /** The front matter block: its parsed data plus the range of every key, so the panel can edit one key at a time. */
 export declare function parseCaseFrontMatter(text: string): CaseFrontMatter | null;
+/**
+ * What a marked line feeds. Only the first two kinds can be wrong and still pass: an assertion, and the wording of an
+ * expectation. A step, a rule and a note are checked by the run itself, so a person does not have to re-read them.
+ */
+export declare function markerFeed(doc: CaseDocument, marker: CaseMarker): CaseMarkerFeed;
+/** How many markers of a case feed an assertion, i.e. how many are worth a person's attention. */
+export declare function assertionMarkerCount(doc: CaseDocument): number;
+/**
+ * The line a marker sits on, without the marker, its reason and its evidence: the sentence a person actually reads.
+ * The `(observed on ...)` part stays, because where it was seen is the context they need.
+ */
+export declare function markerSentence(text: string, marker: CaseMarker): string;
 /** A prose section (`## Goal`, `## Notes`): the panel renders it read-only and reveals a line on click. */
 export declare function parseProse(text: string, name: string): CaseProse | null;
 /** The top-level bullets of a list section, with the blocks (a wrapped text, a TODO block) that belong to each. */
@@ -263,11 +296,15 @@ export declare function setQuestionAnswer(text: string, question: CaseQuestion,
 /** Accepts the suggestion: deletes the whole question block, the answer line included. */
 export declare function acceptQuestion(text: string, question: CaseQuestion): string;
 /**
- * Removes a `🔍 to be confirmed by QA` / `👁️ not observed` marker. When the marker is the only content of its
- * parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
- * `(observed, 🔍 to be confirmed by QA)` as `(observed)`.
+ * What deleting a `🔍 to be confirmed` / `👁️ not observed` marker removes. When the marker is the only content
+ * of its parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
+ * `(observed, 🔍 to be confirmed)` as `(observed)`.
  */
+export declare function markerEdits(text: string, marker: CaseMarker): TextEdit;
+/** Removes one marker, its punctuation and, when it was alone, its parentheses. */
 export declare function removeMarker(text: string, marker: CaseMarker): string;
+/** Removes several markers in one edit, so the panel can confirm a whole list with one undo step. */
+export declare function removeMarkers(text: string, markers: CaseMarker[]): string;
 /** Sets one value of one profile; `null` removes it (an empty cell in the panel means "not set here"). */
 export declare function setCaseValue(text: string, profile: string, key: string, value: string | null): string;
 /** Adds a key to the `default` values of the case. */

package/dist/lib/case-doc.js

@@ -465,8 +465,41 @@ function parseQuestions(text, sections) {
 }
 /* Kept in step with `ui/web/src/lib/highlight-keywords.ts` (same words, same emoji prefixes). */
 const MARKER_RE = /(?:\u{1F50D}\uFE0F?[ \t]*)?(?:\bto be confirmed(?:\s+by\s+QA)?\b|\bTBC\b|\bTBD\b|\bneeds?\s+confirmation\b)|(?:\u{1F441}\uFE0F?[ \t]*)?\bnot observed\b/giu;
-function parseMarkers(text, sections) {
+/** A screenshot named in the same parentheses as a marker: the evidence a person looks at instead of the page. */
+const MARKER_EVIDENCE_RE = /\bevidence:[ \t]*([^\s;)]+\.(?:png|jpe?g|webp))/i;
+/**
+ * What the parentheses around a marker say beyond the marker itself: the one thing a person has to decide (`: ...`)
+ * and the evidence image (`evidence: <path>`). Both are optional, so the old `(observed, 🔍 to be confirmed by QA)`
+ * still reads; it just says less. `removeEnd` runs to the end of the reason and the evidence, so deleting the marker
+ * leaves the observation alone.
+ */
+function markerParts(text, start, end) {
+    const open = text.lastIndexOf('(', start);
+    const close = text.indexOf(')', end);
+    if (open < 0 || close < 0 || close < end || /[\r\n]/.test(text.slice(open, close))) {
+        return { detail: null, evidence: null, removeEnd: end };
+    }
+    const inside = text.slice(open + 1, close);
+    const evidenceMatch = MARKER_EVIDENCE_RE.exec(inside);
+    const evidence = evidenceMatch?.[1] ?? null;
+    const tail = text.slice(end, close);
+    const colon = /^[ \t]*:[ \t]*/.exec(tail);
+    const raw = colon ? tail.slice(colon[0].length) : '';
+    const detail = colon ? raw.replace(/[;,][ \t]*evidence:[\s\S]*$/i, '').trim() : '';
+    const removeEnd = evidenceMatch
+        ? open + 1 + evidenceMatch.index + evidenceMatch[0].length
+        : colon
+            ? end + colon[0].length + raw.trimEnd().length
+            : end;
+    return { detail: detail === '' ? null : detail, evidence, removeEnd };
+}
+/**
+ * Markers of `text`. A marker written inside a question block is not one: the question already says that a person has
+ * to decide, and counting it twice would put the same claim in "Open questions" and "To confirm".
+ */
+function parseMarkers(text, sections, questions) {
     const markers = [];
+    const blocks = questions.map((question) => question.blockRange);
     let fenced = false;
     for (const line of splitLines(text)) {
         if (isFence(line.text)) {
@@ -478,18 +511,59 @@ function parseMarkers(text, sections) {
         for (const match of line.text.matchAll(MARKER_RE)) {
             if (match[0] === '')
                 continue;
+            const start = line.start + (match.index ?? 0);
+            const end = start + match[0].length;
+            if (blocks.some((block) => start >= block.start && start <= block.end))
+                continue;
+            const parts = markerParts(text, start, end);
             markers.push({
                 kind: /not observed/i.test(match[0]) ? 'unseen' : 'confirm',
                 text: match[0],
-                range: { start: line.start + (match.index ?? 0), end: line.start + (match.index ?? 0) + match[0].length },
+                range: { start, end },
+                removeRange: { start, end: parts.removeEnd },
                 sentence: line.text.trim(),
                 section: sectionAt(sections, line.start),
                 line: line.number,
+                detail: parts.detail,
+                evidence: parts.evidence,
             });
         }
     }
     return markers;
 }
+/**
+ * What a marked line feeds. Only the first two kinds can be wrong and still pass: an assertion, and the wording of an
+ * expectation. A step, a rule and a note are checked by the run itself, so a person does not have to re-read them.
+ */
+export function markerFeed(doc, marker) {
+    if (marker.section === 'Values' || marker.section === 'Expected' || marker.section === 'Visual checks') {
+        return { kind: 'assertion', label: `## ${marker.section}` };
+    }
+    if (marker.section === 'Steps')
+        return { kind: 'step', label: 'a step (the run checks it)' };
+    if (marker.section === 'Rules')
+        return { kind: 'rule', label: 'a method rule (never an assertion)' };
+    return { kind: 'note', label: marker.section === '' ? 'the case' : `## ${marker.section}` };
+}
+/** How many markers of a case feed an assertion, i.e. how many are worth a person's attention. */
+export function assertionMarkerCount(doc) {
+    return doc.markers.filter((marker) => markerFeed(doc, marker).kind === 'assertion').length;
+}
+/**
+ * The line a marker sits on, without the marker, its reason and its evidence: the sentence a person actually reads.
+ * The `(observed on ...)` part stays, because where it was seen is the context they need.
+ */
+export function markerSentence(text, marker) {
+    const lineStart = text.lastIndexOf('\n', marker.range.start) + 1;
+    const lineBreak = text.indexOf('\n', marker.range.start);
+    const lineEnd = lineBreak === -1 ? text.length : lineBreak;
+    return (text.slice(lineStart, marker.range.start) + text.slice(marker.removeRange.end, lineEnd))
+        .replace(/^[ \t]*(?:[-*+]|\d+\.)[ \t]+/, '')
+        .replace(/[,;][ \t]*\)/g, ')')
+        .replace(/\([ \t]*\)/g, '')
+        .replace(/[ \t]{2,}/g, ' ')
+        .trim();
+}
 const VALUES_OPEN_RE = /^[ \t]*```ya?ml[ \t]*$/i;
 const VALUES_CLOSE_RE = /^[ \t]*```[ \t]*$/;
 const isPlaceholderValue = (value) => value === null || value === undefined || value === '' || (typeof value === 'string' && /^\s*TODO\b/i.test(value));
@@ -801,13 +875,16 @@ export function caseMetaProblems(id, data, knownEnvs, label = 'case document') {
 export function parseCaseDocument(text) {
     const lines = splitLines(text);
     const sections = sectionsOf(text, lines);
+    // Questions first: a marker written inside one belongs to that question, not to "To confirm".
+    const questions = parseQuestions(text, sections);
     return {
         text,
         frontMatter: parseCaseFrontMatter(text),
         sections,
         steps: parseSteps(text, sections.find((section) => section.name === 'Steps')),
-        questions: parseQuestions(text, sections),
-        markers: parseMarkers(text, sections),
+        rules: parseBullets(text, 'Rules'),
+        questions,
+        markers: parseMarkers(text, sections, questions),
         values: parseValues(text, sections.find((section) => section.name === 'Values')),
         targets: parseTargetCards(text),
         inputs: parseInputs(text, sections.find((section) => section.name === 'Inputs')),
@@ -877,27 +954,42 @@ export function acceptQuestion(text, question) {
     return patchText(text, [{ start: question.blockRange.start, end: endWithBreak(text, question.blockRange.end), text: '' }]);
 }
 /**
- * Removes a `🔍 to be confirmed by QA` / `👁️ not observed` marker. When the marker is the only content of its
- * parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
- * `(observed, 🔍 to be confirmed by QA)` as `(observed)`.
+ * What deleting a `🔍 to be confirmed` / `👁️ not observed` marker removes. When the marker is the only content
+ * of its parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
+ * `(observed, 🔍 to be confirmed)` as `(observed)`.
  */
-export function removeMarker(text, marker) {
-    const open = text.lastIndexOf('(', marker.range.start);
-    const close = text.indexOf(')', marker.range.end);
+export function markerEdits(text, marker) {
+    const start = marker.range.start;
+    const markerEnd = marker.removeRange.end;
+    const open = text.lastIndexOf('(', start);
+    const close = text.indexOf(')', markerEnd);
     if (open >= 0 && close >= 0 && !/[\r\n]/.test(text.slice(open, close))) {
-        const rest = text.slice(open + 1, marker.range.start) + text.slice(marker.range.end, close);
+        const rest = text.slice(open + 1, start) + text.slice(markerEnd, close);
         if (/^[\s,;:—-]*$/.test(rest)) {
             const before = text[open - 1] === ' ' && /[.,;:!?]/.test(text[close + 1] ?? '') ? open - 1 : open;
-            return patchText(text, [{ start: before, end: close + 1, text: '' }]);
+            return { start: before, end: close + 1, text: '' };
         }
     }
-    const lead = /(?:[ \t]*[,;][ \t]*|[ \t]+)$/.exec(text.slice(0, marker.range.start));
+    const lead = /(?:[ \t]*[,;][ \t]*|[ \t]+)$/.exec(text.slice(0, start));
     if (lead) {
-        return patchText(text, [{ start: marker.range.start - lead[0].length, end: marker.range.end, text: '' }]);
+        return { start: start - lead[0].length, end: markerEnd, text: '' };
     }
-    const trail = /^[ \t]+/.exec(text.slice(marker.range.end));
-    const end = trail ? marker.range.end + trail[0].length : marker.range.end;
-    return patchText(text, [{ start: marker.range.start, end, text: '' }]);
+    const trail = /^[ \t]+/.exec(text.slice(markerEnd));
+    const end = trail ? markerEnd + trail[0].length : markerEnd;
+    return { start, end, text: '' };
+}
+/** Removes one marker, its punctuation and, when it was alone, its parentheses. */
+export function removeMarker(text, marker) {
+    return patchText(text, [markerEdits(text, marker)]);
+}
+/** Removes several markers in one edit, so the panel can confirm a whole list with one undo step. */
+export function removeMarkers(text, markers) {
+    if (markers.length === 0)
+        return text;
+    const edits = [...markers]
+        .sort((a, b) => b.range.start - a.range.start)
+        .map((marker) => markerEdits(text, marker));
+    return patchText(text, edits);
 }
 function replaceValues(text, block, values) {
     const yaml = stringifyYaml(values, { lineWidth: 0 }).replace(/\r?\n/g, newlineOf(text));

package/dist/scripts/check-cases.js

@@ -1,11 +1,35 @@
 import fs from 'node:fs';
 import { CASES_DIR } from '../lib/paths.js';
 import { listCaseFileIds, readCaseMeta } from '../lib/cases.js';
-import { parseCaseDocument } from '../lib/case-doc.js';
+import { parseCaseDocument, splitLines } from '../lib/case-doc.js';
 import path from 'node:path';
 import { ROOT } from '../lib/paths.js';
 import { checksNeedingTarget, parseTargets, readCaseText, REQUIRED_FIELDS, targetRefsIn } from '../lib/targets.js';
 import { parseCaseValues } from '../lib/values.js';
+const LIST_ITEM = /^[ \t]*(?:[-*+]|\d+\.)[ \t]+\S/;
+const HEADING = /^##[ \t]+\S/;
+/** The words the panel and `case:check` treat as a marker: one claim carries one signal. */
+const MARKER_WORD = /\b(?:to be confirmed(?:\s+by\s+QA)?|TBC|TBD|not observed)\b/i;
+const indentOf = (text) => text.length - text.trimStart().length;
+/**
+ * The line a question immediately hangs under: the nearest line above it that is indented less and can carry text.
+ * `null` when that line is a paragraph (the model extends a paragraph upwards on purpose) or nothing qualifies.
+ */
+function immediateAnchor(lines, questionLine, indent) {
+    const at = lines.findIndex((line) => line.number === questionLine);
+    for (let index = at - 1; index >= 0; index--) {
+        const text = lines[index].text;
+        if (text.trim() === '' || HEADING.test(text) || /^[ \t]*```/.test(text))
+            return null;
+        if (indentOf(text) >= indent)
+            continue;
+        // Another question at a shallower depth is not the sentence this one stands for.
+        if (/^[ \t]*[-*+][ \t]+(?:\u{1F6AB}|\u{2753}|\u270D)/u.test(text))
+            continue;
+        return LIST_ITEM.test(text) ? lines[index].number : null;
+    }
+    return null;
+}
 /** Step numbers of the lines marked `[input]` or `[writes]` in "## Steps" (a person does them), and the numbers that have a `- Recipe:` line under them (or an old "## Inputs" line). */
 function inputSteps(id) {
     const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
@@ -41,6 +65,11 @@ function questionProblems(id) {
         if (step && question.indent < 4) {
             warnings.push(`the question on line ${question.line} is indented by ${question.indent} space(s) under step ${step.number}; 4 renders it inside the step`);
         }
+        const anchor = immediateAnchor(splitLines(doc.text), question.line, question.indent);
+        if (anchor !== null && anchor !== question.parent.line) {
+            const above = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
+            warnings.push(`the question on line ${question.line} hangs under "${above.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the text above it; indent it under that sentence or lift that sentence to a top-level bullet`);
+        }
     }
     for (const step of doc.steps) {
         if (step.recipes.length === 0)
@@ -62,6 +91,58 @@ function questionProblems(id) {
     }
     return warnings;
 }
+/**
+ * Problems with the markers (`🔍 to be confirmed by QA`, `👁️ not observed`): one claim carries one signal, and a
+ * marker says what a person has to decide. A marker inside a question block is a failure; the old form without a
+ * "why" is a warning, so old cases keep working.
+ */
+function markerProblems(id) {
+    const text = fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8');
+    const doc = parseCaseDocument(text);
+    const fail = [];
+    const warn = [];
+    for (const question of doc.questions) {
+        const end = question.hasAnswerLine ? question.answerRange.start : question.blockRange.end;
+        if (MARKER_WORD.test(text.slice(question.blockRange.start, end))) {
+            fail.push(`the question on line ${question.line} holds a marker word ("to be confirmed" / "not observed"): one claim carries one signal, so keep the question and drop the marker`);
+        }
+    }
+    if (doc.values?.hasBlock && MARKER_WORD.test(text.slice(doc.values.range.start, doc.values.range.end))) {
+        fail.push('a marker inside the "## Values" yaml block would become part of the expected value: put it on the prose line above the block');
+    }
+    const parentLines = new Set(doc.questions.map((question) => question.parent?.line).filter((line) => line !== undefined));
+    for (const marker of doc.markers) {
+        if (parentLines.has(marker.line)) {
+            fail.push(`line ${marker.line} carries a marker and a question under it: keep the question (drop the marker) or the marker (drop the question)`);
+        }
+        if (marker.detail === null) {
+            warn.push(`the marker on line ${marker.line} does not say what a person must confirm; write "🔍 to be confirmed: <the one thing to decide>"` +
+                (marker.evidence === null
+                    ? ', plus "evidence: .explore/observations/<case-id>/<image>.png" when a screenshot says it better'
+                    : ''));
+        }
+    }
+    return { fail, warn };
+}
+/**
+ * Problems with the `## Rules` bullets: a rule may name the step it belongs to (`Step 3:`, `Before step 3:` or
+ * `After step 3:`). A reference to a step the case does not have is a failure, because the rule would silently lose its
+ * scope. An unprefixed rule applies to the whole case and is always valid.
+ */
+function ruleProblems(id) {
+    const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
+    const failures = [];
+    for (const rule of doc.rules) {
+        const match = /^(?:(?:before|after)[ \t]+)?step[ \t]+(\d+)\b/i.exec(rule.text);
+        if (!match)
+            continue;
+        const number = Number(match[1]);
+        if (!doc.steps.some((step) => step.number === number)) {
+            failures.push(`the rule on line ${rule.line} refers to step ${number}, which this case does not have`);
+        }
+    }
+    return failures;
+}
 /**
  * Warnings for the old layout. `## Data` and `## Inputs` are deprecated: the one-sentence summary belongs in
  * `writes-note`, the cleanup in steps, and a person's recipe under its step. Cases keep working, so this never fails.
@@ -131,6 +212,8 @@ for (const id of ids) {
             console.log(`warn ${id}: ${message}`);
         for (const message of targets.fail)
             throw new Error(message);
+        for (const message of ruleProblems(id))
+            throw new Error(message);
         const { marked, recorded } = inputSteps(id);
         const missing = marked.filter((step) => !recorded.includes(step));
         if (missing.length > 0) {
@@ -140,6 +223,11 @@ for (const id of ids) {
             console.log(`warn ${id}: ${message}`);
         for (const message of questionProblems(id))
             console.log(`warn ${id}: ${message}`);
+        const markers = markerProblems(id);
+        for (const message of markers.warn)
+            console.log(`warn ${id}: ${message}`);
+        for (const message of markers.fail)
+            throw new Error(message);
     }
     catch (error) {
         problems++;