@asrunjs/asrun 0.10.0 → 0.12.0

package/dist/scripts/doctor.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
+import { readWorkspaceConfig } from '../lib/config.js';
+import { readProjectRules, mentionedTestDataPrefixes } from '../lib/rules.js';
 import { spawnTarget } from '../lib/command.js';
 import { migrationState, pendingMigrations } from '../lib/migrations.js';
 import { MIGRATIONS } from '../migrations/index.js';
@@ -22,29 +24,6 @@ function read(file) {
         return null;
     }
 }
-/** The ids of the framework rules that a project may not narrow, parsed from the framework's AGENTS.md. */
-function nonNegotiableRules() {
-    const ids = new Set();
-    for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
-        const match = /^- \*\*([A-Z]\d+)\b/.exec(line.trim());
-        if (match && line.includes('[non-negotiable]'))
-            ids.add(match[1]);
-    }
-    return ids;
-}
-/**
- * Every rule id the framework baseline defines (`F1`..`F10`, `B1`..`B4`, `A1`..`A6`, `R1`..`R4`), so a project cannot
- * name one that does not exist.
- */
-function frameworkRuleIds() {
-    const ids = new Set();
-    for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
-        const match = /^- \*\*([A-Z]\d+)\b/.exec(line.trim());
-        if (match)
-            ids.add(match[1]);
-    }
-    return ids;
-}
 /**
  * The framework sources that `pnpm build` compiles into `dist/` and are older than it, or missing from it. Only the
  * framework repository has those sources; an installed package ships `dist/` alone, so the list is empty there.
@@ -253,8 +232,8 @@ export async function main(args) {
             warnings.push(`.claude/skills/${name} is a copy of the framework skill; delete it, or it will never see an update.`);
         }
     }
-    // Project rules: a project may narrow or replace a baseline rule, never one of F1–F6. Rows are
-    // `| <id> | <the project's rule> | <narrows|replaces> |`.
+    // Project rules: a project may narrow or replace a baseline rule, never one of F1–F6/R2, and may add its own rule
+    // under a project id. Rows are `| <id> | <the project's rule> | <narrows|replaces|adds> |`.
     const agents = read(path.join(ROOT, 'AGENTS.md'));
     if (agents === null) {
         warnings.push('AGENTS.md is missing: run "pnpm asrun init" and fill in the project facts.');
@@ -263,30 +242,30 @@ export async function main(args) {
         if (!agents.includes(`${framework}/AGENTS.md`)) {
             errors.push(`AGENTS.md does not point at the framework baseline (${framework}/AGENTS.md).`);
         }
-        const locked = nonNegotiableRules();
-        const known = frameworkRuleIds();
-        let fenced = false;
-        for (const line of agents.split('\n')) {
-            // A fenced block is documentation (an example table), not the project's rules.
-            if (line.trim().startsWith('```')) {
-                fenced = !fenced;
-                continue;
+        const project = readProjectRules(path.join(ROOT, 'AGENTS.md'));
+        errors.push(...project.errors);
+        warnings.push(...project.warnings);
+        if (project.rules.length > 0) {
+            facts.push(`project rules: ${project.rules.map((rule) => `${rule.id} (${rule.effect || '?'})`).join(', ')}`);
+        }
+    }
+    // The project's own settings (`package.json` "asrun"): a bad prefix makes every write case fail, so it is an error.
+    let prefix = null;
+    try {
+        prefix = readWorkspaceConfig().testDataPrefix;
+        facts.push(`test data: ${prefix} <base> (<run stamp>)`);
+    }
+    catch (error) {
+        errors.push(error.message);
+    }
+    // A document that names another test-data prefix cannot change the runtime: report it instead of letting a generated
+    // spec use one prefix while the case document says another.
+    if (agents !== null && prefix !== null) {
+        for (const mention of mentionedTestDataPrefixes(agents)) {
+            if (mention.token !== prefix) {
+                errors.push(`AGENTS.md:${mention.line} names ${mention.token} as the test-data prefix, but package.json has ` +
+                    `"asrun.testDataPrefix": "${prefix}". Set it to "${mention.token}" (the runtime reads package.json, not prose).`);
             }
-            if (fenced)
-                continue;
-            const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
-            if (!/^F\d+$/.test(cells[0]))
-                continue;
-            const id = cells[0];
-            const effect = (cells[2] ?? '').toLowerCase();
-            if (!known.has(id))
-                errors.push(`AGENTS.md names ${id}, which is not a rule of the framework baseline.`);
-            else if (locked.has(id))
-                errors.push(`AGENTS.md changes ${id}, which the framework marks [non-negotiable].`);
-            else if (effect === '')
-                warnings.push(`AGENTS.md rule ${id} has no Effect column: add "narrows" or "replaces" (a table written before 0.3.0 predates it).`);
-            else if (effect !== 'narrows' && effect !== 'replaces')
-                errors.push(`AGENTS.md rule ${id} has Effect "${cells[2]}"; use "narrows" or "replaces".`);
         }
     }
     // The install and the commands the docs use.

package/dist/scripts/explore-notes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/explore-notes.js

@@ -0,0 +1,131 @@
+import path from 'node:path';
+import { isValidCaseId } from '../lib/case-id.js';
+import { caseSha256, exploreNotesDir, exploreNotesFile, noteFreshness, readExploreNotes, } from '../lib/explore-notes.js';
+import { ROOT } from '../lib/paths.js';
+import { loadProfiles } from '../lib/profiles.js';
+const USAGE = `Usage: pnpm explore:notes <case-id> [--profile <profile-id>] [--json] [--check] [--hash]
+
+Prints the exploration notes /explore-case wrote for a case under .explore/notes/<case-id>/.
+They are local, git-ignored and optional: /gen-spec reads a fresh one to verify instead of rediscovering the page,
+and falls back to a full replay when it is missing or stale.
+
+  --profile <id>  only this profile's note
+  --json          the parsed notes (and any errors) as JSON, for a run that reads them
+  --check         validate every note; fails on a malformed file, warns on a stale one
+  --hash          print the case file's sha256, for "caseSha256" in a note
+
+Paths are relative to the workspace root (${ROOT}).`;
+const args = process.argv.slice(2);
+let caseId;
+let profile;
+let json = false;
+let check = false;
+let hash = false;
+let help = false;
+for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h')
+        help = true;
+    else if (arg === '--json')
+        json = true;
+    else if (arg === '--check')
+        check = true;
+    else if (arg === '--hash')
+        hash = true;
+    else if (arg === '--profile') {
+        const value = args[++index];
+        if (value === undefined || value.startsWith('--')) {
+            console.error(`--profile needs a profile id.\n\n${USAGE}`);
+            process.exit(2);
+        }
+        profile = value;
+    }
+    else if (!arg.startsWith('--') && caseId === undefined)
+        caseId = arg;
+    else {
+        console.error(`Unexpected argument: ${arg}\n\n${USAGE}`);
+        process.exit(2);
+    }
+}
+if (help) {
+    console.log(USAGE);
+    process.exit(0);
+}
+if (caseId === undefined) {
+    console.error(USAGE);
+    process.exit(1);
+}
+if (!isValidCaseId(caseId)) {
+    console.error(`"${caseId}" is not a valid case id (one optional group folder, for example documents/landing-page).`);
+    process.exit(1);
+}
+if (hash) {
+    const value = caseSha256(caseId);
+    if (value === null) {
+        console.error(`cases/${caseId}.md does not exist.`);
+        process.exit(1);
+    }
+    console.log(value);
+    process.exit(0);
+}
+const { notes, errors } = readExploreNotes(caseId, profile);
+const relative = (file) => path.relative(ROOT, file).split(path.sep).join('/');
+if (json) {
+    console.log(JSON.stringify({
+        caseId,
+        notes: notes.map((note) => ({ ...note, freshness: noteFreshness(note) })),
+        errors: errors.map((error) => ({ file: relative(error.file), problems: error.problems })),
+    }, null, 2));
+}
+else {
+    console.log(`Exploration notes for cases/${caseId}.md (${relative(exploreNotesDir(caseId))})`);
+    if (notes.length === 0)
+        console.log('  none yet: /gen-spec replays the case.');
+    for (const note of notes) {
+        console.log(`  ${note.profile.padEnd(24)} ${describe(note)}`);
+    }
+}
+let failed = false;
+for (const error of errors) {
+    failed = true;
+    for (const problem of error.problems)
+        console.log(`FAIL ${relative(error.file)}: ${problem}`);
+}
+if (check) {
+    const value = caseSha256(caseId);
+    if (value === null) {
+        failed = true;
+        console.log(`FAIL cases/${caseId}.md does not exist`);
+    }
+    const known = new Set(knownProfiles());
+    for (const note of notes) {
+        const freshness = noteFreshness(note);
+        if (freshness.state !== 'fresh') {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: ${freshness.reason}; current caseSha256 is ${value ?? '(unknown)'}`);
+        }
+        if (!known.has(note.profile)) {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: "${note.profile}" is not in profiles.yaml`);
+        }
+    }
+    if (failed) {
+        console.error('\nA note that fails here is ignored by /gen-spec. Fix it, or delete it and let the case be replayed.');
+        process.exit(1);
+    }
+}
+function describe(note) {
+    const freshness = noteFreshness(note);
+    const steps = Object.keys(note.steps)
+        .sort((a, b) => Number(a) - Number(b))
+        .join(',');
+    const targets = Object.keys(note.targets ?? {}).sort().join(',');
+    const state = freshness.state === 'fresh' ? 'fresh' : `stale (${freshness.reason})`;
+    return `${state}  steps ${steps || '-'}  targets ${targets || '-'}  captured ${note.capturedAt}${note.updatedAt ? `  refreshed ${note.updatedAt}` : ''}`;
+}
+function knownProfiles() {
+    try {
+        return loadProfiles().map((entry) => entry.id);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/scripts/lint-specs.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { listCaseFileIds } from '../lib/cases.js';
+import { caseWrites, hasCaseFile, listCaseFileIds, readCaseMeta } from '../lib/cases.js';
 import { TESTS_DIR } from '../lib/paths.js';
 import { parseTargets, readCaseText, TARGET_REF } from '../lib/targets.js';
 const specFiles = (dir) => fs.existsSync(dir)
@@ -125,6 +125,28 @@ function lint(file) {
                 add('fail', i, 'blocking-target', `${match[1]} still has an open [blocking] question in the case; do not build a check on it (use test.fixme).`);
         }
     });
+    // Test data names must be unique per run (F11): a writes case names what it creates with testDataName().
+    // Old specs predate the rule, so this is a warning: regenerate or heal them to clear it.
+    if (caseId !== undefined && hasCaseFile(caseId) && caseWrites(readCaseMeta(caseId))) {
+        const text = lines.join('\n');
+        const composed = new Set([...text.matchAll(/(?:const|let)\s+(\w+)\s*=\s*(?:await\s+)?testDataName\s*\(/g)].map((match) => match[1]));
+        lines.forEach((line, i) => {
+            if (!/\brecords\.track\s*\(/.test(line))
+                return;
+            for (let end = i; end < Math.min(lines.length, i + 15); end++) {
+                const match = /^\s*name:\s*(.*?),?\s*$/.exec(lines[end]);
+                if (match === null)
+                    continue;
+                const expression = match[1].trim();
+                if (/testDataName\s*\(/.test(expression))
+                    return;
+                if (/^[A-Za-z_$][\w$]*$/.test(expression) && composed.has(expression))
+                    return;
+                add('warn', end, 'test-data-name', `records.track() names the data "${expression}"; build it with testDataName() so the run's name carries its timestamp (F11).`);
+                return;
+            }
+        });
+    }
     TARGET_REF.lastIndex = 0;
     return findings;
 }

package/dist/scripts/rules.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/rules.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { caseSectionText } from '../lib/case-doc.js';
+import { readWorkspaceConfig } from '../lib/config.js';
+import { ROOT } from '../lib/paths.js';
+import { baselineRules, checkProjectRules, describeProjectRule, mentionedTestDataPrefixes, parseProjectRules, } from '../lib/rules.js';
+import { testDataStamp } from '../lib/records.js';
+/**
+ * `pnpm asrun rules`: the effective rules of this workspace, as one digest. An AI step reads this before it applies
+ * anything, so "§2 wins over the baseline" is a fact it was told rather than a layer it has to reason about. It never
+ * writes anything. `--json` is the machine-readable form; `--case <id>` adds that case's `## Rules`.
+ */
+const USAGE = `Usage: pnpm asrun rules [--json] [--case <case-id>]
+
+Prints the framework baseline, the project's AGENTS.md §2 rules and the project settings
+(test-data prefix, name format). --case <id> adds the case's own "## Rules".
+Exit code 1 when §2 or a setting is invalid (the same errors "pnpm asrun doctor" shows).`;
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const json = args.includes('--json');
+const caseIndex = args.findIndex((arg) => arg === '--case' || arg.startsWith('--case='));
+const caseId = caseIndex === -1 ? null : (args[caseIndex].includes('=') ? args[caseIndex].split('=')[1] : args[caseIndex + 1]);
+if (caseIndex !== -1 && !caseId) {
+    console.error('Usage: pnpm asrun rules [--json] [--case <case-id>]\n  --case needs a case id.');
+    process.exit(1);
+}
+const agentsFile = path.join(ROOT, 'AGENTS.md');
+let agentsText;
+try {
+    agentsText = fs.readFileSync(agentsFile, 'utf8');
+}
+catch {
+    console.error(`No AGENTS.md in ${ROOT}: run "pnpm asrun init" first.`);
+    process.exit(1);
+}
+const baseline = baselineRules();
+const project = checkProjectRules(parseProjectRules(agentsText), baseline);
+let config = null;
+let configError = null;
+try {
+    config = readWorkspaceConfig();
+}
+catch (error) {
+    configError = error.message;
+}
+let caseRules = [];
+if (caseId !== null) {
+    const caseFile = path.join(ROOT, 'cases', `${caseId}.md`);
+    try {
+        const text = fs.readFileSync(caseFile, 'utf8');
+        const section = caseSectionText(text, 'Rules');
+        let current = null;
+        const flush = () => {
+            if (current !== null && current.length > 0)
+                caseRules.push({ text: current.join(' ') });
+            current = null;
+        };
+        for (const raw of section.split('\n')) {
+            if (/^-\s+\S/.test(raw.trim())) {
+                flush();
+                current = [raw.trim()];
+            }
+            else if (current !== null && /^\s+\S/.test(raw)) {
+                current.push(raw.trim());
+            }
+            else if (raw.trim() === '') {
+                flush();
+            }
+        }
+        flush();
+    }
+    catch {
+        console.error(`Case "${caseId}" not found (expected cases/${caseId}.md).`);
+        process.exit(1);
+    }
+}
+const prefix = config?.testDataPrefix ?? '';
+const stamp = testDataStamp();
+const errors = [...project.errors, ...(configError === null ? [] : [configError])];
+const prefixMentions = mentionedTestDataPrefixes(agentsText);
+if (config !== null) {
+    for (const mention of prefixMentions) {
+        if (mention.token !== config.testDataPrefix) {
+            errors.push(`AGENTS.md:${mention.line} names ${mention.token} as the test-data prefix, but package.json has ` +
+                `"asrun.testDataPrefix": "${config.testDataPrefix}". Set it to "${mention.token}" (the runtime reads package.json, not prose).`);
+        }
+    }
+}
+if (json) {
+    console.log(JSON.stringify({
+        workspace: ROOT,
+        baseline: baseline.map((rule) => ({ id: rule.id, locked: rule.locked, text: rule.text })),
+        projectRules: project.rules,
+        projectWarnings: project.warnings,
+        settings: { testDataPrefix: config?.testDataPrefix ?? null, testDataNameExample: `${prefix} <base> (${stamp})` },
+        prefixMentions,
+        ...(caseId !== null && { case: { id: caseId, rules: caseRules } }),
+        errors,
+    }, null, 2));
+}
+else {
+    const byLetter = new Map();
+    for (const rule of baseline) {
+        const letter = rule.id[0];
+        byLetter.set(letter, [...(byLetter.get(letter) ?? []), rule.id]);
+    }
+    console.log(`AsRun rules for ${ROOT}\n`);
+    console.log('Framework baseline:');
+    for (const [letter, ids] of byLetter) {
+        console.log(`  ${letter}: ${ids[0]}–${ids[ids.length - 1]}`);
+    }
+    const locked = baseline.filter((rule) => rule.locked).map((rule) => rule.id);
+    console.log(`  [non-negotiable]: ${locked.join(', ')}`);
+    console.log('\nProject rules (AGENTS.md §2):');
+    if (project.rules.length === 0)
+        console.log('  (none: the baseline defaults apply unchanged)');
+    else
+        for (const rule of project.rules)
+            console.log(`  ${describeProjectRule(rule)}`);
+    console.log('\nProject settings:');
+    console.log(`  testDataPrefix: ${config?.testDataPrefix ?? '(invalid)'}   ` +
+        `(package.json "asrun.testDataPrefix"; default [asrun])`);
+    console.log(`  test data name: ${prefix || '[asrun]'} <base> (${stamp})   (UTC, from the run id)`);
+    if (caseId !== null) {
+        console.log(`\nCase rules (cases/${caseId}.md §Rules):`);
+        if (caseRules.length === 0)
+            console.log('  (none)');
+        else
+            for (const rule of caseRules)
+                console.log(`  - ${rule.text.replace(/^-\s+/, '')}`);
+    }
+    if (project.warnings.length > 0) {
+        console.log('');
+        for (const warning of project.warnings)
+            console.log(`! ${warning}`);
+    }
+    if (errors.length > 0) {
+        console.log('');
+        for (const error of errors)
+            console.log(`x ${error}`);
+        console.log('\nFix the errors above; the rules are not applied until they are valid.');
+    }
+    console.log('\nA project rule is applied as written: a difference from the baseline is never a conflict and never a question.');
+}
+process.exit(errors.length > 0 ? 1 : 0);

