@asrunjs/asrun 0.10.0 → 0.12.0

package/.claude/skills/generating-specs/SKILL.md

@@ -9,8 +9,10 @@ Read `references/conventions.md` first. It defines the spec shape, fixtures, ass
 the read-only rules. Read the workspace `AGENTS.md` for the hard rules and the project rules. Read `../exploring-cases/references/open-questions.md`: it
 defines how open questions are written into the case file, resolved and reported. Also read
 `../exploring-cases/references/case-rules.md` (how a case's `## Rules` are read, applied and maintained),
-`../exploring-cases/references/assertion-targets.md` (the exact thing each check looks at) and
-`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts). All four are binding here.
+`../exploring-cases/references/assertion-targets.md` (the exact thing each check looks at),
+`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts),
+`../exploring-cases/references/notes.md` (the local exploration note this run reads first) and
+`../exploring-cases/references/tools.md` (the browser tools this MCP can run). All six are binding here.
 
 This skill never stops to ask the user in the chat, because it may run without anybody present (a one-shot
 `claude -p` / `opencode run`). This holds whatever mode or agent the run is in: plan mode changes what you may write,
@@ -35,10 +37,15 @@ spec afterwards (see the report). Healing (below) is the exception: it reads the
 and the spec, and runs only the profiles that are logged in, and only when the report is not enough.
 
 ## Before you start
-Read the workspace `AGENTS.md`: its §2 holds the project rules, and it points at the framework baseline. If
-`.claude/skills/generating-specs.md` exists in the workspace, read it and apply it after this skill. Then apply
-`AGENTS.md` §2, which wins over both (the baseline, "Precedence"). F1–F6 and R2 always win. This is not a stop
-condition: continue with the procedure below.
+Run `pnpm asrun rules --json` (or `pnpm asrun rules` for people): it prints the framework baseline, the project's
+`AGENTS.md` §2 rules and the project settings (the test-data prefix). Those are the effective rules; if the command is
+unavailable, read the workspace `AGENTS.md` directly. Also read `AGENTS.md` §2, and `.claude/skills/generating-specs.md`
+in the workspace, applying the override after this skill and §2 after both (the baseline, "Precedence"). F1–F6 and R2
+always win. **Never turn a project rule into a question:** a difference between §2 and a framework default is not a
+conflict; apply §2 and, if a row's id does not fit its text, apply the text and report the mismatch. This is not a stop
+condition: continue with the procedure below. If `pnpm asrun rules` exits 1 (an invalid §2 row or a prefix that the
+document and `package.json` disagree on), do not guess and do not turn it into a case question: report its errors and
+end with `RESULT: needs-input`; a person fixes `AGENTS.md` or `package.json` first.
 
 ## Inputs
 - The case id and the environment to explore in (`staging` or `production`). There is no default. If the
@@ -116,42 +123,42 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
      never for what the check asserts about it: that goes to `test.fixme` with the reason, or `needs-input`.
    - Do not invent expected values. If the case's `## Values` and the spec disagree, the case wins: fix the spec and
      mention the change in the report.
-3. **Check sessions** if `login: required`: run `pnpm status --env <env>`. If a profile needs login, tell the
-   user to run `pnpm signin <profile-id>` and continue with the profiles that are ready. A profile the case holds
-   information for is never dropped because it is not logged in: write its part from the case and mark it
-   `not verified on the page` in the report. If `pnpm status` cannot run (a sandbox error such as `listen EPERM` or a
-   Chromium start failure), judge by the page instead: a page that lands on the login page means the profile is not
-   logged in.
-4. **Replay the case on the real page** with the `playwright-test` MCP. Read `../exploring-cases/references/tools.md`
-   first: that MCP lists tools it cannot run, and a call that answers `Tool "<name>" not found` means exactly that (the
-   server is up; use the substitute). If its tools are not registered in this session at all (no `browser_*` /
-   `generator_*` tool) or it reports that it failed to start, do not fall back to ad-hoc Playwright scripts: stop, tell
-   the user which MCP server is missing and to run `pnpm asrun doctor`, write no spec, and end with
-   `RESULT: needs-input`.
-   Call `generator_setup_page` with
-   `project=<profile-id>` (for example `example-staging`), `seedFile=tests/seed.spec.ts` and `plan=""`, then perform the
-   steps in the environment you were given (never ask for it; there is no default) to learn the locators.
+3. **Check sessions** if `login: required`: follow `../exploring-cases/references/tools.md`, "Starting a session". A
+   profile that needs login is named with `pnpm signin <profile-id>`, and the run continues with the profiles that are
+   ready. A profile the case holds information for is never dropped because it is not logged in: write its part from
+   the case and mark it `not verified on the page` in the report.
+4. **Replay the case on the real page** with the `playwright-test` MCP, following
+   `../exploring-cases/references/tools.md` ("Starting a session", "Short calls") and `readiness.md` ("Exploring"). If
+   its tools are not registered in this session at all (no `browser_*` / `generator_*` tool) or it reports that it
+   failed to start, do not fall back to ad-hoc Playwright scripts: stop, tell the user which MCP server is missing and
+   to run `pnpm asrun doctor`, write no spec, and end with `RESULT: needs-input`.
+   **Read each profile's exploration note first** (`../exploring-cases/references/notes.md`): run
+   `pnpm asrun explore:notes <case-id> --json`. A fresh note (its `caseSha256` matches the case) supplies the locator,
+   the request pattern and the target's match count for a step; confirm each on the page instead of rediscovering it,
+   and skip what it does not hold. A missing or stale note means the plain replay below. After confirming an entry of
+   a fresh note, you may write the verified locator or request back into that file (`updatedAt` gets the time); never
+   add a step or a target, and never touch a stale note. Say in the report what came from a note and what was
+   refreshed. Perform the steps in the environment you were given (never ask for it; there is no default).
    Do the read-only steps as written, and follow the `## Rules` that say how to prepare, wait or which control to
    avoid. **Never perform a step that writes or needs a choice**: the agent does not write
    data, in staging or in production, and it does not hand off to a person here or wait for one. A rule never
    authorizes one of those steps. Write those steps
