@asrunjs/asrun 0.8.0 → 0.9.0

package/.claude/commands/explore-case.md

@@ -7,12 +7,16 @@ In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/de
 Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
 framework skill, `.claude/skills/exploring-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
 (Project rules). F1–F6 always win.
-Arguments: `<case-id> <env> [--attended]`. The case id is the path below cases/ without `.md` (it may include a group
+Arguments: `<case-id> <env> [--attended] [--profiles a,b]`. The case id is the path below cases/ without `.md` (it may include a group
 folder, e.g. documents/landing-page) and is required. `<env>` is `staging` or `production`; it is required and there is no
 default (without one, stop and say so). With `--attended` I am at the machine and the browser window is visible: when a step
 writes data or needs a choice, hand it to me as the skill describes, wait for me, and record what I did as a general
 recipe under the step it belongs to (`- Recipe:` lines). Without `--attended`, never wait for me.
+`--profiles a,b` explores only those profiles (comma-separated ids from profiles.yaml); without it, at least one
+logged-in profile per domain. A profile the list leaves out is not opened and nothing is written about it: runs add up,
+so a later run covers the rest.
 Follow `assertion-targets.md` (list the candidates, never pick when in doubt, ask for the exact image/text/place/UI)
 and `readiness.md` (wait for the key requests and the content before you read anything) of the skill.
 This command edits cases/<case-id>.md only (plus screenshots under `.explore/targets/`). Do not ask me questions in the chat: write open questions into the case
-file as the skill describes, and end with the `RESULT:` line.
+file as the skill describes, and end with the `RESULT:` line. If you are not allowed to write files at all (a plan-mode
+run, a read-only sandbox), say what blocked you and end with `RESULT: needs-input`.

package/.claude/commands/gen-spec.md

@@ -10,7 +10,10 @@ framework skill, `.claude/skills/generating-specs.md` if it exists, then the wor
 Arguments: `<case-id> [<env>] [--force]`. The case file is cases/<case-id>.md (the id may include one group folder, e.g.
 documents/landing-page). `<env>` is the environment to explore in (`staging` or `production`); there is no default. If the spec already exists, it is
 left alone unless `--force` is given; with `--force` it is regenerated and overwritten.
+There is no profile option: the spec is generated for every profile the case holds information for (its `## Values`
+keys, its target cards and its observations), not for a chosen subset and not only for the profiles that are logged in.
 Follow the skill's procedure exactly, including `assertion-targets.md` and `readiness.md`; run `pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
 process), and do not create baselines.
 Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for QA,
-write the remaining questions into the case file), and end with the `RESULT:` line.
+write the remaining questions into the case file), and end with the `RESULT:` line. If you are not allowed to write
+files at all (a plan-mode run, a read-only sandbox), say what blocked you and end with `RESULT: needs-input`.

package/.claude/commands/heal-spec.md

@@ -1,8 +1,8 @@
 ---
-description: Diagnose and fix a failing spec from its last report (without hiding real product regressions)
+description: Repair a failing spec, or refine a case and its spec on request, without hiding real product regressions
 ---
 
-Load the `generating-specs` skill, section "Healing a failing spec", and follow it exactly.
+Load the `generating-specs` skill, section "Healing and refining a spec", and follow it exactly.
 In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
 Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
 framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
@@ -11,14 +11,25 @@ Arguments: $ARGUMENTS
 Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`, with optional free text after them.
 - `<case-id>` and `<env>` (`staging` or `production`) are required. There is no default environment. Without one, stop
   and say so.
-- `--profiles`: the profiles to heal. Without it, every profile that is logged in in `<env>`.
+- `--profiles`: the profiles to run when evidence is needed. Without it, every profile that is logged in in `<env>`.
 - `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
-- `--hints <file>`: a file with what the user knows (what to heal, evidence, clues). Read it first. Any free text
-  after the arguments is the same kind of clue. Both are optional.
-Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see steps 4
+- `--hints <file>`: a file with what the user wants repaired or improved, with any evidence. Read it first. Any free
+  text after the arguments is the same kind of request. Both are optional.
+A passing run is not a reason to refuse a request: healing also refines a case and its spec. Never lower the bar for a
+product finding to make a test pass.
+
+Do not ask me questions in the chat: this may run unattended. Resolve what the report, the case and the page can
+resolve, and write what still needs a person into the case as a `[blocking]` question. End with the `RESULT:` line:
+`ready` when the healing or the refinement is finished, `needs-input` when something is still open. If you could not
+write files at all (a plan-mode run, a read-only sandbox, a refused permission), say in one sentence what blocked you
+and end with `RESULT: needs-input`: never answer with a plan and a question instead.
+
+Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see step 5
 of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
 Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when the