package/docs/agents/case-format.md

@@ -89,7 +89,7 @@ Wrong: `- Create a draft named ... and delete it at the end.` (a write → a tag
 - `- Ready when:` is a sub-line of the step: the positive signal that what the step loads is there. The spec waits
   for it before reading; it is not an assertion.
 - `- Recipe (phase):` is a sub-line of an `[input]`/`[writes]` step: what a person did in the browser during an
-  attended exploration (positions, `[asrun]` names, control labels; no selectors). A tagged step with no recipe is a
+  attended exploration (positions, created names, control labels; no selectors). A tagged step with no recipe is a
   `needs-input` stop for `/gen-spec`.
 - 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
@@ -121,7 +121,8 @@ example-staging:
 - A profile with no entry and no `default` fails with "Missing values ...". An empty value or one that starts with
   `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`.
+  `## Expected`, and selectors come from `## Targets`. A name the case creates is stored here **without** its run
+  stamp: the literal is the base, and the spec composes `<base> (<run stamp>)` with `testDataName()` (F11).
 - 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.
 
@@ -201,9 +202,11 @@ test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
   a case limited to some environments is skipped elsewhere; a case that writes elsewhere only is skipped with a
   notice; a write in a non-staging environment needs the confirmation the CLI sets, never an environment variable
   that was merely present.
-- Write cases: name everything `[asrun] ...`, register it with `records.track` right after creating it, remove it
-  newest first (also after a failure), turn retries off with `configureCase`, and keep email steps behind
-  `emailStepAllowed(profile, '<step title>')`.
+- Write cases: name everything `<prefix> <base> (<run stamp>)` through `testDataName(base)`
+  (`@asrunjs/asrun/records`), where the prefix is `asrun.testDataPrefix` in `package.json` (default `[asrun]`, printed
+  by `pnpm asrun rules`) and the stamp is the run's UTC time; register it with `records.track` right after creating
+  it, remove it newest first (also after a failure), turn retries off with `configureCase`, and keep email steps
+  behind `emailStepAllowed(profile, '<step title>')`.
 
 ## Checks to run before reporting
 
@@ -223,5 +226,6 @@ In the framework package:
 - `.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

@@ -83,17 +83,21 @@ publishes, shares or deletes anything, in staging or in production. It:
 - 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
 case keeps what the earlier runs recorded. In the web UI the profile picker of the toolbar does the same: every profile
 that is logged in in that environment is ticked, and the list you tick is remembered for the next run there.
 
-**To accept the suggestion, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
-again. In the web UI, the run's **What to do next** bar offers **Answer**: the question list, an answer box,
-**Use the suggested defaults** and **Generate spec**. A continued job keeps the same conversation and permissions, and
-can be continued once per turn, only while the UI server has not restarted.
+**To keep what the case says, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
+again. In the web UI the panel calls the first action **Keep what the case says**. The run's **What to do next** bar
+offers **Answer**: the question list, an answer box, **Use the suggested defaults** and **Generate spec**. A continued
+job keeps the same conversation and permissions, and can be continued once per turn, only while the UI server has not
+restarted.
 
 ### Attended exploration (`--attended`)
 
@@ -106,9 +110,10 @@ the browser window opens and the agent waits while you do those steps.
 - 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.
+  (`- Recipe (phase): ...`): positions instead of names of changeable data, created names (project prefix plus the
+  run's UTC stamp), control labels but no selectors.
+- Delete the test items you created (they start with the project's test-data prefix and carry this run's timestamp)
+  before you press Done on the last step.
 - Without `--attended` the agent never waits: a step that needs a person becomes a `TODO [blocking]`.
 
 In the web UI the **Attended** box is ticked by default for Explore.
@@ -138,6 +143,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
@@ -213,6 +223,10 @@ Several binding rules hold in exploring, generating and healing. They live in th
 - **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.
+- **Test data is findable per run.** Everything a write case creates is named with the project's test-data prefix
+  (`package.json` `"asrun"`, default `[asrun]`) and the run's UTC stamp: `testDataName()` builds
+  `[autotest] Draft CMA (2026-11-09 12-34-56)`. Two runs never share a name, the stamp matches `reports/<run-id>`, and
+  a person can search the product for one run's data. The case's `## Values` holds the base without the stamp.
 - **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
@@ -232,9 +246,10 @@ Checks you can run yourself:
 
 | Command | What it checks |
 |---|---|
-| `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 spec:lint [case-id]` | fails on screenshots without a target, `.first()` on images, sleeps, `networkidle`, raw download events, a `%PDF` check on its own; warns when a tracked test-data name is not built with `testDataName()` |
 | `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, 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 asrun rules [--json] [--case <id>]` | prints the effective rules (baseline, §2, project settings) the AI steps read; fails on an invalid §2 row or `testDataPrefix` |
 | `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 |
 
@@ -273,10 +288,12 @@ 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`, `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.
+The project's `AGENTS.md` §2 is the other place: a table of rule ids (`F7`–`F11`, `R1`, `R3`, `R4`; `F1`–`F6` and
+`R2` are fixed) with `narrows` (stricter) or `replaces` (a different default). A rule the baseline does not have gets
+a project id (`P1`, `P2`, ...) and `adds`. For example, a project that writes cases in Simplified Chinese `replaces`
+`F10`. `pnpm asrun doctor` fails on an unknown id, a missing `Effect`, a duplicate id, a non-negotiable rule or a
+project id without `adds`, and `pnpm asrun rules` prints the effective set (the AI steps read it before they apply
+anything). A project rule is applied as written: a difference from the baseline is never a question.
 
 An update never overwrites `AGENTS.md`, `CLAUDE.md` or `.claude/skills/**`: `pnpm asrun init --force` refuses them
 without `--reset-rules`. Never edit the framework package itself.

package/docs/cases.md

@@ -110,13 +110,14 @@ report and the trace read like the case.
   choice (an existing document, items), `[email]` for a step that sends email. They are written at the end of the
   step line.
 - **`- Recipe (phase):`** under a tagged step records what a person did in the browser during an attended
-  exploration: positions instead of names of changeable data (`select items #1 to #3`), `[asrun]` names for created
-  data, control labels but no selectors. Several lines per step are normal. A tagged step with no recipe is not
-  generated: `/gen-spec` stops with `needs-input`.
+  exploration: positions instead of names of changeable data (`select items #1 to #3`), created names (project prefix
+  plus run stamp), control labels but no selectors. Several lines per step are normal. A tagged step with no recipe is
+  not generated: `/gen-spec` stops with `needs-input`.
 - **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about,
   with the agent's suggestion written above and a last line `- ✍️ Answer:`. Accepting a question means deleting the
-  whole block; answering means writing after `Answer:`. Hang the block under the sentence that makes the claim, not
-  under a broader one above it, and one claim gets one block.
+  whole block; answering means writing after `Answer:`. In the web panel the two actions are **Keep what the case
+  says** and **Write your answer**. Hang the block under the sentence that makes the claim, not under a broader one
+  above it, and one claim gets one block.
 - **What the AI saw** is marked by what happens if it is wrong: `(seen on <profile>)` is a plain note the run checks by
   itself, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` is a line that would pass even
   if it were wrong, so a person settles it. A marker may name a screenshot (`evidence: .explore/.../x.png`) so nobody
@@ -173,7 +174,10 @@ anything.
 
 A case may write only in the environments listed under `writes`, and only data of the test account:
 
-- everything it creates is named `[asrun] ...` (the `records` fixture refuses other names);
+- everything it creates is named with the project's prefix and the run stamp, `<prefix> <base> (<run stamp>)`
+  (prefix: `asrun.testDataPrefix` in `package.json`, default `[asrun]`; stamp: the run's UTC time). The spec builds
+  the name with `testDataName()` (`records` refuses a name without the prefix), so two runs never collide and a
+  person can search the product for one run's data. `## Values` holds the base without the stamp;
 - created data is registered with `records.track` and removed after the test, also after a failure;
 - the case's own last step is normally the deletion; `track` is the safety net;
 - staging needs no confirmation. In any other environment a person confirms every run (typing the environment name,
@@ -207,7 +211,7 @@ that cannot be answered in place.
 
 ## Rename or move a case
 
-Use the Cases page (click the file name or the pencil icon). The spec and the baseline images move with it and the
-spec is rewritten to match. By hand, move the three things together (`cases/...md`, `tests/...spec.ts`, its
-`*-snapshots/`), and keep the spec's `// case:` line and its imports unchanged: specs import the framework by package
-name, so their folder depth does not change the imports.
+Use the Cases page (open the case, then **Rename or move** in the **⋯** menu at the end of the tab strip). The spec
+and the baseline images move with it and the spec is rewritten to match. By hand, move the three things together
+(`cases/...md`, `tests/...spec.ts`, its `*-snapshots/`), and keep the spec's `// case:` line and its imports
+unchanged: specs import the framework by package name, so their folder depth does not change the imports.