@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/commands/patch/move-files-adopt.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `patch move-files --scan-file <path>`: adopt new engine files into the
+ * move's destination in the same transaction.
+ *
+ * Splitting a widget across patches moved existing files and adopted the
+ * seam modules that appeared beside them. Adopting first (`re-export
+ * --scan --scan-file`) grew the source past its own `large-patch-lines`
+ * ceiling, which refused although the move that followed would have
+ * shrunk it again. Adopting straight into the destination of the move
+ * means no patch ever carries the intermediate body: both sides are linted
+ * on what the transaction leaves behind.
+ */
+import { join } from 'node:path';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { pathExists } from '../../utils/fs.js';
+import { normalizeEngineRelativeInput } from '../re-export-scan.js';
+/**
+ * Validates `--scan-file` paths: each must be engine-relative, exist in
+ * `engine/`, be owned by no patch and not be one of the moved files.
+ * Returns the sorted, de-duplicated list.
+ *
+ * @param rawFiles - The `--scan-file` values
+ * @param patches - Manifest rows
+ * @param enginePath - Engine directory
+ * @param movedFiles - The `--file` paths of the same move
+ */
+export async function resolveAdoptedFiles(rawFiles, patches, enginePath, movedFiles) {
+    const files = [
+        ...new Set((rawFiles ?? []).map((raw) => normalizeEngineRelativeInput(raw, '--scan-file'))),
+    ].sort();
+    const moved = new Set(movedFiles);
+    for (const file of files) {
+        if (moved.has(file)) {
+            throw new InvalidArgumentError(`${file} is passed with both --file and --scan-file. --file moves a file the source owns; ` +
+                '--scan-file adopts a file no patch owns yet.', '--scan-file');
+        }
+        const owner = patches.find((patch) => patch.filesAffected.includes(file));
+        if (owner !== undefined) {
+            throw new InvalidArgumentError(`--scan-file path is already owned by ${owner.filename}: ${file}. ` +
+                '--scan-file adopts files no patch owns; move an owned file with --file from its owner.', '--scan-file');
+        }
+        if (!(await pathExists(join(enginePath, file)))) {
+            throw new InvalidArgumentError(`--scan-file path not found in engine/: ${file}. --scan-file adopts a file the worktree ` +
+                'already carries, so it needs content to diff.', '--scan-file');
+        }
+    }
+    return files;
+}
+/**
+ * Re-checks under the patch-directory lock that no patch claimed an
+ * adopted file while the move waited for confirmation.
+ *
+ * @param patches - Manifest rows read under the lock
+ * @param adoptedFiles - Files the move adopts
+ * @param command - Command name for the error
+ */
+export function assertAdoptedStillUnowned(patches, adoptedFiles, command) {
+    for (const file of adoptedFiles ?? []) {
+        const owner = patches.find((patch) => patch.filesAffected.includes(file));
+        if (owner !== undefined) {
+            throw new InvalidArgumentError(`Patch queue changed while waiting for confirmation: ${owner.filename} now owns ${file}. Re-run the command.`, command);
+        }
+    }
+}

package/dist/src/commands/patch/move-files-create.js

@@ -24,10 +24,35 @@ import { normalizePatchDisplayName } from '../../utils/validation.js';
 import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { resolvePlacementPlan } from '../export-flow.js';
-import { runPatchLint } from '../export-shared.js';
+import { resolveAdoptedFiles } from './move-files-adopt.js';
+import { runMoveSideLint } from './move-size-tier.js';
 import { commitPatchSplit, reportSplitStagedChanges } from './split.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, projectSplitManifest, runProjectedSplitLint, splitDeclarationRenamer, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, projectSplitManifest, runProjectedSplitLint, splitDeclarationReason, splitDeclarationRenamer, } from './split-plan.js';
 import { emptyStagedMaintenance, findOwnerRewriteHolders } from './split-staged.js';