-skill says it is needed. Always run with `--logged-in`. Tell me whether it is a test problem or a product finding.
+skill says it is needed. Always run with `--logged-in`. If the change leaves an open question or an unconfirmed marker
+in the case, stop there, tell me to review the case and run `/explore-case`, and end with `RESULT: needs-input`.
+Otherwise tell me whether it is a test problem or a product finding.
 
 Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and `pnpm status ...` as plain commands, optionally piped to `tail` or
 `head`, and do not chain other commands with them (`;` or `&&`). Only these exact forms run outside Claude Code's

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

@@ -1,6 +1,6 @@
 ---
 name: exploring-cases
-description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
+description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated, for every logged-in profile or only the ones named with --profiles. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
 ---
 
 # Exploring a case document
@@ -34,8 +34,10 @@ under `.auth/`.
 choice (see `references/user-handoff.md`).
 
 It never stops to ask in the chat. A question that cannot be answered from the page goes into the case file, where
-the user answers it by editing the file, and the report says `RESULT: needs-input`. The one exception is a handoff in
-an attended run, where waiting for the person is the point.
+the user answers it by editing the file, and the report says `RESULT: needs-input`. This holds whatever mode or agent
+the run is in: if you are not allowed to write files (plan mode, a read-only sandbox, a refused permission), say what
+blocked you in one sentence and end with `RESULT: needs-input` instead of answering with a plan and a question. The
+one exception is a handoff in an attended run, where waiting for the person is the point.
 
 ## Inputs
 - A case id (path below `cases/` without `.md`, e.g. `documents/landing-page`). It is required: an attended exploration of
@@ -44,13 +46,18 @@ an attended run, where waiting for the person is the point.
   before exploring and report `RESULT: needs-input` ("pass the environment").
 - Optionally `--attended`: a person is at the machine and the browser window is visible, so handoffs may happen.
   Without it nothing waits, and a step that needs a person becomes a `[blocking]` TODO.
+- Optionally `--profiles a,b`: explore only these profiles (ids from `profiles.yaml`, comma-separated). Without it, at
+  least one logged-in profile per domain. The selection is never widened: a profile it leaves out is not opened and
+  nothing about it is written into the case. Runs add up: a later run with other profiles adds their observations and
+  `## Values` entries next to the ones recorded before.
 
 ## Procedure
 1. **Read** the case, `profiles.yaml` and `cases/_template.md`. Apply uncommitted user edits as they are: they are the
    newest wording. Use targeted edits, never rewrite a whole file.
 2. **Static review.** Find:
    - missing values for a profile: compare the entries of `## Values` (keyed by `default` and profile ids) with the
-     ids in `profiles.yaml`. A missing entry is a gap, not something to invent: leave it to the observations and
+     ids in `profiles.yaml` (with `--profiles`, only those ids: the rest belong to a run of their own). A missing
+     entry is a gap, not something to invent: leave it to the observations and
      `/gen-spec`. The case's `## Values` is the only place for expected values; never copy them into `profiles.yaml`;
    - ambiguous steps and checks without an expected result;
    - steps that write data or need a choice: mark them `[writes]` / `[input]`. The front matter must list the
@@ -70,9 +77,11 @@ an attended run, where waiting for the person is the point.
    `RESULT: needs-input`.
    Run `pnpm status --env <env>`. If it cannot run (a sandbox error such as
    `listen EPERM` or a Chromium start failure), do not give up: open the profile's page through the MCP, and a page
-   that lands on the login page means the profile is not logged in. Explore at least one logged-in profile per
-   domain with the `playwright-test` MCP (`generator_setup_page` with `project=<profile-id>` and
-   `seedFile=tests/seed.spec.ts`). Profiles that are not logged in are skipped and named in the report; a human runs
+   that lands on the login page means the profile is not logged in. Explore each profile `--profiles` names that is
+   logged in, and, without `--profiles`, at least one logged-in profile per domain, with the `playwright-test` MCP
+   (`generator_setup_page` with `project=<profile-id>` and
+   `seedFile=tests/seed.spec.ts`). Never explore a profile the selection leaves out, and never add a profile to fill
+   a gap. Profiles that are selected but not logged in are skipped and named in the report; a human runs
    `pnpm signin <profile-id>`.
    - Do the read-only steps yourself: open, look, read, hover, switch tabs, open and close dialogs and menus.
    - **A step that writes or needs a choice is done by the person**, per `references/user-handoff.md`: announce it,
