@hominis/fireforge 0.30.0 → 0.31.0

package/dist/src/commands/patch/compact.js

@@ -3,38 +3,96 @@
  * `fireforge patch compact` — closes ordinal gaps in the patch queue.
  *
  * After deletes or splits, patch ordinals may have gaps (e.g. 1, 3, 7).
- * This command renumbers all patches to sequential ordinals (1, 2, 3, …)
- * in a single atomic operation, preserving relative order.
+ * This command renumbers patches to close those gaps in a single atomic
+ * operation, preserving relative order. Without a patch policy the whole
+ * queue is renumbered from 1; with `patchPolicy.ranges` configured the
+ * compaction is range-aware (each category range compacts independently,
+ * reserved ranges and out-of-range strays are left untouched).
  */
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
+import { requirePatchQueue } from './patch-context.js';
 import { rebuildFilenameForOrder } from './reorder.js';
+/** True when `order` falls inside a configured reserved range. */
+function isReservedOrder(policyCfg, order) {
+    return (policyCfg.reservedRanges ?? []).some((r) => order >= r.from && order <= r.to);
+}
 /**
- * Computes a rename map that assigns sequential ordinals (1, 2, 3, …)
- * to all patches, sorted by their current order.
+ * Computes a rename map that closes ordinal gaps.
+ *
+ * Without a patch policy, all patches are renumbered to 1, 2, 3, … in
+ * current sort order (historical behaviour). With `patchPolicy.ranges`
+ * configured, compaction happens *within* each category range instead:
+ * each range's members are renumbered consecutively starting at the
+ * range's first occupied ordinal, skipping reserved orders — mirroring
+ * what `evaluateGaps` treats as gapless under `allowGaps: false`.
+ * Reserved-range patches and patches outside their category's range are
+ * never moved (a global renumber would project them across range
+ * boundaries and trip `category-range` refusals).
  */
