nx 23.2.0-beta.0 → 23.2.0-beta.10

package/dist/src/command-line/migrate/migrate-commits.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedAgentic } from './agentic/types';
 /**
  * Discriminated result for `commitMigrationIfRequested`. Distinguishes the
  * shapes the executor needs to react to:
@@ -23,21 +24,20 @@ export type CommitResult = {
     status: 'disabled';
 };
 /**
- * Creates a per-migration commit when `shouldCreateCommits` is true.
+ * `pendingMigrations` are listed in the commit body so a `git log -p` reader
+ * can see which earlier migrations' diffs this commit absorbed (their own
+ * commits failed and `git add -A` picked their working-tree state up too).
  *
- * When `pendingMigrations` is non-empty, the commit message body lists
- * those entries so a reader of `git log -p` can see which prior migrations'
- * diffs were absorbed into this commit (because their own commits failed and
- * `git add -A` here captured their working-tree state too). Each entry is
- * rendered as `<package>: <name>` for unambiguous attribution across
- * packages.
+ * The default `failureGuidance` describes the classic loop's absorb-and-recap
+ * behavior; a caller with no later commit or recap to absorb the diff (the
+ * standalone single-migration worker) passes its own.
  */
 export declare function commitMigrationIfRequested(root: string, migration: {
     name: string;
 }, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged: () => Promise<void>, pendingMigrations?: ReadonlyArray<{
     package: string;
     name: string;
-}>): Promise<CommitResult>;
+}>, failureGuidance?: string): Promise<CommitResult>;
 /**
  * Commits any pre-existing working-tree state into a dedicated "checkpoint"
  * commit before the first migration runs. Without this, the first migration's
@@ -48,3 +48,33 @@ export declare function commitMigrationIfRequested(root: string, migration: {
  * the working tree is already clean.
  */
 export declare function commitCheckpointBeforeMigrations(root: string, commitPrefix: string): void;
+/**
+ * `agenticHasDiffContext` gates the agent prompt: without per-migration commits
+ * to isolate a migration's diff, the prompt embeds a file list instead of
+ * pointing at git.
+ */
+export declare function resolveCreateCommits(args: {
+    createCommits: boolean | undefined;
+    mode: ResolvedAgentic['kind'] | 'orchestrated';
+    isGitRepo: boolean;
+    commitPrefixIsCustom?: boolean;
+}): {
+    effective: boolean;
+    agenticHasDiffContext: boolean;
+    warning?: string;
+    error?: string;
+};
+/**
+ * Asks before a run starts committing on the workspace's default branch, and
+ * reports the decision when the answer is no. Returns whether to proceed.
+ *
+ * Callers gate this on commits being effective and on prompting being
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here;
+ * `confirmCommitsOnDefaultBranch` has no guard of its own and would block on a
+ * prompt nobody can answer.
+ */
+export declare function confirmMigrationCommitsOnDefaultBranch(root: string, whatWouldRun: 'running migrations' | 'running the migration'): Promise<boolean>;
+export declare function confirmCommitsOnDefaultBranch(args: {
+    currentBranch: string | null;
+    defaultBranch: string | null;
+}): Promise<boolean>;

package/dist/src/command-line/migrate/migrate-commits.js

@@ -2,34 +2,45 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commitMigrationIfRequested = commitMigrationIfRequested;
 exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
+exports.resolveCreateCommits = resolveCreateCommits;
+exports.confirmMigrationCommitsOnDefaultBranch = confirmMigrationCommitsOnDefaultBranch;
+exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
+const configuration_1 = require("../../config/configuration");
+const command_line_utils_1 = require("../../utils/command-line-utils");
 const git_utils_1 = require("../../utils/git-utils");
 const logger_1 = require("../../utils/logger");
 const output_1 = require("../../utils/output");
