@hominis/fireforge 0.40.0 → 0.41.0

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

@@ -22,15 +22,17 @@ import { Command } from 'commander';
 import { loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { patchNameSlug } from '../../core/patch-export.js';
+import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from '../../core/patch-manifest.js';
-import { buildProjectedManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
+import { buildProjectedManifest, enforcePatchPolicy, getPatchPolicyCategories, isCategoryAllowedByConfig, } 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 { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { projectReorder } from './reorder.js';
 /**
  * Pulls the ordinal-string + category prefix out of a patch filename so
  * the rename keeps the existing ordinal padding verbatim. Returning the
@@ -54,7 +56,11 @@ function splitPatchFilename(filename) {
  * rolls the filesystem rename back.
  */
 async function commitRenameUnderLock(input) {
-    const { patchesDir, target, newFilename, newName, newDescription, filenameChanging, nameChanging, descriptionChanging, } = input;
+    const { patchesDir, target, newFilename, newName, newDescription, filenameChanging, nameChanging, descriptionChanging, orderChanging, categoryChanging, } = input;
+    const identityUpdates = {
+        ...(orderChanging && input.newOrder !== undefined ? { order: input.newOrder } : {}),
+        ...(categoryChanging && input.newCategory !== undefined ? { category: input.newCategory } : {}),
+    };
     await withPatchDirectoryLock(patchesDir, async () => {
         const fresh = await loadPatchesManifest(patchesDir);
         if (!fresh) {
@@ -68,6 +74,12 @@ async function commitRenameUnderLock(input) {
         if (!before) {
             throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename.`);
         }
+        if (orderChanging && input.newOrder !== undefined) {
+            const orderHolder = fresh.patches.find((p) => p.order === input.newOrder && p.filename !== target.filename);
+            if (orderHolder) {
+                throw new InvalidArgumentError(`Order ${String(input.newOrder)} was claimed by ${orderHolder.filename} concurrently. Pick an unused order, or use "fireforge patch reorder" to renumber siblings.`, '--order');
+            }
+        }
         let oldPath;
         let newPath;
         if (filenameChanging) {
@@ -84,6 +96,7 @@ async function commitRenameUnderLock(input) {
                 ...before,
                 filename: newFilename,
                 name: newName,
+                ...identityUpdates,
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
             // Staged-dependency owners on other patches reference the old
@@ -95,6 +108,7 @@ async function commitRenameUnderLock(input) {
         else {
             fresh.patches[idx] = {
                 ...before,
+                ...identityUpdates,
                 ...(nameChanging ? { name: newName } : {}),
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
@@ -132,6 +146,10 @@ async function commitRenameUnderLock(input) {
                     oldName: target.name,
                     newName,
                     ...(descriptionChanging ? { oldDescription: target.description, newDescription } : {}),
+                    ...(orderChanging ? { oldOrder: target.order, newOrder: input.newOrder } : {}),
+                    ...(categoryChanging
+                        ? { oldCategory: target.category, newCategory: input.newCategory }
+                        : {}),
                 },
                 ...(input.yes === true ? { yes: true } : {}),
                 ...(input.forceUnsafe === true ? { unsafeOverride: true } : {}),
@@ -141,66 +159,134 @@ async function commitRenameUnderLock(input) {
         catch (historyError) {
             warn(`History log append failed after patch rename committed (${newFilename}): ${toError(historyError).message}`);
         }
-    });
+    }, { waitLockSeconds: input.waitLockSeconds, command: 'patch rename' });
 }
-/**
- * Runs the `patch rename` command: relabels filename + manifest entry
- * for a single patch atomically.
- *
- * @param projectRoot - Project root directory
- * @param identifier - Patch filename, ordinal, or manifest `name`
- * @param options - Command options (`--to <new-name>` is required)
- */
-export async function patchRenameCommand(projectRoot, identifier, options = {}) {
-    const isDryRun = options.dryRun === true;
-    intro(isDryRun ? 'FireForge patch rename (dry run)' : 'FireForge patch rename');
-    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');
+/** Validates the flags and resolves the new filename/identity fields. */
+function resolveRenamePlan(target, options, config) {
+    const hasTo = options.to !== undefined && options.to.trim() !== '';
+    if (!hasTo &&
+        options.category === undefined &&
+        options.order === undefined &&
+        options.description === undefined) {
+        throw new InvalidArgumentError('Specify at least one of --to <new-name>, --category <category>, --order <n>, or --description. --to is sanitised into the filename slug the same way `export --name` is.', 'patch rename');
     }
-    const config = await loadConfig(projectRoot);
-    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.`);
     }
-    const newSlug = patchNameSlug(options.to, split.category);
+    const newCategory = options.category ?? split.category;
+    if (options.category !== undefined && !isCategoryAllowedByConfig(config, options.category)) {
+        throw new InvalidArgumentError(`Invalid category. Must be one of: ${getPatchPolicyCategories(config).join(', ')}`, '--category');
+    }
+    // Keep the existing slug verbatim when --to is absent: re-running
+    // `patchNameSlug` against a different category could strip a
+    // category-looking prefix out of an established slug.
+    const newSlug = hasTo && options.to !== undefined ? patchNameSlug(options.to, newCategory) : split.slug;
     if (newSlug === '') {
         throw new InvalidArgumentError('--to must contain at least one alphanumeric character after sanitisation.', 'patch rename');
     }
-    const newFilename = `${split.ordinalStr}-${split.category}-${newSlug}.patch`;
-    const filenameChanging = newFilename !== target.filename;
-    const nameChanging = options.to !== target.name;
-    const descriptionChanging = options.description !== undefined && options.description !== target.description;
-    if (!filenameChanging && !nameChanging && !descriptionChanging) {
-        info(`${target.filename}: nothing to change — filename already "${target.filename}" ` +
-            `(slug of "${options.to}" is "${newSlug}"), name already "${target.name}"` +
-            (options.description !== undefined ? ', description already matches' : '') +
-            '.');
-        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
-        return;
+    // Preserve the ordinal's zero-padding width; a wider order simply
+    // prints unpadded-longer.
+    const newOrdinalStr = options.order !== undefined
+        ? String(options.order).padStart(split.ordinalStr.length, '0')
+        : split.ordinalStr;
+    const newFilename = `${newOrdinalStr}-${newCategory}-${newSlug}.patch`;
+    return {
+        hasTo,
+        newCategory,
+        newSlug,
+        newFilename,
+        filenameChanging: newFilename !== target.filename,
+        nameChanging: hasTo && options.to !== target.name,
+        descriptionChanging: options.description !== undefined && options.description !== target.description,
+        orderChanging: options.order !== undefined && options.order !== target.order,
+        categoryChanging: options.category !== undefined &&
+            (options.category !== target.category || options.category !== split.category),
+    };
+}
+/**
+ * Pre-flight refusals: order collision (with a pointer to the verb that
+ * renumbers siblings — `--order` means "this exact unused sparse slot",
+ * mirroring `export --order`), projected cross-patch lint on an order
+ * change (forward imports resolve by queue position, FORGE J10), and the
+ * filename collision. The authoritative collision checks run again inside
+ * the lock to close the TOCTOU window.
+ */
+async function assertRenamePreconditions(patchesDir, manifest, target, plan, options, config) {
+    if (plan.orderChanging && options.order !== undefined) {
+        const holder = manifest.patches.find((p) => p.order === options.order && p.filename !== target.filename);
+        if (holder) {
+            throw new InvalidArgumentError(`Order ${String(options.order)} is already used by ${holder.filename}. Pick an unused order, or use "fireforge patch reorder ${target.filename} --to ${String(options.order)}" to renumber siblings.`, '--order');
+        }
+        if (options.forceUnsafe !== true) {
+            const baseCtx = await buildPatchQueueContext(patchesDir, config);
+            const projected = projectReorder(baseCtx, new Map([[target.filename, { newFilename: plan.newFilename, newOrder: options.order }]]));
+            const projectedErrors = lintPatchQueue(projected).filter((i) => i.severity === 'error');
+            if (projectedErrors.length > 0) {
+                throw new InvalidArgumentError(`Refusing to run patch rename: the order change would introduce ${String(projectedErrors.length)} cross-patch lint error(s):\n  ${projectedErrors
+                    .map(formatPatchLintIssue)
+                    .join('\n  ')}\nPass --force-unsafe to override.`, '--force-unsafe');
+            }
+        }
     }
-    // Pre-flight collision check against the manifest snapshot we already
-    // loaded. The authoritative check happens again inside the lock to
-    // close the TOCTOU window — surface a helpful error here when the
-    // collision is obvious so the operator does not get surprised by a
-    // late refusal after a confirmation prompt.
-    if (filenameChanging) {
-        const collision = manifest.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+    if (plan.filenameChanging) {
+        const collision = manifest.patches.find((p) => p.filename === plan.newFilename && p.filename !== target.filename);
         if (collision) {
-            throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch already uses that filename.`, 'patch rename');
+            throw new InvalidArgumentError(`Cannot rename to "${plan.newFilename}" — a different patch already uses that filename.`, 'patch rename');
         }
     }
+}
+/** Change-summary lines shown by the confirmation prompt. */
+function buildRenameSummary(target, plan, options) {
     const summary = [];
-    if (filenameChanging) {
-        summary.push(`rename ${target.filename} → ${newFilename}`);
+    if (plan.filenameChanging) {
+        summary.push(`rename ${target.filename} → ${plan.newFilename}`);
     }
-    if (nameChanging) {
+    if (plan.nameChanging) {
         summary.push(`name: "${target.name}" → "${options.to}"`);
     }
-    if (descriptionChanging) {
+    if (plan.descriptionChanging) {
         summary.push(`description: "${target.description || '(none)'}" → "${options.description ?? '(none)'}"`);
     }
+    if (plan.orderChanging && options.order !== undefined) {
+        summary.push(`order: ${String(target.order)} → ${String(options.order)}`);
+    }
+    if (plan.categoryChanging) {
+        summary.push(`category: ${target.category} → ${plan.newCategory}`);
+    }
+    return summary;
+}
+/**
+ * Runs the `patch rename` command: relabels filename + manifest entry
+ * (name, category, order, description) for a single patch atomically.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (at least one change flag required)
+ */
+export async function patchRenameCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch rename (dry run)' : 'FireForge patch rename');
+    const config = await loadConfig(projectRoot);
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const target = requirePatchTarget(identifier, manifest.patches);
+    const plan = resolveRenamePlan(target, options, config);
+    const { hasTo, newCategory, newSlug, newFilename, filenameChanging, nameChanging, descriptionChanging, orderChanging, categoryChanging, } = plan;
+    if (!filenameChanging &&
+        !nameChanging &&
+        !descriptionChanging &&
+        !orderChanging &&
+        !categoryChanging) {
+        info(`${target.filename}: nothing to change — filename already "${target.filename}"` +
+            (hasTo && options.to !== undefined ? ` (slug of "${options.to}" is "${newSlug}")` : '') +
+            `, name already "${target.name}"` +
+            (options.description !== undefined ? ', description already matches' : '') +
+            '.');
+        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
+        return;
+    }
+    await assertRenamePreconditions(paths.patches, manifest, target, plan, options, config);
+    const summary = buildRenameSummary(target, plan, options);
     enforcePatchPolicy({
         config,
         manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === target.filename
@@ -208,6 +294,8 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
                 ...entry,
                 filename: newFilename,
                 name: nameChanging ? (options.to ?? entry.name) : entry.name,
+                ...(orderChanging && options.order !== undefined ? { order: options.order } : {}),
+                ...(categoryChanging ? { category: newCategory } : {}),
                 ...(descriptionChanging ? { description: options.description ?? '' } : {}),
             }
             : entry)),
@@ -234,14 +322,19 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
         patchesDir: paths.patches,
         target,
         newFilename,
-        newName: options.to,
+        newName: hasTo && options.to !== undefined ? options.to : target.name,
         ...(options.description !== undefined ? { newDescription: options.description } : {}),
+        ...(orderChanging && options.order !== undefined ? { newOrder: options.order } : {}),
+        ...(categoryChanging ? { newCategory } : {}),
         filenameChanging,
         nameChanging,
         descriptionChanging,
+        orderChanging,
+        categoryChanging,
         ...(options.yes === true ? { yes: true } : {}),
         ...(options.forceUnsafe === true ? { forceUnsafe: true } : {}),
         config,
+        waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
     });
     if (filenameChanging) {
         info(`${target.filename} → ${newFilename}`);
@@ -259,15 +352,23 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
  */
 export function registerPatchRename(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    parent
+    const command = parent
         .command('rename <name>')
-        .description('Rename a patch: filename + manifest name (and optional description) update without rewriting the .patch body.')
-        .requiredOption('--to <new-name>', 'New human-readable name, category-prefixed slug, or full filename stem (normalised into the filename slug)')
+        .description('Rename a patch: filename, manifest name, category, order, and/or description update in one transaction without rewriting the .patch body.')
+        .option('--to <new-name>', 'New human-readable name, category-prefixed slug, or full filename stem (normalised into the filename slug)')
+        .option('--category <category>', 'New category for the patch (validated against configured categories); rewrites the filename prefix and manifest row in one transaction')
+        .option('--order <n>', 'Move the patch to this exact unused order; refuses on collision — use "patch reorder" to renumber siblings', commanderArgParser((raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new InvalidArgumentError(`--order must be a positive integer, got "${raw}".`, '--order');
+        }
+        return n;
+    }))
         .option('-d, --description <text>', 'Replacement description (omit to leave description unchanged)')
         .option('--dry-run', 'Show what would change without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
-        .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals')
-        .action(withErrorHandling(async (name, options) => {
+        .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals');
+    addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
         await patchRenameCommand(getProjectRoot(), name, pickDefined(options));
     }));
 }

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

@@ -8,10 +8,19 @@
  * before any bytes move.
  */
 import { Command } from 'commander';
+import { type PatchQueueContext } from '../../core/patch-lint.js';
+import { type PatchRenameEntry } from '../../core/patch-manifest.js';
 import type { CommandContext } from '../../types/cli.js';
 import type { PatchMetadata, PatchReorderOptions } from '../../types/commands/index.js';
 /** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
 export declare function rebuildFilenameForOrder(existing: PatchMetadata, newOrder: number): string;
+/**
+ * Applies a rename map to a {@link PatchQueueContext} so cross-patch lint
+ * can run against the projected state without touching disk. Exported for
+ * `patch rename --order`, which projects the same single-row move shape
+ * (FORGE J10).
+ */
+export declare function projectReorder(base: PatchQueueContext, renameMap: Map<string, PatchRenameEntry>): PatchQueueContext;
 /**
  * Runs the `patch reorder` command: computes a rename map moving the
  * target patch to the requested slot, projects the new order through

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

@@ -11,14 +11,14 @@
 import { Command, Option } from 'commander';
 import { loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive, } from '../../core/destructive.js';
-import { buildPatchQueueContext, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.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 { info, intro, outro, warn } from '../../utils/logger.js';
-import { commanderArgParser, pickDefined } from '../../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } 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. */
@@ -119,9 +119,11 @@ function renameMapsEqual(left, right) {
 }
 /**
  * Applies a rename map to a {@link PatchQueueContext} so cross-patch lint
- * can run against the projected state without touching disk.
+ * can run against the projected state without touching disk. Exported for
+ * `patch rename --order`, which projects the same single-row move shape
+ * (FORGE J10).
  */
-function projectReorder(base, renameMap) {
+export 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
@@ -235,7 +237,9 @@ async function commitReorderPlan(patchesDir, target, renameMap, anchorFilename,
         const currentProjected = projectReorder(await buildPatchQueueContext(patchesDir), currentRenameMap);
         const currentConflicts = lintPatchQueue(currentProjected).filter((i) => i.severity === 'error');
         if (currentConflicts.length > 0 && options.forceUnsafe !== true) {
-            throw new InvalidArgumentError(`Refusing to run patch reorder: reorder would introduce ${currentConflicts.length} cross-patch lint error(s). Pass --force-unsafe to override.`, '--force-unsafe');
+            throw new InvalidArgumentError(`Refusing to run patch reorder: reorder would introduce ${currentConflicts.length} cross-patch lint error(s):\n  ${currentConflicts
+                .map(formatPatchLintIssue)
+                .join('\n  ')}\nPass --force-unsafe to override.`, '--force-unsafe');
         }
         await renumberPatchesInManifest(patchesDir, currentRenameMap);
         // Append the history record inside the lock so two concurrent
@@ -252,7 +256,7 @@ async function commitReorderPlan(patchesDir, target, renameMap, anchorFilename,
         catch (historyError) {
             warn(`History log append failed after patch reorder committed: ${toError(historyError).message}`);
         }
-    });
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch reorder' });
 }
 /**
  * Runs the `patch reorder` command: computes a rename map moving the
@@ -302,7 +306,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
     const conflicts = errorIssues.length > 0
         ? {
             reason: `reorder would introduce ${errorIssues.length} cross-patch lint error(s)`,
-            details: errorIssues.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+            details: errorIssues.map(formatPatchLintIssue),
         }
         : null;
     const renameEntries = getSortedRenameEntries(renameMap);
@@ -369,7 +373,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
  */
 export function registerPatchReorder(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    parent
+    const command = parent
         .command('reorder <name>')
         .description('Move a patch to a different position in the queue (destructive)')
         .addOption(new Option('--to <order>', 'Destination ordinal').argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--to', v))))
@@ -377,8 +381,8 @@ export function registerPatchReorder(parent, context) {
         .option('--after <anchor>', 'Place the patch immediately after <anchor>')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
-        .option('--force-unsafe', 'Bypass the refusal when the projected order introduces a lint error')
-        .action(withErrorHandling(async (name, options) => {
+        .option('--force-unsafe', 'Bypass the refusal when the projected order introduces a lint error');
+    addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
         await patchReorderCommand(getProjectRoot(), name, pickDefined(options));
     }));
 }

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

@@ -6,6 +6,7 @@
  * budget; consumed only by the split command.
  */
 import { type ConflictReport } from '../../core/destructive.js';
+import { buildPatchQueueContext } from '../../core/patch-lint.js';
 import { buildProjectedManifest } from '../../core/patch-policy.js';
 import type { PatchStagedForwardImport } from '../../types/commands/index.js';
 import type { PatchCategory, PatchMetadata } from '../../types/commands/index.js';
@@ -40,11 +41,15 @@ export interface SplitPlan {
     stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
 }
 /**
- *
+ * Refuses the split unless the source patch currently owns every requested
+ * file. Splitting out a file the source does not own would produce a new patch
+ * whose diff cannot apply.
  */
 export declare function assertSourceOwnsFiles(source: PatchMetadata, files: readonly string[]): void;
 /**
- *
+ * Generates the diff for one side of a split by re-deriving it from the engine
+ * working tree, scoped to `files`. Re-derived rather than sliced out of the
+ * source patch so hunk context is correct for the new file set.
  */
 export declare function buildSplitDiff(engineDir: string, files: readonly string[], label: string, sourceFilename: string): Promise<string>;
 /**
@@ -63,20 +68,22 @@ export declare function mergeStagedForwardImports(patch: PatchMetadata, decls: r
  * patch are auto-declared (and the declarations returned) so the projection
  * matches the real per-patch gate the split leaves behind.
  */
-export declare function runProjectedSplitLint(patchesDir: string, plan: SplitPlan): Promise<{
+export declare function runProjectedSplitLint(plan: SplitPlan, baseCtx: Awaited<ReturnType<typeof buildPatchQueueContext>>): {
     conflicts: ConflictReport | null;
     stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
-}>;
+};
 /** Builds the projected manifest for policy enforcement. */
 export declare function projectSplitManifest(manifest: {
     version: 1;
     patches: PatchMetadata[];
 }, plan: SplitPlan, newMetadata: PatchMetadata): ReturnType<typeof buildProjectedManifest>;
 /**
- *
+ * Builds the manifest row for the patch created by a split, carrying the
+ * source's provenance (product, version, category) onto the new patch.
  */
 export declare function buildNewPatchMetadata(plan: SplitPlan, config: FireForgeConfig): PatchMetadata;
 /**
- *
+ * Renders the operator-facing summary lines for a planned split — the text
+ * shown by `--dry-run` and by the destructive-operation confirmation prompt.
  */
 export declare function buildSplitSummary(plan: SplitPlan): string[];

package/dist/src/commands/patch/split-plan.js

@@ -11,7 +11,7 @@ import {} from '../../core/destructive.js';
 import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
 import { computeProjectedLintRegressions } from '../../core/lint-projection.js';
 import { extractAffectedFiles } from '../../core/patch-apply.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest } from '../../core/patch-policy.js';
 import { buildPatchSourceMetadata } from '../../core/patch-source-metadata.js';
@@ -21,7 +21,9 @@ import { pathExists } from '../../utils/fs.js';
 import { warn } from '../../utils/logger.js';
 import {} from '../export-flow.js';
 /**
- *
+ * Refuses the split unless the source patch currently owns every requested
+ * file. Splitting out a file the source does not own would produce a new patch
+ * whose diff cannot apply.
  */
 export function assertSourceOwnsFiles(source, files) {
     const owned = new Set(source.filesAffected);
@@ -32,7 +34,9 @@ export function assertSourceOwnsFiles(source, files) {
     }
 }
 /**
- *
+ * Generates the diff for one side of a split by re-deriving it from the engine
+ * working tree, scoped to `files`. Re-derived rather than sliced out of the
+ * source patch so hunk context is correct for the new file set.
  */
 export async function buildSplitDiff(engineDir, files, label, sourceFilename) {
     for (const file of files) {
@@ -85,10 +89,9 @@ function buildEntryProjection(diff) {
     return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
 }
 /** Builds the projected post-split queue entries (renumber + shrunken source + new patch). */
-async function buildProjectedSplitEntries(patchesDir, plan) {
+function buildProjectedSplitEntries(baseCtx, plan) {
     const movedSet = new Set(plan.movedFiles);
     const ownerLookup = (old) => plan.placement.renameMap.get(old)?.newFilename;
-    const baseCtx = await buildPatchQueueContext(patchesDir);
     const entries = baseCtx.entries.map((entry) => {
         let metadata = entry.metadata;
         if (metadata) {
@@ -110,7 +113,7 @@ async function buildProjectedSplitEntries(patchesDir, plan) {
         ...buildEntryProjection(plan.movedDiff),
     });
     entries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    return { baseCtx, entries };
+    return entries;
 }
 /**
  * Computes the staged forward-import declarations the split introduces:
@@ -181,14 +184,19 @@ function injectStagedDependencyAdditions(entries, additions) {
  * patch are auto-declared (and the declarations returned) so the projection
  * matches the real per-patch gate the split leaves behind.
  */
-export async function runProjectedSplitLint(patchesDir, plan) {
-    const { baseCtx, entries: projectedEntries } = await buildProjectedSplitEntries(patchesDir, plan);
+export function runProjectedSplitLint(plan, baseCtx) {
+    const projectedEntries = buildProjectedSplitEntries(baseCtx, plan);
     // Discover and auto-declare the forward edges this split introduces into
     // the new patch, then inject them before linting so they resolve.
     const stagedDependencyAdditions = computeSplitStagedDependencyAdditions(projectedEntries, plan.placement.newFilename);
     injectStagedDependencyAdditions(projectedEntries, stagedDependencyAdditions);
     const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({
+        entries: projectedEntries,
+        // Keep the projection patch-policy-aware whenever the baseline is, so
+        // computeProjectedLintRegressions compares symmetric rule sets.
+        ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
+    }).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 ` +
@@ -198,7 +206,7 @@ export async function runProjectedSplitLint(patchesDir, plan) {
         ? null
         : {
             reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
-            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+            details: regressions.map(formatPatchLintIssue),
         };
     return { conflicts, stagedDependencyAdditions };
 }
@@ -216,7 +224,8 @@ export function projectSplitManifest(manifest, plan, newMetadata) {
     return buildProjectedManifest(renamed, [...patched, newMetadata]);
 }
 /**
- *
+ * Builds the manifest row for the patch created by a split, carrying the
+ * source's provenance (product, version, category) onto the new patch.
  */
 export function buildNewPatchMetadata(plan, config) {
     return {
@@ -231,7 +240,8 @@ export function buildNewPatchMetadata(plan, config) {
     };
 }
 /**
- *
+ * Renders the operator-facing summary lines for a planned split — the text
+ * shown by `--dry-run` and by the destructive-operation confirmation prompt.
  */
 export function buildSplitSummary(plan) {
     const summary = [

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

@@ -28,7 +28,7 @@ import { type SplitPlan } from './split-plan.js';
  * failure the steps are rolled back in reverse order. Exported for
  * `patch move-files --create`, which commits the same transaction shape.
  */
-export declare function commitPatchSplit(patchesDir: string, plan: SplitPlan, newMetadata: PatchMetadata, options: Pick<PatchSplitOptions, 'yes' | 'forceUnsafe'>, config: FireForgeConfig): Promise<void>;
+export declare function commitPatchSplit(patchesDir: string, plan: SplitPlan, newMetadata: PatchMetadata, options: Pick<PatchSplitOptions, 'yes' | 'forceUnsafe' | 'waitLock'>, config: FireForgeConfig): Promise<void>;
 /**
  * Runs the `patch split` command: plans the split, lints the projection,
  * confirms, and commits transactionally.