@asrunjs/asrun 0.13.0 → 0.15.0

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

@@ -8,14 +8,19 @@ Rules combine in this order, and a later one wins where they conflict: the frame
 framework skill, `.claude/skills/exploring-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
 (Project rules). F1–F6 and R2 always win. The effective set is what `pnpm asrun rules` prints; §2 is applied as
 written and is never turned into a question (a difference from a framework default is not a conflict).
-Arguments: `<case-id> <env> [--attended] [--profiles a,b] [--hints <file>]`. The case id is the path below cases/ without `.md` (it may include a group
+Arguments: `<case-id> <env> [--attended] [--profiles a,b] [--lead <profile-id>] [--hints <file>]`. 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.
+logged-in profile per domain. Every id in that list is opened in its own session (`generator_setup_page` with
+`project=<id>`); two different hosts are two domains, even for the same product. 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.
+`--lead <profile-id>` explores the selection asymmetrically: that profile in full, every other selected profile only
+where it can differ (its own `## Values` entries, its target screenshots and the steps that reach them), as the skill's
+"Profile passes" says; a profile whose page or flow differs is explored in full and the report says so. Keep lead and
+diff profiles in one run, because the notes are written at its end.
 `--hints <file>` (or free text after the arguments) is what I know or want checked; read it first. After the work, a
 reusable instruction goes into `## Rules` by the gate in `references/case-rules.md`; a one-off clue stays in the report.
 Read `## Rules` before the steps and apply it. Follow `case-rules.md` (a rule says how to run the case, never what it

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, 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. Also writes a local exploration note (locators and data-call paths) under `.explore/` for `/gen-spec` to verify instead of rediscovering. 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 the profiles named with --profiles or, without it, for at least one logged-in profile per domain. With --lead <id> one profile is explored in full and the others only where they can differ. 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. Also writes a local exploration note (locators and data-call paths) under `.explore/` for `/gen-spec` to verify instead of rediscovering. 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
@@ -54,10 +54,17 @@ one exception is a handoff in an attended run, where waiting for the person is t
   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.
+- Optionally `--profiles a,b`: explore only these profiles (ids from `profiles.yaml`, comma-separated): **every id in
+  the list**. Without it, at least one logged-in profile per domain. A different host is a different domain, even when
+  two profiles serve the same product on another address, so the list is never collapsed into one profile. 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.
+- Optionally `--lead <profile-id>`: explore the profiles of this run asymmetrically. The lead profile (one of the ids
+  this run explores, normally the first) is explored **in full**; every other selected profile gets the **diff pass**
+  of step 4: only what can differ on it, plus what reaches it. Without the flag every profile is explored in full.
+  Lead and diff profiles belong in **one run**: the case edits of a diff pass would make a note written before them
+  stale, so a split run falls back to a replay instead of the notes.
 - Optionally `--hints <file>` (or free text after the arguments): what the person knows or wants checked. Read it
   before the static review. It guides this run; after the work, a reusable instruction is written into `## Rules` by
   the gate in `references/case-rules.md`, and a one-off clue stays in the report.
@@ -90,14 +97,46 @@ one exception is a handoff in an attended run, where waiting for the person is t
    in this session at all (no `browser_*` / `generator_*` tool) or the server 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`, make no observations, and end with `RESULT: needs-input`.
-   Explore each profile `--profiles` names that is logged in, and, without `--profiles`, at least one logged-in profile
-   per domain. Never explore a profile the selection leaves out, and never add a profile to fill a gap. Profiles that
+   Explore each profile `--profiles` names that is logged in, and, without `--profiles`, one logged-in profile per
+   domain. 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>`.
+   **One profile at a time, one session each.** Open it with
+   `generator_setup_page({project: '<profile-id>', seedFile: 'tests/seed.spec.ts', plan: ''})`; never call it without
+   `project` (the MCP then opens whichever project it likes). Before the first read, check that `page.url()` starts
+   with that profile's `baseURL` in `profiles.yaml`: if it does not, the wrong project is open, so open the right one
+   and record nothing from the wrong page. A different host is a different domain even when both profiles serve the
+   same product, so two named profiles mean two sessions, never one. Finish every selected profile before you start
+   writing the case.
+   **Profile passes (`--lead`).** Without the flag every selected profile is explored in full. With `--lead <id>` the
+   lead profile is explored in full (every step, every handoff, every recipe, every target, a note with every step) and
+   each other selected profile gets the **diff pass**:
+   - **Confirm the structure first.** Open the profile and check that it is the same application as the lead's: the same
+     header, navigation, page layout and components around each differing check. A different host is no reason to skip
+     this profile, and no reason to assume it matches: it is the same app with another address, style or dataset. A page,
+     a control or a step that differs from the lead's, and any profile whose flow needs another step, makes that
+     profile a **full pass** — explore it as if `--lead` had not been given, and say so in the report.
+   - **Do only the differing steps** and the read-only navigation and `Ready when` signals that reach them. A step
+     differs when (a) a value it asserts comes from that profile's own `## Values` entry, (b) it reads a `[T<n>]` whose
+     card needs this profile's `Reference <profile-id>:`, (c) a `## Rules` bullet tied to that step says so, or (d) its
+     page differs from the lead's. When in doubt whether a step can differ, run it: the diff pass never assumes.
+   - **A write step that a differing check needs is still a handoff** on that profile: data of a test account or a
+     tenant is usually private to it. Hand off only what reaches the check (create, observe, clean up, in that order),
+     and record the observation from the card's `recorded` result as on any profile.
+   - **Record the difference, not the flow**: one observation per differing check, one `Reference <profile-id>:`
+     screenshot for each target card it confirms, and that profile's own `## Values` entries. Every other step stays
+     as the lead observed it and is reported as `observed on <lead>, not verified on <profile>`; do not write a second
+     copy of the steps, a marker or a TODO about them.
+   - **What it cannot reach is a gap, not an assumption**: a differing check whose page cannot be opened gets a
+     `TODO [blocking]` under the step that needs it, never "same as the lead".
+   - **A step whose recipe would differ per profile** (another editor, another dialog, an extra step) is explored in
+     full on that profile, and reported: the case's `- Recipe:` lines are per step, not per profile, so a single recipe
+     cannot describe both. When the difference is real, put a `❓ TODO [non-blocking]` under the step asking whether the
+     case should be split; never rewrite the lead's recipe to fit one profile.
    - 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,
-     name the finish condition, run the wait loop (the card records what the person does), then write down what
-     happened from its `recorded` result. In a run that is not attended, write a `TODO [blocking]` under the step
-     instead.
+   - **A step that writes or needs a choice is done by the person**, per `references/user-handoff.md`: announce it
+     with one sentence plus one action per entry of `steps` and the finish condition in `finish`, run the wait loop
+     (the card records what the person does), then write down what happened from its `recorded` result. In a run that
+     is not attended, write a `TODO [blocking]` under the step instead.
    - Close any modal that opens by itself without confirming it (for example the follow-up modal that opens after
      publishing: close it and confirm nothing).
    - When a confirm dialog appears while closing an email composer, choose "Discard" (see `AGENTS.md`).
@@ -122,7 +161,8 @@ one exception is a handoff in an attended run, where waiting for the person is t
      in the five parts of `references/readiness.md`, "Downloads", and record the file name, size and kind. Render a
      downloaded PDF (`pnpm pdf:render`), open its page images and record which pages show the target, where, and the
      text; the pages follow the case (every page unless the case says ONLY).
-   - Compare every step with what is really there.
+   - Compare every step with what is really there. On a diff pass, that means the steps the pass opened: the rest stay
+     as the lead observed them.
    - **Record the exploration note** for this profile as you go, in the shape of `references/notes.md`: the locator of
      each step's main control, the data-call paths of each loading action, and each target it confirmed. It is local
      cache under `.explore/`, never case content, and `/gen-spec` reads it; step 8 writes the file.
@@ -138,7 +178,8 @@ one exception is a handoff in an attended run, where waiting for the person is t
    (`testDataName`); the recipe records how to build it, never the stamp itself. A step that was not handed off gets
    no recipe line and a `[blocking]` TODO. A case
    that still has the old `## Inputs` section: move the lines of the steps you touch under those steps as
-   `- Recipe:`; `pnpm case:check` names the rest.
+   `- Recipe:`; `pnpm case:check` names the rest. A diff pass normally adds no recipe line: the step's recipe from the
+   lead pass still describes it. When the pass had to write and the step has no recipe yet, write one from that handoff.
 7. **Resolve every open point** in the order of `references/open-questions.md`: answer it from the page, else apply
    the safe default as the sentence above a `[non-blocking]` TODO block, else keep a `[blocking]` block. Write the
    outcome into the case, every block with an empty `Answer:` line. Then mark the facts you wrote: a fact the run
@@ -157,8 +198,20 @@ one exception is a handoff in an attended run, where waiting for the person is t
    line of every profile you explored must say `fresh`), and fix every FAIL. If
    `case:check` fails with a sandbox error (`listen EPERM`), run
    `node --import tsx <framework>/scripts/check-cases.ts` instead; it checks the same thing.
