@asrunjs/asrun 0.8.0 → 0.10.0

package/dist/ui/server/process-info.d.ts

@@ -0,0 +1,17 @@
+export interface ProcessDetails {
+    /** The command line the system reports, empty when the platform could not read it. */
+    commandLine: string;
+    /** Milliseconds since the Unix epoch, or null when the platform could not report it. */
+    startedAt: number | null;
+}
+/**
+ * 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 declare function probeProcesses(pids: number[]): Map<number, ProcessDetails | null>;
+/**
+ * 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 declare function killProcessTree(pid: number, signal: NodeJS.Signals): void;

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

@@ -32,9 +32,15 @@ export interface AiRunOptions {
     attended?: boolean;
     /** Show the agent's reasoning in the log (`--thinking` for OpenCode). Off by default: it costs tokens and time. */
     thinking?: boolean;
-    /** `heal-spec` only: the profiles to heal. Omitted = every profile that is logged in in `env`. */
+    /**
+     * `explore-case` and `heal-spec` only: the profiles to open / heal. Omitted = every profile that applies in `env`
+     * (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 the user's description and 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;
@@ -48,7 +54,7 @@ export interface AiSession {
     id: string;
     resume: boolean;
 }
-/** The prompt of a one-shot run. `heal-spec` has no questions of its own, so it keeps the plain slash command. */
+/** 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 declare function headlessPrompt(command: AiCommand, caseId: string, options: AiRunOptions): string;
 /** Executable and arguments of the one-shot (non-interactive) run. */
 export declare function headlessInvocation(tool: AiTool, command: AiCommand, caseId: string, options: AiRunOptions, session?: AiSession): {

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

@@ -17,18 +17,20 @@ export const AI_COMMAND_WRITES = {
  * Agents never write data in any of them: a person does those steps.
  */
 export const AI_ENV_HINT = {
-    'explore-case': 'Where the agent explores. It only reads; with Attended on, you do the steps that write data.',
+    'explore-case': 'Where the agent explores. Only the profiles you tick are opened; it only reads, and with Attended on you do the steps that write data.',
     'gen-spec': 'Where the agent explores and verifies the spec.',
-    'heal-spec': 'Where the failing spec is diagnosed. Only the profiles that are logged in there are run.',
+    'heal-spec': 'Where the failure is diagnosed and the pages are checked. Only the profiles that are logged in there are run.',
 };
 export const slashCommand = (command, caseId, options) => {
     const { env, force, attended, profiles, hints, report } = options;
     const heal = command === 'heal-spec';
+    // gen-spec has no profile option: its scope is every profile the case names.
+    const picksProfiles = command === 'explore-case' || heal;
     return (`/${command} ${caseId} ${env}${force && command === 'gen-spec' ? ' --force' : ''}` +
         `${attended && command === 'explore-case' ? ' --attended' : ''}` +
-        `${heal && profiles?.length ? ` --profiles ${profiles.join(',')}` : ''}` +
+        `${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__*';
@@ -50,6 +52,7 @@ function claudeAllowedTools(writes) {
         'Edit(/tests/**)',
         'Bash(pnpm typecheck:*)',
         'Bash(pnpm spec:lint:*)',
+        'Bash(pnpm markers:confirm:*)',
         nodeTsx,
         'Bash(pnpm baselines:review:*)',
     ];
@@ -69,7 +72,9 @@ const STREAM_ARGS = {
     opencode: ['--format', 'json'],
 };
 function invocation(tool, prompt, writes, session, model, thinking) {
-    // OpenCode creates the session when the id does not exist yet, and continues it when it does.
+    // OpenCode creates the session when the id does not exist yet, and continues it when it does. It also keeps the
+    // agent (build/plan) on the session, so a session started in plan mode would only propose changes and ask a question
+    // nobody can answer; every one-shot run is a build run, whatever the session it continues.
     // A model is named on every run: without one OpenCode falls back to its built-in free model, which has a daily
     // usage limit, and nothing in the CLI's own state (the TUI's last-used model) applies to a one-shot run.
     if (tool === 'opencode')
@@ -78,6 +83,8 @@ function invocation(tool, prompt, writes, session, model, thinking) {
             args: [
                 'run',
                 '--auto',
+                '--agent',
+                'build',
                 ...STREAM_ARGS.opencode,
                 ...(session ? ['-s', session.id] : []),
                 ...(model ? ['--model', model] : []),
@@ -105,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.
@@ -120,12 +135,10 @@ 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.';
-/** The prompt of a one-shot run. `heal-spec` has no questions of its own, so it keeps the plain slash command. */
+    `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);
-    if (command === 'heal-spec')
-        return slash;
     if (command === 'explore-case' && options.attended)
         return `${slash} ${ATTENDED}`;
     return `${slash} ${NON_INTERACTIVE}`;
@@ -155,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) {
@@ -170,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. */
@@ -103,9 +118,9 @@ export type StartJobRequest = {
      * its built-in free model. `heal-spec` keeps the model of the run it continues.
      */
     model?: string;
-    /** `heal-spec` only: the profiles to heal; omitted = every profile that is logged in. */
+    /** `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,6 +218,7 @@ 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.