@hominis/fireforge 0.30.1 → 0.32.0

package/dist/src/commands/lint.js

@@ -9,7 +9,7 @@ import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
 import { clearPerPatchLintCache } from '../core/lint-cache.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue } from '../core/patch-lint.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, lintExportedPatch, lintPatchQueue, lintPatchSize, } from '../core/patch-lint.js';
 import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
@@ -215,13 +215,12 @@ export function applyAggregateLintIgnoreSuppression(issues, ctx) {
     return { issues: filtered, dropped: issues.length - filtered.length };
 }
 /**
- * Runs the lint command to check engine changes against patch quality rules.
- * @param projectRoot - Root directory of the project
- * @param files - Optional file/directory paths to lint (relative to engine/)
- * @param options - Additional lint options such as `--since` diff-scoping
+ * Up-front flag validation for `lintCommand`: rejects `--only-introduced`
+ * without `--since`, non-integer `--max-warnings`, and `--per-patch`
+ * combined with explicit file paths — each a misconfiguration that should
+ * fail loud rather than silently narrow the result.
  */
-export async function lintCommand(projectRoot, files, options = {}) {
-    intro('FireForge Lint');
+function validateLintFlags(options, files) {
     // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
     // without a revision to anchor the diff there is no "introduced" subset
     // to scope to — reject the combination up-front so a misconfigured CI
@@ -235,85 +234,31 @@ export async function lintCommand(projectRoot, files, options = {}) {
         throw new GeneralError('--max-warnings must be a non-negative integer.');
     }
     // `--per-patch` rescopes the diff from "aggregate engine state" to "each
-    // patch's own filesAffected". Mixing in explicit file paths would produce
-    // an ambiguous set — is the file list an additional filter, or does it
-    // replace the per-patch scope? Reject up-front so the operator gets a
-    // clear error rather than a silently-narrowed result.
+    // patch's own filesAffected". Mixing in explicit engine file paths would
+    // produce an ambiguous set — is the file list an additional filter, or
+    // does it replace the per-patch scope? Reject up-front, but point at the
+    // first-class subset filter so an operator who wanted to target patches
+    // (not engine files) knows the supported syntax.
     if (options.perPatch && files.length > 0) {
-        throw new GeneralError('--per-patch cannot be combined with explicit file paths. Pass either --per-patch or a file list, not both.');
-    }
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+        throw new GeneralError('--per-patch cannot be combined with explicit engine file paths. ' +
+            'To lint a subset of patches, use `--per-patch --patches <name…>`; ' +
+            'to lint specific engine files, drop --per-patch.');
     }
-    if (!(await isGitRepository(paths.engine))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    if (options.perPatch) {
-        await lintPerPatch(projectRoot, paths, options);
-        return;
+    // `--patches` only means something in per-patch mode (it filters the
+    // queue); in aggregate/file-list mode there is no patch loop to narrow.
+    if (options.patches !== undefined && !options.perPatch) {
+        throw new GeneralError('--patches requires --per-patch.');
     }
-    // Load the config before resolving the diff so we can pass
-    // `binaryName` into the aggregate-mode branding exclusion in
-    // `resolveLintDiff`. The config was previously loaded only after
-    // the diff was resolved; hoisting it is cheap and keeps the two
-    // call sites close together.
-    const config = await loadConfig(projectRoot);
-    // Pull the Furnace-managed prefix set up-front so aggregate lint can
-    // mirror the branding exclusion for Furnace material — without it,
-    // preview-generated stories under `browser/components/storybook/
-    // stories/furnace/` show up as license-header errors on every
-    // post-preview lint run.
-    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
-    if (diff === null)
-        return;
-    const filesAffected = extractAffectedFiles(diff);
-    // Build patch queue context once so it can be shared between the
-    // per-patch ownership resolver and the cross-patch rules.
-    let ctx;
-    if (await pathExists(paths.patches)) {
-        ctx = await buildPatchQueueContext(paths.patches);
-    }
-    let issues = [
-        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx)),
-    ];
-    // Cross-patch rules operate over the whole queue, so run them whenever a
-    // patches directory exists — they surface duplicate /dev/null creations
-    // and forward-import chains that the per-patch orchestrator cannot see.
-    if (ctx) {
-        issues.push(...lintPatchQueue(ctx));
-    }
-    // Honor per-patch `lintIgnore` in aggregate mode by attributing each
-    // issue's file to its owning patches via the manifest's
-    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
-    // `lintExportedPatch`; aggregate mode previously had no patch-level
-    // scope to consult, so a check an operator had explicitly waived in
-    // `patches.json` re-surfaced on every `--since` run (CI default).
-    if (ctx) {
-        const result = applyAggregateLintIgnoreSuppression(issues, ctx);
-        issues = result.issues;
-        if (result.dropped > 0) {
-            info(`Suppressed ${result.dropped} issue(s) via per-patch lintIgnore (aggregate mode).`);
-        }
-    }
-    // When a queue manifest exists AND files were NOT scoped explicitly, the
-    // "diff" we just linted is every applied patch summed together. Patch-
-    // size rules (`large-patch-lines`, `large-patch-files`) then fire against
-    // the aggregate rather than any individual patch, producing counts like
-    // "Patch is 37529 lines" that read as a task-specific regression but are
-    // really an artefact of aggregation. Surface a one-line note pointing at
-    // `--per-patch` so the operator knows the per-patch scope exists before
-    // they read the error message as "my queue is broken".
-    //
-    // In aggregate mode over a multi-patch queue we also downgrade the two
-    // size rules from `error` to `warning`. Before this downgrade, a
-    // fresh-imported patch stack of 20+ patches hard-failed `fireforge lint`
-    // on lines-per-aggregate counts that are mathematically impossible to
-    // satisfy without splitting patches that were already split — the
-    // actionable unit is the individual patch, and `--per-patch` is the
-    // mode that matches. Per-patch mode keeps errors as errors (see
-    // `lintPerPatch` below).
+}
+/**
+ * Aggregate-mode patch-size softening: when the linted diff is every
+ * applied patch summed (no explicit file scope, multi-patch queue), the
+ * `large-patch-lines` / `large-patch-files` counts are an artefact of
+ * aggregation rather than a property of any one patch. Surface the
+ * `--per-patch` hint and downgrade those two rules to warnings; per-patch
+ * mode keeps them as errors.
+ */
+function downgradeAggregateSizeRules(issues, files, ctx) {
     const aggregateHintApplicable = files.length === 0 && ctx !== undefined && ctx.entries.length > 1;
     if (aggregateHintApplicable &&
         issues.some((i) => i.check === 'large-patch-lines' || i.check === 'large-patch-files')) {
@@ -325,18 +270,94 @@ export async function lintCommand(projectRoot, files, options = {}) {
             }
         }
     }
