@asrunjs/asrun 0.14.0 → 0.15.0

package/dist/lib/upgrade-prompt.js

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { UNRELEASED, migrationState, pendingMigrations, readMarker, resolveMigrations, } from './migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+import { frameworkPath, frameworkVersion, isInstalled, outstandingDrift, scaffoldDrift } from './scaffold.js';
+import { card } from './term.js';
+/** The checks every upgrade ends with: the workspace's own tools, which know the installed release's rules. */
+const CHECKS = ['pnpm asrun doctor', 'pnpm case:check', 'pnpm spec:lint', 'pnpm typecheck'];
+/** The version of the framework installed in this workspace (not the one running the command). */
+function installedVersion(root) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, frameworkPath(root), 'package.json'), 'utf8'));
+        if (typeof manifest.version === 'string' && manifest.version !== '')
+            return manifest.version;
+    }
+    catch {
+        // fall back to the framework this command runs from
+    }
+    return frameworkVersion().version;
+}
+/** How the workspace reaches the framework: a registry install, or the framework's own git checkout. */
+function installKind(root) {
+    return isInstalled(root) && !frameworkPath(root).startsWith('..') ? 'installed' : 'checkout';
+}
+/** One project file, as the upgrade output and the prompt describe it. */
+function describeFile(entry) {
+    const ack = `pnpm asrun init --ack ${entry.file}`;
+    switch (entry.state) {
+        case 'missing':
+            return { file: entry.file, state: entry.state, action: 'missing in the workspace', command: 'pnpm asrun init', projectData: entry.projectData };
+        case 'replace':
+            return {
+                file: entry.file,
+                state: entry.state,
+                action: 'the template changed and nobody edited the file',
+                command: `pnpm asrun init --force ${entry.file}`,
+                projectData: entry.projectData,
+            };
+        case 'merge':
+            return {
+                file: entry.file,
+                state: entry.state,
+                action: 'the template and the project both changed it: merge the template part, then acknowledge',
+                command: ack,
+                projectData: entry.projectData,
+            };
+        case 'unknown-base':
+            return {
+                file: entry.file,
+                state: entry.state,
+                action: 'no baseline for this file: compare it with the template, report what differs, then acknowledge',
+                command: ack,
+                projectData: entry.projectData,
+            };
+        default:
+            return { file: entry.file, state: entry.state, action: 'nothing to do', command: null, projectData: entry.projectData };
+    }
+}
+/** Everything an upgrade still leaves open, computed from the marker, the registry and the installed templates. */
+export function upgradeOutstanding(root, marker = readMarker(root)) {
+    const to = installedVersion(root);
+    const registry = resolveMigrations(MIGRATIONS, to);
+    const state = migrationState(marker, to);
+    const pending = pendingMigrations(registry, state.since, to);
+    const byId = new Map(registry.map((migration) => [migration.id, migration]));
+    // Outstanding manual steps: what an earlier migrate recorded, plus the manual entries that are still pending here
+    // (a workspace that was installed by hand and has not run "migrate" yet).
+    const ids = [...new Set([...state.manual, ...pending.filter((migration) => (migration.manual ?? []).length > 0).map((migration) => migration.id)])];
+    const migrations = [];
+    for (const id of ids) {
+        const migration = byId.get(id);
+        if (migration === undefined) {
+            migrations.push({ id, version: 'unknown', summary: 'a migration this release no longer knows', manual: [], files: [], ack: `pnpm asrun migrate --ack ${id}` });
+            continue;
+        }
+        migrations.push({
+            id,
+            version: migration.version,
+            summary: migration.summary,
+            ...(migration.details !== undefined && { details: migration.details }),
+            manual: migration.manual ?? [],
+            files: migration.files ?? [],
+            ack: `pnpm asrun migrate --ack ${id}`,
+        });
+    }
+    const drift = scaffoldDrift(root, marker);
+    // An advisory entry asks nothing: `migrate` still records it, but it is not work a person has to see.
+    const work = pending.filter((migration) => migration.advisory !== true);
+    return {
+        drift,
+        files: outstandingDrift(drift).map(describeFile),
+        migrations,
+        pending: work.length,
+    };
+}
+/** True when an upgrade leaves nothing for a person or an AI to do. */
+export function nothingToDo(outstanding) {
+    return outstanding.files.length === 0 && outstanding.migrations.length === 0 && outstanding.pending === 0;
+}
+/**
+ * The rows of the "NEXT" card: one per file or migration, each with the exact command. A person must be able to finish
+ * the upgrade by copying from here, without reading the prompt or the docs.
+ */
+export function nextStepRows(outstanding) {
+    const rows = outstanding.files.map((entry) => ({
+        label: entry.file,
+        // The command goes on its own line: a wrapped command is a command nobody can copy.
+        text: entry.command === null ? entry.action : `${entry.action}\n${entry.command}`,
+    }));
+    for (const migration of outstanding.migrations) {
+        const first = migration.manual[0];
+        rows.push({
+            label: migration.id,
+            text: `${first ?? migration.summary}\nwhen done: ${migration.ack}`,
+        });
+    }
+    if (outstanding.pending > 0) {
+        rows.push({ label: 'migrations', text: `${outstanding.pending} apply to this workspace: pnpm asrun migrate` });
+    }
+    return rows;
+}
+/** One sentence for the title of the card, so the count and the work agree. */
+export function nextStepTitle(outstanding) {
+    const files = outstanding.files.length;
+    const migrations = outstanding.migrations.length + (outstanding.pending > 0 ? 1 : 0);
+    const parts = [];
+    if (files > 0)
+        parts.push(`${files} project file${files === 1 ? '' : 's'}`);
+    if (migrations > 0)
+        parts.push(`${migrations} migration step${migrations === 1 ? '' : 's'}`);
+    return `${parts.join(' and ')} still need${files + migrations === 1 ? 's' : ''} a person or an AI`;
+}
+/** The prompt as Markdown: what an agent reads, and what the web UI copies. */
+function renderPrompt(payload) {
+    const lines = [];
+    const none = payload.files.length === 0 && payload.migrations.length === 0;
+    lines.push(`# Bring this asrun workspace to ${payload.to}`, '');
+    lines.push(`Workspace: ${payload.workspace}`, `Framework: ${payload.framework} (${payload.to})${payload.from === null ? '' : `, upgraded from ${payload.from}`}`, 'Start from a clean tree: `git status` must be empty. If it is not, stop and say so.', '');
+    lines.push('Before you change anything, read:', '');
+    lines.push(`- \`${payload.framework}/AGENTS.md\` — the framework baseline that wins over everything else`, '- `pnpm asrun rules` — this project\'s §2 rules and its test-data prefix', `- \`${payload.framework}/docs/agents/case-format.md\` — the case document contract`);
+    lines.push('');
+    if (none) {
+        lines.push('## 1. Nothing in the project\'s own files needs updating', '');
+        lines.push('This release changed nothing a workspace has to merge. Run the checks below and report; do not change files.');
+        lines.push('');
+    }
+    else {
+        lines.push('## 1. Project files that need updating', '');
+        if (payload.files.length === 0)
+            lines.push('None.');
+        else {
+            lines.push('| File | State | What to do |');
+            lines.push('|---|---|---|');
+            for (const entry of payload.files) {
+                lines.push(`| \`${entry.file}\` | ${entry.state} | ${entry.action}${entry.command === null ? '' : ` → \`${entry.command}\``} |`);
+            }
+        }
+        lines.push('');
+        lines.push('## 2. Manual steps of this release', '');
+        if (payload.migrations.length === 0)
+            lines.push('None.');
+        for (const migration of payload.migrations) {
+            lines.push(`- \`${migration.id}\` (${migration.version}) — ${migration.summary}`);
+            if (migration.details !== undefined)
+                lines.push(`  ${migration.details}`);
+            for (const step of migration.manual)
+                lines.push(`  - ${step}`);
+            lines.push(`  - when done: \`${migration.ack}\``);
+        }
+        lines.push('');
+    }
+    lines.push(`## ${none ? 2 : 3}. Checks — fix every finding, and do nothing else`, '');
+    for (const check of payload.checks)
+        lines.push(`    ${check}`);
+    lines.push('');
+    lines.push(`## ${none ? 3 : 4}. In a case document, only structure may change`, '');
+    lines.push('Front-matter keys, section headings, `- Recipe` lines, `### T<n>` cards and their `[T<n>]` references, and the', '`❓ TODO` / `🚫 TODO` blocks. Never change what a case expects and never invent a value: an ambiguity becomes a', '`❓ TODO [non-blocking]` block with an empty `✍️ Answer:` line. Step tags stay as they are (`[input]`, `[writes]`,', '`[email]`).');
+    lines.push('');
+    lines.push(`## ${none ? 4 : 5}. Boundaries`, '');
+    lines.push(`- Never edit anything inside \`${payload.framework}\` (the installed package).`, '- Never read `.auth/`. Do not run the tests. Do not create test data.', '- Never use `--allow-writes` or `ASRUN_ALLOW_WRITES`. Do not run `pnpm asrun migrate --ack`: the person does that.', '- Do not change what a spec asserts. What `spec:lint` and `typecheck` cannot fix is left for `/heal-spec`.');
+    lines.push('');
+    lines.push(`## ${none ? 5 : 6}. Report`, '');
+    lines.push('A table: file → changed / left alone (why) / needs a person (why), then the commands the person should run,', 'verbatim:');
+    const acks = [...payload.files.filter((entry) => entry.command !== null && entry.command !== 'pnpm asrun init').map((entry) => entry.command), ...payload.acks.map((ack) => ack.command)];
+    if (acks.length === 0)
+        lines.push('    (none)');
+    else
+        for (const command of [...new Set(acks)])
+            lines.push(`    ${command}`);
+    lines.push('', 'The last line of your final message is plain text and nothing else: exactly "RESULT: ready" when nothing needs a', 'person, or "RESULT: needs-input" when something does. Never put it in a code fence or in emphasis.');
+    lines.push('');
+    return lines.join('\n');
+}
+/** The payload and the prompt of one workspace, ready for the command line and for the web UI. */
+export function upgradePrompt(root) {
+    const outstanding = upgradeOutstanding(root);
+    const marker = readMarker(root);
+    const previous = marker?.previous;
+    const base = {
+        workspace: root,
+        framework: frameworkPath(root),
+        kind: installKind(root),
+        from: typeof previous?.version === 'string' && previous.version !== UNRELEASED ? previous.version : null,
+        to: installedVersion(root),
+        drift: outstanding.drift,
+        files: outstanding.files,
+        migrations: outstanding.migrations,
+        pending: outstanding.pending,
+        acks: outstanding.migrations.map((migration) => ({ id: migration.id, command: migration.ack })),
+        checks: [...CHECKS],
+    };
+    return { ...base, prompt: renderPrompt(base) };
+}
+/**
+ * The framed "what is left" block, or null when the workspace has nothing outstanding. It carries the exact commands and
+ * names the recommended way to have an agent do them, so a person never has to remember a flag or an id.
+ */
+export function nextStepsText(root, options) {
+    const outstanding = upgradeOutstanding(root);
+    if (nothingToDo(outstanding))
+        return null;
+    return card({
+        label: 'NEXT',
+        title: nextStepTitle(outstanding),
+        rows: nextStepRows(outstanding),
+        lines: [
+            '',
+            'Recommended: run /upgrade-workspace in Claude Code or OpenCode.',
+            'Without an AI CLI: pnpm asrun upgrade --prompt, and paste it to your agent.',
+        ],
+        color: options.color,
+    }, options.width);
+}