+/**
+ * Validates `--file` and `--scan-file` for a `--create` move: the source
+ * owns every moved file and keeps at least one, and every adopted file is
+ * new and unowned.
+ */
+async function resolveCreateMoveFiles(source, patches, enginePath, options) {
+    const movedFiles = [...new Set((options.file ?? []).map((f) => f.trim()).filter(Boolean))].sort();
+    if (movedFiles.length === 0) {
+        throw new InvalidArgumentError('Specify at least one --file path to move.', '--file');
+    }
+    assertSourceOwnsFiles(source, movedFiles);
+    const movedSet = new Set(movedFiles);
+    const remainingFiles = source.filesAffected.filter((f) => !movedSet.has(f));
+    if (remainingFiles.length === 0) {
+        throw new InvalidArgumentError(`Moving every file out of ${source.filename} would leave it empty. ` +
+            'Use "fireforge patch rename" / "fireforge patch reorder" to repurpose or move the whole patch instead, ' +
+            'or fold it into an existing patch with "patch move-files <from> <to> --retire-empty".', '--file');
+    }
+    // Adopted files join the new patch with the moved ones: one body, linted
+    // as the transaction leaves it.
+    const adoptedFiles = await resolveAdoptedFiles(options.scanFile, patches, enginePath, movedFiles);
+    const newPatchFiles = [...new Set([...movedFiles, ...adoptedFiles])].sort();
+    return { movedFiles, remainingFiles, adoptedFiles, newPatchFiles };
+}
 /**
  * Runs `patch move-files --create --order <n>`: plans the create+move as a
  * split, lints the projection, confirms, and commits transactionally.
@@ -53,18 +78,8 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         throw new InvalidArgumentError(`--create target "${newPatchName}" already exists as ${existingTarget.filename}. ` +
             'Omit --create to preview a move into the existing patch, or pick a new patch name.', '--create');
     }
-    const movedFiles = [...new Set((options.file ?? []).map((f) => f.trim()).filter(Boolean))].sort();
-    if (movedFiles.length === 0) {
-        throw new InvalidArgumentError('Specify at least one --file path to move.', '--file');
-    }
-    assertSourceOwnsFiles(source, movedFiles);
-    const movedSet = new Set(movedFiles);
-    const remainingFiles = source.filesAffected.filter((f) => !movedSet.has(f));
-    if (remainingFiles.length === 0) {
-        throw new InvalidArgumentError(`Moving every file out of ${source.filename} would leave it empty. ` +
-            'Use "fireforge patch rename" / "fireforge patch reorder" to repurpose or move the whole patch instead.', '--file');
-    }
-    const movedDiff = await buildSplitDiff(paths.engine, movedFiles, 'moved', source.filename);
+    const { movedFiles, remainingFiles, adoptedFiles, newPatchFiles } = await resolveCreateMoveFiles(source, manifest.patches, paths.engine, options);
+    const movedDiff = await buildSplitDiff(paths.engine, newPatchFiles, 'moved', source.filename);
     const remainingDiff = await buildSplitDiff(paths.engine, remainingFiles, 'remaining', source.filename);
     const category = options.category ?? source.category;
     const placementOptions = { order: options.order };
@@ -78,7 +93,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     }
     const plan = {
         source,
-        movedFiles,
+        movedFiles: newPatchFiles,
         remainingFiles,
         movedDiff,
         remainingDiff,
@@ -87,11 +102,13 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         category,
         name: displayName,
         description: options.description ?? '',
-        ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
+        ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, new Set(newPatchFiles)),
         // Populated by runProjectedSplitLint below (forward edges into the new
         // patch, and the declarations the move re-homes or makes unused).
         stagedDependencyAdditions: new Map(),
         stagedMaintenance: emptyStagedMaintenance(),
+        operation: 'patch move-files',
+        ...(adoptedFiles.length > 0 ? { adoptedFiles } : {}),
     };
     // Policy first: the projected manifest (orders, ranges, the gap rule)
     // does not depend on the lint below, so a refused --order fails before
@@ -117,9 +134,11 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     // projection lint is blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = buildLintIgnoreChecks(source.lintIgnore);
-    await runPatchLint({
+    await runMoveSideLint({
         engineDir: paths.engine,
         filesAffected: remainingFiles,
+        filesBefore: source.filesAffected,
+        role: 'source',
         diffContent: remainingDiff,
         config,
         skipLint: options.skipLint,
@@ -127,9 +146,10 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         ignoreChecks,
         patchTier: source.tier,
     });
-    await runPatchLint({
+    await runMoveSideLint({
         engineDir: paths.engine,
-        filesAffected: movedFiles,
+        filesAffected: newPatchFiles,
+        role: 'new patch',
         diffContent: movedDiff,
         config,
         skipLint: options.skipLint,
@@ -145,6 +165,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         regressions: projected.regressions,
         out: options.declarationsOut,
         rename: splitDeclarationRenamer(plan),
+        reason: splitDeclarationReason(plan),
     });
     const newMetadata = buildNewPatchMetadata(plan, config);
     const decision = await confirmDestructive({
@@ -160,7 +181,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         return;
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Created ${placement.newFilename} (order ${formatPatchOrder(placement.insertionOrder)}) ` +
-        `and moved ${plan.movedFiles.length} file(s) out of ${source.filename}`);
+        `and moved ${movedFiles.length} file(s) out of ${source.filename}`);
     reportSplitStagedChanges(plan);
     outro('Move complete');
 }

package/dist/src/commands/patch/move-files-into.d.ts

@@ -12,6 +12,11 @@
  * Preconditions match `re-export`: the engine worktree must currently
  * reflect both patches' content, because both bodies are regenerated from
  * the worktree.
+ *
+ * The same transaction can also adopt new, unowned engine files
+ * into the target (`--scan-file`, see move-files-adopt.ts) and fold the
+ * whole source into the target, retiring its slot (`--retire-empty`, see
+ * move-files-retire.ts).
  */
 import type { PatchMetadata, PatchMoveFilesOptions, PatchStagedForwardImport } from '../../types/commands/index.js';
 import type { FireForgeConfig } from '../../types/config.js';