-    if (issues.length === 0) {
-        success('No lint issues found.');
-        outro('Lint passed');
-        return;
+}
+/**
+ * Evaluates the patch-size rules (`large-patch-files` / `large-patch-lines`)
+ * for an ad-hoc explicit-file-list lint, scoped to each file's **owning
+ * patch** rather than the combined file list.
+ *
+ * The default file-list path used to feed every passed file to
+ * `lintExportedPatch` as one synthetic patch, so a cross-patch selection of
+ * eight files belonging to four patches reported `Patch affects 8 files`
+ * even though no single owning patch was oversized. This helper instead
+ * groups the affected files by their owning patch (via the manifest's
+ * `filesAffected`), then runs `lintPatchSize` against each owner's real file
+ * count + diff, honouring that owner's `tier` and `lintIgnore` — so
+ * `lint <files>`, `lint --per-patch`, and `re-export --dry-run` agree on the
+ * same size findings for the same files. Files no patch claims are evaluated
+ * together as one prospective new patch, preserving the pre-export
+ * oversized-change warning.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param filesAffected - Engine-relative files touched by the ad-hoc diff
+ * @param ctx - Patch queue context used to attribute file → owning patch
+ * @returns Size issues, each attributed to its owning patch by message prefix
+ */
+async function lintOwningPatchSizes(engineDir, filesAffected, ctx) {
+    const listed = new Set(filesAffected);
+    const owners = new Map();
+    const ownedListed = new Set();
+    for (const entry of ctx.entries) {
+        const md = entry.metadata;
+        if (!md)
+            continue;
+        let ownsAny = false;
+        for (const f of md.filesAffected) {
+            if (listed.has(f)) {
+                ownedListed.add(f);
+                ownsAny = true;
+            }
+        }
+        if (ownsAny)
+            owners.set(entry.filename, entry);
+    }
+    const issues = [];
+    const lineCountForFiles = async (relPaths) => {
+        const existing = [];
+        for (const f of relPaths) {
+            if (await pathExists(join(engineDir, f)))
+                existing.push(f);
+        }
+        if (existing.length === 0)
+            return 0;
+        const diff = await getDiffForFilesAgainstHead(engineDir, existing);
+        return countNonBinaryDiffLines(diff).textLines;
+    };
+    for (const entry of owners.values()) {
+        const md = entry.metadata;
+        if (!md)
+            continue;
+        const lineCount = await lineCountForFiles(md.filesAffected);
+        const ignore = md.lintIgnore?.length ? new Set(md.lintIgnore) : undefined;
+        for (const issue of lintPatchSize(md.filesAffected, lineCount, md.tier)) {
+            if (ignore?.has(issue.check))
+                continue;
+            issues.push({ ...issue, message: `${entry.filename}: ${issue.message}` });
+        }
     }
+    // Files no patch claims are a prospective new patch: evaluate them as one
+    // unit so a genuinely oversized fresh change still surfaces.
+    const unowned = filesAffected.filter((f) => !ownedListed.has(f));
+    if (unowned.length > 0) {
+        const lineCount = await lineCountForFiles(unowned);
+        issues.push(...lintPatchSize(unowned, lineCount));
+    }
+    return issues;
+}
+/**
+ * Reporting + exit phase of `lintCommand`: tags issues against `--since`,
+ * renders every notice/warning/error row, prints the summary, and applies
+ * the failure criteria (`--only-introduced` scoping, `--max-warnings`)
+ * by throwing GeneralError. Issues must be non-empty.
+ */
+async function reportLintOutcome(engineDir, issues, options) {
     // Diff-scoping: tag each issue as introduced-in-current-task vs
     // cumulative-pre-existing-drift. Never filters — full set still prints
     // and exit code semantics are unchanged — but the per-line prefix and
     // summary make triage trivial on a large patch series.
     const sinceActive = Boolean(options.since);
     if (options.since) {
-        const diffFiles = await collectDiffFilePaths(paths.engine, options.since);
+        const diffFiles = await collectDiffFilePaths(engineDir, options.since);
         tagLintIssues(issues, diffFiles);
     }
     const errors = issues.filter((i) => i.severity === 'error');
@@ -399,6 +420,86 @@ export async function lintCommand(projectRoot, files, options = {}) {
         outro('Lint passed');
     }
 }