package/dist/migrations/index.d.ts

@@ -8,16 +8,24 @@ import type { Migration } from '../lib/migrations.js';
  * for), and anything that only concerns brand-new workspaces belongs in `templates/`.
  *
  * Adding one:
- * 1. Append an entry with an id of `<version>-<slug>` and the version of the release that *introduces* the change
- *    (`version` in `package.json` after the release PR is merged, which is the next version at the time of writing).
+ * 1. Run `pnpm migrations:check`: it lists the surfaces this change touched. Append an entry with an id of
+ *    `unreleased-<slug>` and `version: '0.15.0'`; never write a version number, because release-please only names
+ *    the version in the release pull request. `scripts/build.ts` and `pnpm asrun migrate` resolve the sentinel to the
+ *    installed release, so the published manifest is always correct; `pnpm migrations:freeze` turns it into a real
+ *    version and id on the release branch (the release pull request does it automatically).
  * 2. Explain it for the person: `summary` is one line, `appliesTo` says which workspaces it matters for, `details`
- *    adds what the summary cannot, and `manual` lists what only a person can do.
+ *    adds what the summary cannot, and `manual` lists what only a person can do. `files` names the project-owned
+ *    workspace files the change touches: acknowledging the migration then also records them as aligned with this
+ *    release's templates, which is what clears them from the upgrade's NEXT block.
  * 3. `auto: true` only when the change is idempotent and safe to run without asking (`apply` decides, `detect` skips a
  *    workspace that is already fine). A change to a file the project owns (`AGENTS.md`, `profiles.yaml`, a project
  *    config) is a `manual` step, never an automatic edit.
  * 4. Set `breaking: true` when an untouched workspace can stop working. `pnpm asrun upgrade` then asks before it
  *    installs anything, using the manifest `pnpm build` writes (`dist/migrations/manifest.json`).