-   of the spec from the `- Recipe:` lines under the step (positions, `[asrun]` names, control labels and roles that
+   of the spec from the `- Recipe:` lines under the step (positions, created names, control labels and roles that
    `/explore-case` recorded). Pages that only exist after such a step cannot be seen from here: write their locators
-   from what the recipe and the exploration notes say, mark them in the report as "not verified on the page", and
-   leave the first run of the spec (or `/heal-spec`) to confirm them. Do this for at least one logged-in profile
-   per domain (example.com and exampleshop.com differ in markup). A profile the case holds information for that is
-   not logged in is skipped and named in the report; its part is written from the case and marked `not verified` in
-   the assertion table. Use this exploration to answer the open points of step 2, and read each profile's value from
-   the case's `## Values`: open that profile's page only when a value or a behavior still has to be resolved for it.
-   Keep every browser call short (one action, about 60 s at most, a snapshot between steps, `{timeout: 5000}` when
-   something may not appear, no third retry): see "Keep every browser call short" in `../exploring-cases/SKILL.md`.
-   **Ready before you read, here too** (`readiness.md`): take a marker on `browser_network_requests`
-   (`static: false`), act, wait for the key requests above that mark and the content signal, then snapshot. The request
-   URL patterns for `actAndWait` and the `Ready when` signals of the case are taken from what you see here.
-   **Check every target on the page:** for each target card, find its `Identified by` locator, confirm that it matches
-   exactly one element and that this element is what `What` says (outline it with `locator.highlight()` and look at the
-   screenshot, see `tools.md`). A locator that matches several elements or the wrong one is fixed or becomes a
-   question, never `.first()`.
+   from a fresh note first, then from the recipe, and mark them in the report as "observed by explore on <profile>" or
+   "not verified on the page"; leave the first run of the spec (or `/heal-spec`) to confirm the latter. Do this for at
+   least one logged-in profile per domain (example.com and exampleshop.com differ in markup). A profile the case holds
+   information for that is not logged in is skipped and named in the report; its part is written from the case and
+   marked `not verified` in the assertion table. Use this exploration to answer the open points of step 2, and read each
+   profile's value from the case's `## Values`: open that profile's page only when a value or a behavior still has to be
+   resolved for it.
+   **Ready before you read, here too**: follow `readiness.md`. The request URL patterns for `actAndWait` come from a
+   fresh note or from `browser_network_requests` during this replay, never from a guess; the `Ready when` signal comes
+   from the case.
+   **Check every target on the page:** follow `../exploring-cases/references/assertion-targets.md`, "What the spec does
+   with a card (generating)". Confirm that the card's `Identified by` matches exactly one element and that this element
+   is what `What` says (outline it with `locator.highlight()` and look at the screenshot, see `tools.md`). A locator that
+   matches several elements or the wrong one is fixed or becomes a question, never `.first()`.
    Prefer `getByTestId` (the project uses `data-tn`), then role/label locators. No CSS chains or XPath.
    Update the case file with what you learned: fold observations into the right section, marked `(seen on <profile>)`
    or, for a literal the spec asserts, `(observed on <profile>, 🔍 to be confirmed: <what to decide>)`; remove the
@@ -179,7 +186,8 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    never decided by one `isVisible()` look (its `timeout` option is ignored): use `clickOptionalUntilHidden`
    (`@asrunjs/asrun/ready`) or a waiting `expect(...).toBeVisible({timeout})`; see `readiness.md`, "Optional confirmations".
 7. **Check the files**: run `pnpm typecheck`, `pnpm spec:lint <id>` and `pnpm case:check` (or `node --import tsx <framework>/scripts/check-cases.ts` if
-   it fails with a sandbox error such as `listen EPERM`). Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
+   it fails with a sandbox error such as `listen EPERM`). When you wrote an exploration note back, also run
+   `pnpm asrun explore:notes <id> --check --profile <profile-id>` for each profile you refreshed. Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
    into a question). Every lint `WARN` is handled too: fix it, or name it in the report with the reason it is acceptable.
    Then do the **self-review**: for each assertion answer in writing "if the product were broken, would this fail?"
    and "if the product is right, could this fail by timing?" (a check that cannot fail, or that races the page, is rewritten).