@@ -129,7 +138,8 @@ an attended run, where waiting for the person is the point.
 8. **Check**: run `pnpm case:check` (it fails on an incomplete target card and warns on a check that has none) and fix every FAIL. If it fails with a sandbox error (`listen EPERM`), run
    `node --import tsx <framework>/scripts/check-cases.ts` instead; it checks the same thing.
 9. **Report** in the user's language: what was changed (wording fixes, observations added, TODOs closed or narrowed),
-   what was explored (profile ids), which steps the person did and what was recorded for them, what was skipped and
+   what was explored (profile ids), which profiles `--profiles` left out (and that a run with them covers the rest),
+   which steps the person did and what was recorded for them, what was skipped and
    why, the target cards written (and which ones are still questions), the steps whose first read was too early,
    the steps that could not be observed (and why), the questions that remain with the sentence that deleting each block would confirm, and findings that look
    like product bugs. End with the `RESULT:` line.
@@ -141,6 +151,7 @@ an attended run, where waiting for the person is the point.
 - Never invent expected values, profile names, counts or UI texts. Observations are marked as such. Values that a
   check asserts are written into the case's `## Values` under the profile id (or `default` when they hold for every
   profile), and never into `profiles.yaml`.
+- Never explore a profile that `--profiles` leaves out, and never widen the selection to cover a gap in the case.
 - Never pick a target when in doubt, and never record a fact that was read before the content finished loading.
 - Never read or print anything under `.auth/`. Never automate login or 2FA.
 - Prose follows the artifact language of the workspace `AGENTS.md` §2 (English by default); structural tokens stay English.

package/.claude/skills/exploring-cases/references/open-questions.md

@@ -110,7 +110,7 @@ RESULT: needs-input
 
 - `ready`: no `[blocking]` question remains. Non-blocking ones may remain; list them so QA can confirm them.
 - `needs-input`: at least one `[blocking]` question remains in the case file (list each with its parent sentence),
-  or the work could not be done (no environment, nobody logged in). Say what the user should edit in the case file,
-  then re-run.
+  or the work could not be done (no environment, nobody logged in, or no permission to write files: a plan-mode run,
+  a read-only sandbox). Say what the user should edit in the case file, then re-run.
 
 Do not write anything after the `RESULT:` line.

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

@@ -1,6 +1,6 @@
 ---
 name: generating-specs
-description: Turns a human-written test case (cases/<id>.md, the id may include a group folder such as documents/landing-page) into a Playwright spec (tests/<id>.spec.ts) for the multi-profile test suite, explores the real pages to learn the locators and values, and completes the case's own "## Values" block. It only generates: it never runs the tests. Use when asked to generate, update, fix or heal a spec, or for /gen-spec.
+description: Turns a human-written test case (cases/<id>.md, the id may include a group folder such as documents/landing-page) into a Playwright spec (tests/<id>.spec.ts) for the multi-profile test suite, explores the real pages to learn the locators and values, and completes the case's own "## Values" block. It only generates: it never runs the tests. Healing (repairing a failing spec, or refining a case and its spec on request) is the exception. Use when asked to generate, update, fix, heal or refine a spec, or for /gen-spec or /heal-spec.
 ---
 
 # Generating specs from case documents
@@ -12,16 +12,26 @@ defines how open questions are written into the case file, resolved and reported
 `../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts). All three 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`). Questions go into the case file; the final line is `RESULT: ready` or
-`RESULT: needs-input`.
+`claude -p` / `opencode run`). This holds whatever mode or agent the run is in: plan mode changes what you may write,
+never how you end. If you are not allowed to write files (plan mode, a read-only sandbox, a refused permission), say
+what blocked you in one sentence and end with `RESULT: needs-input` instead of answering with a plan and a question.
+Questions go into the case file; the final line is `RESULT: ready` or `RESULT: needs-input`.
 
 This skill trusts the case. What the pages show, what a person has to enter, and what the open questions are is
 settled by `/explore-case` and recorded in the case (`(observed, ...)` marks, the step recipes). Generating
 only finds locators and writes code: it replays the case and does not judge the case again.
 