- * 5. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
+ * 5. A release that touched one of those surfaces but asks nothing of an existing workspace (documentation, a
+ *    clarified contract, a new optional flag) gets an entry with `advisory: true` and no `manual` steps: it tells
+ *    `pnpm migrations:check` that the change was reviewed, and `migrate` reports it and moves on.
+ * 6. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
  *    in `docs/agents/framework-dev.md`.
  */
 export declare const MIGRATIONS: Migration[];

package/dist/migrations/index.js

@@ -7,16 +7,51 @@
  * for), and anything that only concerns brand-new workspaces belongs in `templates/`.
  *
  * Adding one:
- * 1. Append an entry with an id of `<version>-<slug>` and the version of the release that *introduces* the change
- *    (`version` in `package.json` after the release PR is merged, which is the next version at the time of writing).
+ * 1. Run `pnpm migrations:check`: it lists the surfaces this change touched. Append an entry with an id of
+ *    `unreleased-<slug>` and `version: '0.15.0'`; never write a version number, because release-please only names
+ *    the version in the release pull request. `scripts/build.ts` and `pnpm asrun migrate` resolve the sentinel to the
+ *    installed release, so the published manifest is always correct; `pnpm migrations:freeze` turns it into a real
+ *    version and id on the release branch (the release pull request does it automatically).
  * 2. Explain it for the person: `summary` is one line, `appliesTo` says which workspaces it matters for, `details`
