@asrunjs/asrun 0.9.0 → 0.11.0

package/dist/ui/server/process-info.js

@@ -0,0 +1,126 @@
+import { spawnSync } from 'node:child_process';
+/** 100-ns ticks between 1601-01-01 and 1970-01-01, the epoch a Windows file time counts from. */
+const WINDOWS_EPOCH_MS = 11644473600000;
+/** True when the pid exists and this process may signal it. */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // A process of another user still exists; only a missing one is gone.
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * What the system knows about these pids on Windows, from one PowerShell call for all of them. The command line and the
+ * creation time are what tell a leftover job from a new process that merely reused its pid.
+ */
+function windowsDetails(pids) {
+    const map = new Map();
+    const filter = pids.map((pid) => `ProcessId=${pid}`).join(' OR ');
+    // `\u0001` is an ordinary separator: a Windows command line never holds it.
+    const script = `$p = Get-CimInstance Win32_Process -Filter "${filter}"; ` +
+        'foreach ($x in $p) { $ft = 0; try { $ft = $x.CreationDate.ToFileTimeUtc() } catch {}; ' +
+        'Write-Output ("{0}\u0001{1}\u0001{2}" -f $x.ProcessId, $ft, ($x.CommandLine -replace "\\r?\\n", " ")) }';
+    const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 15_000,
+    });
+    if (result.status === 0 && typeof result.stdout === 'string') {
+        for (const line of result.stdout.split(/\r?\n/)) {
+            if (line.trim() === '')
+                continue;
+            const [pidText, fileTimeText, ...rest] = line.split('\u0001');
+            const pid = Number(pidText);
+            if (!Number.isInteger(pid))
+                continue;
+            const fileTime = Number(fileTimeText);
+            const startedAt = Number.isFinite(fileTime) && fileTime > 0 ? fileTime / 10_000 - WINDOWS_EPOCH_MS : null;
+            map.set(pid, { commandLine: rest.join('\u0001'), startedAt });
+        }
+    }
+    for (const pid of pids) {
+        if (!map.has(pid))
+            map.set(pid, alive(pid) ? { commandLine: '', startedAt: null } : null);
+    }
+    return map;
+}
+/** `etime` of `ps`: `MM:SS`, `HH:MM:SS` or `D-HH:MM:SS`. */
+function parseElapsed(text) {
+    const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(text);
+    if (!match)
+        return null;
+    const days = Number(match[1] ?? 0);
+    const hours = Number(match[2] ?? 0);
+    const minutes = Number(match[3]);
+    const seconds = Number(match[4]);
+    return ((days * 24 + hours) * 60 + minutes) * 60 * 1000 + seconds * 1000;
+}
+/** The same answer on Linux and macOS, from one `ps` call. */
+function posixDetails(pids) {
+    const map = new Map();
+    const result = spawnSync('ps', ['-ww', '-p', pids.join(','), '-o', 'pid=,etime=,args='], {
+        encoding: 'utf8',
+        timeout: 15_000,
+    });
+    if (result.status === 0 && typeof result.stdout === 'string') {
+        for (const line of result.stdout.split(/\r?\n/)) {
+            const match = /^\s*(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+            if (!match)
+                continue;
+            const pid = Number(match[1]);
+            const elapsed = parseElapsed(match[2]);
+            map.set(pid, { commandLine: match[3], startedAt: elapsed === null ? null : Date.now() - elapsed });
+        }
+    }
+    for (const pid of pids) {
+        if (!map.has(pid))
+            map.set(pid, alive(pid) ? { commandLine: '', startedAt: null } : null);
+    }
+    return map;
+}
+/**
+ * The details of these pids, or `null` for one that is gone. One call for all of them: a restart usually has only a
+ * handful of jobs to look at, but probing should not be started once per job.
+ */
+export function probeProcesses(pids) {
+    const unique = [...new Set(pids.filter((pid) => Number.isInteger(pid) && pid > 0))];
+    if (unique.length === 0)
+        return new Map();
+    try {
+        return process.platform === 'win32' ? windowsDetails(unique) : posixDetails(unique);
+    }
+    catch {
+        const fallback = new Map();
+        for (const pid of unique)
+            fallback.set(pid, alive(pid) ? { commandLine: '', startedAt: null } : null);
+        return fallback;
+    }
+}
+/**
+ * Ends a process and everything it started: the agent CLI, the browser and the MCP server below it. Off Windows the
+ * process was spawned as the leader of its own group, so the whole group is signalled; Windows has no process groups,
+ * and `taskkill /T` walks the tree instead.
+ */
+export function killProcessTree(pid, signal) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return;
+    if (process.platform === 'win32') {
+        spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // Not a group leader any more (or already gone): end what is left of the process itself.
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}

package/dist/ui/server/result-state.d.ts

@@ -0,0 +1,10 @@
+import type { ResultState } from '../shared/types.js';
+/**
+ * What a finished AI run declared, or null when its text holds no `RESULT:` line at all.
+ *
+ * A fence normally means "this is quoted", so its content is not the agent's own conclusion. A model still wraps its
+ * closing line in a block of its own often enough to matter, so a fence is read in two narrow cases, after nothing
+ * outside one was found: a fence that holds nothing but the result (the usual drift), and the last line of the whole
+ * message even when a fence wraps all of it (the agent answered from inside one block).
+ */
+export declare function parseResultState(text: string): ResultState | null;

package/dist/ui/server/result-state.js

@@ -0,0 +1,106 @@
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+/** Zero-width characters that a copied line may carry, which would hide the token from a line-anchored match. */
+const ZERO_WIDTH = /[\u200b-\u200d\ufeff]/g;
+/** The first line of a fenced block: a run of three or more backticks or tildes, then an info string without that run. */
+const FENCE_OPEN = /^\s{0,3}(`{3,}|~{3,})([^`~]*)$/;
+/** The last line of a fenced block: a run at least as long as the one that opened it, and nothing else. */
+const FENCE_CLOSE = /^\s{0,3}(`{3,}|~{3,})\s*$/;
+/** Splits the text into lines and marks the ones a fence wraps, so quoted content does not read as the conclusion. */
+function textLines(source) {
+    const lines = [];
+    let open = null;
+    for (const text of source.split('\n')) {
+        if (open === null) {
+            const start = FENCE_OPEN.exec(text);
+            if (start) {
+                open = start[1];
+                lines.push({ text, fenced: true, marker: start[1] });
+                continue;
+            }
+            lines.push({ text, fenced: false });
+            continue;
+        }
+        const end = FENCE_CLOSE.exec(text);
+        const closes = !!end && end[1][0] === open[0] && end[1].length >= open.length;
+        lines.push({ text, fenced: true, ...(closes && { marker: end[1] }) });
+        if (closes)
+            open = null;
+    }
+    return lines;
+}
+/**
+ * The last `RESULT: ready|needs-input` line of what the agent said. The token is fixed (`AGENTS.md`, "Fixed tokens"),
+ * but a model drifts in every way that still means the same thing: a short label in front of it ("结果：", "Status:",
+ * "结果 —"), a full-width colon, bold or a code span, a list bullet or a heading, an emoji, or `needs input` for
+ * `needs-input`. A run that said `needs-input` must not be read as a run that said nothing, so the format is read
+ * leniently; the line stays anchored and the value has to follow the separator at once, so ordinary prose that merely
+ * mentions the token is still not a result. The label may not run across a newline and may not hold a colon of its own.
+ */
+const RESULT_LINE = /^[\s\p{P}\p{S}\d]*(?:[^\n:：]{1,40}(?:[:：]|\s[–—-]\s)\s*)?RESULT[\s*_`]*(?:[:：][\s*_`\p{S}]*|[\s*_`]*[–—-][\s*_`\p{S}]*)[\s*_`\p{S}]*(ready|needs[\s_-]?input)\b/gimu;
+/** The state a single line declares, or null when the line is not a result line. */
+function matchLine(text) {
+    const value = [...text.matchAll(RESULT_LINE)].at(-1)?.[1];
+    if (!value)
+        return null;
+    // The token is fixed, but a drifted `NEEDS INPUT` or `needs_input` means the same as `needs-input`.
+    return value.toLowerCase().replace(/[\s_]+/g, '-');
+}
+/** The state of the last of these lines that is a result line, or null when none is. */
+function lastOf(lines) {
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const state = matchLine(lines[index].text);
+        if (state)
+            return state;
+    }
+    return null;
+}
+/**
+ * What a finished AI run declared, or null when its text holds no `RESULT:` line at all.
+ *
+ * A fence normally means "this is quoted", so its content is not the agent's own conclusion. A model still wraps its
+ * closing line in a block of its own often enough to matter, so a fence is read in two narrow cases, after nothing
+ * outside one was found: a fence that holds nothing but the result (the usual drift), and the last line of the whole
+ * message even when a fence wraps all of it (the agent answered from inside one block).
+ */
+export function parseResultState(text) {
+    const lines = textLines(text.replace(ANSI, '').replace(ZERO_WIDTH, ''));
+    // 1. What the agent said outside any fence: the usual case, and the only place two results can stand against each
+    // other.
+    const plain = lastOf(lines.filter((line) => !line.fenced));
+    if (plain)
+        return plain;
+    // 2. A fence whose body is the result and nothing else, as one block per fence.
+    const blocks = [];
+    let block = null;
+    for (const line of lines) {
+        if (!line.fenced) {
+            block = null;
+            continue;
+        }
+        if (!block) {
+            block = [];
+            blocks.push(block);
+        }
+        block.push(line);
+    }
+    for (let index = blocks.length - 1; index >= 0; index -= 1) {
+        const body = blocks[index].filter((line) => !line.marker && line.text.trim() !== '');
+        if (body.length !== 1)
+            continue;
+        const state = matchLine(body[0].text);
+        if (state)
+            return state;
+    }
+    // 3. The last line of the message, fence or not: the line a person reads as the conclusion, whatever wraps it.
+    // A fence that names two results is a quote of a document, not an answer, so it is not read from its tail.
+    const tail = [...lines].reverse().find((line) => !line.marker && line.text.trim() !== '');
+    if (!tail)
+        return null;
+    const tailState = matchLine(tail.text);
+    if (!tailState)
+        return null;
+    if (!tail.fenced)
+        return tailState;
+    const body = blocks.find((block) => block.includes(tail))?.filter((line) => !line.marker) ?? [];
+    return body.filter((line) => matchLine(line.text)).length === 1 ? tailState : null;
+}

