@asrunjs/asrun 0.2.0 → 0.5.3

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

@@ -1,148 +1,148 @@
-# Spec conventions
-
-## Shape
-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`).
-
-```ts
-// case: cases/<id>.md
-import {caseTags} from '@asrunjs/asrun/cases';
-import {configureCase, expect, test} from '@asrunjs/asrun/fixtures';
-import {requireValues} from '@asrunjs/asrun/values';
-
-test.use({mustLogin: false}); // only for login: none cases (public pages)
-
-test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
-  configureCase('<id>'); // from asrun/fixtures; no retries and a longer timeout for cases that write data
-  test('<single outcome>', async ({page, profile}) => {
-    const expected = requireValues<{...}>('<id>', profile); // the case's "## Values": default + this profile
-    // Locators are lazy: declare them here when several steps share them.
-
-    await test.step('1. <step text from the case>', async () => {
-      ...
-    });
-
-    await test.step('Visual check: <what is compared>', async () => {
-      await expect(locator).toHaveScreenshot('<name>.png');
-    });
-  });
-});
-```
-- Import `test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`. The package name is the import path
-  (the package's `exports` map points at its `dist/` build), so a spec in a group folder uses the same imports as one
-  at the top of `tests/`.
-- `profile` fixture = the current project's profile (`profile.id`, `profile.env`, `profile.baseURL`, `profile.account`,
-  `profile.tags`, `profile.email`). Never branch on `profile.id` or `profile.env` inside a spec: profile differences go
-  into the case's `## Values`, and the selectors come from `## Targets`.
-- Paths are relative (`page.goto('/account/')`); the project sets `baseURL` per profile.
-
-## Tags
-The case's front matter (`suites: [...]`, `writes`) is the single source of truth. The spec never hard-codes
-tags: it passes `{tag: caseTags('<id>')}` (from `@asrunjs/asrun/cases`) to the top-level `test.describe`.
-`caseTags` returns one `@<suite>` per suite (shown as badges in the HTML report, drives `pnpm asrun --suite <name>`)
-and `@writes` for cases that write data (drives `--read-only`).
-- Do not copy suites into the describe title.
-- If the front matter is invalid, `caseTags` throws; ask the user to fix the case.
-- Write permission and `envs` limits are enforced by the `caseGate` fixture in `@asrunjs/asrun/fixtures`; specs do nothing.
-  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.
-- 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
-  its own page (it cannot know where the test stopped) and must not fail if the data is already gone.
-- The case's last step is normally the deletion itself; `track` is the safety net. Do not rely on it alone.
-- If a cleanup fails, the test fails, the data is listed in the run summary (web UI banner and terminal) and
-  `pnpm cleanup --env <env>` lists it until a person deleted it and ran `--forget`.
-- `configureCase('<id>')` turns retries off (a retry would create the data twice) and raises the timeout.
-  Cases that write run one at a time per profile, whatever the number of workers.
-- Mark steps in the case text with `[writes]`; keep their titles unchanged in `test.step`.
-- Email: wrap steps that send email in `if (!emailStepAllowed(profile, '<step title>')) return;` (`@asrunjs/asrun/email`).
-  It is false in production and for profiles with `email: false`; the skip is written to the report annotations.
-
-## Steps (`test.step`)
-Every numbered step of the case is wrapped in `await test.step('<n>. <step text>', async () => {...})`.
-The report and the trace then show the case's own steps, so a reviewer can check what was executed
-without reading the spec.
-- Step title = the case's step text, verbatim, with its number. Do not paraphrase.
-- Put the assertions that belong to a step inside that step.
-- One extra step, titled `Visual check: <what is compared>`, per visual check from the case.
-- A value needed by a later step (for example a page opened in a new tab) is returned from the step:
-  `const previewPage = await test.step('3. ...', async () => {...; return opened;});`
-- Do not put `test.step` inside helpers in the framework (`@asrunjs/asrun/*`), and do not nest steps.
-- Use step comments only for things the title cannot say; the title replaces the old `// 1. ...` comments.
-
-## Assertion layers (use all that apply)
-1. Text: `toHaveText`, `toHaveTitle`, `toContainText`, with values from `requireValues('<id>', profile)`.
-2. DOM of images: `expectLogo(container, expected.logo)` / `expectImageLoaded`
-   (alt, src, loaded). Use `expectImageSha256` when the exact file must match.
-3. Pixels: `await expect(locator).toHaveScreenshot('<name>.png')`. Baselines are stored per
-   profile automatically. Screenshot a small element, not the full page (full pages are flaky).
-
-## Readable failures
-The UI shows the first line of the error to QA and non-technical people, and hides the call log and stack
-trace behind a "Technical details" fold. Write errors so that first line makes sense on its own.
-- Read per-profile data with `requireValues<T>('<id>', profile)` (from `@asrunjs/asrun/values`), never by reading the case
-  yaml yourself. A case with no entry for the profile, or with `TODO`/empty values, then fails with
-  "Missing values: cases/<id>.md has no \"## Values\" for profile ..." instead of a cryptic crash.
-- Give every `expect` a message in plain words about the product, not the code:
-  `expect(locator, 'The documents page did not finish loading').toBeVisible()`.
-  Say what is wrong ("The product logo has the wrong name"), not what the matcher is ("expected true").
-- Guard preconditions that need manual data (for example "at least one published document exists") with an
-  `expect(..., 'No published document found. Create one manually; this test never writes data.')` in the step,
-  so the failure says what the human has to do.
-- Messages are English, one sentence, no selectors or test ids.
-
-## Ready, targets and downloads (`@asrunjs/asrun/ready`, `@asrunjs/asrun/downloads`)
-Binding rules are in `../exploring-cases/references/readiness.md` and `.../assertion-targets.md`. In short:
-- An action that loads data (opens a dialog, a composer, a tab, a list, a preview) goes through
-  `actAndWait(page, () => click(), {responses: [/api-url/], ready: [locator]})`: the response waiters exist before the
-  action, then the content signal must be visible. Read the result only afterwards. `expectNotBusy(scope)` waits until
-  no spinner, skeleton or `aria-busy` is left.
-- A confirmation that may or may not appear after an action (the "Save as Draft?" dialog when closing a composer) is
-  handled with `clickOptionalUntilHidden(confirmButton, target, {message})`: one retry loop that clicks the confirmation
-  when it is visible and checks that the target is hidden. Never `if (await x.isVisible(...)) await x.click()`; see
-  `readiness.md`, "Optional confirmations".
-- A check on a logo, image, file or screenshot has `// target: T<n>` on the line before it (a card in the case's
-  `## Targets`). The element is found by the card's `Identified by` (role and name, test id, alt/title), never `.first()` or
-  a bare `img`/`svg`. Semantic assertion first (name/alt/src, where it is), pixels second, on that element only.
-- A check for absence ("no", "missing", "empty", "hidden") has `// ready: <signal>` in front of it and a positive wait
-  before it. The page must have loaded before "nothing" means anything.
-- A download is `await verifyDownload(page, () => option.click(), {kind: 'pdf'})`. It checks, and fails the step on
-  any failure or timeout: the download starts, finishes, the file exists, the file is valid for its kind (PDF: `%PDF-`
-  start, `%%EOF` end, opens with pages). Add `validate` for the case's own check of the content. Never
-  `waitForEvent('download')` or a magic-number check on its own.
-- A PDF's content is checked with `expectPdf(file.pdf!, {...})` (`@asrunjs/asrun/pdf`): pages rendered to images, regions that must not
-  be blank and are compared with the profile's baseline (2%), extracted text. Pages follow the case: every page by default
-  (`pages: 'all'`), only the named ones when the case says ONLY (a strong requirement) with `// pages: <the case's words>`.
-  The call has `// target: T<n>`. Take names and texts to avoid from `requireValues('<id>', profile)`, never literals.
-  ```ts
-  const file = await verifyDownload(page, () => option.click(), {kind: 'pdf'});
-  // target: T3
-  await expectPdf(file.pdf!, {
-    regions: [{name: 'profile-logo', pages: 'all', region: corner('top-left')}],
-    textNotContains: expected.otherProfileNames,
-  });
-  ```
-- `pnpm spec:lint <id>` (static) must have no `FAIL`. `pnpm baselines:review <id>` lists every baseline with the card
-  that says what it must show.
-
-## Do
-- Locators: `getByTestId` (data-tn) > `getByRole` > `getByLabel` > text.
-- Web-first assertions only; they auto-wait. Never `waitForTimeout`, never `networkidle`, never `if (await x.isVisible())`
-  to decide something that may not have loaded.
-- Keep every test read-only unless the case lists environments under `writes`.
-
-## Don't
-- No login code in specs, and no cases that test the login page or the login flow. Sessions come from
-  `.auth/<profile-id>.json` via the project config; a profile without a valid session fails fast (see
-  `@asrunjs/asrun/fixtures`).
-- No hard-coded profile names or expected values in specs; they come from the case's `## Values` through
-  `requireValues('<id>', profile)`. Site addresses come from `profile.baseURL`.
-- No screenshots of areas with dynamic data (rows, prices, dates, avatars).
-- No `.first()` / `.nth()` / bare `img`, `svg` or `img, svg` to find a logo or image.
-- No hard assertion about something that was never seen on a page.
-- No `isVisible({timeout})` / `isHidden({timeout})` (the timeout is ignored, nothing is waited for), no
-  `if (await x.isVisible()) await x.click()` outside a retry loop, and no `.catch(() => false)` to fake a wait.
+# Spec conventions
+
+## Shape
+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`).
+
+```ts
+// case: cases/<id>.md
+import {caseTags} from '@asrunjs/asrun/cases';
+import {configureCase, expect, test} from '@asrunjs/asrun/fixtures';
+import {requireValues} from '@asrunjs/asrun/values';
+
+test.use({mustLogin: false}); // only for login: none cases (public pages)
+
+test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
+  configureCase('<id>'); // from asrun/fixtures; no retries and a longer timeout for cases that write data
+  test('<single outcome>', async ({page, profile}) => {
+    const expected = requireValues<{...}>('<id>', profile); // the case's "## Values": default + this profile
+    // Locators are lazy: declare them here when several steps share them.
+
+    await test.step('1. <step text from the case>', async () => {
+      ...
+    });
+
+    await test.step('Visual check: <what is compared>', async () => {
+      await expect(locator).toHaveScreenshot('<name>.png');
+    });
+  });
+});
+```
+- Import `test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`. The package name is the import path
+  (the package's `exports` map points at its `dist/` build), so a spec in a group folder uses the same imports as one
+  at the top of `tests/`.
+- `profile` fixture = the current project's profile (`profile.id`, `profile.env`, `profile.baseURL`, `profile.account`,
+  `profile.tags`, `profile.email`). Never branch on `profile.id` or `profile.env` inside a spec: profile differences go
+  into the case's `## Values`, and the selectors come from `## Targets`.
+- Paths are relative (`page.goto('/account/')`); the project sets `baseURL` per profile.
+
+## Tags
+The case's front matter (`suites: [...]`, `writes`) is the single source of truth. The spec never hard-codes
+tags: it passes `{tag: caseTags('<id>')}` (from `@asrunjs/asrun/cases`) to the top-level `test.describe`.
+`caseTags` returns one `@<suite>` per suite (shown as badges in the HTML report, drives `pnpm asrun --suite <name>`)
+and `@writes` for cases that write data (drives `--read-only`).
+- Do not copy suites into the describe title.
+- If the front matter is invalid, `caseTags` throws; ask the user to fix the case.
+- Write permission and `envs` limits are enforced by the `caseGate` fixture in `@asrunjs/asrun/fixtures`; specs do nothing.
+  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.
+- 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
+  its own page (it cannot know where the test stopped) and must not fail if the data is already gone.
+- The case's last step is normally the deletion itself; `track` is the safety net. Do not rely on it alone.
+- If a cleanup fails, the test fails, the data is listed in the run summary (web UI banner and terminal) and
+  `pnpm cleanup --env <env>` lists it until a person deleted it and ran `--forget`.
+- `configureCase('<id>')` turns retries off (a retry would create the data twice) and raises the timeout.
+  Cases that write run one at a time per profile, whatever the number of workers.
+- Mark steps in the case text with `[writes]`; keep their titles unchanged in `test.step`.
+- Email: wrap steps that send email in `if (!emailStepAllowed(profile, '<step title>')) return;` (`@asrunjs/asrun/email`).
+  It is false in production and for profiles with `email: false`; the skip is written to the report annotations.
+
+## Steps (`test.step`)
+Every numbered step of the case is wrapped in `await test.step('<n>. <step text>', async () => {...})`.
+The report and the trace then show the case's own steps, so a reviewer can check what was executed
+without reading the spec.
+- Step title = the case's step text, verbatim, with its number. Do not paraphrase.
+- Put the assertions that belong to a step inside that step.
+- One extra step, titled `Visual check: <what is compared>`, per visual check from the case.
+- A value needed by a later step (for example a page opened in a new tab) is returned from the step:
+  `const previewPage = await test.step('3. ...', async () => {...; return opened;});`
+- Do not put `test.step` inside helpers in the framework (`@asrunjs/asrun/*`), and do not nest steps.
+- Use step comments only for things the title cannot say; the title replaces the old `// 1. ...` comments.
+
+## Assertion layers (use all that apply)
+1. Text: `toHaveText`, `toHaveTitle`, `toContainText`, with values from `requireValues('<id>', profile)`.
+2. DOM of images: `expectLogo(container, expected.logo)` / `expectImageLoaded`
+   (alt, src, loaded). Use `expectImageSha256` when the exact file must match.
+3. Pixels: `await expect(locator).toHaveScreenshot('<name>.png')`. Baselines are stored per
+   profile automatically. Screenshot a small element, not the full page (full pages are flaky).
+
+## Readable failures
+The UI shows the first line of the error to QA and non-technical people, and hides the call log and stack
+trace behind a "Technical details" fold. Write errors so that first line makes sense on its own.
+- Read per-profile data with `requireValues<T>('<id>', profile)` (from `@asrunjs/asrun/values`), never by reading the case
+  yaml yourself. A case with no entry for the profile, or with `TODO`/empty values, then fails with
+  "Missing values: cases/<id>.md has no \"## Values\" for profile ..." instead of a cryptic crash.
+- Give every `expect` a message in plain words about the product, not the code:
+  `expect(locator, 'The documents page did not finish loading').toBeVisible()`.
+  Say what is wrong ("The product logo has the wrong name"), not what the matcher is ("expected true").
+- Guard preconditions that need manual data (for example "at least one published document exists") with an
+  `expect(..., 'No published document found. Create one manually; this test never writes data.')` in the step,
+  so the failure says what the human has to do.
+- Messages follow the artifact language of `AGENTS.md` §2 (English by default), one sentence, no selectors or test ids.
+
+## Ready, targets and downloads (`@asrunjs/asrun/ready`, `@asrunjs/asrun/downloads`)
+Binding rules are in `../exploring-cases/references/readiness.md` and `.../assertion-targets.md`. In short:
+- An action that loads data (opens a dialog, a composer, a tab, a list, a preview) goes through
+  `actAndWait(page, () => click(), {responses: [/api-url/], ready: [locator]})`: the response waiters exist before the
+  action, then the content signal must be visible. Read the result only afterwards. `expectNotBusy(scope)` waits until
+  no spinner, skeleton or `aria-busy` is left.
+- A confirmation that may or may not appear after an action (the "Save as Draft?" dialog when closing a composer) is
+  handled with `clickOptionalUntilHidden(confirmButton, target, {message})`: one retry loop that clicks the confirmation
+  when it is visible and checks that the target is hidden. Never `if (await x.isVisible(...)) await x.click()`; see
+  `readiness.md`, "Optional confirmations".
+- A check on a logo, image, file or screenshot has `// target: T<n>` on the line before it (a card in the case's
+  `## Targets`). The element is found by the card's `Identified by` (role and name, test id, alt/title), never `.first()` or
+  a bare `img`/`svg`. Semantic assertion first (name/alt/src, where it is), pixels second, on that element only.
+- A check for absence ("no", "missing", "empty", "hidden") has `// ready: <signal>` in front of it and a positive wait
+  before it. The page must have loaded before "nothing" means anything.
+- A download is `await verifyDownload(page, () => option.click(), {kind: 'pdf'})`. It checks, and fails the step on
+  any failure or timeout: the download starts, finishes, the file exists, the file is valid for its kind (PDF: `%PDF-`
+  start, `%%EOF` end, opens with pages). Add `validate` for the case's own check of the content. Never
+  `waitForEvent('download')` or a magic-number check on its own.
+- A PDF's content is checked with `expectPdf(file.pdf!, {...})` (`@asrunjs/asrun/pdf`): pages rendered to images, regions that must not
+  be blank and are compared with the profile's baseline (2%), extracted text. Pages follow the case: every page by default
+  (`pages: 'all'`), only the named ones when the case says ONLY (a strong requirement) with `// pages: <the case's words>`.
+  The call has `// target: T<n>`. Take names and texts to avoid from `requireValues('<id>', profile)`, never literals.
+  ```ts
+  const file = await verifyDownload(page, () => option.click(), {kind: 'pdf'});
+  // target: T3
+  await expectPdf(file.pdf!, {
+    regions: [{name: 'profile-logo', pages: 'all', region: corner('top-left')}],
+    textNotContains: expected.otherProfileNames,
+  });
+  ```
+- `pnpm spec:lint <id>` (static) must have no `FAIL`. `pnpm baselines:review <id>` lists every baseline with the card
+  that says what it must show.
+
+## Do
+- Locators: `getByTestId` (data-tn) > `getByRole` > `getByLabel` > text.
+- Web-first assertions only; they auto-wait. Never `waitForTimeout`, never `networkidle`, never `if (await x.isVisible())`
+  to decide something that may not have loaded.
+- Keep every test read-only unless the case lists environments under `writes`.
+
+## Don't
+- No login code in specs, and no cases that test the login page or the login flow. Sessions come from
+  `.auth/<profile-id>.json` via the project config; a profile without a valid session fails fast (see
+  `@asrunjs/asrun/fixtures`).
+- No hard-coded profile names or expected values in specs; they come from the case's `## Values` through
+  `requireValues('<id>', profile)`. Site addresses come from `profile.baseURL`.
+- No screenshots of areas with dynamic data (rows, prices, dates, avatars).
+- No `.first()` / `.nth()` / bare `img`, `svg` or `img, svg` to find a logo or image.
+- No hard assertion about something that was never seen on a page.
+- No `isVisible({timeout})` / `isHidden({timeout})` (the timeout is ignored, nothing is waited for), no
+  `if (await x.isVisible()) await x.click()` outside a retry loop, and no `.catch(() => false)` to fake a wait.

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