- *    adds what the summary cannot, and `manual` lists what only a person can do.
+ *    adds what the summary cannot, and `manual` lists what only a person can do. `files` names the project-owned
+ *    workspace files the change touches: acknowledging the migration then also records them as aligned with this
+ *    release's templates, which is what clears them from the upgrade's NEXT block.
  * 3. `auto: true` only when the change is idempotent and safe to run without asking (`apply` decides, `detect` skips a
  *    workspace that is already fine). A change to a file the project owns (`AGENTS.md`, `profiles.yaml`, a project
  *    config) is a `manual` step, never an automatic edit.
  * 4. Set `breaking: true` when an untouched workspace can stop working. `pnpm asrun upgrade` then asks before it
  *    installs anything, using the manifest `pnpm build` writes (`dist/migrations/manifest.json`).
- * 5. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
+ * 5. A release that touched one of those surfaces but asks nothing of an existing workspace (documentation, a
+ *    clarified contract, a new optional flag) gets an entry with `advisory: true` and no `manual` steps: it tells
+ *    `pnpm migrations:check` that the change was reviewed, and `migrate` reports it and moves on.
+ * 6. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
  *    in `docs/agents/framework-dev.md`.
  */
-export const MIGRATIONS = [];
+export const MIGRATIONS = [
+    {
+        id: '0.15.0-upgrade-workspace',
+        version: '0.15.0',
+        summary: 'A new /upgrade-workspace command aligns a workspace with the release it runs',
+        appliesTo: 'every workspace: the command is generated, its one line in the project-owned AGENTS.md is not',
+        details: 'The generated commands now include /upgrade-workspace (Claude Code and OpenCode): it runs "pnpm asrun upgrade ' +
+            '--prompt" and follows the task it prints, which is the work an upgrade leaves to a person or an AI. The layout ' +
+            'list in AGENTS.md names the new command; that file belongs to the project and is never rewritten.',
+        files: ['AGENTS.md'],
+        manual: [
+            'Add `/upgrade-workspace` to the command list in your AGENTS.md (the "Layout of this workspace" section, outside ' +
+                '## 2 and ## 3). The file the command itself lives in is generated and was already refreshed.',
+        ],
+    },
+    {
+        id: '0.15.0-explore-lead-docs',
+        version: '0.15.0',
+        summary: 'The case format documents per-profile reference lines for /explore-case --lead, and the workflow text names the flag',
+        appliesTo: 'every workspace: this is documentation; no file a workspace owns has to change',
+        details: 'A target card may now carry one "Reference <profile-id>:" line per profile that was looked at separately, and a ' +
+            'profile that shares the lead screenshot says "none: <reason>". The case format gained a paragraph about what a ' +
+            'diff profile adds to a case (its Values entry and its reference line, never a second copy of the steps). None of ' +
+            'this changes an existing case: a card with one reference line stays valid.',
+        files: ['AGENTS.md', 'cases/**'],
+        advisory: true,
+    },
+];