+const types_1 = require("./agentic/types");
+const safe_prompt_1 = require("./safe-prompt");
+// `git add -A` captures an orchestrated run's scratch state whenever the
+// ignore rule that normally hides it goes missing mid-run (a checkout, a
+// .gitignore edit, or the migration's own changes).
+const MIGRATE_COMMIT_EXCLUDES = [types_1.MIGRATE_RUNS_RELATIVE_DIR];
 /**
- * Creates a per-migration commit when `shouldCreateCommits` is true.
+ * `pendingMigrations` are listed in the commit body so a `git log -p` reader
+ * can see which earlier migrations' diffs this commit absorbed (their own
+ * commits failed and `git add -A` picked their working-tree state up too).
  *
- * When `pendingMigrations` is non-empty, the commit message body lists
- * those entries so a reader of `git log -p` can see which prior migrations'
- * diffs were absorbed into this commit (because their own commits failed and
- * `git add -A` here captured their working-tree state too). Each entry is
- * rendered as `<package>: <name>` for unambiguous attribution across
- * packages.
+ * The default `failureGuidance` describes the classic loop's absorb-and-recap
+ * behavior; a caller with no later commit or recap to absorb the diff (the
+ * standalone single-migration worker) passes its own.
  */
-async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = []) {
+async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = [], failureGuidance = 'The next successful commit will absorb it and reference this migration in its body; if no later commit lands, the end-of-run output will list this migration so you can commit or revert manually.') {
     if (!shouldCreateCommits)
         return { status: 'disabled' };
     await installDepsIfChanged();
-    // Generator may have only touched gitignored paths, or the prompt half
-    // made no change — log neutrally instead of as an error.
-    if (!(0, git_utils_1.hasUncommittedChanges)(root)) {
+    // Generator may have only touched gitignored paths or the excluded scratch
+    // dir, or the prompt half made no change: log neutrally, not as an error.
+    // The probe excludes what the commit excludes, else the commit fails empty.
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, MIGRATE_COMMIT_EXCLUDES)) {
         logger_1.logger.info(pc.dim(`- No changes to commit for ${migration.name}.`));
         return { status: 'no-changes' };
     }
     const commitMessage = buildCommitMessage(`${commitPrefix}${migration.name}`, pendingMigrations);
     try {
-        const sha = (0, git_utils_1.tryCommitChanges)(commitMessage, root);
+        const sha = (0, git_utils_1.tryCommitChanges)(commitMessage, root, MIGRATE_COMMIT_EXCLUDES);
         if (sha)
             return { status: 'committed', sha };
         // null = commit landed but `git rev-parse HEAD` failed (see
@@ -39,7 +50,7 @@ async function commitMigrationIfRequested(root, migration, shouldCreateCommits,
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        logger_1.logger.info(pc.red(`Could not create a commit for ${migration.name}:\n${reason}\nThe migration's diff remains in the working tree; inspect with \`git status\` / \`git diff\` to review. The next successful commit will absorb it and reference this migration in its body; if no later commit lands, the end-of-run output will list this migration so you can commit or revert manually.`));
+        logger_1.logger.info(pc.red(`Could not create a commit for ${migration.name}:\n${reason}\nThe migration's diff remains in the working tree; inspect with \`git status\` / \`git diff\` to review. ${failureGuidance}`));
         return { status: 'failed', reason };
     }
 }
@@ -72,10 +83,10 @@ function buildCommitMessage(subject, pendingMigrations) {
  * the working tree is already clean.
  */
 function commitCheckpointBeforeMigrations(root, commitPrefix) {
-    if (!(0, git_utils_1.hasUncommittedChanges)(root))
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, MIGRATE_COMMIT_EXCLUDES))
         return;
     try {
-        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root);
+        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root, MIGRATE_COMMIT_EXCLUDES);
         if (sha) {
             logger_1.logger.info(pc.dim(`- Checkpoint commit created: ${sha}`));
             return;
@@ -100,3 +111,107 @@ function commitCheckpointBeforeMigrations(root, commitPrefix) {
         });
     }
 }