+   **A selected profile that is logged in gets its own note.** The note, the target card's `Reference
+   <profile-id>` and at least one observation marked with that profile id are the proof: before you report, compare the
+   selection with `.explore/notes/<case-id>/` and with the profile ids the case now names. A profile with no note that
+   was not skipped for its login was not explored: write a `TODO [blocking]` under the first step it affects (a person
+   re-runs `/explore-case` with that profile) and say so in the report; never report a run as complete for a profile
+   that was not opened. A profile skipped because it is not logged in gets no note and is named as skipped instead.
+   **A full note covers every step; a diff note covers the steps its pass opened** and names the lead in `depth: "diff"`
+   and `basedOn: "<lead profile-id>"` (`references/notes.md`, "Coverage"). A diff note is complete as it is: do not add
+   the lead's steps to it, and do not report the profile as unexplored. `pnpm asrun explore:notes <case-id> --check`
+   warns when a diff note's lead has no note of its own.
 9. **Report** in the user's language: what was changed (wording fixes, observations added, TODOs closed or narrowed),
-   what was explored (profile ids), which profiles `--profiles` left out (and that a run with them covers the rest),
+   what was explored (profile ids), which profile was explored in full and which in a diff pass (with the steps each
+   diff pass opened, which checks stay `observed on <lead>, not verified on <profile>`, and any profile that turned out
+   to need a full pass and why), 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 the exploration note covers (and what it does not),
    what was skipped and
    why, the target cards written (and which ones are still questions), the steps whose first read was too early,
@@ -181,6 +234,11 @@ one exception is a handoff in an attended run, where waiting for the person is t
   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.
+- A diff pass never assumes: a page, a control or a step that differs from the lead's makes that profile a full pass,
+  and a differing check it cannot reach is a `TODO [blocking]`, never "same as the lead".
+- The diff pass covers values, targets and the pages that reach them. A step whose recipe differs per profile is
+  explored in full on that profile and reported (a `- Recipe:` belongs to a step, not to a profile), never folded into
+  the lead's recipe.
 - 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/handoff-card.js

@@ -4,8 +4,25 @@ async (page) => {
   const ctx = page.context();
   const cfg = ctx.__handoffCfg || {};
   const message = cfg.message || 'Do the step, then press Done';
+  // The steps are the person's actions, one per line and numbered by the card: a handoff that needs several things
+  // never becomes one sentence nobody can follow (see user-handoff.md, "Before the handoff").
+  const steps = (Array.isArray(cfg.steps) ? cfg.steps : [])
+    .filter((step) => typeof step === 'string' && step.trim())
+    .map((step) => step.trim());
   const copy = Array.isArray(cfg.copy) ? cfg.copy : [];
   const doneText = cfg.doneText || null;
+  // The finish condition gets its own block. `doneText` is the same promise as a text the card can watch for, so an
+  // older handoff that only set it still says when the step is done.
+  const finish = typeof cfg.finish === 'string' && cfg.finish.trim()
+    ? cfg.finish.trim()
+    : doneText ? `"${doneText}" appears` : null;
+  // The finish condition usually quotes the text it waits for ("Unfavorite Article"). A handoff that left `doneText`
+  // out gets that text as its signal, so the card ends by itself; the check below drops it when the page already shows
+  // it, because a condition that holds before the person acts must never end the handoff at once.
+  const quoted = finish
+    ? ((finish.match(/["“]([^"”]{2,})["”]/) || finish.match(/'([^']{2,})'/)) || [])[1]
+    : undefined;
+  let watchedText = doneText || (quoted ? quoted.trim() : null);
   const maxMs = cfg.maxMs || 600000;
   await ctx.grantPermissions(['clipboard-read', 'clipboard-write']).catch(() => {});
 
@@ -55,7 +72,18 @@ async (page) => {
     }
   }
 
-  const paint = (p) => p.evaluate(({message, copy}) => {
+  /** True when the page's own text holds `text`: the card's text is never part of it (it quotes the condition). */
+  const pageHasText = (p, text) => p.evaluate((needle) => {
+    const lower = needle.toLowerCase();
+    if (!document.body) return false;
+    if (document.body.innerText.toLowerCase().includes(lower)) return true;
+    // Sites that render inside their own shadow roots are not in innerText.
+    return Array.from(document.querySelectorAll('*')).some((el) =>
+      el.id !== '__ASRUN_panel' && el.shadowRoot &&
+      el.shadowRoot.textContent.toLowerCase().includes(lower));
+  }, text).catch(() => false);
+
+  const paint = (p) => p.evaluate(({message, steps, finish, copy, autoEnd}) => {
     if (document.getElementById('__ASRUN_panel')) return;
     const KEY = '__ASRUN_panel_state';
     let state = {minimized: false, left: null, top: null};
@@ -74,24 +102,55 @@ async (page) => {
     host.style.cssText = 'all:initial;position:fixed;z-index:2147483647;left:16px;bottom:16px';
     const root = host.attachShadow({mode: 'open'});
     root.innerHTML = '<style>' +
-      '.card{width:300px;max-width:calc(100vw - 32px);background:#1e3340;color:#fff;font:13px/1.4 system-ui,sans-serif;border-radius:8px;box-shadow:0 6px 20px rgba(0,0,0,.35);overflow:hidden}' +
+      '.card{width:340px;max-width:calc(100vw - 32px);background:#1e3340;color:#fff;font:13px/1.4 system-ui,sans-serif;border-radius:8px;box-shadow:0 6px 20px rgba(0,0,0,.35);overflow:hidden}' +
       '.card.min{width:auto}.card.ok{background:#15803d}' +
       '.bar{display:flex;align-items:center;gap:8px;padding:7px 8px 7px 12px;background:#b45309;cursor:grab;user-select:none;touch-action:none}' +
       '.ok .bar{background:#166534;align-items:flex-start;padding-top:9px}.bar b{flex:1;min-width:0;font-size:12px;letter-spacing:.04em;white-space:nowrap}.ok .bar b{white-space:normal;line-height:1.35}.grip{display:inline-flex;opacity:.8}' +
       'button{all:unset;box-sizing:border-box;cursor:pointer;display:inline-flex;align-items:center;justify-content:center;gap:4px;padding:3px 8px;border-radius:4px;background:rgba(255,255,255,.18);color:#fff;font:600 12px system-ui,sans-serif}' +
       'button:hover{background:rgba(255,255,255,.3)}' +
-      '.body{padding:10px 12px 12px;display:flex;flex-direction:column;gap:8px}.min .body,.ok .body{display:none}' +
+      // The steps scroll on their own: a long list never pushes the finish condition or the buttons out of the card.
+      '.body{display:flex;flex-direction:column}.min .body,.ok .body{display:none}' +
+      '.content{display:flex;flex-direction:column;gap:9px;padding:10px 12px 0}' +
+      '.summary{font-weight:600;white-space:pre-wrap;overflow-wrap:anywhere}' +
+      '.steps{margin:0;padding:0 2px 0 1.6em;display:flex;flex-direction:column;gap:6px;max-height:min(30vh,240px);overflow:auto;scrollbar-width:thin;scrollbar-color:rgba(255,255,255,.35) transparent}' +
+      '.steps li{padding-left:2px;overflow-wrap:anywhere}.steps li::marker{color:#fbbf24;font-weight:700}' +
+      // A list longer than its box fades out at the bottom instead of cutting a line in half, so nobody reads it as the end.
+      '.steps.scrolly{-webkit-mask-image:linear-gradient(to bottom,#000 calc(100% - 16px),transparent);mask-image:linear-gradient(to bottom,#000 calc(100% - 16px),transparent)}' +
+      '.finish{margin:9px 12px 0;border-left:4px solid #22c55e;background:rgba(34,197,94,.18);border-radius:4px;padding:7px 10px;display:flex;flex-direction:column;gap:3px}' +
+      '.finish .label{font-size:10px;font-weight:700;letter-spacing:.1em;color:#86efac}' +
+      '.finish .cond{font-weight:600;line-height:1.35;overflow-wrap:anywhere}' +
+      '.finish .also{font-size:11px;opacity:.8}' +
       '.mini-done{display:none}.min .mini-done{display:inline-flex}' +
       '.chip{display:flex;align-items:center;gap:6px;background:rgba(0,0,0,.28);padding:4px 4px 4px 8px;border-radius:4px}' +
       '.chip span{flex:1;font:12px ui-monospace,Menlo,monospace;word-break:break-all;user-select:all}' +
-      '.row{display:flex;gap:8px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}' +
+      '.row{display:flex;gap:8px;padding:12px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}' +
       '</style>' +
       '<div class="card" id="card"><div class="bar" id="bar" title="Drag to move"><span class="grip">' + ICON.move + '</span><b id="title">YOUR TURN</b>' +
       '<button class="mini-done" data-a="done" aria-label="AsRun handoff: done">Done</button><button id="toggle" title="Minimize or expand" aria-label="AsRun handoff: minimize or expand"></button></div>' +
-      '<div class="body"><div id="msg"></div><div id="chips"></div><div class="row">' +
+      '<div class="body"><div class="content"><div id="msg" class="summary"></div><ol id="steps" class="steps"></ol><div id="chips"></div></div>' +
+      '<div id="finish" class="finish" style="display:none"><div class="label">DONE WHEN</div><div id="cond" class="cond"></div>' +
+      '<div id="also" class="also"></div></div>' +
+      '<div class="row">' +
       '<button class="primary" data-a="done" aria-label="AsRun handoff: done">Done</button><button data-a="skip" aria-label="AsRun handoff: cannot do this">Cannot do this</button></div></div></div>';
     const card = root.getElementById('card'), bar = root.getElementById('bar'), toggle = root.getElementById('toggle');
+    // Every text goes in through `textContent`: the message comes from an agent, never from the site under test.
     root.getElementById('msg').textContent = message;
+    const list = root.getElementById('steps');
+    if (steps.length) {
+      for (const step of steps) {
+        const item = document.createElement('li');
+        item.textContent = step;
+        list.appendChild(item);
+      }
+    } else list.style.display = 'none';
+    if (finish) {
+      root.getElementById('cond').textContent = finish;
+      // Say which way the wait can end: a card that can never notice the condition must not suggest that it will.
+      root.getElementById('also').textContent = autoEnd
+        ? 'The card ends by itself when this shows. Done also works.'
+        : 'Press Done when you are finished.';
+      root.getElementById('finish').style.display = 'flex';
+    }
     const chips = root.getElementById('chips');
     chips.style.cssText = 'display:' + (copy.length ? 'flex' : 'none') + ';flex-direction:column;gap:6px';
     for (const text of copy) {
@@ -115,6 +174,10 @@ async (page) => {
       card.classList.toggle('min', state.minimized);
       toggle.innerHTML = state.minimized ? ICON.up : ICON.down;
       root.getElementById('title').textContent = state.minimized ? 'YOUR TURN' : 'YOUR TURN: control is yours';
+      // The minimized pill hides the steps and the finish condition: keep both one hover away, so nothing is missed.
+      const hidden = state.minimized ? [message, ...steps, ...(finish ? ['Done when: ' + finish] : [])].join('\n') : null;
+      bar.title = hidden || 'Drag to move';
+      bar.setAttribute('aria-label', hidden || 'AsRun handoff: drag to move');
     };
     const place = () => {
       if (state.left === null) return;
@@ -147,10 +210,21 @@ async (page) => {
     apply();
     document.documentElement.appendChild(host);
     place();
+    // Only a list longer than its box gets the fade; a short one must not look cut off. Measured after the card is in
+    // the document: before that every height is zero. The fade goes away at the end of the list, where nothing is left.
+    const markScroll = () =>
+      list.classList.toggle('scrolly', list.scrollHeight - list.clientHeight - list.scrollTop > 1);
+    list.addEventListener('scroll', markScroll);
+    markScroll();
     if (!document.title.startsWith('YOUR TURN | ')) document.title = 'YOUR TURN | ' + document.title;
-  }, {message, copy}).catch(() => {});
+  }, {message, steps, finish, copy, autoEnd: Boolean(watchedText)}).catch(() => {});
 
   for (const p of ctx.pages()) await p.evaluate(() => { window.__handoff = null; }).catch(() => {});
+  // A text the handoff only implies (from its finish condition) is dropped when the page already shows it: it would
+  // end the handoff before the person does anything. An explicit `doneText` keeps its meaning as the agent gave it.
+  if (!doneText && watchedText) {
+    for (const p of ctx.pages()) if (await pageHasText(p, watchedText)) { watchedText = null; break; }
+  }
   const started = Date.now();
   let outcome = null;
   try {
@@ -159,7 +233,7 @@ async (page) => {
         await paint(p);
         const flag = await p.evaluate(() => window.__handoff || null).catch(() => null);
         if (flag) outcome = flag;
-        else if (doneText && await p.getByText(doneText).first().isVisible().catch(() => false)) outcome = 'condition';
+        else if (watchedText && await pageHasText(p, watchedText)) outcome = 'condition';
       }
       if (!outcome) await page.waitForTimeout(500);
     }

package/.claude/skills/exploring-cases/references/notes.md

@@ -2,7 +2,8 @@
 
 Local, git-ignored and optional. `exploring-cases` writes it; `generating-specs` (and healing) read it to **verify**
 instead of rediscovering the page. It is not part of the case and never becomes part of it: expected values stay in
-`## Values`, behaviour in `## Expected`, ready signals in `Ready when:`, and assertions never appear here.
+`## Values`, behaviour in `## Expected`, ready signals in `Ready when:`, and assertions never appear here. A note is
+**full** (every step of the case) or **diff** (only the steps a `--lead` diff pass opened); see "Coverage".
 
 ## Where it lives
 