@@ -188,7 +196,8 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    Do NOT run `pnpm asrun`, do not use
    `--update-snapshots` and do not create baselines: the first run of the spec does that, and a person reviews them.
 8. **Report** in the user's language: spec path, **an assertion table** (step, what is asserted, target card, ready signal, and
-   `observed on the page` or `not verified`; no row may be missing), profiles explored, profiles skipped (and why),
+   `observed on the page` or `not verified`; no row may be missing), profiles explored, which steps were written from a
+   fresh exploration note and which notes were refreshed (or that there were none), profiles skipped (and why),
    the profiles of `profiles.yaml` the case holds no information for (they run on `default` alone), whether the case file was
    translated, what was added to the case file as `(seen on <profile>)` and which lines still need a person
    (`🔍 to be confirmed`, with the reason), checks generated from observations, visual checks that need a baseline on
@@ -203,11 +212,13 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
 
 ## Cases that write data
 Only when the case front matter lists environments under `writes` (for example `writes: [staging]`). Never add
-`--allow-writes` or set `ASRUN_ALLOW_WRITES`. Use the `records` fixture, `configureCase` and `emailStepAllowed` as
-described in `references/conventions.md`. The agent does not perform write steps while generating (see step 4); the
-spec does, when a person runs it in an environment that `writes` lists. Elsewhere the runner skips the case with a
-notice. Never send email in production; in other environments only if `profile.email` is true, otherwise skip that step and say so
-in the report.
+`--allow-writes` or set `ASRUN_ALLOW_WRITES`. Use the `records` fixture, `configureCase`, `testDataName` and
+`emailStepAllowed` as described in `references/conventions.md`. Every name the case creates is
+`testDataName(expected.<key>)`, using the base literal from `## Values` and the project prefix from
+`pnpm asrun rules`; use the composed value for the form, the locators and `records.track`. The agent does not perform
+write steps while generating (see step 4); the spec does, when a person runs it in an environment that `writes` lists.
+Elsewhere the runner skips the case with a notice. Never send email in production; in other environments only if
+`profile.email` is true, otherwise skip that step and say so in the report.
 
 ## Healing and refining a spec
 Inputs: the case id and the environment (both required, there is no default: without an environment stop and say so),
@@ -250,12 +261,15 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    leaves out the profiles that are not logged in instead of failing them. A profile that is not logged in is never healed:
    name it in the report with `pnpm signin <profile-id>`.
 4. **Look at the pages when the change depends on them.** Reading a page is not a run and is always allowed, also for an