+/**
+ * Runs the lint command to check engine changes against patch quality rules.
+ * @param projectRoot - Root directory of the project
+ * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
+ */
+export async function lintCommand(projectRoot, files, options = {}) {
+    intro('FireForge Lint');
+    validateLintFlags(options, files);
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    if (options.perPatch) {
+        await lintPerPatch(projectRoot, paths, options);
+        return;
+    }
+    // Load the config before resolving the diff so we can pass
+    // `binaryName` into the aggregate-mode branding exclusion in
+    // `resolveLintDiff`. The config was previously loaded only after
+    // the diff was resolved; hoisting it is cheap and keeps the two
+    // call sites close together.
+    const config = await loadConfig(projectRoot);
+    // Pull the Furnace-managed prefix set up-front so aggregate lint can
+    // mirror the branding exclusion for Furnace material — without it,
+    // preview-generated stories under `browser/components/storybook/
+    // stories/furnace/` show up as license-header errors on every
+    // post-preview lint run.
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
+    if (diff === null)
+        return;
+    const filesAffected = extractAffectedFiles(diff);
+    // Build patch queue context once so it can be shared between the
+    // per-patch ownership resolver and the cross-patch rules.
+    let ctx;
+    if (await pathExists(paths.patches)) {
+        ctx = await buildPatchQueueContext(paths.patches);
+    }
+    // Ad-hoc explicit-file-list mode evaluates the patch-size rules per
+    // owning patch (see `lintOwningPatchSizes`), so suppress the synthetic
+    // combined-list size check in the shared pass — otherwise a cross-patch
+    // selection synthesises a phantom oversized patch from the file count.
+    const fileListMode = files.length > 0 && ctx !== undefined;
+    let issues = [
+        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx, undefined, undefined, fileListMode ? { skipPatchSize: true } : undefined)),
+    ];
+    if (files.length > 0 && ctx) {
+        issues.push(...(await lintOwningPatchSizes(paths.engine, filesAffected, ctx)));
+    }
+    // Cross-patch rules operate over the whole queue, so run them whenever a
+    // patches directory exists — they surface duplicate /dev/null creations
+    // and forward-import chains that the per-patch orchestrator cannot see.
+    if (ctx) {
+        issues.push(...lintPatchQueue(ctx));
+    }
+    // Honor per-patch `lintIgnore` in aggregate mode by attributing each
+    // issue's file to its owning patches via the manifest's
+    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
+    // `lintExportedPatch`; aggregate mode previously had no patch-level
+    // scope to consult, so a check an operator had explicitly waived in
+    // `patches.json` re-surfaced on every `--since` run (CI default).
+    if (ctx) {
+        const result = applyAggregateLintIgnoreSuppression(issues, ctx);
+        issues = result.issues;
+        if (result.dropped > 0) {
+            info(`Suppressed ${result.dropped} issue(s) via per-patch lintIgnore (aggregate mode).`);
+        }
+    }
+    downgradeAggregateSizeRules(issues, files, ctx);
+    if (issues.length === 0) {
+        success('No lint issues found.');
+        outro('Lint passed');
+        return;
+    }
+    await reportLintOutcome(paths.engine, issues, options);
+}
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {
     const lint = program
@@ -409,6 +510,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
+        .option('--patches <names...>', 'With --per-patch, lint only the named patches (by filename or manifest name) instead of the whole queue. Queue-level findings are scoped to files those patches touch.')
         .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes.')
         .action(withErrorHandling(async (paths, options) => {
@@ -422,6 +524,9 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.perPatch !== undefined) {
             lintOptions.perPatch = options.perPatch;
         }
+        if (options.patches !== undefined) {
+            lintOptions.patches = options.patches;
+        }
         if (options.maxWarnings !== undefined) {
             const maxWarnings = Number(options.maxWarnings);
             if (!Number.isInteger(maxWarnings) || maxWarnings < 0) {

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

@@ -2,8 +2,11 @@
  * `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 { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

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');
 }
 /**