@@ -36,13 +37,47 @@ that is a normal state: generation falls back to replaying the case.
 ```
 
 - Keys of `steps` are the case's step numbers, keys of `targets` are its card ids (`T1`).
-- `steps` may be `{}` and `targets` may be omitted; every other key is required (`env` and `updatedAt` are optional).
-  No other field is accepted.
+- `steps` may be `{}` and `targets` may be omitted; every other key is required (`env`, `updatedAt`, `depth` and
+  `basedOn` are optional). No other field is accepted.
 - `caseSha256` is the 64-character hash `pnpm asrun explore:notes <case-id> --hash` prints (not the placeholder above).
 - `pnpm asrun explore:notes <case-id> --check` validates the files: it fails on a malformed note and warns on a note
   whose `caseSha256` no longer matches the case (the summary already prints it as `stale`; re-run the exploration, or
   delete the note and let the case be replayed). A file that fails is ignored by `/gen-spec`.
 
+## Coverage
+
+A note is either **full** or **diff**:
+
+- **full** (the default, and what a note without `depth` is): every step of the case is in `steps`. `/explore-case`
+  writes one for a profile it explored without `--lead`.
+- **diff**: the note belongs to a profile that an `--lead` run explored only where it can differ. `depth` is
+  `"diff"` and `basedOn` names the lead profile whose note covers the steps this one did not open. `steps` holds only
+  the steps the diff pass opened; `targets` holds the cards it confirmed on that profile.
+
+```json
+{
+  "version": 1,
+  "caseId": "conduit/header-logo",
+  "profile": "conduit-b",
+  "env": "staging",
+  "caseSha256": "<the same hash as the lead's note>",
+  "capturedAt": "2026-11-10T08:12:04Z",
+  "depth": "diff",
+  "basedOn": "conduit-a",
+  "steps": {"4": {"url": "/profile/asrun-b", "locators": [{"purpose": "the profile heading", "locator": "page.getByRole('heading', {name: 'asrun-b'})"}]}},
+  "targets": {"T1": {"locator": "page.getByRole('img', {name: 'Conduit B'})", "matches": 1}}
+}
+```
+
+Rules for a diff note:
+- `basedOn` is required (`explore:notes --check` fails without it) and must be a profile, not a case or a URL.
+- It is **complete as it is**. `/gen-spec` writes the steps the note does not hold from the lead's note, and reports
+  them as `observed on <lead>, not verified on <profile>`. Never pad it with steps copied from the lead's note.
+- A diff note whose lead has no note of its own (or whose lead note is itself a diff note) is a warning, not a failure:
+  generation replays the steps neither note holds. A profile that a diff pass turned into a full pass gets a normal
+  full note.
+- `caseSha256` is the same for every note of one run: they are all written after the last case edit.
+
 ## What goes in
 
 `steps.<n>`
@@ -53,6 +88,8 @@ that is a normal state: generation falls back to replaying the case.
 - `requests`: the data-call paths the step's action started, taken from `browser_network_requests` above the marker
   (`tools.md`, "Network requests without a clear"). Path only: `/api/articles`, never a host, a query string or a token.
   Images, fonts and analytics are not data calls.
+- A diff note holds only the steps its pass opened; the steps it did not open come from `basedOn` and are not copied
+  here.
 
 `targets.T1`
 - `locator`: the card's `Identified by`, confirmed on the page.
@@ -76,7 +113,8 @@ the name of the item, because the data changes between runs. The same rule as a
 ## Freshness and the write-back
 
 - `caseSha256` is the sha256 of `cases/<case-id>.md` at the moment the note was written. If the case changes after that,
-  the note is **stale**: `/gen-spec` replays the case and does not use it.
+  the note is **stale**: `/gen-spec` replays the case and does not use it. Every note of one run shares the hash, because
+  `/explore-case` writes them after its last case edit; a later run that edits the case makes them stale together.
 - `/gen-spec` confirms an entry of a fresh note on the page and may write the verified locator or request back
   (`updatedAt` gets the time). It never adds a step or a target, and it never touches a stale note.
 - Deleting `.explore/notes/` is always safe: generation then re-derives everything from the page.

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

@@ -45,8 +45,8 @@ Rules for writing it:
   It needs no TODO block. See "Marker or question, never both" below.
 
 ## Where the block hangs
-The parent line is the sentence the question is about: the panel shows it on its own, next to "The text above this
-question", so it has to make sense without the rest of the document.
+The parent line is the sentence the question is about: the panel shows it on its own, under "The case says", so it
+has to make sense without the rest of the document.
 - **The immediate line, not an ancestor.** Hang the block under the one sentence that makes the claim. Under a
   nested bullet, indent it under that bullet, not under the top-level one above it; when the claim only makes sense
   with an umbrella sentence, write the claim itself as a top-level bullet and hang the block there.

package/.claude/skills/exploring-cases/references/readiness.md

@@ -136,6 +136,12 @@ in the same `browser_run_code_unsafe` call that waits for the download), run
 images** and say in the card where the logo really is on each page, which pages have it and which do not, and what the
 text shows. The rendered pages are the card's `Reference`. If the logo is not where the case says, that is a question.
 
+When `pnpm pdf:render` itself fails, the install is broken — a PDF check would fail the same way once the spec runs, so
+there is nothing to explore: end with `needs-input` and name the error (`pnpm asrun doctor` says which part is
+missing). **Never substitute another renderer** (Ghostscript, an image converter, a preview from the browser): the
+baseline a spec compares against is produced by `expectPdf` and pdf.js, so a page drawn by anything else is not a
+`Reference` and the card would describe a picture that never appears again.
+
 While exploring, do the same by hand: click, wait for the download event, see the file finish, read its size and its first
 bytes. Record "(observed: <file name>, <size>, valid <kind>)".
 

package/.claude/skills/exploring-cases/references/user-handoff.md

@@ -23,15 +23,19 @@ perform this step; run /explore-case with --attended") and goes on with the rest
 that nobody watches.
 
 ## Before the handoff
-1. Say what the user has to do and when it is finished, in one or two sentences ("Fill in the form, pick two
-   items, then press Done"). Name the finish condition first (below).
-2. Put every text the user has to type into `copy` (the name of a document, a title), so it can be
+1. Say in one sentence what the handoff is about (`message`), and put what to do in `steps`, **one action per entry, in
+   the order the person does it**. The card numbers them. Never chain actions in one entry ("pick items, then press
+   Next"): a step is one thing to click, type or choose. More than about five steps is two handoffs, not one long card.
+2. Name the finish condition in `finish`, in the words of the page ("'Published' appears at the top of the page",
+   without a closing full stop), and keep it out of the steps: the card puts it in its own highlighted "DONE WHEN"
+   block. `doneText` is the same condition as a text the card can watch for (see "Finish condition").
+3. Put every text the user has to type into `copy` (the name of a document, a title), so it can be
    copied with one click. Build a created name with the project's test-data prefix (default `[asrun]`, printed by
    `pnpm asrun rules`) and a run stamp: `<prefix> <base> (<YYYY-MM-DD HH-mm-ss>, UTC)`, the same shape
    `testDataName()` builds. The stamp is chosen now, not recorded in the recipe.
-3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
+4. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
    profile). Never ask for login or 2FA. Name everything the user creates `<prefix> <something> (<run stamp>)`.
-4. Do not start a recording yourself: the card starts and stops it (see "Recording"). Never call
+5. Do not start a recording yourself: the card starts and stops it (see "Recording"). Never call
    `browser_start_recording` or `browser_stop_recording`: the `playwright-test` MCP lists them but cannot run them
    (`devtools` tools; see `tools.md`).
 
@@ -39,9 +43,14 @@ that nobody watches.
 Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
 timeout), so no polling from outside is needed. The loop:
 
-- **Shows a small floating card, not a bar.** It sits in the bottom-left corner and only the card takes clicks, so
-  nothing of the page is covered or blocked. The user can **drag** it by its title bar and **minimize** it to a small
-  pill that still has a Done button. Position and minimized state survive a page reload (kept in `sessionStorage`).
+- **Shows a small floating card, not a bar.** It reads top to bottom: one sentence about the handoff, the steps as a
+  numbered list, a line per text to copy, and the finish condition in its own green "DONE WHEN" block at the bottom,
+  with a line under it that says whether the card ends by itself. A list longer than its box scrolls (and fades at the
+  edge), while the finish condition and the buttons stay in view.
+  It sits in the bottom-left corner and only the card takes clicks, so nothing of the page is covered or blocked. The
+  user can **drag** it by its title bar and **minimize** it to a small pill that still has a Done button (its tooltip
+  keeps the steps and the finish condition). Position and minimized state survive a page reload (kept in
+  `sessionStorage`).
 - **Click to copy.** Every text in `copy` (for example the `<prefix> <name> (<run stamp>)` the user has to type) is shown on its
   own line with a copy icon; one click puts it on the clipboard and the icon shows "Copied". Pass only text that the
   case says to type; leave `copy` empty when there is none.
@@ -72,9 +81,14 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    // browser_run_code_unsafe({intent: 'set the handoff card options', code: ...})
    async (page) => {
      page.context().__handoffCfg = {
-       message: '<what the user does, one sentence>',
+       message: '<what this handoff is for, one sentence>',
+       steps: [                   // one action per entry, in order: the card numbers them
+         '<first thing to do>',
+         '<next thing to do>',
+       ],
+       finish: '<what the page shows when it is done, in the page\'s own words, no full stop>',
        copy: [],                  // texts to type, e.g. ['[autotest] published document (2026-11-09 12-34-56)']
-       doneText: null,            // text that appears when finished, or null
+       doneText: '<the exact text that appears when it is done>', // so the card ends by itself (see below)
        maxMs: 600000,
      };
      return 'cfg set';
@@ -89,26 +103,44 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    the recording was unavailable (`recording: false`; `recordingError` says why).
 
 Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
-chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. Playwright's own recording
-toolbar at the top of the page is expected and is not part of the card. If the card is not right, stop and report it;
-do not hand off with a broken card.
-
-Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
-Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
-UI, the UI notices the handoff by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call, whether the
-browser tool is called directly or through the CLI's code mode, as OpenCode's `execute` tool does) and shows the
-"Your turn" badge, a count in the tab title and, if the person switched notifications on, a browser notification;
-this is why the message in `__handoffCfg` must be a plain string literal. A macOS notification is a bonus and may
-fail in a sandbox: `osascript -e 'display notification "<task>" with title "AsRun" sound name "Glass"'`. If it
-fails, go on.
+chevron button at its right, the message as one line, the steps numbered, the finish condition in its own green
+"DONE WHEN" block saying "The card ends by itself when this shows", and, when `copy` is not empty, a line per text
+with a copy icon. The Done button must be visible without scrolling. Playwright's own recording toolbar at the top of
+the page is expected and is not part of the card. If the card is not right (or says "Press Done when you are
+finished"), fix `doneText` before you hand the step over.
+
+Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Done
+when <finish condition>. Press Done on the card (bottom-left; drag it if it is in the way) when you finish." Name the
+finish condition there too, not only on the card. When the run was started from the web UI, the UI notices the handoff
+by itself (it sees the `__handoffCfg` call and the `handoff-card.js` call, whether the browser tool is called directly
+or through the CLI's code mode, as OpenCode's `execute` tool does) and shows the "Your turn" badge, a count in the tab
+title and a desktop notification saying what to do and when it is done — this is why the message and the finish
+condition in `__handoffCfg` must be plain string literals. The UI server shows that notification itself; **never send
+one yourself** (`osascript`, `notify-send`, a toast): a CLI that refuses a shell call leaves a failed call in the job
+log, and the person gets nothing either way.
 
 ## Finish condition
-Pick one that the page can show, before the handoff, and write it into the message of the card:
+Pick one that the page can show, before the handoff, and write it into `finish`, where the card shows it alone:
 - a text that appears (a "Saved" toast, the title of the next step) or one that goes away;
 - a URL that the page reaches;
 - an element that appears or disappears (an editor that closes).
 
-The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give up a step.
+**Also give `doneText`: the exact text that is not on the page yet and shows up when the step is done** (the new
+button label, the toast, the heading of the next screen). Without it the card cannot notice the condition and waits for
+the person to press Done, which is the one thing a handoff must not need every time. Only a condition that carries no
+text at all (a URL, an empty editor) may leave it out.
+
+- Both must agree: nobody should read "DONE WHEN ..." on the card while `doneText` watches for something else.
+- Quote the *new* text, not the one that is already there: `doneText: 'Unfavorite Article'`, never `'Favorite Article'`
+  when the button already reads that.
+- If `finish` quotes a text and `doneText` is missing, the card uses that quoted text as its signal — but only when the
+  page did not show it when the card appeared, so a condition that already held can never end the handoff at once.
+  Relying on that is a mistake: set `doneText` yourself.
+- The block says which way the wait ends: "The card ends by itself when this shows. Done also works." when the card can
+  notice the condition, "Press Done when you are finished." when it cannot. Read that line on the screenshot: a
+  handoff that will never end by itself is a handoff to fix, not to run.
+- The Done button is always there (also on the minimized card) as the fallback, and "Cannot do this" lets the user give
+  up a step.
 
 ## After the handoff
 - The card turns green and says control is back ("Done: control is back with Playwright. Do not touch the page.")
@@ -116,9 +148,10 @@ The Done button is always there (also on the minimized card) as the fallback, an
 - `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
   not depend on it.
 - Take a snapshot, write down what the user did from the card's `recorded` (see "Recording"), then continue read-only.
