@asrunjs/asrun 0.14.0 → 0.15.0

package/dist/scripts/migrations-check.js

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { FRAMEWORK_ROOT } from '../lib/paths.js';
+import { compareVersions, isVersion, UNRELEASED } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+import { GENERATED, ONCE } from '../lib/scaffold.js';
+/**
+ * `pnpm migrations:check`: the release discipline of this repository, enforced instead of remembered.
+ *
+ * A change to something an *existing* workspace has to do something about needs a migration entry, and a migration
+ * entry needs the right shape. The check compares the working tree with the newest release tag and answers three
+ * questions: which surfaces changed, which entries cover them, and is every entry valid. It runs in CI on every pull
+ * request, so a forgotten entry stops the change instead of reaching a user as a silently stale workspace.
+ */
+const USAGE = `Usage: pnpm migrations:check [--base <ref>] [--json]
+
+  --base <ref>  compare with this ref (default: the newest asrun-v* / v* tag)
+  --json        print the result as JSON
+
+Exit code 1 when a changed surface has no migration entry, or an entry is invalid.
+An entry names "unreleased" or a release that already has a tag; the one exception is the version package.json
+declares, which is the release an open release pull request prepares and which gets its tag at the merge.
+What needs an entry: templates/** of the once-only files (AGENTS.md, .mcp.json, ...), the case document format, the
+rule ids, the peer dependency range. What does not: everything init --update or init's merge rewrites by itself.`;
+/** Files whose change alters what an existing workspace must do, beyond what `init` refreshes by itself. */
+const FORMAT_FILES = [
+    {
+        file: 'AGENTS.md',
+        names: ['AGENTS.md'],
+        why: 'the baseline rules and the fixed tokens live there; a workspace copies parts of them',
+    },
+    {
+        file: 'docs/agents/case-format.md',
+        names: ['cases/**'],
+        why: 'the case document contract changed',
+    },
+    { file: 'lib/case-doc.ts', names: ['cases/**'], why: 'the case document parser and its tokens changed' },
+    { file: 'lib/targets.ts', names: ['cases/**'], why: 'target cards changed' },
+    { file: 'lib/values.ts', names: ['cases/**'], why: 'the Values block changed' },
+    { file: 'lib/records.ts', names: ['cases/**'], why: 'the test-data name format changed' },
+    { file: 'lib/rules.ts', names: ['AGENTS.md'], why: 'how project rules are read or validated changed' },
+];
+function git(args) {
+    return execFileSync('git', args, { cwd: FRAMEWORK_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+function tryGit(args) {
+    try {
+        return git(args);
+    }
+    catch {
+        return null;
+    }
+}
+/** The newest release tag, so the check compares against what users have rather than against the last commit. */
+function newestTag() {
+    const tags = tryGit(['for-each-ref', '--sort=-v:refname', '--format=%(refname:short)', 'refs/tags']);
+    if (tags === null)
+        return null;
+    return tags.split('\n').map((tag) => tag.trim()).find((tag) => /^asrun-v\d/.test(tag) || /^v\d/.test(tag)) ?? null;
+}
+/** Changed and untracked paths, relative to the repository root. */
+function changedFiles(base) {
+    const diff = tryGit(['diff', '--name-only', base, '--']);
+    const untracked = tryGit(['ls-files', '--others', '--exclude-standard']);
+    const files = new Set();
+    for (const list of [diff, untracked]) {
+        for (const line of (list ?? '').split('\n')) {
+            const file = line.trim();
+            if (file !== '')
+                files.add(file.split('\\').join('/'));
+        }
+    }
+    return [...files].sort();
+}
+/** True when the change to `package.json` touches the peer dependency range, which a workspace has to follow. */
+function peerDependencyChanged(base) {
+    const file = path.join(FRAMEWORK_ROOT, 'package.json');
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : tryGit(['show', ':package.json']);
+    const previous = tryGit(['show', `${base}:package.json`]);
+    if (current === null || previous === null)
+        return false;
+    const peers = (text) => {
+        try {
+            return JSON.stringify(JSON.parse(text).peerDependencies ?? null);
+        }
+        catch {
+            return '';
+        }
+    };
+    return peers(current) !== peers(previous);
+}
+/** The surfaces a change list touches. */
+function surfaces(files, base) {
+    const found = [];
+    for (const file of files) {
+        const once = ONCE.find((entry) => `templates/${entry.template}` === file);
+        if (once !== undefined) {
+            // `package.json` is merged by init (scripts and devDependencies) and never replaced, so a change there only needs
+            // an entry when the peer dependency range moves, which the workspace has to follow by hand.
+            if (once.file === 'package.json')
+                continue;
+            found.push({ file, names: [once.file], why: `templates/${once.file} is a project-owned file that init never rewrites` });
+            continue;
+        }
+        const generated = GENERATED.find((entry) => `templates/${entry.template}` === file);
+        if (generated !== undefined)
+            continue; // init --update rewrites it; no entry needed
+        const format = FORMAT_FILES.find((entry) => entry.file === file);
+        if (format !== undefined)
+            found.push(format);
+    }
+    if (files.includes('package.json') && peerDependencyChanged(base)) {
+        found.push({ file: 'package.json', names: ['package.json'], why: 'the peer dependency range changed and a workspace has to follow it' });
+    }
+    return found;
+}
+/** True when an entry says it is about one of the names a surface requires. */
+function covers(entry, surface) {
+    const files = entry.files ?? [];
+    return surface.names.some((name) => files.some((file) => {
+        const normalized = file.split('\\').join('/').replace(/^\.\//, '');
+        if (normalized === name)
+            return true;
+        // A `cases/**` name covers a case-format change; a specific case file does not.
+        return name.endsWith('/**') && normalized.startsWith(name.slice(0, -2));
+    }));
+}
+/** Why an entry is invalid, in the words of the person who wrote it. */
+function entryProblems(entry, pending) {
+    const problems = [];
+    if (!/^([0-9]+\.[0-9]+\.[0-9]+|unreleased)-[a-z0-9][a-z0-9-]*$/.test(entry.id)) {
+        problems.push(`id "${entry.id}" is not <version>-<slug> or unreleased-<slug>`);
+    }
+    else if (!entry.id.startsWith(`${entry.version}-`)) {
+        // The id is what a person sees in `doctor` and in the upgrade output, so it has to name the version the entry
+        // declares; freezing writes both together, and a hand edit that moves only one of them leaves a lie behind.
+        problems.push(`id "${entry.id}" does not start with "${entry.version}-", the version the entry declares`);
+    }
+    if (entry.version !== UNRELEASED && !isVersion(entry.version)) {
+        problems.push(`version "${entry.version}" is not an x.y.z version (use "${UNRELEASED}" while the release is open)`);
+    }
+    if ((entry.manual ?? []).length === 0 && entry.auto !== true && entry.advisory !== true) {
+        problems.push('it has neither "manual" steps, "auto: true" nor "advisory: true", so nothing would ever clear it');
+    }
+    if (entry.version !== UNRELEASED && isVersion(entry.version)) {
+        // A migration runs only between the release a workspace came from and the release that is installed, so an entry
+        // above the installed release is silently skipped. The version in package.json is the ceiling: on a release pull
+        // request it is the release being prepared (frozen entries, no tag until the merge) and everywhere else it is the
+        // installed release itself.
+        const isPending = pending !== null && compareVersions(entry.version, pending) === 0;
+        if (pending !== null && compareVersions(entry.version, pending) > 0) {
+            problems.push(`version ${entry.version} is newer than ${pending} in package.json, the release this checkout prepares: ` +
+                `a migration above the installed release never runs. Use "${UNRELEASED}".`);
+        }
+        else if (!isPending && !releaseTagExists(entry.version)) {
+            const prepared = pending === null ? 'package.json names no readable version' : `package.json prepares ${pending}`;
+            problems.push(`version ${entry.version} has no release tag, and it is not the release this checkout prepares (${prepared}): ` +
+                `an entry names the release that ships it, so a version that names neither is a mistake. Use "${UNRELEASED}" ` +
+                'and let the release pull request name it.');
+        }
+    }
+    for (const file of entry.files ?? []) {
+        const normalized = file.split('\\').join('/').replace(/^\.\//, '');
+        const known = ONCE.some((candidate) => candidate.file === normalized) || normalized.startsWith('cases/') || normalized === 'package.json';
+        if (!known)
+            problems.push(`files names "${file}", which is not a project-owned file this repository knows`);
+    }
+    return problems;
+}
+function releaseTagExists(version) {
+    const tags = tryGit(['tag', '--list']);
+    if (tags === null)
+        return true; // no git here: do not block on an environment that cannot answer
+    return tags.split('\n').some((tag) => tag.trim() === `asrun-v${version}` || tag.trim() === `v${version}`);
+}
+/**
+ * The version package.json declares. On a release pull request release-please has already bumped it and
+ * `release-freeze.yml` has frozen the entries to it, while the tag only appears when that pull request is merged:
+ * this is the one version the check accepts without a tag, and the ceiling every entry has to stay under.
+ */
+function pendingVersion() {
+    try {
+        const file = path.join(FRAMEWORK_ROOT, 'package.json');
+        const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return typeof manifest.version === 'string' && isVersion(manifest.version) ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function main(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const value = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 && args[index + 1] !== undefined && !args[index + 1].startsWith('-') ? args[index + 1] : undefined;
+    };
+    const base = value('--base') ?? newestTag();
+    if (base === null) {
+        console.error('No release tag to compare with: pass --base <ref> (for example the first commit).');
+        return 1;
+    }
+    const files = changedFiles(base);
+    const found = surfaces(files, base);
+    const pending = pendingVersion();
+    const problems = [];
+    const ids = new Set();
+    for (const entry of MIGRATIONS) {
+        if (ids.has(entry.id))
+            problems.push(`${entry.id}: two migrations share this id`);
+        ids.add(entry.id);
+        for (const problem of entryProblems(entry, pending))
+            problems.push(`${entry.id}: ${problem}`);
+    }
+    const missing = found.filter((surface) => !MIGRATIONS.some((entry) => covers(entry, surface)));
+    if (args.includes('--json')) {
+        console.log(JSON.stringify({ base, pending, files, surfaces: found, missing, problems }, null, 2));
+    }
+    else {
+        console.log(`migrations:check  base ${base}`);
+        if (pending !== null && !releaseTagExists(pending)) {
+            console.log(`  ${pending} is the release this checkout prepares (package.json): its tag comes with the merge`);
+        }
+        const generated = files.filter((file) => GENERATED.some((entry) => `templates/${entry.template}` === file));
+        if (found.length === 0)
+            console.log('  no surface changed that needs a migration entry');
+        for (const surface of found) {
+            const covered = !missing.includes(surface);
+            console.log(`  ${covered ? 'ok ' : '-> '}${surface.file.padEnd(34)} ${covered ? 'covered' : 'needs a migration entry'}`);
+            console.log(`      ${surface.why}`);
+        }
+        for (const file of generated)
+            console.log(`     ${file.padEnd(34)} generated: init --update refreshes it, no entry`);
+        if (missing.length > 0) {
+            console.log(`\n${missing.length} surface(s) have no migration entry. Add one to migrations/index.ts:`);
+            console.log(entryTemplate(missing));
+        }
+        for (const problem of problems)
+            console.log(`\n  ! ${problem}`);
+    }
+    if (missing.length > 0 || problems.length > 0)
+        return 1;
+    if (!args.includes('--json'))
+        console.log('\nEvery changed surface is covered, and every entry is valid.');
+    return 0;
+}
+/** A ready-to-paste entry for the missing surfaces, so the check is faster to satisfy than to ignore. */
+function entryTemplate(missing) {
+    const files = [...new Set(missing.flatMap((surface) => surface.names))];
+    return [
+        '',
+        '  {',
+        `    id: '${UNRELEASED}-<slug>',`,
+        `    version: '${UNRELEASED}',`,
+        "    summary: '<one line for the person>',",
+        "    appliesTo: '<which workspaces this matters for>',",
+        "    details: '<what changed and why>',",
+        `    files: [${files.map((file) => `'${file}'`).join(', ')}],`,
+        '    manual: [',
+        "      '<what a person or an AI has to do, one step per line>',",
+        '    ],',
+        '  },',
+        '',
+        `No version: release-please names it in the release pull request, and "pnpm migrations:freeze" writes it then.`,
+    ].join('\n');
+}
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+    process.exit(main(process.argv.slice(2)));
+}

package/dist/scripts/migrations-freeze.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): number;

package/dist/scripts/migrations-freeze.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { FRAMEWORK_ROOT } from '../lib/paths.js';
+import { UNRELEASED, isVersion } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+/**
+ * `pnpm migrations:freeze`: writes the release's version into the entries that are still `unreleased`.
+ *
+ * Release Please names the version only once the release pull request exists, so an author never guesses one. Entries
+ * carry `version: 'unreleased'` until then; `scripts/build.ts` and `pnpm asrun migrate` resolve it to the installed
+ * release, so a release is always correct even if nobody freezes. Freezing only fixes the *id* that a workspace will
+ * see in `doctor` and in the upgrade output (`unreleased-agents-scaffold` → `0.15.0-agents-scaffold`), which is why the
+ * release pull request runs it.
+ *
+ * The version comes from `package.json`, which the release pull request has already bumped beyond the newest tag.
+ */
+const USAGE = `Usage: pnpm migrations:freeze [--version <x.y.z>] [--check] [--dry-run]
+
+  --version <v>  the release to freeze to (default: package.json, which must be newer than the newest tag)
+  --check        exit 1 when an entry is still "unreleased"; change nothing (used before publishing)
+  --dry-run      show what would change, and change nothing`;
+const REGISTRY = path.join(FRAMEWORK_ROOT, 'migrations', 'index.ts');
+function git(args) {
+    try {
+        return execFileSync('git', args, { cwd: FRAMEWORK_ROOT, encoding: 'utf8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** The versions of the release tags, newest first; used to tell "the release is open" from "not yet". */
+function tags() {
+    const list = git(['for-each-ref', '--sort=-v:refname', '--format=%(refname:short)', 'refs/tags']);
+    if (list === null)
+        return [];
+    return list
+        .split('\n')
+        .map((tag) => tag.trim())
+        .filter((tag) => /^(asrun-)?v\d/.test(tag))
+        .map((tag) => tag.replace(/^asrun-v/, '').replace(/^v/, ''));
+}
+function currentVersion() {
+    const manifest = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8'));
+    return manifest.version ?? '0.0.0';
+}
+/** The entries that still carry the sentinel, as ids and line numbers, for `--check` and the summary. */
+function pendingEntries() {
+    return MIGRATIONS.filter((entry) => entry.version === UNRELEASED || entry.id.startsWith(`${UNRELEASED}-`)).map((entry) => entry.id);
+}
+/** Replaces the sentinel with the release version: `version: 'unreleased'` and the `unreleased-` id prefix. */
+function freezeText(text, version) {
+    let replacements = 0;
+    const next = text
+        .replace(/(\bversion:\s*)(['"`])unreleased\2/g, (_match, head, quote) => {
+        replacements++;
+        return `${head}${quote}${version}${quote}`;
+    })
+        .replace(/(\bid:\s*)(['"`])unreleased-/g, (_match, head, quote) => {
+        replacements++;
+        return `${head}${quote}${version}-`;
+    });
+    return { next, replacements };
+}
+export function main(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const value = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 && args[index + 1] !== undefined && !args[index + 1].startsWith('-') ? args[index + 1] : undefined;
+    };
+    const check = args.includes('--check');
+    const dryRun = args.includes('--dry-run');
+    const pending = pendingEntries();
+    if (check) {
+        if (pending.length === 0) {
+            console.log('Every migration entry names a release.');
+            return 0;
+        }
+        console.error(`${pending.length} migration entr${pending.length === 1 ? 'y is' : 'ies are'} still "unreleased":`);
+        for (const id of pending)
+            console.error(`  ${id}`);
+        console.error('\nRun "pnpm migrations:freeze" on the release branch and push it before the release is cut.');
+        return 1;
+    }
+    if (pending.length === 0) {
+        console.log('Nothing to freeze: every migration entry already names a release.');
+        return 0;
+    }
+    const installed = currentVersion();
+    const version = value('--version') ?? installed;
+    if (!isVersion(version)) {
+        console.error(`"${version}" is not a version. Pass --version x.y.z.`);
+        return 1;
+    }
+    const released = tags();
+    if (value('--version') === undefined && released.includes(version)) {
+        console.error(`package.json is still ${version}, which is already a release tag: the release pull request has not bumped it yet.\n` +
+            'Wait for the release pull request, then run this on that branch (or pass --version explicitly).');
+        return 1;
+    }
+    const text = fs.readFileSync(REGISTRY, 'utf8');
+    const { next, replacements } = freezeText(text, version);
+    if (replacements === 0) {
+        console.log(`No sentinel text found in ${path.relative(FRAMEWORK_ROOT, REGISTRY)}; nothing to do.`);
+        return 0;
+    }
+    if (dryRun) {
+        console.log(`Would freeze ${pending.length} entr${pending.length === 1 ? 'y' : 'ies'} to ${version} (${replacements} replacements).`);
+        for (const id of pending)
+            console.log(`  ${id} -> ${id.replace(new RegExp(`^${UNRELEASED}-`), `${version}-`)}`);
+        console.log('Nothing was written (--dry-run).');
+        return 0;
+    }
+    fs.writeFileSync(REGISTRY, next);
+    console.log(`Froze ${pending.length} migration entr${pending.length === 1 ? 'y' : 'ies'} to ${version}:`);
+    for (const id of pending)
+        console.log(`  ${id} -> ${id.replace(new RegExp(`^${UNRELEASED}-`), `${version}-`)}`);
+    console.log('\nNext: "pnpm build" (the manifest in dist/), then "pnpm migrations:check".');
+    return 0;
+}
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+    process.exit(main(process.argv.slice(2)));
+}

package/dist/scripts/upgrade.js

@@ -7,6 +7,8 @@ import { compareVersions, isVersion, migrationState, pendingMigrations, readMark
 import { FRAMEWORK_ROOT, MARKER, ROOT } from '../lib/paths.js';
 import { releaseInfo, releaseManifest } from '../lib/registry.js';
 import { excludeReleaseAge } from '../lib/runtime-deps.js';
+import { nextStepsText, upgradePrompt } from '../lib/upgrade-prompt.js';
+import { useColor } from '../lib/term.js';
 import { frameworkPath, PACKAGE } from './init.js';
 /**
  * `pnpm asrun upgrade`: one command that installs the newest framework, refreshes the workspace files and applies the
@@ -16,12 +18,14 @@ import { frameworkPath, PACKAGE } from './init.js';
  * changes are known before anything is written; the install comes next, and `init --update`, `migrate` and `doctor`
  * then run through the *newly installed* package, never through the code that is being replaced.
  */
-const USAGE = `Usage: pnpm asrun upgrade [--version <version|dist-tag>] [--root <dir>] [--dry-run] [--yes]
+const USAGE = `Usage: pnpm asrun upgrade [--version <version|dist-tag>] [--root <dir>] [--dry-run] [--yes|-y] [--prompt [--json]]
 
   --version <v>   the release to install (default: latest); a dist-tag or a concrete version
   --root <dir>    the workspace to upgrade (default: the current workspace)
   --dry-run       print the target release and the migrations it brings, and change nothing
-  --yes           install without asking (a breaking change, or a release that cannot be checked)
+  --yes, -y       install without asking (a breaking change, or a release that cannot be checked)
+  --prompt        print the prompt that hands the leftover work to an AI agent, and change nothing (local only)
+  --json          with --prompt: the same answer as JSON, for the web UI
 
 What it does, in this order:
   1. resolve the target release and read its migration manifest from the registry;
@@ -30,7 +34,11 @@ What it does, in this order:
   4. run "init --update", "migrate" and "doctor" through the installed package.
 
 A release older than the migration manifest cannot be checked in advance: the command says so and asks before it
-installs. "pnpm asrun migrate" runs only the migration part, for a workspace that was upgraded by hand.`;
+installs. "pnpm asrun migrate" runs only the migration part, for a workspace that was upgraded by hand.
+
+When the release changes files the project owns (AGENTS.md and the other once-only files), the upgrade ends with a
+NEXT block. "pnpm asrun upgrade --prompt" prints the task for an AI agent (or run "/upgrade-workspace" in Claude Code or
+OpenCode).`;
 /** How a workspace reaches its install: the nearest `node_modules/@asrunjs/asrun` at or above the workspace root. */
 function installedDir(root) {
     for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
@@ -53,20 +61,27 @@ function installedVersion(dir) {
         return null;
     }
 }
-/** A person types the word; without a terminal there is no confirmation, and the command refuses. */
+/**
+ * A person answers y/N; an empty line, or anything that is not "y"/"yes", means no. Without a terminal there is nobody
+ * to ask, and the command refuses instead of assuming an answer (`--yes` is the way through).
+ */
 async function confirm(question) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         return null;
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        return (await rl.question(question)).trim().toLowerCase() === 'upgrade';
+        const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
     }
     finally {
         rl.close();
     }
 }
 function printMigration(entry) {
-    const tags = [entry.breaking === true ? 'breaking' : '', entry.auto === true ? 'runs automatically' : 'needs a person']
+    const tags = [
+        entry.breaking === true ? 'breaking' : '',
+        entry.advisory === true ? 'nothing to do' : entry.auto === true ? 'runs automatically' : 'needs a person',
+    ]
         .filter(Boolean)
         .join(', ');
     console.log(`  ${entry.breaking === true ? '!' : ' '} ${entry.version}  ${entry.summary}`);
@@ -89,7 +104,9 @@ export async function main(args) {
     };
     const root = path.resolve(value('--root') ?? ROOT);
     const dryRun = args.includes('--dry-run');
-    const yes = args.includes('--yes');
+    const yes = args.includes('--yes') || args.includes('-y');
+    const promptOnly = args.includes('--prompt');
+    const asJson = args.includes('--json');
     const spec = value('--version') ?? 'latest';
     if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
         console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun upgrade" in the project that uses ' +
@@ -100,6 +117,17 @@ export async function main(args) {
         console.error(`No ${MARKER} in ${root}: this is not an initialized asrun workspace. Run "pnpm asrun init" first.`);
         return 1;
     }
+    // `--prompt` answers "what is left" for the release that is already installed: it reads the workspace and the
+    // installed package only, so it works offline and changes nothing (not even the update cache).
+    if (promptOnly) {
+        const payload = upgradePrompt(root);
+        console.log(asJson ? JSON.stringify(payload, null, 2) : payload.prompt);
+        return 0;
+    }
+    if (asJson) {
+        console.error('--json belongs to --prompt: "pnpm asrun upgrade --prompt --json".');
+        return 1;
+    }
     console.log('[1/4] Checking the release');
     const directory = installedDir(root);
     const current = installedVersion(directory);
@@ -177,12 +205,17 @@ export async function main(args) {
         return 0;
     }
     if (needsConfirmation) {
+        if (breaking.length > 0) {
+            console.log('');
+            for (const entry of breaking)
+                console.log(`  ! ${entry.id}  ${entry.summary}`);
+        }
         const question = breaking.length > 0
-            ? `\nType "upgrade" to install ${PACKAGE}@${target} despite ${breaking.length} breaking change(s): `
-            : `\nType "upgrade" to install ${PACKAGE}@${target} without the pre-install check: `;
+            ? `\nInstall ${PACKAGE}@${target} in ${root}, despite ${breaking.length} breaking change(s)?`
+            : `\nInstall ${PACKAGE}@${target} in ${root} without the pre-install check?`;
         const answer = await confirm(question);
         if (answer === null) {
-            console.error('Refusing to install: there is no terminal to confirm in. A person adds --yes to do it.');
+            console.error('Refusing to install: there is no terminal to confirm in. A person adds --yes (or -y) to do it.');
             return 1;
         }
         if (!answer) {
@@ -190,6 +223,9 @@ export async function main(args) {
             return 1;
         }
     }
+    else if (yes) {
+        console.log(`\nInstalling without asking (--yes).`);
+    }
     console.log(`\n[2/4] Installing ${PACKAGE}@${target}`);
     const age = excludeReleaseAge(root, PACKAGE);
     if (age === 'added' || age === 'created') {
@@ -252,5 +288,12 @@ export async function main(args) {
     console.log(`\n[4/4] Checking the workspace`);
     const doctor = run(['doctor']);
     console.log(`\nUpgraded ${PACKAGE} ${current} -> ${after ?? target} in ${root}.`);
+    // The release is installed; what is left are files the project owns and the manual steps a migration recorded. The
+    // block is printed only when there is something to do, so a patch release stays quiet.
+    const next = nextStepsText(root, { color: useColor(process.stdout) });
+    if (next === null)
+        console.log('Nothing in the project\'s own files needs updating.');
+    else
+        console.log(`\n${next}`);
     return doctor.status ?? 0;
 }

package/dist/ui/server/app.js

@@ -15,6 +15,7 @@ import { JobConflictError, jobs } from './jobs.js';
 import { listAiModels } from './ai-models.js';
 import { fileEvents } from './watch-files.js';
 import { refreshUpdate, updateEvents, updateInfo } from './update.js';
+import { upgradePrompt } from '../../lib/upgrade-prompt.js';
 const REPORTS_DIR = path.join(ROOT, 'reports');
 // Built by `prepack` and shipped with the package; the framework repository builds it with `pnpm ui`.
 const WEB_DIST = path.join(FRAMEWORK_ROOT, 'ui', 'dist');
@@ -240,6 +241,9 @@ export function createApp({ port }) {
             void refreshUpdate(true);
         return c.json(info);
     });
+    // What an upgrade leaves open, and the prompt that hands it to an agent. Read-only; the dialog asks for it only when
+    // it opens, because it reads the installed templates and can be long.
+    api.get('/upgrade/prompt', (c) => c.json(upgradePrompt(ROOT)));
     api.get('/reports', (c) => {
         if (!fs.existsSync(REPORTS_DIR))
             return c.json([]);

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

@@ -348,6 +348,12 @@ export interface ReportInfo {
     counts: Record<ResultStatus, number> | null;
 }
 export type { ParsedError, ResultStatus, RunSettings, RunSummary, TestRunResult } from '../../lib/run-summary.js';
+/**
+ * What an upgrade leaves to a person or an AI, and the prompt that hands it over. Built by `lib/upgrade-prompt.ts`,
+ * the same module `pnpm asrun upgrade --prompt --json` prints.
+ */
+export type { ScaffoldDrift, ScaffoldState } from '../../lib/scaffold.js';
+export type { OutstandingFile, OutstandingMigration, UpgradeOutstanding, UpgradePromptPayload } from '../../lib/upgrade-prompt.js';
 export interface InfoResponse {
     root: string;
     envs: string[];

package/docs/agents/case-format.md

@@ -149,6 +149,8 @@ One card per distinct thing a check looks at:
 - `What`, `Where` and `Identified by` are required for a card that is not blocking.
 - `Reference <profile-id>:` must point under `.explore/targets/<case-id>/` (git-ignored), or be `none: <reason>`.
   A missing file on this machine is a warning, not a failure: a fresh checkout has the card but not the screenshot.
+  A card carries one line per profile that was looked at separately: an `--lead` exploration adds its own line for a
+  profile whose element differs, and `none: <reason>` for one that shares the lead's screenshot.
 - A card may hold a `🚫 TODO [blocking]` block. Such a card is not complete; `pnpm case:check` does not fail on it,
   and the check that uses it is not generated yet.
 - Every `[T<n>]` in a step, a ready signal or a check resolves to a card. `pnpm case:check` fails on a reference with
@@ -208,6 +210,10 @@ test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
   by `pnpm asrun rules`) and the stamp is the run's UTC time; register it with `records.track` right after creating
   it, remove it newest first (also after a failure), turn retries off with `configureCase`, and keep email steps
   behind `emailStepAllowed(profile, '<step title>')`.
+- `/explore-case --lead` explores one profile in full and the others only where they can differ. What a diff profile
+  adds to the case is its `## Values` entry and its `Reference <profile-id>:` line, never a second copy of the steps;
+  `/gen-spec` writes those profiles' parts from the lead's note and names them `not verified`. A step whose recipe
+  would differ per profile has no per-profile form (`- Recipe:` belongs to the step): split the case, or ask.
 
 ## Checks to run before reporting