-   improvement request with no failure behind it. Use the `playwright-test` MCP exactly as `/gen-spec` step 4 describes
-   (`generator_setup_page` with `project=<profile-id>`, one action per call, ready before you read). Do the read-only
+   improvement request with no failure behind it. Use the `playwright-test` MCP exactly as `/gen-spec` step 4 describes,
+   following `../exploring-cases/references/tools.md` ("Starting a session", "Short calls"), `readiness.md` and the
+   exploration note (`../exploring-cases/references/notes.md`). Do the read-only
    steps only: **never perform a step that writes or needs a choice**, in any environment. What you see goes into the
    case by the gate in `open-questions.md` ("Which sentences carry a marker"): `(seen on <profile>)` for a locator, a
    flow or a request, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` only for a
-   literal the spec asserts, so the person settles that in the review gate below.
+   literal the spec asserts, so the person settles that in the review gate below. If the note was stale, edit the case
+   as usual; if it was fresh, a verified locator may be written back
+   (`../exploring-cases/references/notes.md`).
 5. **Audit the assertion before you blame anyone.** Read the `assertion-targets.md` and `readiness.md` sections on healing.
    - Is the locator still what the target card says (`What`, `Identified by`)? Open the failure screenshot and the
      baseline (`pnpm baselines:review <case-id>`) and look at each: a baseline that shows something other than the card

package/.claude/skills/generating-specs/references/conventions.md

@@ -47,8 +47,12 @@ and `@writes` for cases that write data (drives `--read-only`).
   A case that writes only in some environments is skipped (not failed) in the others, with a notice.
 
 ## Cases that write data (`writes: [<env>, ...]`)
-- Name everything the case creates `[asrun] <something>` (`TEST_DATA_PREFIX` in `@asrunjs/asrun/records`). `records.track`
-  refuses other names, so cleanup can never touch real data.
+- Name everything the case creates through `testDataName(base)` (`@asrunjs/asrun/records`), where `base` is the
+  literal from the case's `## Values`: it returns `<prefix> <base> (<UTC run stamp>)`, for example
+  `[asrun] Draft CMA (2026-11-09 12-34-56)`. The prefix is the project's `asrun.testDataPrefix` (default `[asrun]`,
+  printed by `pnpm asrun rules`). `records.track` refuses a name without the prefix, and the stamp keeps two runs
+  apart so a person can find and delete one run's data. Compose a name once and use that variable for the form, the
+  locators, the assertions and `records.track`; never pass a raw `expected.*` value as the created name.
 - Register data with the `records` fixture right after creating it, together with the function that removes it:
   `await records.track({kind: 'Document draft', name, where: '/app/documents'}, async () => {...delete it from the documents list...});`
   Everything tracked is removed after the test, newest first, also when the test failed. The remove function opens

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