-function computeCompactRenameMap(patches) {
-    const sorted = [...patches].sort((a, b) => a.order - b.order);
+function computeCompactRenameMap(patches, policyCfg) {
+    if (!policyCfg || policyCfg.ranges.length === 0) {
+        const sorted = [...patches].sort((a, b) => a.order - b.order);
+        const renames = new Map();
+        for (const [i, patch] of sorted.entries()) {
+            const newOrder = i + 1;
+            if (patch.order !== newOrder) {
+                renames.set(patch.filename, {
+                    newOrder,
+                    newFilename: rebuildFilenameForOrder(patch, newOrder),
+                });
+            }
+        }
+        return renames;
+    }
     const renames = new Map();
-    for (const [i, patch] of sorted.entries()) {
-        const newOrder = i + 1;
-        if (patch.order !== newOrder) {
-            renames.set(patch.filename, {
-                newOrder,
-                newFilename: rebuildFilenameForOrder(patch, newOrder),
-            });
+    for (const range of policyCfg.ranges) {
+        const members = patches
+            .filter((p) => p.category === range.category &&
+            p.order >= range.from &&
+            p.order <= range.to &&
+            !isReservedOrder(policyCfg, p.order))
+            .sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+        if (members.length === 0)
+            continue;
+        // Anchor at the first occupied ordinal rather than range.from: gap
+        // evaluation only requires contiguity between first and last occupied,
+        // and anchoring minimizes renames.
+        let next = members[0].order;
+        for (const patch of members) {
+            while (isReservedOrder(policyCfg, next))
+                next++;
+            if (patch.order !== next) {
+                renames.set(patch.filename, {
+                    newOrder: next,
+                    newFilename: rebuildFilenameForOrder(patch, next),
+                });
+            }
+            next++;
         }
     }
     return renames;
 }
+/**
+ * Patches a range-aware compact leaves in place because they sit outside
+ * their category's configured range (or outside all ranges) without a
+ * reserved-range exception. They already violate `category-range`; moving
+ * them is a policy decision compact must not make silently.
+ */
+function findCompactStrays(patches, policyCfg) {
+    return patches.filter((p) => {
+        if (isReservedOrder(policyCfg, p.order))
+            return false;
+        return !policyCfg.ranges.some((range) => range.category === p.category && p.order >= range.from && p.order <= range.to);
+    });
+}
 /**
  * Runs the `patch compact` command: renumbers all patches to close ordinal
  * gaps in a single atomic operation.
@@ -44,16 +102,18 @@ function computeCompactRenameMap(patches) {
  */
 export async function patchCompactCommand(projectRoot, options = {}) {
     intro(options.dryRun ? 'FireForge patch compact (dry run)' : 'FireForge patch compact');
-    const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
-    if (!(await pathExists(paths.patches))) {
-        throw new GeneralError('Patches directory not found.');
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('No patches in manifest.');
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const policyCfg = config.patchPolicy;
+    if (policyCfg && policyCfg.ranges.length > 0) {
+        const strays = findCompactStrays(manifest.patches, policyCfg);
+        for (const stray of strays) {
+            warn(`${stray.filename} (order ${stray.order}, category ${stray.category}) sits outside its ` +
+                'configured category range; compact leaves it in place. Use "fireforge patch reorder" ' +
+                'to move it into range first.');
+        }
     }
-    const renameMap = computeCompactRenameMap(manifest.patches);
+    const renameMap = computeCompactRenameMap(manifest.patches, policyCfg);
     if (renameMap.size === 0) {
         info('Patch queue is already compact. Nothing to do.');
         outro('Compact complete (no-op)');
@@ -91,7 +151,7 @@ export async function patchCompactCommand(projectRoot, options = {}) {
         if (!currentManifest) {
             throw new GeneralError('Manifest disappeared while waiting for lock.');
         }
-        const currentRenameMap = computeCompactRenameMap(currentManifest.patches);
+        const currentRenameMap = computeCompactRenameMap(currentManifest.patches, policyCfg);
         if (currentRenameMap.size === 0) {
             info('Patch queue was compacted by another process. Nothing to do.');
             return;
@@ -138,7 +198,7 @@ export function registerPatchCompact(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
     parent
         .command('compact')
-        .description('Close ordinal gaps in the patch queue (renumber sequentially)')
+        .description('Close ordinal gaps in the patch queue (range-aware when patchPolicy.ranges is configured)')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals')

package/dist/src/commands/patch/delete.js

@@ -8,17 +8,14 @@
  * `--dry-run`, and appends to `patches/.fireforge-history.jsonl` on success.
  */
 import { basename } from 'node:path';
-import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
-import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, removePatchFileAndManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
-import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { removePatchFileAndManifest } from '../../core/patch-manifest.js';
 import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Runs the `patch delete` command: removes a patch file and its manifest
  * row atomically, refusing when a later patch imports a leaf owned by the
@@ -30,18 +27,10 @@ import { pickDefined } from '../../utils/options.js';
  */
 export async function patchDeleteCommand(projectRoot, identifier, options = {}) {
     intro(options.dryRun ? 'FireForge patch delete (dry run)' : 'FireForge patch delete');
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.patches))) {
-        throw new GeneralError('Patches directory not found. No patches to delete.');
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('No patches in manifest.');
-    }
-    const target = resolvePatchIdentifier(identifier, manifest.patches);
-    if (!target) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot, {
+        missingDirMessage: 'Patches directory not found. No patches to delete.',
+    });
+    const target = requirePatchTarget(identifier, manifest.patches);
     // Build the full queue context once so we can scan each patch's newFiles
     // without re-parsing for the dependency check below.
     const baseCtx = await buildPatchQueueContext(paths.patches);
@@ -113,6 +102,17 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
                 break;
         }
     }
+    // Staged-dependency declarations on other patches may name the deleted
+    // patch as their forward-import owner. The dangling reference also
+    // surfaces via cross-patch lint later, but warning here puts the exact
+    // cleanup command in front of the operator at decision time.
+    const danglingOwnerHolders = baseCtx.entries.filter((entry) => entry.filename !== target.filename &&
+        (entry.metadata?.stagedDependencies?.forwardImports ?? []).some((fi) => fi.owner === target.filename));
+    for (const holder of danglingOwnerHolders) {
+        warn(`${holder.filename} declares a staged dependency with owner ${target.filename}; ` +
+            `after the delete, update it via "fireforge patch staged-dependency ${holder.filename} --remove ..." ` +
+            'or re-point the owner at the patch that will create the file.');
+    }
     const conflicts = dependents.length > 0
         ? {
             // Wording deliberately clarifies the *runtime* impact: `git apply`

package/dist/src/commands/patch/index.js

@@ -13,6 +13,7 @@ import { registerPatchLintIgnore } from './lint-ignore.js';
 import { registerPatchMoveFiles } from './move-files.js';
 import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
+import { registerPatchSplit } from './split.js';
 import { registerPatchStagedDependency } from './staged-dependency.js';
 import { registerPatchTier } from './tier.js';
 /**
@@ -40,6 +41,7 @@ export function registerPatch(program, context) {
     registerPatchMoveFiles(patch, context);
     registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchSplit(patch, context);
     registerPatchStagedDependency(patch, context);
     registerPatchTier(patch, context);
 }

package/dist/src/commands/patch/lint-ignore.js

@@ -19,15 +19,12 @@
  * write — important when an operator scripts repeated invocations or
  * runs `--add` and `--remove` back-to-back.
  */
-import { getProjectPaths } from '../../core/config.js';
 import { appendHistory } from '../../core/destructive.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
-import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
-import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Computes the post-mutation `lintIgnore` list for a given mode.
  * Returns `undefined` when the result should drop the field from the
@@ -108,18 +105,8 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     }
     const mode = adding ? 'add' : removing ? 'remove' : 'clear';
     const values = mode === 'add' ? (options.add ?? []) : mode === 'remove' ? (options.remove ?? []) : [];
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.patches))) {
-        throw new GeneralError('Patches directory not found.');
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('No patches in manifest.');
-    }
-    const target = resolvePatchIdentifier(identifier, manifest.patches);
-    if (!target) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const target = requirePatchTarget(identifier, manifest.patches);
     if (isDryRun) {
         const existing = target.lintIgnore ?? [];
         const projected = applyMode(existing, mode, values) ?? [];

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

@@ -116,6 +116,8 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     const applyTarget = formatReExportCommand(target.filename, targetAfter, []);
     note(`${dryRunSource}\n${dryRunTarget}`, 'Preview commands');
     note(`${applySource}\n${applyTarget}`, 'Apply commands');
+    info('Tip: to move files into a brand-new patch in one transaction (including ' +
+        'staged-dependency owner rewrites), use "fireforge patch split" instead.');
     outro('Move plan complete - no changes made');
 }
 /**

package/dist/src/commands/patch/patch-context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared preamble for the patch subcommands: every mutation command starts
+ * by loading the project paths and the patches manifest and (for the
+ * single-patch commands) resolving the operator-supplied identifier. The
+ * sequence and its error wording were previously copied into each command;
+ * this module is the single source for both.
+ */
+import type { PatchesManifest, PatchMetadata } from '../../types/commands/index.js';
+import type { ProjectPaths } from '../../types/config.js';
+/** Resolved project paths plus the non-empty patches manifest. */
+export interface PatchQueueContext {
+    /** Project paths resolved from the project root. */
+    paths: ProjectPaths;
+    /** The loaded manifest; guaranteed to contain at least one patch. */
+    manifest: PatchesManifest;
+}
+/**
+ * Loads the project paths and the patches manifest, throwing the shared
+ * command-preamble errors when the patches directory is missing or the
+ * manifest has no patches.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Optional overrides for the preamble error wording
+ * @param options.missingDirMessage - Replacement for the default
+ *   "Patches directory not found." error (e.g. `patch delete` appends
+ *   "No patches to delete.")
+ * @returns The resolved paths and the non-empty manifest
+ */
+export declare function requirePatchQueue(projectRoot: string, options?: {
+    missingDirMessage?: string;
+}): Promise<PatchQueueContext>;
+/**
+ * Resolves an operator-supplied patch identifier (order number, filename,
+ * or unique name fragment) against the manifest, throwing the shared
+ * not-found error with suggestions when no patch matches.
+ *
+ * @param identifier - Identifier as passed on the command line
+ * @param patches - Manifest rows to resolve against
+ * @returns The matching manifest row
+ */
+export declare function requirePatchTarget(identifier: string, patches: PatchMetadata[]): PatchMetadata;

package/dist/src/commands/patch/patch-context.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared preamble for the patch subcommands: every mutation command starts
+ * by loading the project paths and the patches manifest and (for the
+ * single-patch commands) resolving the operator-supplied identifier. The
+ * sequence and its error wording were previously copied into each command;
+ * this module is the single source for both.
+ */
+import { getProjectPaths } from '../../core/config.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { pathExists } from '../../utils/fs.js';
+/**
+ * Loads the project paths and the patches manifest, throwing the shared
+ * command-preamble errors when the patches directory is missing or the
+ * manifest has no patches.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Optional overrides for the preamble error wording
+ * @param options.missingDirMessage - Replacement for the default
+ *   "Patches directory not found." error (e.g. `patch delete` appends
+ *   "No patches to delete.")
+ * @returns The resolved paths and the non-empty manifest
+ */
+export async function requirePatchQueue(projectRoot, options = {}) {
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError(options.missingDirMessage ?? 'Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    return { paths, manifest };
+}
+/**
+ * Resolves an operator-supplied patch identifier (order number, filename,
+ * or unique name fragment) against the manifest, throwing the shared
+ * not-found error with suggestions when no patch matches.
+ *
+ * @param identifier - Identifier as passed on the command line
+ * @param patches - Manifest rows to resolve against
+ * @returns The matching manifest row
+ */
+export function requirePatchTarget(identifier, patches) {
+    const target = resolvePatchIdentifier(identifier, patches);
+    if (!target) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, patches), identifier);
+    }
+    return target;
+}
+//# sourceMappingURL=patch-context.js.map