+/**
+ * `agenticHasDiffContext` gates the agent prompt: without per-migration commits
+ * to isolate a migration's diff, the prompt embeds a file list instead of
+ * pointing at git.
+ */
+function resolveCreateCommits(args) {
+    const { createCommits, mode, isGitRepo, commitPrefixIsCustom } = args;
+    // The orchestrator forces the agentic defaults without the `--agentic` flag,
+    // so its warnings must not name a flag the user never passed.
+    const orchestrated = mode === 'orchestrated';
+    const agenticKind = orchestrated ? 'enabled' : mode;
+    if (createCommits === true && !isGitRepo) {
+        return {
+            effective: false,
+            agenticHasDiffContext: false,
+            error: '`--create-commits` requires a git repository. Run `git init` first, or omit the flag.',
+        };
+    }
+    if (agenticKind === 'enabled') {
+        if (createCommits === false) {
+            return {
+                effective: false,
+                agenticHasDiffContext: false,
+                warning: (orchestrated
+                    ? "--no-create-commits was passed, but orchestrated migrate runs create per-migration commits by default. Without them, the agent can't isolate the current migration's changes from earlier migrations in this run. Drop --no-create-commits for accurate per-migration review."
+                    : "--no-create-commits was passed alongside --agentic. Without per-migration commits, the agent can't isolate the current migration's changes from earlier migrations in this run. Drop --no-create-commits for accurate per-migration review.") +
+                    (commitPrefixIsCustom
+                        ? ' Note: the custom --commit-prefix value will have no effect because commits are disabled.'
+                        : ''),
+            };
+        }
+        // Not an error like the explicit `--create-commits` branch above: the
+        // agentic default was never asked for, so degrade instead.
+        if (!isGitRepo) {
+            return {
+                effective: false,
+                agenticHasDiffContext: false,
+                warning: (orchestrated
+                    ? 'Orchestrated migrate runs create per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.'
+                    : '`--agentic` enables per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.') +
+                    (commitPrefixIsCustom
+                        ? ' The custom --commit-prefix value will have no effect.'
+                        : ''),
+            };
+        }
+        return { effective: true, agenticHasDiffContext: true };
+    }
+    return {
+        effective: createCommits === true,
+        agenticHasDiffContext: false,
+        warning: commitPrefixIsCustom && createCommits !== true
+            ? 'A custom migrate commit prefix is configured, but commits are not enabled for this run, so it has no effect. Set `migrate.createCommits` to `true` (or pass `--create-commits`) to create a commit per migration.'
+            : undefined,
+    };
+}
+// The branch to hold `getBaseRef`'s value against. It may name a remote-tracking
+// ref whose local counterpart drops the remote (the CI-workflow generator writes
+// `origin/<branch>`), yet a local branch can be named `up/feature` while `up` is
+// a remote, so an exact match wins before any stripping and the longest matching
+// remote wins after. `origin` counts even undeclared: the generator assumes it.
+function defaultBranchToCompare(baseRef, currentBranch, root) {
+    if (currentBranch === baseRef) {
+        return baseRef;
+    }
+    const remote = [...(0, git_utils_1.getGitRemoteNames)(root), 'origin']
+        .filter((name) => baseRef.startsWith(`${name}/`))
+        .sort((a, b) => b.length - a.length)[0];
+    return remote ? baseRef.slice(remote.length + 1) : baseRef;
+}
+/**
+ * Asks before a run starts committing on the workspace's default branch, and
+ * reports the decision when the answer is no. Returns whether to proceed.
+ *
+ * Callers gate this on commits being effective and on prompting being
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here;
+ * `confirmCommitsOnDefaultBranch` has no guard of its own and would block on a
+ * prompt nobody can answer.
+ */
+async function confirmMigrationCommitsOnDefaultBranch(root, whatWouldRun) {
+    const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+    const proceed = await confirmCommitsOnDefaultBranch({
+        currentBranch,
+        defaultBranch: defaultBranchToCompare((0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)), currentBranch, root),
+    });
+    if (!proceed) {
+        output_1.output.log({
+            title: `Skipped ${whatWouldRun} to avoid committing to the default branch '${currentBranch}'.`,
+            bodyLines: [
+                'Switch to a different branch and re-run, or re-run and confirm to proceed.',
+            ],
+        });
+    }
+    return proceed;
+}
+async function confirmCommitsOnDefaultBranch(args) {
+    const { currentBranch, defaultBranch } = args;
+    if (!currentBranch || !defaultBranch || currentBranch !== defaultBranch) {
+        return true;
+    }
+    return (0, safe_prompt_1.migrateConfirm)({
+        message: `You're on the default branch '${currentBranch}'. nx migrate will create a commit for each migration on this branch. Continue?`,
+        initial: false,
+    });
+}