@@ -28,6 +33,14 @@ export interface MoveIntoPlan {
     ownerRewrites: string[];
     /** Forward-import declarations the move introduces, keyed by importing patch. */
     stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+    /** New engine files no patch owned that the target adopts (`--scan-file`). */
+    adoptedFiles: string[];
+    /**
+     * `--retire-empty`: the move empties the source, so every declaration
+     * owned by the source re-points to the target and the source's slot is
+     * retired. `sourceDiff` is empty then.
+     */
+    retireSource: boolean;
 }
 /**
  * Plans, lints, confirms, and commits a file-ownership move into an
@@ -41,7 +54,12 @@ export declare function runMoveFilesInto(args: {
     target: PatchMetadata;
     files: string[];
     sourceAfter: string[];
+    /** Includes `adoptedFiles`. */
     targetAfter: string[];
+    /** New, unowned engine files the target adopts (`--scan-file`). */
+    adoptedFiles?: string[];
+    /** The move empties the source and retires its slot (`--retire-empty`). */
+    retireSource?: boolean;
     options: PatchMoveFilesOptions;
     config: FireForgeConfig;
 }): Promise<void>;

package/dist/src/commands/patch/move-files-into.js

@@ -13,6 +13,11 @@
  * Preconditions match `re-export`: the engine worktree must currently
  * reflect both patches' content, because both bodies are regenerated from
  * the worktree.