+The profile scope is the case's, not a selection. It is every profile id that appears in the case — the keys of
+`## Values`, a target card's `Reference <profile-id>:` line, a step observation — plus the `default` entry. There is no
+`--profiles` here: never narrow the scope to the profiles that are logged in, and never ask for a subset. The spec runs
+once per profile in the environment, so it must cover every profile the case says something about. A profile the case
+says nothing about runs on `default` alone; name those in the report. Runs of `/explore-case` add up, so a case explored
+with A and B first and C later generates a spec for all three.
+
 Generating a spec and running it are separate processes. This skill only writes files: it does not run
 `pnpm asrun`, does not create screenshot baselines and does not judge whether the spec passes. The user runs the
-spec afterwards (see the report). Healing a failing spec (below) is the exception: it reads the last report first and runs only the profiles that are logged in, and only when the report is not enough.
+spec afterwards (see the report). Healing (below) is the exception: it reads the last report first, may edit the case
+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
@@ -33,6 +43,8 @@ continue with the procedure below.
 - The case id and the environment to explore in (`staging` or `production`). There is no default. If the
   environment is missing, stop before exploring and report `RESULT: needs-input` ("pass the environment").
 - Optionally `--force`: regenerate the spec from scratch and overwrite the existing one. See "An existing spec".
+- No profile selection: the profile scope is the case's (see above). A case id and an environment are all this command
+  takes besides `--force`.
 
 A case id is its path below `cases/` without `.md`: `hub-landing`, or `documents/landing-page` when the case is in a
 folder (one level only). The spec is at the same path below `tests/` (`tests/documents/landing-page.spec.ts`); both import
@@ -94,9 +106,11 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    - 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. 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.
+   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. If its tools are not registered in this
    session (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,
@@ -109,10 +123,11 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    of the spec from the `- Recipe:` lines under the step (positions, `[asrun]` 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 profile
-   per domain (example.com and exampleshop.com differ in markup). Profiles that are not logged in are skipped and
-   named in the report. Use this exploration to answer the open points of step 2, and look at every profile that has
-   an entry in `## Values` to read its value.
+   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`): `browser_network_clear`, act, wait for the key requests
@@ -126,8 +141,11 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    `(observed, 🔍 to be confirmed by QA)`, remove the TODO blocks they answer (rewrite the sentence above the block),
    and narrow the ones that remain. Keep the shape of `open-questions.md` for every block. Edit the case
    with targeted edits; never touch its `## Source` table.
-5. **Complete the case's `## Values`**: for every profile the spec runs for, add the entry with the literals the spec
-   asserts (the same keys as `default`, only what differs). Do not move values into `profiles.yaml`; it holds connection
+5. **Complete the case's `## Values`**: for every profile the case holds information for, add the entry with the
+   literals the spec asserts (the same keys as `default`, only what differs); put a literal that holds for every profile
+   in `default`. Do not add an entry for a profile the case says nothing about, and never invent a value to fill one: a
+   profile without an entry runs on `default` alone, and a literal the case does not hold is a question in the case.
+   Do not move values into `profiles.yaml`; it holds connection
    settings only. Mention every value you added or corrected in the report.
 6. **Write `tests/<id>.spec.ts`** (inside the group folder if the id has one, creating it if needed) following the conventions. One `test()` per outcome, and every
    case step wrapped in `test.step()` with the case's step text as the title, and the top-level
@@ -150,7 +168,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), whether the case file was
+   `observed on the page` or `not verified`; no row may be missing), profiles explored, 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 observed, checks generated from observations (QA must confirm
    them), visual checks that need a baseline on the first run, and the remaining TODO blocks (`[blocking]` ones with
    the sentence that deleting the block would confirm). State that the spec was not run and give the command to run it:
@@ -166,34 +185,51 @@ spec does, when a person runs it in an environment that `writes` lists. Elsewher
 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 a failing spec
+## 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),
 optionally `--profiles a,b`, `--report <run-id>` and `--hints <file>` (or free text after the arguments). Healing is
 the one case where this skill runs specs, and only in the environment given.
 
+Healing has two jobs, and the same command does both: **repair** a spec that fails, and **refine** a case and its spec
+when the user asks for a change. A passing run is never a reason to refuse a request, and "nothing failed" is never a
+reason to do nothing when the user asked for something.
+
 Heal from evidence, not from a habit of rerunning. A report that already exists says what failed.
 