package/dist/migrations/manifest.json

@@ -1 +1,27 @@
-[]
+[
+  {
+    "id": "0.15.0-upgrade-workspace",
+    "version": "0.15.0",
+    "summary": "A new /upgrade-workspace command aligns a workspace with the release it runs",
+    "appliesTo": "every workspace: the command is generated, its one line in the project-owned AGENTS.md is not",
+    "details": "The generated commands now include /upgrade-workspace (Claude Code and OpenCode): it runs \"pnpm asrun upgrade --prompt\" and follows the task it prints, which is the work an upgrade leaves to a person or an AI. The layout list in AGENTS.md names the new command; that file belongs to the project and is never rewritten.",
+    "manual": [
+      "Add `/upgrade-workspace` to the command list in your AGENTS.md (the \"Layout of this workspace\" section, outside ## 2 and ## 3). The file the command itself lives in is generated and was already refreshed."
+    ],
+    "files": [
+      "AGENTS.md"
+    ]
+  },
+  {
+    "id": "0.15.0-explore-lead-docs",
+    "version": "0.15.0",
+    "summary": "The case format documents per-profile reference lines for /explore-case --lead, and the workflow text names the flag",
+    "appliesTo": "every workspace: this is documentation; no file a workspace owns has to change",
+    "details": "A target card may now carry one \"Reference <profile-id>:\" line per profile that was looked at separately, and a profile that shares the lead screenshot says \"none: <reason>\". The case format gained a paragraph about what a diff profile adds to a case (its Values entry and its reference line, never a second copy of the steps). None of this changes an existing case: a card with one reference line stays valid.",
+    "files": [
+      "AGENTS.md",
+      "cases/**"
+    ],
+    "advisory": true
+  }
+]

package/dist/scripts/build.js

@@ -23,6 +23,9 @@ for (const file of COPIED_SCRIPTS) {
 }
 // The migration manifest of the published package. A still-old `pnpm asrun upgrade` reads it out of the *target*
 // tarball before installing, so it has to be in `dist/`, next to the compiled registry the installed command uses.
+// `version: 'unreleased'` entries are resolved to the version being built: the manifest must never carry a sentinel,
+// because the reader compares versions without knowing about one.
 const manifestFile = path.join(FRAMEWORK_ROOT, MANIFEST_FILE);
+const built = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8'));
 fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
-fs.writeFileSync(manifestFile, JSON.stringify(toManifest(MIGRATIONS), null, 2) + '\n');
+fs.writeFileSync(manifestFile, JSON.stringify(toManifest(MIGRATIONS, built.version ?? '0.0.0'), null, 2) + '\n');

package/dist/scripts/cli.js

@@ -67,7 +67,8 @@ const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explor
   reset            Remove node_modules and the files init writes, for a clean reinstall (keeps cases, specs,
                    profiles.yaml, package.json and edited scaffold files; see "pnpm asrun reset --help").
   upgrade          Install the newest asrun, refresh the workspace files and apply its migrations, after checking the
-                   target release for breaking changes (see "pnpm asrun upgrade --help").
+                   target release for breaking changes. It ends with what an AI agent should still fix, and "upgrade
+                   --prompt" prints that task (see "pnpm asrun upgrade --help").
   migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
                    --help"). "upgrade" runs it; use it after a manual install.
   explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").

package/dist/scripts/doctor.js

@@ -6,9 +6,10 @@ import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR, packageDir } from '../lib/paths.js';
 import { readWorkspaceConfig } from '../lib/config.js';
 import { readProjectRules, mentionedTestDataPrefixes } from '../lib/rules.js';
 import { spawnTarget } from '../lib/command.js';
-import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { compareVersions, migrationState, pendingMigrations, resolveMigrations } from '../lib/migrations.js';
 import { MIGRATIONS } from '../migrations/index.js';
 import { GENERATED, frameworkPath, frameworkVersion, PACKAGE, renderTemplate } from './init.js';