@@ -1,64 +1,72 @@
----
-name: making-cases
-description: Turns raw, informal test notes from a human (a QA memo, a list of buttons to check, a pasted chat) into well-formed case documents (cases/<id>.md) for the AsRun suite. Normalizes the text, classifies steps as read-only, writing or email, finds gaps and asks about them, never opens a browser, and splits the notes into cases. Use when asked to make, write or normalize cases from notes, or for /make-case. The next step after it is exploring-cases, then generating-specs.
----
-
-# Making case documents from raw notes
-
-Read `AGENTS.md` (hard rules) and `cases/_template.md` (the target format) first. Then read the references:
-- `references/normalizing.md`: how to clean up the text and keep the original traceable.
-- `references/writes-and-email.md`: how to classify steps that write data or send email, and the data rules.
-- `references/gaps.md`: what to ask, and the default to suggest for each question.
-- `references/splitting.md`: how many cases to make.
-
-This skill writes `cases/*.md` only. It never writes specs, `profiles.yaml`, or anything under `tests/`.
-
-## Inputs
-- Raw notes: pasted text or a file path. Any language, any quality.
-- No environment: this skill never opens a browser. What the pages really show is found by `/explore-case`.
-
-## Procedure
-1. **Read everything and keep the original.** Number every distinct statement of the notes (N1, N2, ...). The
-   original wording is stored verbatim in each case's `## Source` table, so nothing is lost and a reviewer can check
-   what became of each line. Do not edit the input file.
-2. **Normalize.** Follow `references/normalizing.md`: English, one action or check per step, concrete UI wording,
-   quoted UI text kept exactly. Do not add checks the notes did not ask for, and do not drop any.
-3. **Classify each step**: read-only, `[writes]`, or `[email]` (`references/writes-and-email.md`). A step that
-   creates, edits, publishes, shares, deletes or sends is not read-only, even if the notes do not say so.
-4. **Find the gaps** (`references/gaps.md`): missing expected results, unknown values a spec must assert, unclear starting
-   state, steps that need data that may not exist, ordering that is not linear. Never invent an expected value.
-   Unknown values are written as the suggested default sentence with a `❓ TODO` block under it (see `gaps.md`), or as an
-   `Observed, 🔍 to be confirmed by QA` bullet. Every marker starts with its emoji. A literal nobody knows yet goes into
-   the case's `## Values` as `TODO` (the spec then fails 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.
-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
-     lowercase kebab-case. Reuse an existing folder in `cases/` when the area matches. If the area is unclear,
-     ask in step 5. The group does not repeat in the name: `documents/landing-page`, not `documents/documents-landing-page`.
-   - Front matter: `id`, `title`, `login`, `suites`, `writes`, `writes-note` (required when `writes` is not `none`),
-     `envs` when a case must not run everywhere. When unsure: `suites: [regression]`, no `writes` (read-only), or `writes: [staging]` when a step writes.
-   - Fill the sections that apply (Goal, Steps, Expected, Values, Visual checks, Data, Source, Notes).
-     Remove template placeholders you do not use. Use `## Values` only for the literals a spec asserts; `default`
-     applies to every profile, and a profile id entry holds only what differs.
-   - Case ids are lowercase kebab-case and name the thing, not the ticket: `landing-page`.
-   - Existing case files: do not overwrite. If a new case overlaps one (for example another case about the same page), say so,
-     propose "keep", "merge" or "replace", and wait for the user.
-7. **Check.** Run `pnpm case:check`. Fix every FAIL. Re-read each written case against the numbered statements: every
-   N must appear in exactly one `## Source` table, or in the report as "not used, because ...".
-8. **Report** in the user's language: the cases written (id, suites, writes, envs), the traceability summary, the
-   questions that are still open, and the next steps per case: `/explore-case <id> <env> --attended` (after `pnpm signin`
-   for the profiles and environment; a person does the steps that write data), then `/gen-spec <id> <env>`.
-
-## Hard rules
-- Never open a browser and never write data. A step that writes is only described and marked; the case lists the
-  environments the spec may write in under `writes`. Never add `--allow-writes`, never set
-  `ASRUN_ALLOW_WRITES`; this skill does not run write cases at all.
-- Never send email in production. In other environments only for profiles with `email: true`. New profiles and AI-written
-  entries in `profiles.yaml` get `email: false`; do not change an existing `email: true`.
-- Never write a case for the login page or the login flow.
-- Never invent expected values, profile names, counts, or UI texts.
-- All files are written in English.
+---
+name: making-cases
+description: Turns raw, informal test notes from a human (a QA memo, a list of buttons to check, a pasted chat) into well-formed case documents (cases/<id>.md) for the AsRun suite. Normalizes the text, classifies steps as read-only, writing or email, finds gaps and asks about them, never opens a browser, and splits the notes into cases. Use when asked to make, write or normalize cases from notes, or for /make-case. The next step after it is exploring-cases, then generating-specs.
+---
+
+# Making case documents from raw notes
+
+Read the workspace `AGENTS.md` (hard rules and project rules) and `cases/_template.md` (the target format) first. Then read the references:
+- `references/normalizing.md`: how to clean up the text and keep the original traceable.
+- `references/writes-and-email.md`: how to classify steps that write data or send email, and the data rules.
+- `references/gaps.md`: what to ask, and the default to suggest for each question.
+- `references/splitting.md`: how many cases to make.
+
+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 always win. This is not a stop condition: continue with
+the procedure below.
+
+## Inputs
+- Raw notes: pasted text or a file path. Any language, any quality.
+- No environment: this skill never opens a browser. What the pages really show is found by `/explore-case`.
+
+## Procedure
+1. **Read everything and keep the original.** Number every distinct statement of the notes (N1, N2, ...). The
+   original wording is stored verbatim in each case's `## Source` table, so nothing is lost and a reviewer can check
+   what became of each line. Do not edit the input file.
+2. **Normalize.** Follow `references/normalizing.md`: the artifact language of `AGENTS.md` §2 (English by default),
+   one action or check per step, concrete UI wording,
+   quoted UI text kept exactly. Do not add checks the notes did not ask for, and do not drop any.
+3. **Classify each step**: read-only, `[writes]`, or `[email]` (`references/writes-and-email.md`). A step that
+   creates, edits, publishes, shares, deletes or sends is not read-only, even if the notes do not say so.
+4. **Find the gaps** (`references/gaps.md`): missing expected results, unknown values a spec must assert, unclear starting
+   state, steps that need data that may not exist, ordering that is not linear. Never invent an expected value.
+   Unknown values are written as the suggested default sentence with a `❓ TODO` block under it (see `gaps.md`), or as an
+   `Observed, 🔍 to be confirmed by QA` bullet. Every marker starts with its emoji. A literal nobody knows yet goes into
+   the case's `## Values` as `TODO` (the spec then fails 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.
+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
+     lowercase kebab-case. Reuse an existing folder in `cases/` when the area matches. If the area is unclear,
+     ask in step 5. The group does not repeat in the name: `documents/landing-page`, not `documents/documents-landing-page`.
+   - Front matter: `id`, `title`, `login`, `suites`, `writes`, `writes-note` (required when `writes` is not `none`),
+     `envs` when a case must not run everywhere. When unsure: `suites: [regression]`, no `writes` (read-only), or `writes: [staging]` when a step writes.
+   - Fill the sections that apply (Goal, Steps, Expected, Values, Visual checks, Source, Notes).
+     Remove template placeholders you do not use. Use `## Values` only for the literals a spec asserts; `default`
+     applies to every profile, and a profile id entry holds only what differs. Do not add `- Recipe:` lines: a person
+     records them during `/explore-case --attended`.
+   - Case ids are lowercase kebab-case and name the thing, not the ticket: `landing-page`.
+   - Existing case files: do not overwrite. If a new case overlaps one (for example another case about the same page), say so,
+     propose "keep", "merge" or "replace", and wait for the user.
+7. **Check.** Run `pnpm case:check`. Fix every FAIL. Re-read each written case against the numbered statements: every
+   N must appear in exactly one `## Source` table, or in the report as "not used, because ...".
+8. **Report** in the user's language: the cases written (id, suites, writes, envs), the traceability summary, the
+   questions that are still open, and the next steps per case: `/explore-case <id> <env> --attended` (after `pnpm signin`
+   for the profiles and environment; a person does the steps that write data), then `/gen-spec <id> <env>`.
+
+## Hard rules
+- Never open a browser and never write data. A step that writes is only described and marked; the case lists the
+  environments the spec may write in under `writes`. Never add `--allow-writes`, never set
+  `ASRUN_ALLOW_WRITES`; this skill does not run write cases at all.
+- Never send email in production. In other environments only for profiles with `email: true`. New profiles and AI-written
+  entries in `profiles.yaml` get `email: false`; do not change an existing `email: true`.
+- Never write a case for the login page or the login flow.
+- Never invent expected values, profile names, counts, or UI texts.
+- Prose follows the artifact language of the workspace `AGENTS.md` §2 (English by default); structural tokens stay English.