@@ -16,10 +16,15 @@ Read the workspace `AGENTS.md` (hard rules and project rules) and `cases/_templa
 This skill writes `cases/*.md` only. It never writes specs, `profiles.yaml`, or anything under `tests/`.
 
 ## Before you start
-Read the workspace `AGENTS.md`: its §2 holds the project rules, and it points at the framework baseline. If
-`.claude/skills/making-cases.md` exists in the workspace, read it and apply it after this skill. Then apply `AGENTS.md`
-§2, which wins over both (the baseline, "Precedence"). F1–F6 and R2 always win. This is not a stop condition:
-continue with the procedure below.
+Run `pnpm asrun rules --json` (or `pnpm asrun rules` for people): it prints the framework baseline, the project's
+`AGENTS.md` §2 rules and the project settings (the test-data prefix). Those are the effective rules; if the command is
+unavailable, read the workspace `AGENTS.md` directly. Also read `AGENTS.md` §2, and `.claude/skills/making-cases.md`
+in the workspace, applying the override after this skill and §2 after both (the baseline, "Precedence"). F1–F6 and R2
+always win. **Never turn a project rule into a question:** a difference between §2 and a framework default is not a
+conflict; apply §2 and, if a row's id does not fit its text, apply the text and report the mismatch. This is not a stop
+condition: continue with the procedure below. If `pnpm asrun rules` exits 1 (an invalid §2 row or a prefix that the
+document and `package.json` disagree on), do not guess and do not turn it into a case question: report its errors and
+stop before writing anything; a person fixes `AGENTS.md` or `package.json` first.
 
 ## Inputs
 - Raw notes: pasted text or a file path. Any language, any quality.
@@ -43,7 +48,9 @@ continue with the procedure below.
    with a clear message until it is filled), never into `profiles.yaml`.
 5. **Ask before writing.** Show the user a short plan and the open questions in one message: the proposed split
    into cases, the classification (which steps write, which send email), and the gaps with your suggested default
-   for each. Wait for answers. Do not write case files before that.
+   for each. Wait for answers. Do not write case files before that. **Never ask a project-wide question:** §2 and
+   `pnpm asrun rules` settle project policy (the test-data prefix, the language, a wait); apply them. Ask only about
+   this case's unknowns.
 6. **Split** (`references/splitting.md`) and **write** `cases/<id>.md` for each case from `cases/_template.md`.
    - Group folder: when the notes (or the user) name an area (documents, search, account...), put the cases in
      `cases/<group>/<name>.md` and set `id: <group>/<name>` in the front matter. Use one folder level and

package/.claude/skills/making-cases/references/writes-and-email.md

@@ -14,9 +14,12 @@ dialog (read-only) but sending the share is `[writes]` and probably `[email]`. W
 ## What a case with writes must look like
 - Front matter: `writes: [<env>, ...]`, the environments the finished spec may write in (`[staging]`; add `production`
   only when the notes or the user say so), and a `writes-note` that says what is created, changed and removed, in one
-  sentence ("Creates one draft document named '[asrun] ...', publishes it, deletes it at the end"). The `writes-note`
+  sentence ("Creates one draft document named '[asrun] ... (<run stamp>)', publishes it, deletes it at the end"). The `writes-note`
   is the only summary; there is no separate Data section, and the removal itself is a step in `## Steps`.
-- Everything created is named `[asrun] <something>` (the spec enforces this).
+- Everything created is named `<prefix> <something> (<run stamp>)`, where the prefix is the project's
+  `asrun.testDataPrefix` (default `[asrun]`; `pnpm asrun rules` prints it) and the stamp is the UTC time of the run
+  (`testDataName()` builds it). The case's `## Values` holds the base without the stamp; the spec composes it, so two
+  runs never collide and a person can find one run's data in the product.
 - The case ends by deleting what it created. If the notes do not say how to delete it, that is a gap: ask, and
   never guess a delete path. Until it is known, write the likeliest delete step ("Select the 'Delete' option of the
   item's menu on the list page.") and put a `TODO [blocking]: How is <thing> deleted?` block under that step (see

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 This file is the binding baseline for every project that uses the AsRun framework. It describes no particular
 product: a project adds its own rules in its own `AGENTS.md` §2, and they win where they differ (see "Precedence").
-Its hard rules carry ids (`F1`..`F10`, `B1`..`B4`, `A1`..`A6`).
+Its hard rules carry ids (`F1`..`F11`, `B1`..`B4`, `A1`..`A6`, `R1`..`R4`).
 
 Paths are relative to the **workspace root**: the project that owns `profiles.yaml`, `cases/` and `tests/`. In a
 project that uses asrun, the framework files are in `node_modules/@asrunjs/asrun` (an installed dependency: never edit it).
@@ -19,9 +19,16 @@ Rules are applied in this order; a later layer wins where they conflict.
    own procedure.
 5. **The project's `AGENTS.md` §2 (Project rules).** It states the project's intent and wins over layers 2–4.
 
-A project writes §2 only for what differs from the defaults here, names the rule id, and says whether it `narrows` or
-`replaces` the rule. `replaces` is refused for F1–F6 and R2; `pnpm asrun doctor` checks the table. A rule file never
-renames the structural tokens under "Fixed tokens".
+A project writes §2 only for what differs from the defaults here. A row names a baseline rule and says whether it
+`narrows` (stricter) or `replaces` (a different default) it; a rule with no baseline counterpart gets a project id
+(`P1`, `P2`, ...) and `adds`. `replaces` is refused for F1–F6 and R2; `pnpm asrun doctor` checks the table and
+`pnpm asrun rules` prints the effective set. A rule file never renames the structural tokens under "Fixed tokens".
+
+**A project rule is applied, never questioned.** §2 wins over the baseline defaults by definition, and a `P<n>` rule
+stands next to them: a difference between §2 and a framework default (a naming prefix, a language, a wait) is not a
+conflict and never becomes a TODO, a marker or a question in a case. The only refusal is a §2 row that weakens
+F1–F6/R2, and `doctor` reports that before any run. Options the framework needs at run time (the test-data prefix)
+live in `package.json` `"asrun"`, so the document and the code read the same value.
 
 Inside a case, `## Rules` is a case-local layer below this file and the project's §2: it says how to run that case,
 never what is true (`R1`), and a rule that conflicts with the rest of the case is a question, not an override.
@@ -57,6 +64,12 @@ never what is true (`R1`), and a rule that conflicts with the rest of the case i
   written in English by default. A project replaces this in §2 of its own `AGENTS.md` (for example Simplified Chinese
   for case prose and reports). Code, comments, identifiers, commit messages and the structural tokens under
   "Fixed tokens" always stay in English.
+- **F11 — Test data is findable per run.** A step that writes names what it creates with the project's test-data
+  prefix and a run stamp: `testDataName(base)` in `@asrunjs/asrun/records` builds `<prefix> <base> (<YYYY-MM-DD
+  HH-mm-ss>)`, the UTC time of the run id (so it matches `reports/<runId>` and the ledger). The prefix is
+  `asrun.testDataPrefix` in the project's `package.json` (default `[asrun]`). Two runs never share a name, and a
+  person can search the product for one run's data to edit or delete it by hand. The case's `## Values` holds the base
+  literal without the stamp; the spec composes it, and a check on the created item uses the composed name.
 
 ## Browser exploration rules (`B`)
 These apply to every agent that drives a browser to explore pages for cases or specs (`making-cases`,
@@ -160,7 +173,7 @@ This file holds the rules. The exact shape those rules apply to is documented on
 - `.claude/skills/exploring-cases/references/tools.md`: which browser tools the `playwright-test` MCP can run, the
   substitute for each one it only lists, and the arguments every call has to carry. Read it before the first browser
   call of a run.
-- `docs/commands.md`: every command and flag.
+- `docs/commands.md`: every command and flag, including `pnpm asrun rules`.
 - `docs/cases.md`: the same case format for the people who write cases by hand.
 - `docs/agents/framework-dev.md`: the framework's own layout and how to change it.
 The project's own `AGENTS.md` §2 (project rules) and §3 (project facts) still win over the documentation where they
@@ -173,6 +186,8 @@ differ, and `F1`–`F6` and `R2` win over everything.
 - `tests/**/*.spec.ts` generated Playwright specs (output of the AI workflow), one per case, same folder as the case,
   with their `*-snapshots/` baselines next to them
 - `profiles.yaml`       one entry per environment: URL, account label, tags, environment (connection settings only)
+- `package.json`        npm scripts and the framework dependency; its `"asrun"` object holds project settings
+  (for example `testDataPrefix`)
 - `AGENTS.md`           the project's own rules: they point at this baseline, and §2 holds what differs
 - `.auth/` `reports/` `.tmp/` `.explore/`  local state, never committed
 
@@ -184,15 +199,16 @@ Three steps, each learns one thing: the intent, the facts and inputs, the implem
 1. `making-cases` (or `/make-case <notes>`) turns raw notes into case documents. It writes `cases/*.md` only and
    never opens a browser. Check them with `pnpm case:check`.
 2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended] [--profiles a,b]`) explores the real pages for one
-   case. It edits that case file only: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
-   of the steps that write or need a choice. `--profiles` narrows the run to those profiles; runs add up, so the case
-   can be explored in passes.
-3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case and its
-   step recipes and `## Values`, writes the spec (values stay in the case document), but never runs the tests, never
-   writes data and never creates baselines. There is no profile selection here: it covers every profile the case names,
-   which is why a case explored in passes generates one spec for all of them. A tagged step with no `- Recipe:` line
-   (an old `## Inputs` line counts until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs
-   is a separate step (`pnpm asrun`, or the Run page).
+   case. It edits that case file: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
+   of the steps that write or need a choice, and it writes a local note under `.explore/notes/` with the locators and
+   data-call paths it saw. `--profiles` narrows the run to those profiles; runs add up, so the case can be explored in
+   passes.
+3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case, its
+   step recipes and the exploration note, and `## Values`, writes the spec (values stay in the case document), but never
+   runs the tests, never writes data and never creates baselines. There is no profile selection here: it covers every
+   profile the case names, which is why a case explored in passes generates one spec for all of them. A tagged step with
+   no `- Recipe:` line (an old `## Inputs` line counts until it is moved) stops with `needs-input`: run
+   `/explore-case` first. Running specs is a separate step (`pnpm asrun`, or the Run page).
 Workspace maintenance is separate from the AI steps: `pnpm asrun upgrade` installs the newest framework, refreshes the
 generated files and applies the release's workspace migrations (it checks the target release for breaking changes
 before installing), `pnpm asrun init [--update] [--force]` writes or refreshes the workspace files, `pnpm asrun

package/README.md

@@ -99,11 +99,12 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
 3. **Write a case.** `pnpm case:new header-logo` creates `cases/header-logo.md` from the template; or start from raw
    notes with `/make-case notes.md`. Fill in the steps, what is expected and the exact values.
 4. **Check it against the real pages.** `/explore-case header-logo staging` opens the pages (with your saved session),
-   writes what they show into the case and turns what it cannot know into questions. Answer them in the case file, or
-   in the UI's **Answer** sheet, and run it again. With many profiles, `--profiles a,b` opens only those; a later run
-   with the others adds theirs, and the case keeps both.
-5. **Generate, run, read.** `/gen-spec header-logo staging` writes `tests/header-logo.spec.ts` and fills the case's
-   `## Values`. Then:
+   writes what they show into the case and turns what it cannot know into questions. It also saves a local note of the
+   locators and data calls it saw. Answer the questions in the case file, or in the UI's **Answer** sheet, and run it
+   again. With many profiles, `--profiles a,b` opens only those; a later run with the others adds theirs, and the case
+   keeps both.
+5. **Generate, run, read.** `/gen-spec header-logo staging` reads those notes, writes `tests/header-logo.spec.ts` and
+   fills the case's `## Values`. Then:
 
    ```bash
    pnpm asrun --env staging --grep header-logo
@@ -137,11 +138,14 @@ Rules combine in this order, and a later layer wins where they conflict:
 2. The framework baseline, `node_modules/@asrunjs/asrun/AGENTS.md`.
 3. The framework skill.
 4. Your override, `.claude/skills/<skill>.md`.
-5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`, `R1`, `R3`, `R4`) with `narrows` or `replaces`, for example
-   the artifact language.
+5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F11`, `R1`, `R3`, `R4`) with `narrows` or `replaces`, and
+   project ids (`P1`, ...) with `adds` for a rule the baseline does not have, for example the artifact language or the
+   test-data prefix (`package.json` `"asrun"`). A difference from the baseline is applied, never turned into a
+   question.
 6. A case's `## Rules`: how to run that one case, never what is true.
 
-`pnpm asrun doctor` validates the table and lists the overrides it sees. An update never rewrites your rules:
+`pnpm asrun doctor` validates the table and `pnpm asrun rules` prints the effective set (the AI steps read it before
+they apply anything). An update never rewrites your rules:
 `init --force` refuses `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` without `--reset-rules`. Never edit the
 framework package itself: an update replaces it, and only the override files are yours. The AI tool stays configurable
 too: `.mcp.json` (Claude Code), `opencode.jsonc` (OpenCode and its model), `.claude/settings.json` (sandbox
@@ -192,7 +196,8 @@ the top bar. The check never blocks a command and stays quiet when the registry
 Tests run against real sites, so the defaults are strict:
 
 - **Read-only unless the case says otherwise.** A case may create, edit or delete data only in the environments it
-  lists under `writes`, and only data of the test accounts, named `[asrun] ...`, which it must clean up. Elsewhere the
+  lists under `writes`, and only data of the test accounts, named with the project's prefix (default `[asrun]`) and a
+  run stamp such as `[autotest] Draft CMA (2026-11-09 12-34-56)`, which it must clean up. Elsewhere the
   case is skipped with a notice, not failed.
 - **A person confirms non-staging writes on every run** by typing the environment name, or in a dialog in the UI.
   `--read-only` leaves those cases out; `--allow-writes=<env>` is for unattended runs, and AI agents never use it.
@@ -201,8 +206,8 @@ Tests run against real sites, so the defaults are strict:
   the browser, in an attended exploration. Logins are always a person's job, 2FA included.
 - **A failing baseline is a person's decision.** An agent never updates a baseline to make a difference disappear.
 
-The rules that enforce this are `F1`–`F10` in [AGENTS.md](./AGENTS.md); a project can tighten or replace the last
-four, never the first six.
+The rules that enforce this are `F1`–`F11` in [AGENTS.md](./AGENTS.md); a project can tighten or replace the last
+five, never the first six.
 
 ## Documentation
 

package/bin/asrun.mjs

@@ -23,6 +23,7 @@ const SCRIPTS = {
   status: 'status.js',
   report: 'report.js',
   explore: 'explore.js',
+  'explore:notes': 'explore-notes.js',
   cleanup: 'cleanup.js',
   'case:new': 'new-case.js',
   'case:check': 'check-cases.js',

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

@@ -131,7 +131,7 @@ export interface CaseReadySignal {
 }
 /**
  * One `- Recipe (phase): ...` bullet under a step: what a person did for that step during `/explore-case --attended`,
- * as a general recipe (positions, `[asrun]` names, control labels). It is not test data: the asserted values live in
+ * as a general recipe (positions, created names, control labels). It is not test data: the asserted values live in
  * `## Values`.
  */
 export interface CaseRecipe {

package/dist/lib/config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Project-wide settings that the framework needs at run time, read from the `asrun` object of the workspace's
+ * `package.json`:
+ *
+ * ```json
+ * "asrun": { "testDataPrefix": "[autotest]" }
+ * ```
+ *
+ * The file is the project's own: `pnpm asrun init` merges it and never replaces it. A project that does not set an
+ * option gets the default below, so an existing workspace keeps working unchanged.
+ */
+export interface WorkspaceConfig {
+    /** The prefix every piece of data a case creates carries. Default `[asrun]`. */
+    testDataPrefix: string;
+}
+/** The frame's prefix: unmistakably test data, so cleanup can never touch real data. */
+export declare const DEFAULT_TEST_DATA_PREFIX = "[asrun]";
+/**
+ * Reads and validates the project settings. Throws an Error whose message says what to fix, so `doctor` and `rules`
+ * can report it and a spec that imports it fails with the same sentence instead of a confusing one.
+ */
+export declare function readWorkspaceConfig(): WorkspaceConfig;
+/** The prefix every name a case creates must start with. Reads `package.json`; default `[asrun]`. */
+export declare function testDataPrefix(): string;
+/** Forget the cached settings (a tool that edits `package.json` in the same process). */
+export declare function resetWorkspaceConfig(): void;

package/dist/lib/config.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ROOT } from './paths.js';
+/** The frame's prefix: unmistakably test data, so cleanup can never touch real data. */
+export const DEFAULT_TEST_DATA_PREFIX = '[asrun]';
+/** A bracketed lowercase word: `[asrun]`, `[autotest]`, `[qa_team]`. Easy to search for in the product. */
+const PREFIX = /^\[[a-z0-9][a-z0-9_-]*\]$/i;
+let cached = null;
+function readPackageJson() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads and validates the project settings. Throws an Error whose message says what to fix, so `doctor` and `rules`
+ * can report it and a spec that imports it fails with the same sentence instead of a confusing one.
+ */
+export function readWorkspaceConfig() {
+    if (cached !== null)
+        return cached;
+    const pkg = readPackageJson();
+    const section = pkg?.asrun;
+    if (section !== undefined && (section === null || typeof section !== 'object' || Array.isArray(section))) {
+        throw new Error('package.json: "asrun" must be an object, for example "asrun": { "testDataPrefix": "[autotest]" }.');
+    }
+    const raw = section?.testDataPrefix;
+    if (raw !== undefined && typeof raw !== 'string') {
+        throw new Error('package.json: "asrun.testDataPrefix" must be a string like "[asrun]".');
+    }
+    const prefix = (raw ?? DEFAULT_TEST_DATA_PREFIX).trim();
+    if (!PREFIX.test(prefix)) {
+        throw new Error(`package.json: "asrun.testDataPrefix" is "${prefix}"; use a bracketed word such as "[asrun]" or "[autotest]" ` +
+            '(letters, digits, "-" and "_" inside the brackets).');
+    }
+    cached = { testDataPrefix: prefix };
+    return cached;
+}
+/** The prefix every name a case creates must start with. Reads `package.json`; default `[asrun]`. */
+export function testDataPrefix() {
+    return readWorkspaceConfig().testDataPrefix;
+}
+/** Forget the cached settings (a tool that edits `package.json` in the same process). */
+export function resetWorkspaceConfig() {
+    cached = null;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * The local exploration note: what `/explore-case` saw on the page, in a form `/gen-spec` can read.
+ *
+ * It lives under `.explore/notes/<case-id>/<profile-id>.json`, one file per profile, so a run with `--profiles` never
+ * has to merge with an earlier one. `.explore/` is git-ignored local state: a note is optional, may be deleted at any
+ * time, and a fresh checkout simply has none (generation then replays the case as before).
+ *
+ * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
+ * actions that load something, and the match count of a target card's element. Expected values stay in the case's
+ * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ */
+export declare const NOTES_VERSION = 1;
+export interface ExploreLocator {
+    /** What the locator is for, in words ("the header navigation link"). */
+    purpose: string;
+    /** A Playwright locator as `browser_generate_locator` returned it, for example `page.getByRole('link', {name: 'Home'})`. */
+    locator: string;
+}
+export interface ExploreNoteStep {
+    /** The path the step runs on, relative to `baseURL` (for example `/documents/`). */
+    url?: string;
+    locators?: ExploreLocator[];
+    /** Data-call paths the step's action starts, path only (`/api/articles`). */
+    requests?: string[];
+}
+export interface ExploreNoteTarget {
+    locator: string;
+    /** How many elements the locator matched when it was confirmed (1 for a target that is not a question). */
+    matches?: number;
+}
+export interface ExploreNote {
+    version: typeof NOTES_VERSION;
+    caseId: string;
+    profile: string;
+    env?: string;
+    /** sha256 of `cases/<case-id>.md` when the note was written; a different one makes the note stale. */
+    caseSha256: string;
+    capturedAt: string;
+    /** Set when a later `/gen-spec` refreshed an entry it confirmed on the page. */
+    updatedAt?: string;
+    steps: Record<string, ExploreNoteStep>;
+    targets?: Record<string, ExploreNoteTarget>;
+}
+export interface ExploreNoteError {
+    file: string;
+    problems: string[];
+}
+/** The folder that holds one case's notes; `<case-id>` may contain its group folder (`documents/landing-page`). */
+export declare function exploreNotesDir(caseId: string): string;
+/** The note of one profile: `.explore/notes/<case-id>/<profile-id>.json`. */
+export declare function exploreNotesFile(caseId: string, profileId: string): string;
+/** sha256 of the case document, or null when it does not exist. */
+export declare function caseSha256(caseId: string): string | null;
+export type NoteFreshness = 'fresh' | 'stale' | 'no-case';
+/**
+ * Whether a note still describes the case. A stale note is not an error: `/gen-spec` replays the case and ignores it.
+ */
+export declare function noteFreshness(note: ExploreNote): {
+    state: NoteFreshness;
+    reason?: string;
+};
+/** Every reason the note is not usable, in plain words. An empty list means it is valid. */
+export declare function validateExploreNote(value: unknown, expected: {
+    caseId: string;
+    profile: string;
+}): string[];
+/**
+ * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
+ * the caller decides whether it matters, and generation treats an unreadable note as a missing one.
+ */
+export declare function readExploreNotes(caseId: string, profileId?: string): {
+    notes: ExploreNote[];
+    errors: ExploreNoteError[];
+};