package/dist/ui/shared/ai-commands.d.ts

@@ -37,7 +37,10 @@ export interface AiRunOptions {
      * (all that are logged in, for heal). `gen-spec` takes none: it uses every profile the case names.
      */
     profiles?: string[];
-    /** `heal-spec` only: file (relative to the project root) with what the user wants repaired or improved, and any clues. */
+    /**
+     * Every command: file (relative to the project root) with what the user knows, wants checked or wants changed. A
+     * reusable instruction is written into the case's `## Rules`; a one-off clue stays in the report.
+     */
     hints?: string;
     /** `heal-spec` only: the report (folder name under reports/) to read first instead of the newest one. */
     report?: string;

package/dist/ui/shared/ai-commands.js

@@ -30,7 +30,7 @@ export const slashCommand = (command, caseId, options) => {
         `${attended && command === 'explore-case' ? ' --attended' : ''}` +
         `${picksProfiles && profiles?.length ? ` --profiles ${profiles.join(',')}` : ''}` +
         `${heal && report ? ` --report ${report}` : ''}` +
-        `${heal && hints ? ` --hints ${hints}` : ''}`);
+        `${hints ? ` --hints ${hints}` : ''}`);
 };
 /** The MCP tools of the Playwright server that agents explore with. */
 const PLAYWRIGHT_MCP = 'mcp__playwright-test__*';