package/dist/src/command-line/migrate/migrate-config.d.ts

@@ -1,20 +1,21 @@
 import type { NxMigrateConfiguration } from '../../config/nx-json';
 import { type MigrateArgs } from './command-object';
 /**
- * Overlays `nx.json` `migrate` defaults onto the raw `nx migrate` CLI args so a
- * CLI flag always wins, then `nx.json`, then the built-in default. Returns a new
- * args object; the input is not mutated.
+ * Overlays `nx.json` `migrate` defaults onto the raw CLI args: a CLI flag wins,
+ * then `nx.json`, then the built-in default. Returns a new args object; the
+ * input is not mutated.
  *
- * Phase-aware: generate-only options (`include`, `multiMajorMode`) are applied only
- * when not running migrations; run-only options (`createCommits`,
- * `commitPrefix`, `agentic`, `validate`) only when running migrations. This
- * mirrors where each option is consumed and avoids tripping the "cannot be
- * combined with --run-migrations" guards in `parseMigrationsOptions`.
+ * Phase-aware so each option is only filled where it is consumed, and so a
+ * config value never trips the mutually-exclusive-flag guards in
+ * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
+ * phase only; `createCommits` / `commitPrefix` and `agentic` / `validate` when
+ * running the whole migrations file or a standalone single migration. A
+ * `--run-id` invocation takes none of them: a recorded run takes its commit
+ * config from run.json and is driven by the outer agent.
  *
- * `include` is carried as `includeFromConfig` rather than `include` so it is never
- * mistaken for an explicit `--include`: `resolveInclude` applies it only when the
- * resolved target supports optional updates, leaving targets that don't opt in
- * unaffected.
+ * `include` is carried as `includeFromConfig` so it is never mistaken for an
+ * explicit `--include`: `resolveInclude` applies it only when the resolved
+ * target supports optional updates.
  */
 export declare function applyNxJsonMigrateDefaults(args: MigrateArgs, migrateConfig: NxMigrateConfiguration | undefined, env?: NodeJS.ProcessEnv): MigrateArgs;
 /**

package/dist/src/command-line/migrate/migrate-config.js

@@ -6,20 +6,21 @@ const cli_args_1 = require("./agentic/cli-args");
 const command_object_1 = require("./command-object");
 const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
 /**
- * Overlays `nx.json` `migrate` defaults onto the raw `nx migrate` CLI args so a
- * CLI flag always wins, then `nx.json`, then the built-in default. Returns a new
- * args object; the input is not mutated.
+ * Overlays `nx.json` `migrate` defaults onto the raw CLI args: a CLI flag wins,
+ * then `nx.json`, then the built-in default. Returns a new args object; the
+ * input is not mutated.
  *
- * Phase-aware: generate-only options (`include`, `multiMajorMode`) are applied only
- * when not running migrations; run-only options (`createCommits`,
- * `commitPrefix`, `agentic`, `validate`) only when running migrations. This
- * mirrors where each option is consumed and avoids tripping the "cannot be
- * combined with --run-migrations" guards in `parseMigrationsOptions`.
+ * Phase-aware so each option is only filled where it is consumed, and so a
+ * config value never trips the mutually-exclusive-flag guards in
+ * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
+ * phase only; `createCommits` / `commitPrefix` and `agentic` / `validate` when
+ * running the whole migrations file or a standalone single migration. A
+ * `--run-id` invocation takes none of them: a recorded run takes its commit
+ * config from run.json and is driven by the outer agent.
  *
- * `include` is carried as `includeFromConfig` rather than `include` so it is never
- * mistaken for an explicit `--include`: `resolveInclude` applies it only when the
- * resolved target supports optional updates, leaving targets that don't opt in
- * unaffected.
+ * `include` is carried as `includeFromConfig` so it is never mistaken for an
+ * explicit `--include`: `resolveInclude` applies it only when the resolved
+ * target supports optional updates.
  */
 function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     if (!migrateConfig) {
@@ -29,7 +30,14 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
     // `--run-migrations` with no value is normalized to '' by yargs, so a defined
     // (even empty-string) value means we're in the run-migrations phase.
     const isRunMigrations = merged.runMigrations !== undefined;
-    if (isRunMigrations) {
+    // A bare `--run-id` (orchestrated reconcile) must never take the
+    // generate-options overlay, which would leak `include` etc. from nx.json.
+    const isSingleMigration = merged.runMigration !== undefined || merged.runId !== undefined;
+    // Both overlays are for an invocation that decides these options for
+    // itself, which a `--run-id` invocation never does: the recorded worker and
+    // the reconcile both read the commit config from run.json, and overlaying
+    // `agentic` would trip the `--agentic`/`--run-id` parse conflict.
+    if ((isRunMigrations || isSingleMigration) && merged.runId === undefined) {
         if (merged.createCommits === undefined &&
             migrateConfig.createCommits !== undefined) {
             assertType(migrateConfig.createCommits, 'boolean', 'createCommits');
@@ -53,7 +61,7 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
             merged.validate = migrateConfig.validate;
         }
     }
-    else {
+    if (!isRunMigrations && !isSingleMigration) {
         if (merged.include === undefined && migrateConfig.include !== undefined) {
             assertOneOf(migrateConfig.include, command_object_1.MIGRATE_INCLUDE_VALUES, 'include');
             merged.includeFromConfig = migrateConfig.include;

package/dist/src/command-line/migrate/migrate-output.d.ts

@@ -1,11 +1,10 @@
 /**
- * Presentation layer for `nx migrate --run-migrations`. Pure helpers — every
- * function maps (state) → (terminal output or string lines). Shared visual
- * vocabulary across the migrate run:
- *   `→` start  ·  `✓` success  ·  `✗` failure  ·  `↷` skipped  ·  `ℹ` info  ·  `─` boundary
+ * Pure presentation helpers for the migrate run phase (`--run-migrations` and
+ * the single-migration worker). Shared glyph vocabulary:
+ *   `→` start, `✓` success, `✗` failure, `↷` skipped, `ℹ` info, `─` boundary
  *
  * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
- * stays decoupled from `ExecutableMigration` and the executor in migrate.ts.
+ * stays decoupled from the migration executor in migrate.ts.
  */
 /**
  * Some agent TUIs (codex, opencode) don't fully reset their cursor / SGR state
@@ -24,6 +23,22 @@ export declare function logMigrationBoundary(index: number, total: number, pkg:
  *   ✓ <label>[ (<sha>)]: <summary>
  */
 export declare function logAgenticSuccessOutcome(label: string, sha: string | null, summary: string): void;
+/**
+ * Logs the skip line for a migration that waived its AI step through
+ * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
+ * dropped. A hybrid waives its paired prompt; a generator-only migration
+ * waives the validation pass, so callers must reach here only once they know
+ * one was on the table. Under `inside-agent` only a hybrid can, so the
+ * hand-off dropped alongside is always a prompt's; a waived generator-only
+ * migration keeps its own. The note is author-facing, hence `--verbose`.
+ */
+export declare function logWaivedAgenticStep(migration: {
+    package: string;
+    name: string;
+    prompt?: string;
+    implementation?: string;
+    factory?: string;
+}, agentContext: string[]): void;
 /**
  * Per-migration outcome record consumed by the failure recap. One entry is
  * appended per iteration that returned without throwing; the failing migration
@@ -80,6 +95,13 @@ export type CommitState = {
  * means the migration threw before completing — the executor's catch block
  * records it so the recap can list it under retained-state alongside any
  * other migrations whose commits never landed.
+ *
+ * `waivedAgenticStep` is set when the migration returned `skipAgentic: true`
+ * and something was actually waived: a hybrid's prompt, which is owed in every
+ * agentic mode, or a generator-only migration's validation step, only when it
+ * would have run. Recorded here rather than counted in the executor so the
+ * success tally and the failure recap derive the same number from the same
+ * records instead of threading a counter through both.
  */
 export type MigrationOutcome = {
     migration: {
@@ -89,6 +111,7 @@ export type MigrationOutcome = {
     status: 'completed';
     kind: MigrationOutcomeKind;
     commit: CommitState;
+    waivedAgenticStep?: boolean;
 } | {
     migration: {
         package: string;
@@ -106,6 +129,18 @@ export type MigrationOutcome = {
  * counted because the absorbing commit's record already contributes one.
  */
 export declare function countLandedCommits(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * Counts the migrations that waived the AI step they would otherwise have
+ * run. Shared by the success tally and the failure recap so the two can't
+ * report different numbers.
+ */
+export declare function countWaivedAgenticSteps(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * The recap phrase for waived AI steps. "not needed" rather than
+ * "skipped"/"deferred", which both recaps reserve for work the user still
+ * owes.
+ */
+export declare function formatWaivedAgenticSteps(count: number): string;
 /**
  * Migrations whose own commit attempt failed and whose diff was never
  * absorbed by a later commit. Surfaces what the user has to commit or
@@ -144,17 +179,20 @@ export declare function logFailureRecap(opts: {
  * emitting a misleading `0 prompt migrations skipped.` line.
  *
  * Rule (kept coherent across every scenario):
- * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>]`.
+ * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>][, <W> AI steps not needed]`.
  *   The `<K> commits created` part stays even at 0 — it tells the reader work
  *   was applied but not committed (the J4/J8 information made explicit).
  * - When zero migrations were applied but some prompt halves were
- *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only.
+ *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only. Waiving
+ *   never adds to `skippedPromptsCount`, so `appliedCount` is non-zero whenever
+ *   `waivedAgenticStepsCount` is, and this branch can't be reached with one.
  * - When zero of either: no body line.
  */
 export declare function buildTallyBodyLine(opts: {
     appliedCount: number;
     committedShasCount: number;
     skippedPromptsCount: number;
+    waivedAgenticStepsCount: number;
     insideAgent: boolean;
 }): string | null;
 /**

package/dist/src/command-line/migrate/migrate-output.js

@@ -3,7 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetSgrAfterAgent = resetSgrAfterAgent;
 exports.logMigrationBoundary = logMigrationBoundary;
 exports.logAgenticSuccessOutcome = logAgenticSuccessOutcome;
+exports.logWaivedAgenticStep = logWaivedAgenticStep;
 exports.countLandedCommits = countLandedCommits;
+exports.countWaivedAgenticSteps = countWaivedAgenticSteps;
+exports.formatWaivedAgenticSteps = formatWaivedAgenticSteps;
 exports.retainedMigrations = retainedMigrations;
 exports.logFailureRecap = logFailureRecap;
 exports.buildTallyBodyLine = buildTallyBodyLine;
@@ -14,13 +17,12 @@ const pc = tslib_1.__importStar(require("picocolors"));
 const logger_1 = require("../../utils/logger");
 const migration_shape_1 = require("./migration-shape");
 /**
- * Presentation layer for `nx migrate --run-migrations`. Pure helpers — every
- * function maps (state) → (terminal output or string lines). Shared visual
- * vocabulary across the migrate run:
- *   `→` start  ·  `✓` success  ·  `✗` failure  ·  `↷` skipped  ·  `ℹ` info  ·  `─` boundary
+ * Pure presentation helpers for the migrate run phase (`--run-migrations` and
+ * the single-migration worker). Shared glyph vocabulary:
+ *   `→` start, `✓` success, `✗` failure, `↷` skipped, `ℹ` info, `─` boundary
  *
  * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
- * stays decoupled from `ExecutableMigration` and the executor in migrate.ts.
+ * stays decoupled from the migration executor in migrate.ts.
  */
 /**
  * Some agent TUIs (codex, opencode) don't fully reset their cursor / SGR state
@@ -49,6 +51,23 @@ function logAgenticSuccessOutcome(label, sha, summary) {
     const shaPart = sha ? ` (${sha})` : '';
     logger_1.logger.info(`${pc.green('✓')} ${label}${shaPart}: ${summary}`);
 }
+/**
+ * Logs the skip line for a migration that waived its AI step through
+ * `skipAgentic`, plus a verbose note for any `agentContext` the waiver
+ * dropped. A hybrid waives its paired prompt; a generator-only migration
+ * waives the validation pass, so callers must reach here only once they know
+ * one was on the table. Under `inside-agent` only a hybrid can, so the
+ * hand-off dropped alongside is always a prompt's; a waived generator-only
+ * migration keeps its own. The note is author-facing, hence `--verbose`.
+ */
+function logWaivedAgenticStep(migration, agentContext) {
+    logger_1.logger.info(pc.dim((0, migration_shape_1.isHybridMigration)(migration)
+        ? '↷ Prompt phase skipped. The migration reported nothing left for the AI step to do.'
+        : '↷ Validation skipped. The migration reported its changes need no AI review.'));
+    if (agentContext.length === 0)
+        return;
+    logger_1.logger.verbose(`${migration.package}: ${migration.name} returned skipAgentic: true alongside agentContext, which was dropped. agentContext exists to feed the AI step this migration waived.`);
+}
 /**
  * Counts the migrations whose own commit actually landed — including the
  * HEAD-resolve-race case (`commit: { kind: 'landed', sha: null }`). Used by
@@ -60,6 +79,22 @@ function logAgenticSuccessOutcome(label, sha, summary) {
 function countLandedCommits(outcomes) {
     return outcomes.filter((o) => o.commit.kind === 'landed').length;
 }
+/**
+ * Counts the migrations that waived the AI step they would otherwise have
+ * run. Shared by the success tally and the failure recap so the two can't
+ * report different numbers.
+ */
+function countWaivedAgenticSteps(outcomes) {
+    return outcomes.filter((o) => o.status === 'completed' && o.waivedAgenticStep === true).length;
+}
+/**
+ * The recap phrase for waived AI steps. "not needed" rather than
+ * "skipped"/"deferred", which both recaps reserve for work the user still
+ * owes.
+ */
+function formatWaivedAgenticSteps(count) {
+    return `${count} AI step${count === 1 ? '' : 's'} not needed`;
+}
 /**
  * Migrations whose own commit attempt failed and whose diff was never
  * absorbed by a later commit. Surfaces what the user has to commit or
@@ -90,6 +125,7 @@ function logFailureRecap(opts) {
     const appliedCount = outcomes.filter((o) => o.status === 'completed' &&
         (o.kind === 'applied' || o.kind === 'no-changes')).length;
     const deferredCount = outcomes.filter((o) => o.status === 'completed' && o.kind === 'deferred').length;
+    const waivedAgenticCount = countWaivedAgenticSteps(outcomes);
     const notAttempted = totalMigrations - migrationIndex;
     // Walk back to the most recent completed record whose work is anchored to
     // a sha — either its own commit (`landed`), or a later commit that
@@ -146,6 +182,9 @@ function logFailureRecap(opts) {
         if (deferredCount > 0) {
             parts.push(`${deferredCount} deferred`);
         }
+        if (waivedAgenticCount > 0) {
+            parts.push(formatWaivedAgenticSteps(waivedAgenticCount));
+        }
         logger_1.logger.info(`${parts.join(', ')}. ${notAttempted} not attempted.`);
         logger_1.logger.info(`See the per-migration log above for full details.`);
     }
@@ -181,15 +220,17 @@ function logFailureRecap(opts) {
  * emitting a misleading `0 prompt migrations skipped.` line.
  *
  * Rule (kept coherent across every scenario):
- * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>]`.
+ * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>][, <W> AI steps not needed]`.
  *   The `<K> commits created` part stays even at 0 — it tells the reader work
  *   was applied but not committed (the J4/J8 information made explicit).
  * - When zero migrations were applied but some prompt halves were
- *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only.
+ *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only. Waiving
+ *   never adds to `skippedPromptsCount`, so `appliedCount` is non-zero whenever
+ *   `waivedAgenticStepsCount` is, and this branch can't be reached with one.
  * - When zero of either: no body line.
  */
 function buildTallyBodyLine(opts) {
-    const { appliedCount, committedShasCount, skippedPromptsCount, insideAgent } = opts;
+    const { appliedCount, committedShasCount, skippedPromptsCount, waivedAgenticStepsCount, insideAgent, } = opts;
     const skipVerb = insideAgent ? 'deferred' : 'skipped';
     if (appliedCount === 0) {
         if (skippedPromptsCount === 0)
@@ -203,6 +244,9 @@ function buildTallyBodyLine(opts) {
     if (skippedPromptsCount > 0) {
         parts.push(`${skippedPromptsCount} prompt migration${skippedPromptsCount === 1 ? '' : 's'} ${skipVerb}`);
     }
+    if (waivedAgenticStepsCount > 0) {
+        parts.push(formatWaivedAgenticSteps(waivedAgenticStepsCount));
+    }
     return `${parts.join(', ')}.`;
 }
 /**

package/dist/src/command-line/migrate/migrate-ui-api.d.ts

@@ -19,6 +19,7 @@ export type SuccessfulMigration = {
     ref: string;
     nextSteps?: string[];
     acknowledgedPrompt?: boolean;
+    skipAgentic?: boolean;
 };
 export type FailedMigration = {
     type: 'failed';
@@ -41,7 +42,7 @@ export declare function runSingleMigration(workspacePath: string, migration: Mig
 }): Promise<void>;
 export declare function getImplementationPath(workspacePath: string, migration: MigrationDetailsWithId): Promise<string>;
 export declare function modifyMigrationsJsonMetadata(workspacePath: string, modify: (migrationsJsonMetadata: MigrationsJsonMetadata) => MigrationsJsonMetadata): void;
-export declare function addSuccessfulMigration(id: string, fileChanges: Omit<FileChange, 'content'>[], ref: string, nextSteps: string[]): (migrationsJsonMetadata: MigrationsJsonMetadata) => MigrationsJsonMetadata;
+export declare function addSuccessfulMigration(id: string, fileChanges: Omit<FileChange, 'content'>[], ref: string, nextSteps: string[], skipAgentic?: boolean): (migrationsJsonMetadata: MigrationsJsonMetadata) => MigrationsJsonMetadata;
 export declare function updateRefForSuccessfulMigration(id: string, ref: string): (migrationsJsonMetadata: MigrationsJsonMetadata) => MigrationsJsonMetadata;
 export declare function addFailedMigration(id: string, error: string): (migrationsJsonMetadata: MigrationsJsonMetadata) => {
     completedMigrations?: Record<string, SuccessfulMigration | FailedMigration | SkippedMigration | StoppedMigration>;