+ *
+ * The same transaction can also adopt new, unowned engine files
+ * into the target (`--scan-file`, see move-files-adopt.ts) and fold the
+ * whole source into the target, retiring its slot (`--retire-empty`, see
+ * move-files-retire.ts).
  */
 import { dirname, join, resolve } from 'node:path';
 import { assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
@@ -22,17 +27,45 @@ import { buildLintIgnoreChecks } from '../../core/patch-lint-ignore.js';
 import { computeProjectedLintRegressions } from '../../core/patch-lint-projection.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
+import { removePatchFileAndManifest } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
-import { readText, writeText } from '../../utils/fs.js';
+import { pathExists, readText, writeText } from '../../utils/fs.js';
 import { info, outro, success, warn } from '../../utils/logger.js';
 import { resolveWaitLockSeconds } from '../../utils/options.js';
 import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
-import { runPatchLint } from '../export-shared.js';
 import { projectEntryBody } from './entry-projection.js';
-import { buildSplitDiff, mergeStagedForwardImports } from './split-plan.js';
+import { assertAdoptedStillUnowned } from './move-files-adopt.js';
+import { foldSourceRows, retiredSlotForFold } from './move-files-retire.js';
+import { runMoveSideLint } from './move-size-tier.js';
+import { buildSplitDiff, mergeStagedForwardImports, moveDeclarationReason } from './split-plan.js';
 import { findOwnerRewriteHolders, rewriteSplitOwners } from './split-staged.js';
+/**
+ * Applies the manifest side of a move to its rows: owner rewrites (every
+ * source-owned declaration on a fold, the moved files' otherwise), the
+ * auto-declared forward imports and both `filesAffected` lists. A folded
+ * source row is left as is for the retire step to remove.
+ */
+function applyMoveToRows(rows, plan) {
+    const movedSet = new Set([...plan.movedFiles, ...plan.adoptedFiles]);
+    const rewritten = plan.retireSource
+        ? foldSourceRows(rows, plan.source.filename, plan.target.filename).patches
+        : rows.map((row) => rewriteSplitOwners(row, plan.source.filename, movedSet, plan.target.filename));
+    return rewritten.map((row) => {
+        let updated = row;
+        const decls = plan.stagedDependencyAdditions.get(updated.filename);
+        if (decls?.length)
+            updated = mergeStagedForwardImports(updated, decls);
+        if (updated.filename === plan.source.filename && !plan.retireSource) {
+            return { ...updated, filesAffected: plan.sourceAfter };
+        }
+        if (updated.filename === plan.target.filename) {
+            return { ...updated, filesAffected: plan.targetAfter };
+        }
+        return updated;
+    });
+}
 /**
  * Projects the post-move queue through cross-patch lint, auto-declaring the
  * forward edges the move introduces into the target (an importer that used
@@ -40,12 +73,16 @@ import { findOwnerRewriteHolders, rewriteSplitOwners } from './split-staged.js';
  * target is later-ordered). Reports only regressions the move itself adds.
  */
 function runProjectedMoveLint(plan, baseCtx) {
-    const movedSet = new Set(plan.movedFiles);
-    const entries = baseCtx.entries.map((entry) => {
-        let metadata = entry.metadata;
-        if (metadata) {
-            metadata = rewriteSplitOwners(metadata, plan.source.filename, movedSet, plan.target.filename);
-        }
+    const movedSet = new Set([...plan.movedFiles, ...plan.adoptedFiles]);
+    const reason = moveDeclarationReason(plan.source.filename, plan.target.filename, 'patch move-files');
+    // The projected rows go through the same rewrite the commit applies, so
+    // the projection and the written manifest cannot disagree.
+    const rows = baseCtx.entries.flatMap((entry) => (entry.metadata ? [entry.metadata] : []));
+    const projectedRows = new Map(applyMoveToRows(rows, { ...plan, stagedDependencyAdditions: new Map() }).map((row) => [row.filename, row]));
+    const entries = baseCtx.entries
+        .filter((entry) => !(plan.retireSource && entry.filename === plan.source.filename))
+        .map((entry) => {
+        const metadata = entry.metadata ? (projectedRows.get(entry.filename) ?? null) : null;
         if (entry.filename === plan.source.filename) {
             return { ...entry, metadata, ...projectEntryBody(plan.sourceDiff) };
         }
@@ -63,6 +100,7 @@ function runProjectedMoveLint(plan, baseCtx) {
             specifier: edge.specifier,
             creates: edge.creates,
             owner: plan.target.filename,
+            reason,
         };
         const list = stagedDependencyAdditions.get(edge.entry) ?? [];
         if (!list.some((d) => d.file === decl.file && d.specifier === decl.specifier && d.creates === decl.creates)) {
@@ -77,10 +115,10 @@ function runProjectedMoveLint(plan, baseCtx) {
         }
     }
     const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({
-        entries,
-        ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
-    }).filter((i) => i.severity === 'error');
+    // Keep every queue-wide lint setting (patch policy, forward-registration
+    // scope, token scales) so the projection checks what the committed gate
+    // checks, test-manifest suite entries included.
+    const projectedIssues = lintPatchQueue({ ...baseCtx, entries }).filter((i) => i.severity === 'error');
     const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
     if (baselineIssues.length > 0 && regressions.length === 0) {
         warn(`Note: projected queue still has ${baselineIssues.length} pre-existing cross-patch ` +
@@ -94,6 +132,15 @@ function runProjectedMoveLint(plan, baseCtx) {
         };
     return { conflicts, regressions, stagedDependencyAdditions };
 }
+/** Restores one body during rollback, warning instead of throwing. */
+async function restoreBody(path, body, label) {
+    try {
+        await writeText(path, body);
+    }
+    catch (rollbackError) {
+        warn(`Rollback warning: could not restore ${label} body: ${toError(rollbackError).message}`);
+    }
+}
 /**
  * Commits a confirmed move under the patch-directory lock: write both
  * rewritten bodies, then one manifest rewrite (filesAffected on both rows +
@@ -113,7 +160,7 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
             currentTarget.filesAffected.join('\n') !== plan.target.filesAffected.join('\n')) {
             throw new InvalidArgumentError('Patch queue changed while waiting for move confirmation. Re-run the command.', 'patch move-files');
         }
-        const movedSet = new Set(plan.movedFiles);
+        assertAdoptedStillUnowned(manifest.patches, plan.adoptedFiles, 'patch move-files');
         const sourcePath = join(patchesDir, plan.source.filename);
         const targetPath = join(patchesDir, plan.target.filename);
         const originalSourceBody = await readText(sourcePath);
@@ -121,25 +168,20 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
         let sourceWritten = false;
         let targetWritten = false;
         try {
-            await writeText(sourcePath, plan.sourceDiff);
-            sourceWritten = true;
+            if (!plan.retireSource) {
+                await writeText(sourcePath, plan.sourceDiff);
+                sourceWritten = true;
+            }
             await writeText(targetPath, plan.targetDiff);
             targetWritten = true;
-            const updatedPatches = manifest.patches.map((patch) => {
-                let updated = rewriteSplitOwners(patch, plan.source.filename, movedSet, plan.target.filename);
-                const decls = plan.stagedDependencyAdditions.get(updated.filename);
-                if (decls?.length)
-                    updated = mergeStagedForwardImports(updated, decls);
-                if (updated.filename === plan.source.filename) {
-                    return { ...updated, filesAffected: plan.sourceAfter };
-                }
-                if (updated.filename === plan.target.filename) {
-                    return { ...updated, filesAffected: plan.targetAfter };
-                }
-                return updated;
-            });
+            const updatedPatches = applyMoveToRows(manifest.patches, plan);
             const updated = validatePatchesManifest({ ...manifest, patches: updatedPatches });
             await savePatchesManifest(patchesDir, updated);
+            if (plan.retireSource) {
+                // Same write `patch retire` makes: the row and the .patch file
+                // leave, and the order stays spent as a retired slot.
+                await removePatchFileAndManifest(patchesDir, plan.source.filename, retiredSlotForFold(plan.source, plan.target.filename));
+            }
             await appendHistoryBestEffort(patchesDir, {
                 operation: 'patch-move-files',
                 args: {
@@ -147,26 +189,19 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
                     target: plan.target.filename,
                     files: plan.movedFiles,
                     ownerRewrites: plan.ownerRewrites,
+                    ...(plan.adoptedFiles.length > 0 ? { adoptedFiles: plan.adoptedFiles } : {}),
+                    ...(plan.retireSource
+                        ? { retiredSource: { filename: plan.source.filename, order: plan.source.order } }
+                        : {}),
                 },
                 result: 'ok',
             }, `patch move-files committed`);
         }
         catch (error) {
-            if (targetWritten) {
-                try {
-                    await writeText(targetPath, originalTargetBody);
-                }
-                catch (rollbackError) {
-                    warn(`Rollback warning: could not restore target body: ${toError(rollbackError).message}`);
-                }
-            }
-            if (sourceWritten) {
-                try {
-                    await writeText(sourcePath, originalSourceBody);
-                }
-                catch (rollbackError) {
-                    warn(`Rollback warning: could not restore source body: ${toError(rollbackError).message}`);
-                }
+            if (targetWritten)
+                await restoreBody(targetPath, originalTargetBody, 'target');
+            if (sourceWritten || !(await pathExists(sourcePath))) {
+                await restoreBody(sourcePath, originalSourceBody, 'source');
             }
             try {
                 await savePatchesManifest(patchesDir, manifest);
@@ -185,28 +220,40 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
  */
 export async function runMoveFilesInto(args) {
     const { enginePath, patchesDir, source, target, files, sourceAfter, targetAfter, options } = args;
+    const adoptedFiles = args.adoptedFiles ?? [];
+    const retireSource = args.retireSource === true;
     // Refuse a prompt-less run before the diff/lint work, not after it.
     assertConfirmationAvailable('patch move-files', options);
-    const sourceDiff = await buildSplitDiff(enginePath, sourceAfter, 'remaining', source.filename);
+    const sourceDiff = retireSource
+        ? ''
+        : await buildSplitDiff(enginePath, sourceAfter, 'remaining', source.filename);
     const targetDiff = await buildSplitDiff(enginePath, targetAfter, 'moved', target.filename);
-    // Per-patch lint both projected bodies with each patch's own waivers.
-    // The whole-queue context (built once, with the config for committed-gate
+    // Per-patch lint both projected bodies with each patch's own waivers,
+    // judged on what the whole transaction leaves (adopted files land in the
+    // target directly, so no patch is judged on an intermediate body). The
+    // whole-queue context (built once, with the config for committed-gate
     // parity) resolves cross-patch imports and sibling head.js harness roots
     // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(patchesDir, args.config);
-    await runPatchLint({
-        engineDir: enginePath,
-        filesAffected: sourceAfter,
-        diffContent: sourceDiff,
-        config: args.config,
-        skipLint: options.skipLint,
-        patchQueueCtx,
-        ignoreChecks: buildLintIgnoreChecks(source.lintIgnore),
-        patchTier: source.tier,
-    });
-    await runPatchLint({
+    if (!retireSource) {
+        await runMoveSideLint({
+            engineDir: enginePath,
+            filesAffected: sourceAfter,
+            filesBefore: source.filesAffected,
+            role: 'source',
+            diffContent: sourceDiff,
+            config: args.config,
+            skipLint: options.skipLint,
+            patchQueueCtx,
+            ignoreChecks: buildLintIgnoreChecks(source.lintIgnore),
+            patchTier: source.tier,
+        });
+    }
+    await runMoveSideLint({
         engineDir: enginePath,
         filesAffected: targetAfter,
+        filesBefore: target.filesAffected,
+        role: 'destination',
         diffContent: targetDiff,
         config: args.config,
         skipLint: options.skipLint,
@@ -223,8 +270,12 @@ export async function runMoveFilesInto(args) {
         targetAfter,
         sourceDiff,
         targetDiff,
-        ownerRewrites: findOwnerRewriteHolders(manifest?.patches ?? [], source.filename, new Set(files)),
+        ownerRewrites: retireSource
+            ? foldSourceRows(manifest?.patches ?? [], source.filename, target.filename).repointed
+            : findOwnerRewriteHolders(manifest?.patches ?? [], source.filename, new Set([...files, ...adoptedFiles])),
         stagedDependencyAdditions: new Map(),
+        adoptedFiles,
+        retireSource,
     };
     const projected = runProjectedMoveLint(plan, patchQueueCtx);
     plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
@@ -232,13 +283,21 @@ export async function runMoveFilesInto(args) {
         projectRoot: dirname(resolve(patchesDir)),
         regressions: projected.regressions,
         out: options.declarationsOut,
+        reason: moveDeclarationReason(source.filename, target.filename, 'patch move-files'),
     });
     const decision = await confirmDestructive({
         operation: 'patch-move-files',
         title: `Move ${files.length} file(s) from ${source.filename} to ${target.filename}`,
         summary: [
             `moved files (${files.length}): ${files.join(', ')}`,
-            `${source.filename} keeps (${sourceAfter.length}): ${sourceAfter.join(', ')}`,
+            ...(adoptedFiles.length > 0
+                ? [
+                    `adopted from the worktree (no patch owned them) (${adoptedFiles.length}): ${adoptedFiles.join(', ')}`,
+                ]
+                : []),
+            retireSource
+                ? `${source.filename} is emptied and retired; order ${source.order} stays spent as a retired slot`
+                : `${source.filename} keeps (${sourceAfter.length}): ${sourceAfter.join(', ')}`,
             `${target.filename} grows to (${targetAfter.length}): ${targetAfter.join(', ')}`,
             ...(plan.ownerRewrites.length > 0
                 ? [`staged-dependency owners re-pointed in: ${plan.ownerRewrites.join(', ')}`]
@@ -253,8 +312,14 @@ export async function runMoveFilesInto(args) {
         return;
     await commitMoveInto(patchesDir, plan, resolveWaitLockSeconds(options.waitLock));
     success(`Moved ${files.length} file(s) from ${source.filename} to ${target.filename}`);
+    if (adoptedFiles.length > 0) {
+        info(`Adopted ${adoptedFiles.length} new file(s) into ${target.filename}`);
+    }
     if (plan.ownerRewrites.length > 0) {
         info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
     }
+    if (retireSource) {
+        info(`Retired ${source.filename}; order ${source.order} is kept as a retired slot.`);
+    }
     outro('Move complete');
 }

package/dist/src/commands/patch/move-files-retire.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `patch move-files --retire-empty`: fold every file of a patch into
+ * another and retire the emptied patch's slot in the same transaction.
+ *
+ * Without the flag `move-files` refuses to empty the source, and
+ * `patch retire` on an emptied patch refuses while another patch's
+ * declaration still names it as the owner. With the flag the move re-points
+ * those declarations to the destination first (after the fold the
+ * destination creates every file the source did), carries the source's own declarations over with its files, and then
+ * retires the source the way `patch retire` does: the row and `.patch` file
+ * leave, and the order stays spent as a `patches.json#retired` slot so
+ * `patchPolicy.allowGaps: false` sees no gap.
+ */
+import type { PatchMetadata, PatchRetiredSlot } from '../../types/commands/index.js';
+/** The rows of a fold, before the source row is retired. */
+export interface FoldedRows {
+    /** Every row: owners re-pointed, the destination carrying the source's declarations. */
+    patches: PatchMetadata[];
+    /** Patches (other than the source) whose declarations named the source as owner. */
+    repointed: string[];
+}
+/**
+ * Re-points every declaration whose owner is `source` to `destination` and
+ * carries the source's own declarations onto the destination. The source
+ * row is returned unchanged; the caller retires it.
+ *
+ * @param patches - Manifest rows
+ * @param source - Filename of the patch the fold empties
+ * @param destination - Filename of the patch that receives its files
+ */
+export declare function foldSourceRows(patches: readonly PatchMetadata[], source: string, destination: string): FoldedRows;
+/**
+ * The retired slot the emptied source leaves, shaped as `patch retire`
+ * writes it.
+ *
+ * @param source - The emptied source row
+ * @param destination - Filename of the patch that took its files
+ */
+export declare function retiredSlotForFold(source: PatchMetadata, destination: string): PatchRetiredSlot;