@@ -52,6 +52,7 @@ function claudeAllowedTools(writes) {
         'Edit(/tests/**)',
         'Bash(pnpm typecheck:*)',
         'Bash(pnpm spec:lint:*)',
+        'Bash(pnpm markers:confirm:*)',
         nodeTsx,
         'Bash(pnpm baselines:review:*)',
     ];
@@ -111,12 +112,20 @@ function invocation(tool, prompt, writes, session, model, thinking) {
     };
 }
 const commandLine = ({ file, args }) => [file, ...args.map((arg) => (/^[\w@=,.:/-]+$/.test(arg) ? arg : JSON.stringify(arg)))].join(' ');
+/**
+ * The closing line of every one-shot run. The server reads the last `RESULT:` line to tell a finished run from one that
+ * said nothing, and the shapes it drifts into are Markdown ones: a code fence, bold, a heading, a bullet. The wording is
+ * the same in every prompt so a continuation of a run asks for the same thing.
+ */
+const RESULT_LINE_RULE = 'The last line of your final message is plain text and nothing else: exactly "RESULT: ready" or ' +
+    '"RESULT: needs-input". Never put it in a code fence or inline code, never make it bold, a heading or a list item, ' +
+    'put no label, number or emoji in front of it, and write nothing after it.';
 /**
  * Said in every one-shot run: nobody is there to answer, so questions go into the case file and the last line
  * is a result the UI can read. The skills define the details.
  */
 const NON_INTERACTIVE = 'Non-interactive run: nobody can answer questions, so do not stop to ask. Write open questions into the case file ' +