package/dist/src/commands/patch/rename.js

@@ -18,18 +18,18 @@
  */
 import { rename as fsRename } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { sanitizeName } from '../../core/patch-export.js';
-import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, resolvePatchIdentifier, savePatchesManifest, } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from '../../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Pulls the ordinal-string + category prefix out of a patch filename so
  * the rename keeps the existing ordinal padding verbatim. Returning the
@@ -85,6 +85,11 @@ async function commitRenameUnderLock(input) {
                 name: newName,
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
+            // Staged-dependency owners on other patches reference the old
+            // filename; remap them so forward-import declarations survive the
+            // rename instead of dangling.
+            const ownerLookup = (old) => old === target.filename ? newFilename : undefined;
+            fresh.patches = fresh.patches.map((p) => rewriteStagedDependencyOwners(p, ownerLookup));
         }
         else {
             fresh.patches[idx] = {
@@ -151,19 +156,9 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
     if (options.to === undefined || options.to.trim() === '') {
         throw new InvalidArgumentError('Specify --to <new-name>. The new name is sanitised into the filename slug the same way `export --name` is.', 'patch rename');
     }
-    const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
-    if (!(await pathExists(paths.patches))) {
-        throw new GeneralError('Patches directory not found.');
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('No patches in manifest.');
-    }
-    const target = resolvePatchIdentifier(identifier, manifest.patches);
-    if (!target) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const target = requirePatchTarget(identifier, manifest.patches);
     const split = splitPatchFilename(target.filename);
     if (!split) {
         throw new GeneralError(`Cannot rename ${target.filename}: filename does not match the expected {ordinal}-{category}-{slug}.patch convention. Re-export the patch instead.`);

package/dist/src/commands/patch/reorder.d.ts

@@ -10,8 +10,6 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 import type { PatchMetadata, PatchReorderOptions } from '../../types/commands/index.js';
-/** Zero-pads an ordinal number to the given width. */
-export declare function padOrder(value: number, width: number): string;
 /** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
 export declare function rebuildFilenameForOrder(existing: PatchMetadata, newOrder: number): string;
 /**

package/dist/src/commands/patch/reorder.js

@@ -9,21 +9,20 @@
  * before any bytes move.
  */
 import { Option } from 'commander';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive, } from '../../core/destructive.js';
-import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, rewriteStagedDependencyOwners, } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /** Zero-pads an ordinal number to the given width. */
-export function padOrder(value, width) {
+function padOrder(value, width) {
     return String(value).padStart(width, '0');
 }
 /** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
@@ -123,12 +122,22 @@ function renameMapsEqual(left, right) {
  * can run against the projected state without touching disk.
  */
 function projectReorder(base, renameMap) {
+    const ownerLookup = (oldFilename) => renameMap.get(oldFilename)?.newFilename;
     const projectedEntries = base.entries.map((entry) => {
+        // Project staged-dependency owner references through the rename map on
+        // every entry — owners point at *other* patches' filenames, so a
+        // projection that skips non-renamed entries would lint against stale
+        // owners and report false forward-import regressions.
+        const metadata = entry.metadata
+            ? rewriteStagedDependencyOwners(entry.metadata, ownerLookup)
+            : entry.metadata;
         const rename = renameMap.get(entry.filename);
-        if (!rename)
-            return entry;
+        if (!rename) {
+            return metadata === entry.metadata ? entry : { ...entry, metadata };
+        }
         return {
             ...entry,
+            metadata,
             filename: rename.newFilename,
             order: rename.newOrder,
         };
@@ -268,19 +277,9 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
     if (specifiedTargets > 1) {
         throw new InvalidArgumentError('--to, --before, and --after are mutually exclusive.', 'patch reorder');
     }
-    const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
-    if (!(await pathExists(paths.patches))) {
-        throw new GeneralError('Patches directory not found.');
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('No patches in manifest.');
-    }
-    const target = resolvePatchIdentifier(identifier, manifest.patches);
-    if (!target) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const target = requirePatchTarget(identifier, manifest.patches);
     const { destinationOrder, anchorFilename } = resolveDestination(target, manifest.patches, options);
     const renameMap = computeRenameMap(manifest.patches, target, destinationOrder);
     if (renameMap.size === 0) {

package/dist/src/commands/patch/split-plan.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Planning helpers for `fireforge patch split`: ownership guards, diff
+ * construction from the worktree, staged-dependency owner-rewrite
+ * discovery, cross-patch lint projection, and policy-manifest projection.
+ * Split out of `split.ts` to keep both files within the per-file line
+ * budget; consumed only by the split command.
+ */
+import { type ConflictReport } from '../../core/destructive.js';
+import { buildProjectedManifest } from '../../core/patch-policy.js';
+import type { PatchCategory, PatchMetadata } from '../../types/commands/index.js';
+import type { FireForgeConfig } from '../../types/config.js';
+import { type PlacementPlan } from '../export-flow.js';
+/** Everything the commit step needs, computed and confirmed up front. */
+export interface SplitPlan {
+    source: PatchMetadata;
+    movedFiles: string[];
+    remainingFiles: string[];
+    movedDiff: string;
+    remainingDiff: string;
+    placement: PlacementPlan;
+    /** Effective placement flags (with the after-source default applied). */
+    placementOptions: {
+        order?: number;
+        before?: string;
+        after?: string;
+    };
+    category: PatchCategory;
+    name: string;
+    description: string;
+    /** Patches (by current filename) whose staged-dependency owners re-point to the new patch. */
+    ownerRewrites: string[];
+}
+/**
+ *
+ */
+export declare function assertSourceOwnsFiles(source: PatchMetadata, files: readonly string[]): void;
+/**
+ *
+ */
+export declare function buildSplitDiff(engineDir: string, files: readonly string[], label: string, sourceFilename: string): Promise<string>;
+/**
+ * Finds patches declaring a staged-dependency forward-import whose `owner`
+ * is the source patch and whose `creates` path moves to the new patch.
+ */
+export declare function findOwnerRewriteHolders(patches: readonly PatchMetadata[], sourceFilename: string, movedSet: ReadonlySet<string>): string[];
+/** Rewrites split-affected owners on one manifest row. */
+export declare function rewriteSplitOwners(patch: PatchMetadata, sourceFilename: string, movedSet: ReadonlySet<string>, newFilename: string): PatchMetadata;
+/**
+ * Projects the full split (renumber + shrunken source + synthetic new
+ * patch + owner rewrites) through cross-patch lint, reporting only the
+ * regressions the split itself would introduce.
+ */
+export declare function runProjectedSplitLint(patchesDir: string, plan: SplitPlan): Promise<ConflictReport | null>;
+/** Builds the projected manifest for policy enforcement. */
+export declare function projectSplitManifest(manifest: {
+    version: 1;
+    patches: PatchMetadata[];
+}, plan: SplitPlan, newMetadata: PatchMetadata): ReturnType<typeof buildProjectedManifest>;
+/**
+ *
+ */
+export declare function buildNewPatchMetadata(plan: SplitPlan, config: FireForgeConfig): PatchMetadata;
+/**
+ *
+ */
+export declare function buildSplitSummary(plan: SplitPlan): string[];