@asrunjs/asrun 0.14.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 the profiles named with --profiles or, without it, for at least one logged-in profile per domain. 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
@@ -60,6 +60,11 @@ one exception is a handoff in an attended run, where waiting for the person is t
   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.
@@ -102,6 +107,31 @@ one exception is a handoff in an attended run, where waiting for the person is t
    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
      with one sentence plus one action per entry of `steps` and the finish condition in `finish`, run the wait loop
@@ -131,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.
@@ -147,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
@@ -172,8 +204,14 @@ one exception is a handoff in an attended run, where waiting for the person is t
    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,
@@ -196,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/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/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

package/AGENTS.md

@@ -199,11 +199,13 @@ 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] [--profiles a,b]`) explores the real pages for one
+2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended] [--profiles a,b] [--lead <profile-id>]`) explores the real pages for one
    case. It edits that case file: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
    of the steps that write or need a choice, and it writes a local note under `.explore/notes/` with the locators and
    data-call paths it saw. `--profiles` narrows the run to those profiles; runs add up, so the case can be explored in
-   passes.
+   passes. `--lead` explores one profile in full and the rest only where they can differ (values, targets, the steps
+   that reach them), so a case with many profiles is not paid for once per profile; a profile whose page or flow
+   differs is explored in full instead, and the report says so.
 3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case, its
    step recipes and the exploration note, and `## Values`, writes the spec (values stay in the case document), but never
    runs the tests, never writes data and never creates baselines. There is no profile selection here: it covers every
@@ -216,6 +218,11 @@ before installing), `pnpm asrun init [--update] [--force]` writes or refreshes t
 migrate` applies only the migrations (for a manual install), and `pnpm asrun reset` removes `node_modules` and the
 files init wrote (edited files, cases, specs, `profiles.yaml` and `package.json` stay), so
 `pnpm dlx @asrunjs/asrun init --install` can scaffold again.
+A release can change a file the project owns (its `AGENTS.md`, `.mcp.json`, `cases/_template.md`) or ask for a manual
+migration step; `pnpm asrun upgrade` ends with a `NEXT` block that names each one with its exact command.
+`/upgrade-workspace` (or `pnpm asrun upgrade --prompt`, whose output it follows) does that work: it merges only the
+scaffold text outside `## 2`/`## 3`, fixes case structure without changing what a case expects, runs the checks, and
+leaves `pnpm asrun migrate --ack <id>` and the `init --ack <file>` confirmations to the person.
 Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec pass.
 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`).

package/README.md

@@ -58,6 +58,17 @@ generated files, applies the migrations and runs `doctor`. `--dry-run` shows the
 that predates `upgrade` updates once by hand: `pnpm add -D @asrunjs/asrun@latest`, `pnpm asrun init --update`,
 `pnpm asrun migrate`, `pnpm asrun doctor`.
 
+When the release changes a file the project owns (`AGENTS.md`, `.mcp.json`, a case template) or records manual
+migration steps, the upgrade ends with a `NEXT` block that names each one with its exact command. Hand that block to
+an AI:
+
+```bash
+pnpm asrun upgrade --prompt   # the task as Markdown; changes nothing
+```
+
+or run `/upgrade-workspace` in Claude Code / OpenCode, which does the same. The prompt is the same for every release —
+it reads which files moved and which steps are open from the workspace and the installed package.
+
 `init --update` alone refreshes only the generated files; it never overwrites `AGENTS.md`, `CLAUDE.md` or your skill
 overrides. `doctor` checks profiles, generated files, the installed version, the migrations and the project rules.
 `init --force` rewrites every file init writes (rules still need `--reset-rules`; `profiles.yaml` and `package.json`
@@ -102,7 +113,8 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
    writes what they show into the case and turns what it cannot know into questions. It also saves a local note of the
    locators and data calls it saw. Answer the questions in the case file, or in the UI's **Answer** sheet, and run it
    again. With many profiles, `--profiles a,b` opens only those; a later run with the others adds theirs, and the case
-   keeps both.
+   keeps both. `--lead <profile-id>` pays for the flow once: that profile is explored in full, the others only where
+   they can differ (their values, their target screenshots, the steps that reach them).
 5. **Generate, run, read.** `/gen-spec header-logo staging` reads those notes, writes `tests/header-logo.spec.ts` and
    fills the case's `## Values`. Then:
 

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