package/.claude/skills/making-cases/references/normalizing.md

@@ -1,38 +1,39 @@
-# Normalizing raw notes
-
-## Goal
-Turn informal notes into steps that someone who never saw the notes can follow, without changing what was asked.
-
-## Rules
-1. **Translate to English.** Keep text the page shows exactly as written in the notes (button labels such as
-   "Create New", pill names such as "My documents", "Shared with me"). Do not translate or "fix" those.
-2. **One action or one check per step.** Split "create, publish and preview it" into three steps. A check that
-   belongs to an action stays in the same step as its action ("Open Share and check the logo").
-3. **Make the wording concrete.** Say where (page, path, card, corner), what (exact label), and what happens.
-   "Check the logo" is not a step by itself: it needs an expected result (see `gaps.md`). Until it has one, write
-   the default as a sentence under "Expected" ("The <thing> is visible and not empty.") with a
-   `TODO [non-blocking]` block under it (see `gaps.md`).
-4. **Keep the order of the notes** unless the notes say otherwise, then fix the order and say so in the Source table.
-5. **Do not add checks** the notes did not ask for (no extra assertions "while we are at it"), and do not drop any.
-   When a line is a heading or a list of things on one page ("Landing: Create New, All, My documents, Shared with me,
-   search bar"), each item becomes a check: "is visible" is the only meaning you may assume, and you say so.
-6. **Mark steps** with `[writes]` or `[email]` at the end of the step text (see `writes-and-email.md`).
-7. **Use paths relative to the app** (`/app/documents`), never a full domain. Domains differ per profile and environment.
-8. **No profile-specific values in steps.** The exact literals go in `## Values`; a sentence about behaviour goes in `Expected`.
-
-## Traceability (`## Source` section in every case)
-Number every statement of the raw notes once (N1, N2, ...). Each case ends with:
-
-```markdown
-## Source
-Original notes, verbatim. Do not edit this table; it only exists so a reviewer can check what became of each line.
-
-| # | Original text | Became |
-|---|---------------|--------|
-| N3 | `Published document: publish (a follow-up modal opens by itself)` | Steps 6-7 |
-```
-
-- The original text is copied character by character, in a code span, in its original language.
-- "Became" points at step numbers, or says "Expected", "Visual checks", "Not used: <reason>".
-- A statement used by two cases appears in both tables.
-- A statement that is not used anywhere is a gap: ask about it, do not silently drop it.
+# Normalizing raw notes
+
+## Goal
+Turn informal notes into steps that someone who never saw the notes can follow, without changing what was asked.
+
+## Rules
+1. **Use the artifact language.** Translate the notes into the language `AGENTS.md` §2 sets (English by default).
+   Keep text the page shows exactly as written in the notes (button labels such as
+   "Create New", pill names such as "My documents", "Shared with me"). Do not translate or "fix" those.
+2. **One action or one check per step.** Split "create, publish and preview it" into three steps. A check that
+   belongs to an action stays in the same step as its action ("Open Share and check the logo").
+3. **Make the wording concrete.** Say where (page, path, card, corner), what (exact label), and what happens.
+   "Check the logo" is not a step by itself: it needs an expected result (see `gaps.md`). Until it has one, write
+   the default as a sentence under "Expected" ("The <thing> is visible and not empty.") with a
+   `TODO [non-blocking]` block under it (see `gaps.md`).
+4. **Keep the order of the notes** unless the notes say otherwise, then fix the order and say so in the Source table.
+5. **Do not add checks** the notes did not ask for (no extra assertions "while we are at it"), and do not drop any.
+   When a line is a heading or a list of things on one page ("Landing: Create New, All, My documents, Shared with me,
+   search bar"), each item becomes a check: "is visible" is the only meaning you may assume, and you say so.
+6. **Mark steps** with `[writes]` or `[email]` at the end of the step text (see `writes-and-email.md`).
+7. **Use paths relative to the app** (`/app/documents`), never a full domain. Domains differ per profile and environment.
+8. **No profile-specific values in steps.** The exact literals go in `## Values`; a sentence about behaviour goes in `Expected`.
+
+## Traceability (`## Source` section in every case)
+Number every statement of the raw notes once (N1, N2, ...). Each case ends with:
+
+```markdown
+## Source
+Original notes, verbatim. Do not edit this table; it only exists so a reviewer can check what became of each line.
+
+| # | Original text | Became |
+|---|---------------|--------|
+| N3 | `Published document: publish (a follow-up modal opens by itself)` | Steps 6-7 |
+```
+
+- The original text is copied character by character, in a code span, in its original language.
+- "Became" points at step numbers, or says "Expected", "Visual checks", "Not used: <reason>".
+- A statement used by two cases appears in both tables.
+- A statement that is not used anywhere is a gap: ask about it, do not silently drop it.