+import { outstandingDrift, scaffoldDrift } from '../lib/scaffold.js';
 import { BUILD_APPROVALS, RUNTIME_EXTRAS, hasCapability, installedInWorkspace } from '../lib/runtime-deps.js';
 import { builtFile, COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 /**
@@ -161,6 +162,28 @@ export async function main(args) {
         }
     }
     const framework = recordedPath ?? actualPath;
+    // The registry, read before the workspace state: an entry above the installed release never runs, because
+    // `pendingMigrations` stops at the installed version. That is what a workspace several releases behind should see (the
+    // entry waits for its own release), but it is a mistake in the registry itself — a hand-written version, a checkout of
+    // a release that is not published yet — so doctor names it instead of letting the entry disappear silently.
+    const registry = resolveMigrations(MIGRATIONS, installedVersion.version);
+    const reportRegistryError = (error) => {
+        const message = `The migration registry is invalid: ${error instanceof Error ? error.message : String(error)}`;
+        if (!errors.includes(message))
+            errors.push(message);
+    };
+    try {
+        const newer = registry.filter((entry) => compareVersions(entry.version, installedVersion.version) > 0);
+        if (newer.length > 0) {
+            warnings.push(`${newer.length} migration entr${newer.length === 1 ? 'y' : 'ies'} in the registry ` +
+                `${newer.length === 1 ? 'names' : 'name'} a release newer than the installed ${installedVersion.version} ` +
+                `(${newer.map((entry) => entry.id).join(', ')}): ${newer.length === 1 ? 'it never runs' : 'they never run'} ` +
+                'here, so an entry written by hand stays "unreleased" until the release names it.');
+        }
+    }
+    catch (error) {
+        reportRegistryError(error);
+    }
     // Workspace migrations: `migrations.since` is the release the workspace matches, so newer ones are still to do. A
     // workspace upgraded by hand (pnpm add + init --update) keeps the old baseline, which is what makes this check work.
     if (marker !== null) {
@@ -168,7 +191,7 @@ export async function main(args) {
             const state = migrationState(marker, installedVersion.version);
             const outstanding = state.manual.length;
             facts.push(`migrations: since ${state.since}${outstanding > 0 ? `, ${outstanding} manual step(s) outstanding` : ''}`);
-            const pending = pendingMigrations(MIGRATIONS, state.since, installedVersion.version);
+            const pending = pendingMigrations(registry, state.since, installedVersion.version);
             if (pending.length > 0) {
                 warnings.push(`${pending.length} workspace migration(s) apply between ${state.since} and ${installedVersion.version} ` +
                     `(${pending.map((migration) => migration.id).join(', ')}): run "pnpm asrun migrate".`);
@@ -177,9 +200,17 @@ export async function main(args) {
                 warnings.push(`Manual migration steps are still open (${state.manual.join(', ')}): run "pnpm asrun migrate --list" to see ` +
                     'them, then "pnpm asrun migrate --ack <id>" once they are done.');
             }
+            // Project-owned files whose template moved under the workspace: no command can merge them, so doctor keeps
+            // naming them until somebody does it and records it. The prompt is the one entry point that explains the rest.
+            const drift = outstandingDrift(scaffoldDrift(ROOT, marker));
+            if (drift.length > 0) {
+                const shown = drift.map((entry) => `${entry.file} (${entry.state})`).join(', ');
+                warnings.push(`${drift.length} project file(s) to align with ${installedVersion.version}: ${shown}. Run ` +
+                    '"pnpm asrun migrate --prompt" for the task, then "pnpm asrun init --ack <file>" (or "init --force <file>").');
+            }
         }
         catch (error) {
-            errors.push(`The migration registry is invalid: ${error instanceof Error ? error.message : String(error)}`);
+            reportRegistryError(error);
         }
     }
     // The framework repository compiles itself into `dist/`, and `templates/playwright.config.ts` makes every workspace

package/dist/scripts/explore-notes.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { isValidCaseId } from '../lib/case-id.js';
-import { caseSha256, exploreNotesDir, exploreNotesFile, noteFreshness, readExploreNotes, } from '../lib/explore-notes.js';
+import { caseSha256, exploreNotesDir, exploreNotesFile, noteCoverage, noteFreshness, readExploreNotes, } from '../lib/explore-notes.js';
 import { ROOT } from '../lib/paths.js';
 import { loadProfiles } from '../lib/profiles.js';
 const USAGE = `Usage: pnpm explore:notes <case-id> [--profile <profile-id>] [--json] [--check] [--hash]
@@ -14,6 +14,9 @@ and falls back to a full replay when it is missing or stale.
   --check         validate every note; fails on a malformed file, warns on a stale one
   --hash          print the case file's sha256, for "caseSha256" in a note
 
+A note is "full" (it explored every step) or "diff" (an /explore-case --lead run explored only the steps that can
+differ on that profile, and "basedOn" names the lead profile the rest comes from).
+
 Paths are relative to the workspace root (${ROOT}).`;
 const args = process.argv.slice(2);
 let caseId;
@@ -98,6 +101,9 @@ if (check) {
         console.log(`FAIL cases/${caseId}.md does not exist`);
     }
     const known = new Set(knownProfiles());
+    // A --profile run must still see the lead note a diff note leans on.
+    const all = profile === undefined ? notes : readExploreNotes(caseId).notes;
+    const byProfile = new Map(all.map((note) => [note.profile, note]));
     for (const note of notes) {
         const freshness = noteFreshness(note);
         if (freshness.state !== 'fresh') {
@@ -106,6 +112,15 @@ if (check) {
         if (!known.has(note.profile)) {
             console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: "${note.profile}" is not in profiles.yaml`);
         }
+        if (note.depth !== 'diff' || note.basedOn === undefined)
+            continue;
+        const lead = byProfile.get(note.basedOn);
+        if (lead === undefined) {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: based on "${note.basedOn}", which has no note; /gen-spec replays the steps this note does not hold`);
+        }
+        else if (lead.depth === 'diff') {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: based on "${note.basedOn}", which is itself a diff note; /gen-spec replays the steps neither note holds`);
+        }
     }
     if (failed) {
         console.error('\nA note that fails here is ignored by /gen-spec. Fix it, or delete it and let the case be replayed.');
@@ -119,7 +134,9 @@ function describe(note) {
         .join(',');
     const targets = Object.keys(note.targets ?? {}).sort().join(',');
     const state = freshness.state === 'fresh' ? 'fresh' : `stale (${freshness.reason})`;
-    return `${state}  steps ${steps || '-'}  targets ${targets || '-'}  captured ${note.capturedAt}${note.updatedAt ? `  refreshed ${note.updatedAt}` : ''}`;
+    const coverage = noteCoverage(note);
+    const cover = coverage.depth === 'diff' ? `diff, based on ${coverage.basedOn}` : 'full';
+    return `${state}  ${cover}  steps ${steps || '-'}  targets ${targets || '-'}  captured ${note.capturedAt}${note.updatedAt ? `  refreshed ${note.updatedAt}` : ''}`;
 }
 function knownProfiles() {
     try {

package/dist/scripts/init.d.ts

@@ -1,31 +1,11 @@
 import { MARKER, PACKAGE } from '../lib/paths.js';
-/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
-export declare const GENERATED: {
-    file: string;
-    template: string;
-}[];
-/** Files `init` creates once; after that the project owns them and may edit them freely. */
-export declare const ONCE: {
-    file: string;
-    template: string;
-}[];
+/**
+ * The files `init` writes come from `lib/scaffold.ts`, together with the baseline that records which template a
+ * project-owned file is aligned with. They are re-exported here because `doctor`, `reset` and the prompt import them
+ * from the command that writes them.
+ */
+export { GENERATED, ONCE, frameworkPath, frameworkVersion, isInstalled, renderTemplate } from '../lib/scaffold.js';
 export { MARKER };
 export { PACKAGE };
 export declare const DOTENV_HEADER = "# asrun: the workspace these commands run against (relative to this file).";
-/** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
-export declare function frameworkPath(root: string): string;
-/** True when this workspace has the package installed (or is the framework's own checkout). */
-export declare function isInstalled(root: string): boolean;
-/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
-export declare function renderTemplate(name: string, root: string): string;
-/**
- * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
- * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
- * Kept relative: the file is committed and must not name a machine.
- */
-export declare function playwrightBin(root: string): string;
-export declare function frameworkVersion(): {
-    version: string;
-    commit: string;
-};
 export declare function main(args: string[]): Promise<number>;