@@ -8,6 +8,9 @@
  * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
  * actions that load something, and the match count of a target card's element. Expected values stay in the case's
  * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ *
+ * A `full` note (the default) covers every step. A `diff` note belongs to a profile that an `--lead` run explored only
+ * where it can differ, and names the lead profile in `basedOn` for the steps it did not open.
  */
 export declare const NOTES_VERSION = 1;
 export interface ExploreLocator {
@@ -38,6 +41,13 @@ export interface ExploreNote {
     capturedAt: string;
     /** Set when a later `/gen-spec` refreshed an entry it confirmed on the page. */
     updatedAt?: string;
+    /**
+     * `full` (the default when absent) explored every step of the case; `diff` explored only the steps that can differ
+     * on this profile, and leans on `basedOn` for the rest. See `references/notes.md`, "Coverage".
+     */
+    depth?: 'full' | 'diff';
+    /** The lead profile a `diff` note leans on for the steps it did not open. */
+    basedOn?: string;
     steps: Record<string, ExploreNoteStep>;
     targets?: Record<string, ExploreNoteTarget>;
 }
@@ -64,6 +74,11 @@ export declare function validateExploreNote(value: unknown, expected: {
     caseId: string;
     profile: string;
 }): string[];
+/** `full` when the note explored every step, `diff` when it covered only the steps that can differ per profile. */
+export declare function noteCoverage(note: ExploreNote): {
+    depth: 'full' | 'diff';
+    basedOn?: string;
+};
 /**
  * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
  * the caller decides whether it matters, and generation treats an unreadable note as a missing one.

package/dist/lib/explore-notes.js

@@ -13,6 +13,9 @@ import { CASES_DIR, EXPLORE_DIR } from './paths.js';
  * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
  * actions that load something, and the match count of a target card's element. Expected values stay in the case's
  * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ *
+ * A `full` note (the default) covers every step. A `diff` note belongs to a profile that an `--lead` run explored only
+ * where it can differ, and names the lead profile in `basedOn` for the steps it did not open.
  */
 export const NOTES_VERSION = 1;
 const HASH = /^[a-f0-9]{64}$/;
@@ -194,15 +197,45 @@ export function validateExploreNote(value, expected) {
     if (value.env !== undefined && (typeof value.env !== 'string' || value.env.trim() === '')) {
         problems.push('env must be a non-empty string when it is present');
     }
+    if (value.depth !== undefined && value.depth !== 'full' && value.depth !== 'diff') {
+        problems.push('depth must be "full" or "diff" when it is present');
+    }
+    if (value.basedOn !== undefined) {
+        if (typeof value.basedOn !== 'string' || !PROFILE_FILE.test(value.basedOn)) {
+            problems.push('basedOn must be a profile id (letters, digits, ".", "_" and "-")');
+        }
+        else if (value.depth !== 'diff') {
+            problems.push('basedOn is only allowed on a note whose depth is "diff"');
+        }
+    }
+    if (value.depth === 'diff' && value.basedOn === undefined) {
+        problems.push('a diff note must name the lead profile in basedOn');
+    }
     checkSteps(value.steps, problems);
     if (value.targets !== undefined)
         checkTargets(value.targets, problems);
-    const known = new Set(['version', 'caseId', 'profile', 'env', 'caseSha256', 'capturedAt', 'updatedAt', 'steps', 'targets']);
+    const known = new Set([
+        'version',
+        'caseId',
+        'profile',
+        'env',
+        'caseSha256',
+        'capturedAt',
+        'updatedAt',
+        'depth',
+        'basedOn',
+        'steps',
+        'targets',
+    ]);
     for (const key of Object.keys(value))
         if (!known.has(key))
             problems.push(`${key} is not a known field`);
     return problems;
 }
+/** `full` when the note explored every step, `diff` when it covered only the steps that can differ per profile. */
+export function noteCoverage(note) {
+    return note.depth === 'diff' ? { depth: 'diff', basedOn: note.basedOn } : { depth: 'full' };
+}
 /**
  * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
  * the caller decides whether it matters, and generation treats an unreadable note as a missing one.

package/dist/lib/migrations.d.ts

@@ -23,9 +23,9 @@ export interface MigrationContext {
  * on any older release may still need it.
  */
 export interface Migration {
-    /** stable and unique: `<version>-<slug>`, for example `0.9.0-pnpm-release-age` */
+    /** stable and unique: `<version>-<slug>`, or `unreleased-<slug>` until the release names its version */
     id: string;
-    /** the release that introduced the change; workspaces older than this get the migration */
+    /** the release that introduced the change; `unreleased` while it is still being prepared */
     version: string;
     /** one line for the person, in the release plan before the install and in the migration output after it */
     summary: string;
@@ -37,6 +37,17 @@ export interface Migration {
     details?: string;
     /** steps only a person can do; they are printed and remembered until they are acknowledged */
     manual?: string[];
+    /**
+     * The project files the change touches. A once-only scaffold file here (`AGENTS.md`, `.mcp.json`, ...) also advances
+     * that file's baseline when the migration is acknowledged, so one `migrate --ack` clears both reminders.
+     */
+    files?: string[];
+    /**
+     * `true` for a release that touched project files but asks nothing of an existing workspace: documentation, a
+     * clarified contract, a new optional flag. The entry exists so `pnpm migrations:check` can tell "reviewed, nothing
+     * to do" from "forgotten"; the command reports it and moves on.
+     */
+    advisory?: boolean;
     /** true when the migration runs without asking after the install; the command still prints what it did */
     auto?: boolean;
     /** true when the workspace already looks migrated; a false answer skips `apply` */
@@ -46,6 +57,21 @@ export interface Migration {
 }
 /** A migration as it travels in `dist/migrations/manifest.json`: the same entry without its code. */
 export type MigrationManifestEntry = Omit<Migration, 'detect' | 'apply'>;
+/**
+ * `version` written by an entry that is still being prepared: the release it ships with names the version later, and
+ * release-please only knows it once the release pull request exists. Resolved to the installed release's own version,
+ * which is by definition the release that carries the entry's code.
+ */
+export declare const UNRELEASED = "unreleased";
+/** True for an entry whose version is still `unreleased`. */
+export declare function isUnreleased(version: string): boolean;
+/**
+ * The registry with `unreleased` resolved to the installed release. Every consumer compares versions, so they must all
+ * see the resolved entries: a leftover sentinel would sort as a plain string and silently pick the wrong migrations.
+ */
+export declare function resolveMigrations<T extends {
+    version: string;
+}>(entries: readonly T[], installedVersion: string): T[];
 /**
  * The migration state of a workspace, recorded in `.asrun.json`. `since` is the release the workspace was last
  * migrated from, so only newer entries apply. It survives `init --update`, which is what keeps a manual
@@ -63,6 +89,10 @@ export interface WorkspaceMarker {
         since?: unknown;
         manual?: unknown;
     };
+    /** The template each once-only project file is known to be aligned with (`lib/scaffold.ts`). */
+    scaffold?: unknown;
+    /** The release the workspace came from, before the last `init` wrote the current one. */
+    previous?: unknown;
     [key: string]: unknown;
 }
 /** Where `pnpm build` writes the manifest, relative to the package root. */
@@ -88,8 +118,12 @@ export interface VersionedMigration {
  * `since` is the release the workspace already matches, `to` is the release being installed.
  */
 export declare function pendingMigrations<T extends VersionedMigration>(entries: readonly T[], since: string, to: string): T[];
-/** The manifest of a registry: the same entries, without the code that cannot travel in JSON. */
-export declare function toManifest(entries: readonly Migration[]): MigrationManifestEntry[];
+/**
+ * The manifest of a registry: the same entries, without the code that cannot travel in JSON. Versions are resolved
+ * first, so a published manifest never carries the `unreleased` sentinel: an older `upgrade` reads it out of the target
+ * tarball before installing anything, and has to compare real versions.
+ */
+export declare function toManifest(entries: readonly Migration[], installedVersion: string): MigrationManifestEntry[];
 /** The marker of a workspace, or null when the file is missing or not a JSON object. */
 export declare function readMarker(root: string): WorkspaceMarker | null;
 /**
@@ -98,6 +132,11 @@ export declare function readMarker(root: string): WorkspaceMarker | null;
  * starts at the installed version, so no historical entry runs on it.
  */
 export declare function migrationState(marker: WorkspaceMarker | null, installedVersion: string): MigrationState;
+/**
+ * Reads the marker, lets the caller change it and writes it back, keeping every other field. Every module that records
+ * something in `.asrun.json` goes through this one function, so two of them can never overwrite each other's block.
+ */
+export declare function updateMarker(root: string, mutate: (marker: WorkspaceMarker) => void): void;
 /**
  * Writes the migration state back into the marker and keeps every other field (init writes the rest). The workspace
  * must already have a marker: `migrate` says so instead of creating one, because a workspace that was never

package/dist/lib/migrations.js

@@ -1,6 +1,23 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { MARKER } from './paths.js';
+/**
+ * `version` written by an entry that is still being prepared: the release it ships with names the version later, and
+ * release-please only knows it once the release pull request exists. Resolved to the installed release's own version,
+ * which is by definition the release that carries the entry's code.
+ */
+export const UNRELEASED = 'unreleased';
+/** True for an entry whose version is still `unreleased`. */
+export function isUnreleased(version) {
+    return version === UNRELEASED;
+}
+/**
+ * The registry with `unreleased` resolved to the installed release. Every consumer compares versions, so they must all
+ * see the resolved entries: a leftover sentinel would sort as a plain string and silently pick the wrong migrations.
+ */
+export function resolveMigrations(entries, installedVersion) {
+    return entries.map((entry) => (entry.version === UNRELEASED ? { ...entry, version: installedVersion } : entry));
+}
 /** Where `pnpm build` writes the manifest, relative to the package root. */
 export const MANIFEST_FILE = 'dist/migrations/manifest.json';
 /** The same file inside an npm tarball, which prefixes every path with `package/`. */
@@ -53,9 +70,13 @@ export function pendingMigrations(entries, since, to) {
         .filter((entry) => compareVersions(entry.version, since) > 0 && compareVersions(entry.version, to) <= 0)
         .sort((a, b) => compareVersions(a.version, b.version) || a.id.localeCompare(b.id));
 }
-/** The manifest of a registry: the same entries, without the code that cannot travel in JSON. */
-export function toManifest(entries) {
-    return entries.map(({ id, version, summary, breaking, appliesTo, details, manual, auto }) => ({
+/**
+ * The manifest of a registry: the same entries, without the code that cannot travel in JSON. Versions are resolved
+ * first, so a published manifest never carries the `unreleased` sentinel: an older `upgrade` reads it out of the target
+ * tarball before installing anything, and has to compare real versions.
+ */
+export function toManifest(entries, installedVersion) {
+    return resolveMigrations(entries, installedVersion).map(({ id, version, summary, breaking, appliesTo, details, manual, files, advisory, auto }) => ({
         id,
         version,
         summary,
@@ -63,6 +84,8 @@ export function toManifest(entries) {
         ...(appliesTo !== undefined && { appliesTo }),
         ...(details !== undefined && { details }),
         ...(manual !== undefined && { manual }),
+        ...(files !== undefined && { files }),
+        ...(advisory !== undefined && { advisory }),
         ...(auto !== undefined && { auto }),
     }));
 }
@@ -93,14 +116,23 @@ export function migrationState(marker, installedVersion) {
         : [];
     return { since, manual: [...new Set(manual)] };
 }
+/**
+ * Reads the marker, lets the caller change it and writes it back, keeping every other field. Every module that records
+ * something in `.asrun.json` goes through this one function, so two of them can never overwrite each other's block.
+ */
+export function updateMarker(root, mutate) {
+    const file = path.join(root, MARKER);
+    const marker = readMarker(root) ?? {};
+    mutate(marker);
+    fs.writeFileSync(file, JSON.stringify(marker, null, 2) + '\n');
+}
 /**
  * Writes the migration state back into the marker and keeps every other field (init writes the rest). The workspace
  * must already have a marker: `migrate` says so instead of creating one, because a workspace that was never
  * initialized has no release to migrate from.
  */
 export function writeMigrationState(root, state) {
-    const file = path.join(root, MARKER);
-    const marker = readMarker(root) ?? {};
-    marker.migrations = { since: state.since, manual: [...new Set(state.manual)] };
-    fs.writeFileSync(file, JSON.stringify(marker, null, 2) + '\n');
+    updateMarker(root, (marker) => {
+        marker.migrations = { since: state.since, manual: [...new Set(state.manual)] };
+    });
 }