-    'as the skill describes and end with the RESULT: line.';
+    `as the skill describes. ${RESULT_LINE_RULE}`;
 /**
  * An attended exploration: nobody answers questions in the chat, but a person sits at the machine and works in the
  * browser window, so the agent hands them the steps that write data and waits, as user-handoff.md describes.
@@ -126,7 +135,7 @@ const ATTENDED = 'Attended run: a person is at the machine and the browser windo
     'with its own call that sets __handoffCfg, before the call that runs handoff-card.js, and never change those options ' +
     'inside the call that runs the card: the web UI sees that a person is needed only from that call, so without it ' +
     'there is no "Your turn" badge and no notification. Nobody can answer questions in the chat, so write open ' +
-    'questions into the case file as the skill describes and end with the RESULT: line.';
+    `questions into the case file as the skill describes. ${RESULT_LINE_RULE}`;
 /** The prompt of a one-shot run. Every command may leave open questions in the case, so every one ends with a RESULT line. */
 export function headlessPrompt(command, caseId, options) {
     const slash = slashCommand(command, caseId, options);
@@ -159,7 +168,7 @@ export function replyPrompt(command, replyFile) {
         `Their answers are in ${replyFile}, relative to the project root: read that file first.\n` +
         'Fold every answer into the case file as the skill describes: write the answer into the sentence above the ' +
         'TODO block and remove the block, and keep a TODO block (with an empty Answer: line, emoji prefixes included) for what is still unknown. ' +
-        `Then finish the task of /${command} and end with the RESULT: line.`);
+        `Then finish the task of /${command}. ${RESULT_LINE_RULE}`);
 }
 /** The next turn of an earlier run, in its session and with exactly the permissions of the first turn. */
 export function continueInvocation(tool, command, replyFile, sessionId, model, thinking) {
@@ -174,6 +183,7 @@ export const makeCasePrompt = (memoPath) => `/make-case ${memoPath} ` +
     'Non-interactive run: nobody can answer questions, so do not stop to ask. ' +
     'Do not open a browser or explore pages. Write the suggested default of every gap as a normal sentence and put a ' +
     'TODO block with an empty Answer: line under it, as open-questions.md describes (every marker starts with its emoji). ' +
+    'Never put a marker word inside a TODO block: one claim carries one signal. ' +
     'Never overwrite an existing case: choose a new id instead. ' +
     'Put the cases of one area in a group folder (cases/<group>/<name>.md, id <group>/<name>), reusing an existing folder when it fits. ' +
     'Write the cases, run pnpm case:check, and list the open questions in your final report.';

package/dist/ui/shared/types.d.ts

@@ -1,7 +1,16 @@
 import type { ResultStatus } from '../../lib/run-summary.js';
 import type { AiCommand, AiTool } from './ai-commands.js';
-export type JobStatus = 'running' | 'succeeded' | 'failed' | 'cancelled';
+export type JobStatus = 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted';
 export type JobKind = 'signin' | 'visit' | 'run' | 'ai';
+/**
+ * A job that was still running when the UI server stopped, and the process left behind. `alive`: it was identified as
+ * this job's process; `unknown`: a process has that pid but could not be identified, so it is never killed; `gone` /
+ * `stopped`: nothing is left to stop.
+ */
+export interface LeftoverInfo {
+    pid: number;
+    state: 'alive' | 'unknown' | 'gone' | 'stopped';
+}
 /** What changed on disk: case files (`cases/**`) and/or specs (`tests/**`). */
 export interface FilesChange {
     cases: boolean;
@@ -41,6 +50,12 @@ export interface JobInfo {
     continuesJobId?: string;
     /** An AI run that has handed a step to the person in the browser window and waits for them to press Done. */
     awaitingUser?: AwaitingUserInfo | null;
+    /** When the UI server found this job still running from a previous server. */
+    interruptedAt?: string;
+    /** A job the previous UI server left behind: what is known about its process, and whether it is still there. */
+    leftover?: LeftoverInfo;
+    /** True when "Run again" can start this job from the request it was started with. */
+    rerunable?: boolean;
 }
 export interface AwaitingUserInfo {
     /** What the person is asked to do, as the agent wrote it on the card; null when unknown. */
@@ -105,7 +120,7 @@ export type StartJobRequest = {
     model?: string;
     /** `explore-case` and `heal-spec` only: the profiles to open / heal; omitted = every profile that applies. `gen-spec` takes none: it uses every profile the case names. */
     profiles?: string[];
-    /** `heal-spec` only: what the user knows (optional). The server stores it as a file for the agent. */
+    /** Every command: what the user knows or wants changed (optional). The server stores it as a file for the agent. */
     hints?: string;
     /** `heal-spec` only: the report to read first (folder name under reports/); omitted = the newest one. */
     report?: string;

package/docs/agents/case-format.md

@@ -5,7 +5,7 @@ spec consumes it. It holds no rules of its own: the rules are in the framework `
 references listed at the end.
 
 Read `AGENTS.md` first. If a project has `.claude/skills/<skill>.md`, that override comes after the skill; the
-project's `AGENTS.md` §2 comes last and wins over both. `F1`–`F6` always win.
+project's `AGENTS.md` §2 comes last and wins over both. `F1`–`F6` and `R2` always win.
 
 ## Identity and paths
 
@@ -20,15 +20,17 @@ project's `AGENTS.md` §2 comes last and wins over both. `F1`–`F6` always win.
 
 The parser and the web panel match these literals. A project language never translates them:
 
-- Section headings: `## Goal`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`, `## Notes`,
-  and `## Source` when the case was made from notes.
+- Section headings: `## Goal`, `## Rules`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`,
+  `## Notes`, and `## Source` when the case was made from notes.
 - Front matter keys: `id`, `title`, `login`, `suites`, `writes`, `writes-note`, `envs`.
 - Step tags at the end of a step line: `[input]`, `[writes]`, `[email]`.
 - Under a step: `- Ready when:` lines and `- Recipe (phase):` lines.
 - Target cards: `### T<n> <name>` and their references `[T<n>]`.
 - Questions: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, and the markers
-  `🔍 to be confirmed by QA` / `👁️ not observed`.
-- The last line of a run: `RESULT: ready` or `RESULT: needs-input`.
+  `🔍 to be confirmed` / `👁️ not observed`. A marker's parentheses may hold its reason (`🔍 to be confirmed: <what a
+  person must decide>`) and a screenshot (`evidence: <path under .explore/>`); `(seen on <profile>)` is a plain note.
+- The last line of a run: `RESULT: ready` or `RESULT: needs-input`, plain text, alone on its line (no label in front of
+  it, no code fence or emphasis around it).
 
 ## Front matter
 
@@ -56,6 +58,28 @@ hard-codes tags.
 
 ## Sections
 
+### Rules
+
+Case-local instructions for the agents that explore, generate and heal this case: **how** to run it, never **what is
+true** (framework baseline `R1`–`R4`). The section is optional and written by a person; an AI run may add a rule only
+under `R4` and never rewrites or deletes one silently.
+
+- One top-level bullet per rule, plain prose. No nested bullets and no code fences: `parseBullets` reads only the
+  top-level bullets, so a nested list is not part of the rule the panel edits.
+- A bullet may start with `Step <n>:`, `Before step <n>:` or `After step <n>:` to tie it to that step.
+  `pnpm case:check` fails when that step does not exist. Without a prefix the rule applies to the whole case.
+- Use it for a page quirk, a mandatory read-only preparation, a control to avoid, or a waiting/attention hint.
+- Do **not** use it for an expectation (`## Expected`), a literal (`## Values`), a target (`## Targets`), or a step that
+  writes, sends email or needs a person. Those stay in their own sections, and such a step keeps its tags and recipe.
+- A rule that conflicts with the rest of the case is a `🚫 TODO [blocking]` question, not an override. A rule that no
+  longer holds (the page changed, the banner is gone) is recorded with a TODO and evidence, never deleted silently.
+- The same artifact language as the rest of the case applies; the heading itself stays `## Rules`.
+
+Good: `- Before step 1: dismiss the cookie banner; it covers the header and blocks clicks.`
+Good: `- Never use "Continue with Google": it requires 2FA and is out of scope.`
+Wrong: `- The header logo must be the Acme logo.` (an expectation → `## Expected` / `## Values` / `## Targets`)
+Wrong: `- Create a draft named ... and delete it at the end.` (a write → a tagged step with a recipe)
+
 ### Steps
 
 - Numbered Markdown lines (`1.`, `2.`, ...). The spec wraps each one in `test.step('<n>. <text>', ...)` with the text
@@ -70,7 +94,11 @@ hard-codes tags.
 - A question block is indented under the sentence it belongs to: 4 spaces under a numbered step, 2 under a bullet.
   The parent line is the suggestion, written as a finished sentence; the `TODO` line holds one question and optional
   `(evidence)`; the block ends with `- ✍️ Answer:` at one level deeper and that line is the last line of the block.
+  Hang it under the immediate sentence, never under a broader one above it, and never inside the `## Values` yaml.
   Details: `.claude/skills/exploring-cases/references/open-questions.md`.
+- A marker (`🔍 to be confirmed: <what a person must decide>`) is the alternative to a question, not a companion: it
+  says nobody has to decide, only to check. `(seen on <profile>)` is a plain note the run checks by itself. Its
+  `evidence: <path>` is served by the panel from `.explore/`.
 
 ### Expected
 
@@ -94,6 +122,8 @@ example-staging:
   `TODO` fails with "Incomplete values ...". Fill them before running; never make a spec read the YAML itself.
 - Values hold literals only: names, labels, options, test-data names. The checks themselves stay in `## Steps` and
   `## Expected`, and selectors come from `## Targets`.
+- No marker or question inside the yaml: it would become part of the expected value. Put it on the prose line above
+  the block and name the key there.
 
 ### Visual checks
 
@@ -155,6 +185,9 @@ test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
 - `// target: T<n>` goes on the line before an image/screenshot/PDF check. `// ready: <signal>` goes before a check
   for absence ("missing", "empty", "hidden") and needs a positive wait before it. `// pages: <the case's words>` goes
   before an `expectPdf` that follows a case limit written in strong words ("only", "exactly", "must").
+- `## Rules` are applied while replaying the case and writing the spec, but they never become assertions. Code that
+  exists only because of a rule carries `// rule: <short quote>` on the line before it. A rule that cannot be honored
+  is a question in the case, never an invented value or a skipped expectation.
 - Import `test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`. Locators:
   `getByTestId` > `getByRole` > `getByLabel` > text.
 - No branching on `profile.id` or `profile.env`: differences go into `## Values`, selectors into `## Targets`.
@@ -185,9 +218,11 @@ test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
 
 In the framework package:
 
+- `.claude/skills/exploring-cases/references/case-rules.md` — how `## Rules` are read, applied and maintained.
 - `.claude/skills/exploring-cases/references/assertion-targets.md` — what a check looks at, and when to ask.
 - `.claude/skills/exploring-cases/references/readiness.md` — wait for the content, optional confirmations, downloads.
 - `.claude/skills/exploring-cases/references/open-questions.md` — question blocks and how answers are folded in.
 - `.claude/skills/exploring-cases/references/user-handoff.md` — attended exploration and the handoff card.
+- `.claude/skills/exploring-cases/references/notes.md` — the local exploration note `/gen-spec` reads (not part of the case).
 - `.claude/skills/generating-specs/references/conventions.md` — spec shape, assertion layers, readable failures.
 - `docs/cases.md` — the same format for people writing a case by hand.

package/docs/agents/framework-dev.md

@@ -53,6 +53,10 @@ is relevant to a project that uses asrun as a dependency.
 - Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
   assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
   `FRAMEWORK_ROOT` at run time.
+- `.explore/` is local state (git-ignored): target reference screenshots and the exploration notes that
+  `lib/explore-notes.ts` reads (`.explore/notes/<case-id>/<profile-id>.json`). Nothing there is committed, and a
+  workspace without it generates specs by replaying the case. `scripts/explore-notes.ts` (`pnpm explore:notes`) prints
+  and validates those notes.
 - After changing `lib/`, run `pnpm build` before exercising the demo's specs.
 - `pnpm build` copies `scripts/*.mjs` into `dist/scripts/`, where they sit one folder deeper than in this repository.
   `pnpm verify:pack` (part of CI) checks that layout on a packed tarball; the checkout alone hides such bugs, because

package/docs/ai-workflow.md

@@ -8,8 +8,8 @@ so the procedure lives in one place and a project can refine it (see
 | Command | What it does |
 |---|---|
 | `/make-case <notes-or-path>` | Turn raw notes into case documents. Optional step. |
-| `/explore-case <case-id> <env> [--attended] [--profiles a,b]` | Open the real pages and write what they show into the case. |
-| `/gen-spec <case-id> <env> [--force]` | Write `tests/<case-id>.spec.ts` and fill the case's `## Values`. |
+| `/explore-case <case-id> <env> [--attended] [--profiles a,b] [--hints <file>]` | Open the real pages and write what they show into the case. |
+| `/gen-spec <case-id> <env> [--force] [--hints <file>]` | Write `tests/<case-id>.spec.ts` and fill the case's `## Values`. |
 | `/heal-spec <case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]` | Repair a failing spec, or refine a case and its spec on request, from the last report and what you asked for. |
 
 The environment is **required** by every command except `/make-case`, which does not open pages. There is no default.
@@ -17,7 +17,13 @@ The environment is **required** by every command except `/make-case`, which does
 `--profiles` exists on `/explore-case` and `/heal-spec`, not on `/gen-spec`: a spec runs once per profile in the
 environment, so it is generated from every profile the case holds information for, never from a chosen subset.
 
-Every command ends with `RESULT: ready` or `RESULT: needs-input`. `needs-input` means somebody has to answer a
+`--hints <file>` (or free text after the arguments) is optional on all three commands that read a case: what you know,
+want checked or want changed. It guides that run. After the work, a reusable instruction that is **method**, not an
+expectation, is written into the case's `## Rules`; a one-off clue stays in the report. See
+[Rules for one case](#rules-for-one-case).
+
+Every command ends with `RESULT: ready` or `RESULT: needs-input` as plain text on its last line (never in a code fence
+or in emphasis: the web UI reads that line to show the outcome). `needs-input` means somebody has to answer a
 question in the case file (or, in the web UI, in the job's **Answer** sheet). A one-shot run cannot ask in the chat:
 it writes its questions into the case and stops.
 
@@ -49,6 +55,19 @@ It writes `cases/<id>.md` only, and never overwrites an existing case. `pnpm cas
 `pnpm case:new header-logo` creates `cases/header-logo.md` from the template, or use a case you already have. The
 format is in [cases.md](./cases.md). Write the steps, the expectations and — when you know them — the values.
 
+### Rules for one case
+
+A case can hold a `## Rules` section: case-local instructions on **how** to run it (dismiss a cookie banner first, wait
+for a dialog after a request, never use an entry that needs 2FA). It is the place to talk to the agent without putting
+a requirement into the wrong section. One bullet per rule; `Step 3:`, `Before step 3:` or `After step 3:` ties it to a
+step, and `pnpm case:check` fails when that step does not exist.
+
+Rules never say what the case proves, never replace a step or an expected value, and never allow writing data, sending
+email or doing a person's step: those stay in `## Expected`, `## Values` and tagged steps with a recipe. The AI reads
+and applies every rule in every run, re-checks them against the page, and lists them in its report. `/explore-case`,
+`/gen-spec` and `/heal-spec` re-check the rules and never delete or rewrite one on their own; a rule that no longer
+holds becomes a question for you.
+
 ## 2. Explore the case (only where a person and the agent work together)
 
 ```
@@ -58,11 +77,16 @@ format is in [cases.md](./cases.md). Write the steps, the expectations and — w
 The agent opens the real pages of the profiles that are logged in and only **reads** them. It never creates, edits,
 publishes, shares or deletes anything, in staging or in production. It:
 
-- fixes wording in the case file and writes what the pages show into it, marked `observed, 🔍 to be confirmed by QA`;
+- fixes wording in the case file and writes what the pages show into it: a plain note `(seen on <profile>)` when the
+  run checks it, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` only for a line that
+  would pass even if it were wrong;
 - turns what it cannot know into `🚫 TODO [blocking]` / `❓ TODO [non-blocking]` questions, each under a sentence that
   is its suggestion and can stand in the case as it is, with a last line `- ✍️ Answer:`;
 - lists the candidates instead of guessing a target (`## Targets`);
-- edits the case file only (plus reference screenshots under `.explore/targets/`).
+- edits the case file and the `.explore/` files (reference screenshots and the note below), and nothing else;
+- writes a local **exploration note** (`.explore/notes/<case-id>/<profile-id>.json`, git-ignored) with the locators and
+  data-call paths it saw. `/gen-spec` reads it to verify instead of rediscovering, and a page that only exists after a
+  write step is written from it. Delete it at any time: without it, generation replays the case.
 
 With many profiles, `--profiles a,b` opens only those (ids from `profiles.yaml`, comma-separated). The others are not
 opened and nothing is written about them, so a case can be explored in passes: A and B first, C later. Runs add up; the
@@ -82,7 +106,9 @@ the browser window opens and the agent waits while you do those steps.
 - The window shows a small draggable card in the bottom-left corner with what to do, **Done** (hand control back) and
   **Cannot do this**. The agent also continues by itself when the finish condition it named shows up (for example a
   "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
-- What you did is recorded in the case under the step as **general recipe lines**
+- Recording starts and stops by itself. If Playwright's own recording toolbar shows at the top of the page, leave it
+  alone: it can stop the recording.
+- The card records what you did, and the agent writes it into the case under the step as **general recipe lines**
   (`- Recipe (phase): ...`): positions instead of names of changeable data, `[asrun]` names for created data, control
   labels but no selectors.
 - Delete the `[asrun]` items you created before you press Done on the last step.
@@ -115,6 +141,11 @@ subset adds up: explore A and B first and C later, and `/gen-spec` covers all th
 about runs on `default` alone, and the report names it. A profile that is not logged in is not dropped: its part is
 written from the case and marked `not verified on the page`.
 
+It reads each profile's **exploration note** first: a fresh note supplies the locators and request patterns, which it
+confirms on the page instead of rediscovering; a missing or stale note means a full replay. A page that only exists
+after a write step is written from a fresh note. `pnpm explore:notes <case-id> [--profile <id>]` shows what was
+recorded, and `--check` validates it.
+
 It does **not** run the spec and does **not** create screenshot baselines: running is a separate step (6).
 
 - A case must be in the project's artifact language. If it is in another language, `/gen-spec` translates the case
@@ -161,7 +192,9 @@ whether it found a real product problem, and it **never** edits an expectation j
   instead of failing them).
 - The web UI first opens a dialog: which profiles to run (every logged-in profile ticked) and an optional text box
   for what should be repaired or improved, with evidence. The text is stored in `.tmp/hints/` and passed as `--hints`.
-  It guides the work; it never lowers the bar for a product finding.
+  It guides the work; it never lowers the bar for a product finding. A reusable instruction that is method rather than
+  an expectation is also written into the case's `## Rules` (see [Rules for one case](#rules-for-one-case)); a one-off
+  clue stays in the report.
 - It reads the existing report first:
 
   ```bash
@@ -174,15 +207,20 @@ whether it found a real product problem, and it **never** edits an expectation j
   performs a step that writes data. After editing the spec, it runs the case once to confirm.
 - The case is the source of truth: a change to a step, an expectation, a value or a target is written into the case
   first, then into the spec. A large change regenerates the spec from the case.
-- **Review gate.** If the change leaves an open question or an unconfirmed observation in the case, healing stops
-  before the spec: you review the case, answer or accept what it asks, and run `/explore-case` again. The spec is
-  generated after that, not before.
+- **Review gate.** If the change leaves an open question or a `🔍 to be confirmed` marker in the case, healing stops
+  before the spec: you review the case, answer what it asks or settle the marker (the panel shows why it needs you, and
+  `pnpm markers:confirm` settles the ones a passing run already checks), then run `/explore-case` again. The spec is
+  generated after that, not before. A plain `(seen on <profile>)` note never stops it: the run checks those. A marker
+  inside `## Rules` does not stop the spec either, unless it covers a literal the spec asserts.
 
 ## Why a generated spec can be trusted
 
-Three binding rules hold in exploring, generating and healing. They live in the framework's `AGENTS.md` and in
-`.claude/skills/exploring-cases/references/assertion-targets.md` and `readiness.md`.
+Several binding rules hold in exploring, generating and healing. They live in the framework's `AGENTS.md` and in
+`.claude/skills/exploring-cases/references/case-rules.md`, `assertion-targets.md` and `readiness.md`.
 
+- **Case rules.** A `## Rules` bullet says how to run the case, never what it proves. The agent applies it while
+  exploring and generating, marks code that exists only because of a rule with `// rule: <short quote>`, and lists every
+  rule in its report. It never becomes an assertion and never authorizes a write or a person's step.
 - **Targets.** A check on a logo, image, icon, file, PDF, screenshot or repeated text points to a `[T1]` card under
   `## Targets`: what it is (and what it is not), where it is, how it is identified (never `.first()` or a bare `img`),
   when it is ready, and a highlighted reference screenshot under `.explore/targets/`. When in doubt the agent does not
@@ -204,7 +242,8 @@ Checks you can run yourself:
 |---|---|
 | `pnpm spec:lint [case-id]` | fails on screenshots without a target, `.first()` on images, sleeps, `networkidle`, raw download events, a `%PDF` check on its own |
 | `pnpm baselines:review [case-id] [--new]` | lists every baseline with the card that says what it must show, so you can look at each new image |
-| `pnpm case:check [case-id]` | fails on an incomplete card or bad values; warns on an image check with no card |
+| `pnpm case:check [case-id]` | fails on an incomplete card, bad values, a marker inside a question or a question under a marked line; warns on an image check with no card and on a marker that does not say what to decide |
+| `pnpm markers:confirm --case <id> --env <env> [--report <run-id>]` | after a passing run, removes the `🔍 to be confirmed` markers whose line the spec checks with `// unconfirmed:`; `--dry-run` lists them |
 | `pnpm pdf:render <file.pdf> --out <dir> [--pages all] [--corner top-left]` | renders the pages to images and prints the text, to look at a PDF by hand |
 
 ## Customizing the prompts
@@ -225,11 +264,12 @@ A project refines a skill with a **flat override file**, named after the skill (
 The command and the skill read it; it is not discovered as a standalone skill. Rules combine in this order, and a
 later one wins where they conflict:
 
-1. `F1`–`F6` of the framework baseline: safety, in every project. Nothing can change them.
+1. `F1`–`F6` and `R2` of the framework baseline: safety, in every project. Nothing can change them.
 2. The framework baseline, `<framework>/AGENTS.md`.
 3. The framework skill.
 4. The project override `.claude/skills/<skill>.md`.
 5. The project's own `AGENTS.md` §2 (Project rules).
+6. A case's `## Rules`: how to run that one case, never what is true.
 
 An override is plain Markdown; write only what differs:
 
@@ -241,8 +281,8 @@ An override is plain Markdown; write only what differs:
 - The staging account has no published documents: assert the empty state there instead.
 ```
 
-The project's `AGENTS.md` §2 is the other place: a table of rule ids (`F7`–`F10`; `F1`–`F6` are fixed) with `narrows`
-(stricter) or `replaces` (a different default). For example, a project that writes cases in Simplified Chinese
+The project's `AGENTS.md` §2 is the other place: a table of rule ids (`F7`–`F10`, `R1`, `R3`, `R4`; `F1`–`F6` and
+`R2` are fixed) with `narrows` (stricter) or `replaces` (a different default). For example, a project that writes cases in Simplified Chinese
 `replaces` `F10`. `pnpm asrun doctor` fails on an unknown id, a missing `Effect`, or a non-negotiable rule, and lists
 the overrides it sees.