-- At the end of the exploration hand off once more when the user created data: "Delete the test items you
-  created (they start with <the project's prefix> and carry this run's timestamp), then press Done". The case must
-  clean up after itself, and so must the exploration.
+- At the end of the exploration hand off once more when the user created data, with the same shape as any other
+  handoff: `message` "Clean up the test items this run created", `steps` = "Open the list", "Delete the items that
+  start with <prefix> and carry this run's timestamp", `finish` = "the list holds no item of this run any more". The
+  case must clean up after itself, and so must the exploration.
 
 ## Recording
 The card records what the person does: it starts the recording when it shows and stops it on every way out (Done,

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

@@ -135,7 +135,11 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    **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
+   and skip what it does not hold. A `depth: "diff"` note covers only the steps that profile's exploration opened: take
+   those, take the rest from the lead note named in `basedOn` when it is fresh, and report the rest as
+   `observed on <lead>, not verified on <profile>`. A diff note is a normal input, never a gap: do not stop on it, do not
+   ask for a full exploration of that profile, and never write the lead's steps into it. 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).
@@ -147,7 +151,9 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    `/explore-case` recorded). Pages that only exist after such a step cannot be seen from here: write their locators
    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
+   least one logged-in profile per domain (example.com and exampleshop.com differ in markup). A profile with a fresh
+   diff note does not have to be opened again for the steps the note leaves to its lead: open it only to resolve a
+   value or a behavior, as below. 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
@@ -196,7 +202,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, which steps were written from a
+   `observed on the page` or `not verified`; no row may be missing), profiles explored (naming the profile whose note
+   each row came from, and `observed on <lead>, not verified on <profile>` for a diff note's rows), 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