-1. **Read the user's clues first** (the `--hints` file, or the free text). They say what to look at and may hold
-   evidence the report lacks. They guide the diagnosis and nothing else: they never lower the bar for a product
-   finding and never allow an expectation to be changed just to make a test pass. Quote the clue you used, or say that
-   it did not hold up, in the report.
-2. **Read the existing report**: run `pnpm heal:evidence --case <case-id> --env <env>` (add `--profile a,b` when `--profiles`
+1. **Read the user's request first** (the `--hints` file, or the free text). It says what to repair or improve and may
+   hold evidence the report lacks. Decide which kind of work it is:
+   - a failure to repair (the last run failed, or the user names one);
+   - an improvement, even when the last run passed: a check that is too loose, a step, expectation, value or target
+     that no longer matches the page, wording a person cannot follow;
+   - both.
+   Quote the request you used, or say that it did not hold up, in the report. It guides the work and nothing else: it
+   never lowers the bar for a product finding and never allows an expectation to be changed just to make a test pass.
+   - **No report and no request:** do not invent work. Say that nothing asks for a change, list what
+     `pnpm spec:lint <case-id>` and the last report call weak (as suggestions, not edits), and end with `RESULT: ready`.
+   - **A passing report and no request:** the same. Do not start an improvement of your own.
+2. **Read the existing report** if there is one: run `pnpm heal:evidence --case <case-id> --env <env>` (add `--profile a,b` when `--profiles`
    was given). It reads `reports/*/summary.json` and prints, per profile, the status, the failed step, the error, the call
    log, the screenshots and videos, and ends with `EVIDENCE: fresh | stale | no-failure | none`. With `--report <run-id>`,
    read `reports/<run-id>/summary.json` instead. Look at the screenshot when the error alone does not explain it. A profile
-   that failed only because it was not logged in is no evidence about the spec.
+   that failed only because it was not logged in is no evidence about the spec. `EVIDENCE: none` or `no-failure` with an
+   improvement request is a starting point, not a stop.
 3. **Decide whether to rerun the case**. Do not rerun when the report is `fresh`, names the failing step and the error,
    and that is enough to tell whether the product changed or the test is wrong. Rerun when:
    - there is no report (`none`), or it is `stale` (the spec, the case or `profiles.yaml` changed after it);
    - the report does not explain the failure (a bare timeout with no locator, a failure before any step, a truncated log);
-   - a clue from the user has to be checked against the real page;
+   - a clue or a requested improvement has to be checked against the real page, and no recent report shows it;
    - a profile that must be healed has no result in the report (for example it was not logged in then).
    Rerun with one plain command, as few profiles as possible, and say why in the report:
    `pnpm asrun --env <env> --logged-in --profile <ids> --grep <case-id>` (optionally piped to `tail`; do not chain it
    with other commands, or it runs inside Claude's sandbox and fails with `listen EPERM`). Always add `--logged-in`: it
    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. **Audit the assertion before you blame anyone.** Read the `assertion-targets.md` and `readiness.md` sections on healing.
+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
+   steps only: **never perform a step that writes or needs a choice**, in any environment. What you see goes into the
+   case as `(observed, 🔍 to be confirmed by QA)`, so the person can confirm it in the review gate below.
+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
      (a content image instead of a logo) is a wrong test, and passing runs on it prove nothing. Delete it and report it; a
@@ -204,16 +240,35 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    - A download that fails says which stage failed (start, finish, exists, valid): fix the stage, do not loosen the check.
    - Doubt about which element is meant: write the question into the case (a `[blocking]` TODO naming the exact image,
      text, place or UI) instead of choosing; do not rewrite the card quietly.
-5. **Decide whether the PRODUCT changed or the TEST is wrong.**
+6. **Decide what the change belongs to, and change the case first.**
    - Locator/timing problem: fix the spec.
    - A real product difference (wrong logo, wrong name): do NOT change the expectation to make it
      pass. Report it as a finding with the trace/screenshot path.
-6. **After editing the spec, run it once to confirm** (same command as in step 3, for the profiles you healed). That rerun
-   is the only one that is always allowed. Run `pnpm typecheck` too.
-7. **Report** in the user's language: which report was read (or that there was none) and whether it was fresh or stale,
-   whether the case was run again and why (or why not), what was changed, what is a product finding (with paths),
-   which assertions were wrong or raced the page, which baselines are wrong and were deleted, what the user's clues contributed, which profiles were left out because they are not logged in, and the result of the
-   confirming run.
+   - A request the case can settle: the case is the source of truth, so write the change into `cases/<case-id>.md`
+     first, then into the spec. That covers a step, an expectation, a value in `## Values`, a target card, a ready
+     signal and a recipe. The spec follows the case (its step titles copy the case's step text). When the case changed
+     more than a sentence (a new or removed step, different expected values, another target), regenerate the spec from
+     the case as "## Procedure" steps 5–6 describes instead of patching it; otherwise edit it in place. Say in the
+     report which of the two you did.
+7. **Stop at the review gate.** After editing the case, read it back. If **this run** left a `🚫 TODO [blocking]` or
+   `❓ TODO [non-blocking]` block, or a `🔍 to be confirmed by QA` or `👁️ not observed` marker, do not edit or
+   regenerate the spec any further: a case that still asks something is not a source for a spec. Report exactly what
+   to review, that answering or deleting those blocks comes first, and that the next command is
+   `/explore-case <case-id> <env>` (with `--attended` when a step writes data). End with `RESULT: needs-input`. Blocks
+   and markers that were already in the case before this run and that it did not touch do not stop it.
+8. **After editing the spec, run it once to confirm** (same command as in step 3, for the profiles you healed). That rerun
+   is the only one that is always allowed. Run `pnpm typecheck`, `pnpm spec:lint <case-id>` and `pnpm case:check`, and
+   fix every failure of the checks you touched. An improvement may make the run fail on purpose: a tightened check that
+   now fails is evidence about the product, so report it as a finding instead of loosening it again.
+9. **Report** in the user's language: which report was read (or that there was none) and whether it was fresh or stale,
+   whether the case was run again and why (or why not), what the request asked for and what came of it, what was
+   changed in the case and in the spec (and whether the spec was regenerated), what is a product finding (with paths),
+   which assertions were wrong or raced the page, which baselines are wrong and were deleted, what the user's request
+   contributed, which profiles were left out because they are not logged in, and the result of the
+   confirming run. The last line is `RESULT: ready` (nothing left for a person, the spec changed and its checks pass)
+   or `RESULT: needs-input` (the case waits for a review, as in step 7, or a person has to decide something). A run
+   that could not write files at all (plan mode, a read-only sandbox, a refused permission) is `needs-input` too:
+   never end with a plan and a question instead.
 
 A case that writes data in `production` needs a person's confirmation at run time, so the rerun is refused there:
 use the report, or heal in staging, and never add `--allow-writes`.

package/AGENTS.md

@@ -143,14 +143,16 @@ The framework folder is read-only in a project: never edit it. Its own layout an
 Three steps, each learns one thing: the intent, the facts and inputs, the implementation.
 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]`) 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.
+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. 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).
+   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
@@ -161,9 +163,15 @@ Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec p
 Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
 case's own steps (see the skill's `references/conventions.md`).
 Every AI command needs an environment (`--env`/`<env>`); there is no default and no "no environment" mode.
-`/heal-spec <case-id> <env>` reads the existing report first (`pnpm heal:evidence --case <id> --env <env>`), reads the
-user's optional clues (`--hints <file>`), runs only the profiles that are logged in (`--logged-in`) and runs the case
-again only when the report is missing, stale or not enough.
+A one-shot AI run is a build run: it writes the case or the spec, never a plan. AsRun starts OpenCode with
+`--agent build`, because OpenCode keeps the agent (build or plan) on the session and a plan session would only propose
+changes and ask a question nobody can answer. Whatever mode or sandbox a run finds itself in, it still ends with the
+`RESULT:` line: a run that was not allowed to write files is `needs-input`, never a plan and a question.
+`/heal-spec <case-id> <env>` repairs one failing spec or refines a case and its spec on request (a passing run is not
+a reason to refuse): it reads the existing report first (`pnpm heal:evidence --case <id> --env <env>`), the user's
+request (`--hints <file>`), runs only the profiles that are logged in (`--logged-in`) and runs the case again only
+when the report is missing, stale or not enough. A change that leaves an open question or an unconfirmed observation
+in the case stops before the spec: the person reviews the case and runs `/explore-case` again.
 Run `pnpm typecheck`, `pnpm spec:lint <case-id>` and `pnpm case:check` before reporting that a spec was generated. Run
 `pnpm asrun --env <env> --profile <id> --grep <case-id>` only when healing a spec or when asked to.
 Pick `--env staging` while developing. A case that does not list `production` under `writes` is skipped in

package/README.md

@@ -13,8 +13,8 @@ AsRun is a devDependency, not a service. Your profiles, cases, specs and baselin
 - **One spec, every profile.** Each entry in `profiles.yaml` becomes a Playwright project with its own base URL,
   saved login and screenshot baselines. Two accounts of one site give two independent runs.
 - **An AI workflow, not a prompt dump.** `/make-case` turns raw notes into cases, `/explore-case` checks them against
-  the real pages, `/gen-spec` writes the spec, `/heal-spec` repairs it from the last report. Each command ends with
-  `RESULT: ready` or `RESULT: needs-input`, so it works unattended.
+  the real pages, `/gen-spec` writes the spec, `/heal-spec` repairs it from the last report or refines a case and its
+  spec on request. Each command ends with `RESULT: ready` or `RESULT: needs-input`, so it works unattended.
 - **Evidence for every run.** One video per test (browser tabs joined), a trace with every action and request,
   screenshots on failure, and a report that puts the failure first.
 - **Safe by default.** A case is read-only unless it lists environments under `writes`; writing anywhere except
@@ -100,7 +100,8 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
    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.
+   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:
 

package/dist/ui/server/actions.js

@@ -209,15 +209,20 @@ export function buildJobSpec(request) {
         if (request.attended && request.command !== 'explore-case') {
             throw new ActionError('Only explore-case can be attended.');
         }
-        if ((request.profiles || request.hints !== undefined || request.report) && request.command !== 'heal-spec') {
-            throw new ActionError('Only heal-spec takes profiles, hints and a report.');
+        if ((request.hints !== undefined || request.report) && request.command !== 'heal-spec') {
+            throw new ActionError('Only heal-spec takes hints and a report.');
+        }
+        // The spec is generated for every profile the case names (and runs for every profile), so a selection could only
+        // narrow it wrongly.
+        if (request.profiles && request.command === 'gen-spec') {
+            throw new ActionError('gen-spec takes no profiles: it uses every profile the case holds information for.');
         }
         const profilesInEnv = listProfiles(request.env, knownProfiles).map((profile) => profile.id);
         if (request.profiles?.some((id) => !profilesInEnv.includes(id))) {
             throw new ActionError(`Unknown profile for "${request.env}".`);
         }
         if (request.profiles?.length === 0)
-            throw new ActionError('Choose at least one profile to heal.');
+            throw new ActionError('Choose at least one profile.');
         if (request.report !== undefined && !(REPORT_ID.test(request.report) && fs.existsSync(path.join(REPORTS_DIR, request.report, 'summary.json')))) {
             throw new ActionError(`Unknown report "${request.report}".`);
         }
@@ -234,7 +239,7 @@ export function buildJobSpec(request) {
             thinking: request.thinking,
             force: request.force,
             attended: request.attended,
-            // Naming every profile is the same as leaving it out: the agent then takes all that are logged in.
+            // Naming every profile of the environment is the same as leaving it out: the agent then takes all that are logged in.
             profiles: request.profiles && request.profiles.length < profilesInEnv.length ? request.profiles : undefined,
             hints: hintsPath,
             report: request.report,

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

@@ -32,9 +32,12 @@ 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. */
+    /** `heal-spec` only: file (relative to the project root) with what the user wants repaired or improved, and any clues. */
     hints?: string;
     /** `heal-spec` only: the report (folder name under reports/) to read first instead of the newest one. */
     report?: string;
@@ -48,7 +51,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,16 +17,18 @@ 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}` : ''}`);
 };
@@ -69,7 +71,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 +82,8 @@ function invocation(tool, prompt, writes, session, model, thinking) {
             args: [
                 'run',
                 '--auto',
+                '--agent',
+                'build',
                 ...STREAM_ARGS.opencode,
                 ...(session ? ['-s', session.id] : []),
                 ...(model ? ['--model', model] : []),
@@ -121,11 +127,9 @@ const ATTENDED = 'Attended run: a person is at the machine and the browser windo
     '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. */
+/** 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}`;

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

@@ -103,7 +103,7 @@ 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. */
     hints?: string;