@hominis/fireforge 0.49.1 → 0.50.0

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

@@ -12,19 +12,25 @@
  *   re-export's engine read + diff regeneration roundtrip is wasted.
  *
  * Modes are mutually exclusive: exactly one of `--add`, `--remove`, or
- * `--clear` must be supplied per invocation. The read-modify-write
+ * `--clear` must be supplied per invocation. `--add <rule> --max <n>
+ * --reason <text>` writes a size waiver with a ceiling (see
+ * `core/patch-lint-ignore.ts`) instead of a bare check ID; an `--add` for a
+ * rule that already has an entry replaces it, so the same command moves a
+ * ceiling or widens it back to a bare waiver. The read-modify-write
  * happens inside the patch directory lock via {@link mutatePatchMetadata}
  * so a concurrent writer cannot interleave between the read and the
  * write, which matters when an operator scripts repeated invocations or
  * runs `--add` and `--remove` back-to-back.
  */
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { confirmDestructive } from '../../core/destructive.js';
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
+import { addedLintIgnoreEntries, formatLintIgnoreEntry, formatLintIgnoreList, LINT_IGNORE_CEILING_RULES, lintIgnoreRule, removeLintIgnoreRules, upsertLintIgnoreEntries, } from '../../core/patch-lint-ignore.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
-import { addWaitLockOption, resolveWaitLockSeconds, stringListOption, } from '../../utils/options.js';
+import { addWaitLockOption, commanderArgParser, resolveWaitLockSeconds, stringListOption, } from '../../utils/options.js';
+import { parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
@@ -44,19 +50,10 @@ const LINT_IGNORE_REVIEW_WARNING = "This lint waiver is subject to the project's
  * present" contract).
  */
 function applyMode(existing, mode, values) {
-    const existingSet = new Set(existing);
-    if (mode === 'add') {
-        for (const v of values)
-            existingSet.add(v);
-        const merged = [...existingSet];
-        return merged.length > 0 ? merged : undefined;
-    }
-    if (mode === 'remove') {
-        for (const v of values)
-            existingSet.delete(v);
-        const remaining = [...existingSet];
-        return remaining.length > 0 ? remaining : undefined;
-    }
+    if (mode === 'add')
+        return upsertLintIgnoreEntries(existing, values);
+    if (mode === 'remove')
+        return removeLintIgnoreRules(existing, values.map(lintIgnoreRule));
     // mode === 'clear'
     return undefined;
 }
@@ -66,29 +63,62 @@ function applyMode(existing, mode, values) {
  * message format directly without mocking the logger transport.
  */
 function describeChange(before, after, mode, values) {
-    const beforeSet = new Set(before);
-    const afterSet = new Set(after);
     if (mode === 'clear') {
         return before.length === 0
             ? 'lintIgnore was already empty — no change'
-            : `lintIgnore cleared (was ${before.join(', ')})`;
+            : `lintIgnore cleared (was ${formatLintIgnoreList(before)})`;
     }
-    const currentLabel = before.length > 0 ? `[${before.join(', ')}]` : '(empty)';
+    const currentLabel = before.length > 0 ? `[${formatLintIgnoreList(before)}]` : '(empty)';
     if (mode === 'add') {
-        const added = values.filter((v) => !beforeSet.has(v));
+        const added = addedLintIgnoreEntries(before, after);
         if (added.length === 0) {
             // Surface the existing list so a no-op `--add` does not require a
             // follow-up `patches.json` read to confirm what was already present.
             return `lintIgnore unchanged (current: ${currentLabel}; all requested IDs already present)`;
         }
-        return `lintIgnore += ${added.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
+        return `lintIgnore += ${formatLintIgnoreList(added)} → ${formatLintIgnoreList(after)}`;
     }
     // mode === 'remove'
-    const removed = values.filter((v) => beforeSet.has(v));
+    const requested = new Set(values.map(lintIgnoreRule));
+    const removed = before.filter((entry) => requested.has(lintIgnoreRule(entry)));
     if (removed.length === 0) {
         return `lintIgnore unchanged (current: ${currentLabel}; none of the requested IDs were present)`;
     }
-    return `lintIgnore −= ${removed.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
+    return `lintIgnore −= ${formatLintIgnoreList(removed)} → ${formatLintIgnoreList(after)}`;
+}
+/**
+ * Turns the mode's IDs into manifest entries, applying `--max`/`--reason`
+ * to `--add`. Refuses a ceiling flag without `--add`, a `--max` without a
+ * `--reason` (and the reverse), and a ceiling on a rule that carries no
+ * measurement, so a waiver that could never suppress anything is not
+ * written.
+ */
+function resolveRequestedEntries(mode, options) {
+    const hasMax = options.max !== undefined;
+    const hasReason = options.reason !== undefined;
+    if ((hasMax || hasReason) && mode !== 'add') {
+        throw new InvalidArgumentError('--max and --reason only apply to --add.', hasMax ? '--max' : '--reason');
+    }
+    if (hasMax !== hasReason) {
+        throw new InvalidArgumentError('A lintIgnore ceiling needs both --max <n> and --reason <text>.', hasMax ? '--reason' : '--max');
+    }
+    if (mode === 'remove')
+        return [...(options.remove ?? [])];
+    if (mode !== 'add')
+        return [];
+    const ids = options.add ?? [];
+    if (options.max === undefined || options.reason === undefined)
+        return [...ids];
+    if (options.reason.trim() === '') {
+        throw new InvalidArgumentError('--reason must not be empty.', '--reason');
+    }
+    const unmeasured = ids.filter((id) => !LINT_IGNORE_CEILING_RULES.includes(id));
+    if (unmeasured.length > 0) {
+        throw new InvalidArgumentError(`--max only applies to the measured size rules (${LINT_IGNORE_CEILING_RULES.join(', ')}); ` +
+            `got ${unmeasured.join(', ')}.`, '--max');
+    }
+    const { max, reason } = options;
+    return ids.map((rule) => ({ rule, max, reason }));
 }
 /**
  * Runs the `patch lint-ignore` command: reads the patch's existing
@@ -116,7 +146,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         throw new InvalidArgumentError('Specify --add <id>, --remove <id>, or --clear.', 'patch lint-ignore');
     }
     const mode = adding ? 'add' : removing ? 'remove' : 'clear';
-    const values = mode === 'add' ? (options.add ?? []) : mode === 'remove' ? (options.remove ?? []) : [];
+    const values = resolveRequestedEntries(mode, options);
     const { paths, manifest } = await requirePatchQueue(projectRoot);
     const target = requirePatchTarget(identifier, manifest.patches);
     // Destructive-operation contract (docs/lifecycle-invariants.md): manifest
@@ -126,7 +156,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     // of mutation an operator should approve consciously.
     const currentList = target.lintIgnore ?? [];
     const projectedList = applyMode(currentList, mode, values) ?? [];
-    const addsNewIds = mode === 'add' && projectedList.length > currentList.length;
+    const addsNewIds = mode === 'add' && addedLintIgnoreEntries(currentList, projectedList).length > 0;
     const projectedSummary = describeChange(currentList, projectedList, mode, values);
     const decision = await confirmDestructive({
         operation: 'patch-lint-ignore',
@@ -158,7 +188,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     const existing = result.before.lintIgnore ?? [];
     const projected = result.after.lintIgnore ?? [];
     info(`${target.filename}: ${describeChange(existing, projected, mode, values)}.`);
-    if (mode === 'add' && projected.length > existing.length) {
+    if (mode === 'add' && addedLintIgnoreEntries(existing, projected).length > 0) {
         warn(LINT_IGNORE_REVIEW_WARNING);
     }
     await appendHistoryBestEffort(paths.patches, {
@@ -166,7 +196,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         args: {
             filename: target.filename,
             mode,
-            values: [...values],
+            values: values.map(formatLintIgnoreEntry),
             before: existing,
             after: projected,
         },
@@ -189,6 +219,9 @@ export function registerPatchLintIgnore(parent, context) {
         .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable)', ...stringListOption())
         .option('--remove <check-id>', 'Lint check ID to remove from the patch lintIgnore list (repeatable)', ...stringListOption())
         .option('--clear', 'Drop the lintIgnore field entirely')
+        .addOption(new Option('--max <n>', 'With --add: write a size waiver with a ceiling, suppressing the rule only while its ' +
+        'measurement is at most <n> (file-too-large, large-patch-lines, large-patch-files)').argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--max', v))))
+        .option('--reason <text>', 'With --add --max: why the ceiling exists (required with --max)')
         .option('--dry-run', 'Show what would change without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)');
     addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
@@ -203,6 +236,10 @@ export function registerPatchLintIgnore(parent, context) {
             normalized.remove = options.remove;
         if (options.clear === true)
             normalized.clear = true;
+        if (options.max !== undefined)
+            normalized.max = options.max;
+        if (options.reason !== undefined)
+            normalized.reason = options.reason;
         if (options.dryRun === true)
             normalized.dryRun = true;
         if (options.yes === true)

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

@@ -14,6 +14,7 @@ import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { assertConfirmationAvailable, confirmDestructive } from '../../core/destructive.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
+import { buildLintIgnoreChecks } from '../../core/patch-lint-ignore.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
 import { formatPatchOrder } from '../../core/patch-parse.js';
 import { enforcePatchPolicy } from '../../core/patch-policy.js';
@@ -23,8 +24,9 @@ import { normalizePatchDisplayName } from '../../utils/validation.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
-import { commitPatchSplit } from './split.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, projectSplitManifest, runProjectedSplitLint, } from './split-plan.js';
+import { commitPatchSplit, reportSplitStagedChanges } from './split.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, projectSplitManifest, runProjectedSplitLint, } from './split-plan.js';
+import { emptyStagedMaintenance, findOwnerRewriteHolders } from './split-staged.js';
 /**
  * Runs `patch move-files --create --order <n>`: plans the create+move as a
  * split, lints the projection, confirms, and commits transactionally.
@@ -85,9 +87,26 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         name: displayName,
         description: options.description ?? '',
         ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
-        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        // Populated by runProjectedSplitLint below (forward edges into the new
+        // patch, and the declarations the move re-homes or makes unused).
         stagedDependencyAdditions: new Map(),
+        stagedMaintenance: emptyStagedMaintenance(),
     };
+    // Policy first: the projected manifest (orders, ranges, the gap rule)
+    // does not depend on the lint below, so a refused --order fails before
+    // the per-patch and projected lint passes instead of after them.
+    enforcePatchPolicy({
+        config,
+        manifest: projectSplitManifest(manifest, plan, buildNewPatchMetadata(plan, config)),
+        command: 'patch move-files --create',
+        forceUnsafe: options.forceUnsafe === true,
+        hints: {
+            'description-required': 'Pass --description "<text>" (or -d) on this command to set the created patch\'s description.',
+            'numeric-gap': 'With patchPolicy.allowGaps: false, orders are contiguous within a range: --order must ' +
+                "fill an existing gap or a retired slot, or take the number right after the range's last " +
+                'patch. A number reserved past a gap cannot be used until the numbers before it exist.',
+        },
+    });
     // Per-patch lint both projected bodies, threading the source patch's
     // tier/lintIgnore so an intentional-advisory patch can still move files.
     // The whole-queue context (built once, with the config so it carries the
@@ -96,7 +115,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     // resolve exactly as they will after the move lands. Without it the
     // projection lint is blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
-    const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
+    const ignoreChecks = buildLintIgnoreChecks(source.lintIgnore);
     await runPatchLint({
         engineDir: paths.engine,
         filesAffected: remainingFiles,
@@ -117,18 +136,10 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         ignoreChecks,
         patchTier: source.tier,
     });
-    const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
+    const { conflicts, stagedDependencyAdditions, stagedMaintenance } = runProjectedSplitLint(plan, patchQueueCtx);
     plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    plan.stagedMaintenance = stagedMaintenance;
     const newMetadata = buildNewPatchMetadata(plan, config);
-    enforcePatchPolicy({
-        config,
-        manifest: projectSplitManifest(manifest, plan, newMetadata),
-        command: 'patch move-files --create',
-        forceUnsafe: options.forceUnsafe === true,
-        hints: {
-            'description-required': 'Pass --description "<text>" (or -d) on this command to set the created patch\'s description.',
-        },
-    });
     const decision = await confirmDestructive({
         operation: 'patch-move-files-create',
         title: `Create ${placement.newFilename} (order ${placement.insertionOrder}) and move ${movedFiles.length} file(s) out of ${source.filename}`,
@@ -143,8 +154,6 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Created ${placement.newFilename} (order ${formatPatchOrder(placement.insertionOrder)}) ` +
         `and moved ${plan.movedFiles.length} file(s) out of ${source.filename}`);
-    if (plan.ownerRewrites.length > 0) {
-        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
-    }
+    reportSplitStagedChanges(plan);
     outro('Move complete');
 }

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

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import { assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { buildPatchQueueContext, collectForwardImportEdges, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildLintIgnoreChecks } from '../../core/patch-lint-ignore.js';
 import { computeProjectedLintRegressions } from '../../core/patch-lint-projection.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
@@ -29,7 +30,8 @@ import { resolveWaitLockSeconds } from '../../utils/options.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { runPatchLint } from '../export-shared.js';
 import { projectEntryBody } from './entry-projection.js';
-import { buildSplitDiff, findOwnerRewriteHolders, mergeStagedForwardImports, rewriteSplitOwners, } from './split-plan.js';
+import { buildSplitDiff, mergeStagedForwardImports } from './split-plan.js';
+import { findOwnerRewriteHolders, rewriteSplitOwners } from './split-staged.js';
 /**
  * Projects the post-move queue through cross-patch lint, auto-declaring the
  * forward edges the move introduces into the target (an importer that used
@@ -198,7 +200,7 @@ export async function runMoveFilesInto(args) {
         config: args.config,
         skipLint: options.skipLint,
         patchQueueCtx,
-        ignoreChecks: source.lintIgnore ? new Set(source.lintIgnore) : undefined,
+        ignoreChecks: buildLintIgnoreChecks(source.lintIgnore),
         patchTier: source.tier,
     });
     await runPatchLint({
@@ -208,7 +210,7 @@ export async function runMoveFilesInto(args) {
         config: args.config,
         skipLint: options.skipLint,
         patchQueueCtx,
-        ignoreChecks: target.lintIgnore ? new Set(target.lintIgnore) : undefined,
+        ignoreChecks: buildLintIgnoreChecks(target.lintIgnore),
         patchTier: target.tier,
     });
     const manifest = await loadPatchesManifest(patchesDir);

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

@@ -164,7 +164,9 @@ export function registerPatchMoveFiles(parent, context) {
         'or create the target patch and move the files in one transaction with --create --order <n>.')
         .option('--file <path>', 'File path relative to engine/ to move (repeatable)', ...stringListOption())
         .option('--create', 'Create <to> as a new patch and move the files into it (requires --order)')
-        .option('--order <n>', 'Exact sparse order for the created patch (only valid with --create)', commanderArgParser((raw) => parsePositiveIntegerFlag('--order', raw)))
+        .option('--order <n>', 'Exact sparse order for the created patch (only valid with --create). With ' +
+        'patchPolicy.allowGaps: false, orders are contiguous within a range: pick a gap, a ' +
+        "retired slot, or the number after the range's last patch; checked before any lint runs", commanderArgParser((raw) => parsePositiveIntegerFlag('--order', raw)))
         .option('--category <category>', "Category for the created patch (default: the source patch's)")
         .option('-d, --description <desc>', 'Description for the created patch')
         .option('--dry-run', 'Show what would happen without writing')

package/dist/src/commands/patch/removal-dependents.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The dependency scan `patch delete` and `patch retire` share: which later
+ * patches import a file the removed patch creates, and which staged
+ * declarations name it as their owner. Both commands take the patch out of
+ * the queue, so both must refuse and warn on exactly the same evidence.
+ */
+import type { ConflictReport } from '../../core/destructive.js';
+import { type PatchQueueContext } from '../../core/patch-lint.js';
+import type { PatchMetadata } from '../../types/commands/index.js';
+/**
+ * Lists every later patch site that imports a file `target` creates.
+ *
+ * Both source-site maps are covered: `newFiles` (files the later patch
+ * creates) and `modifiedFileAdditions` (added lines against files that
+ * already exist). Scanning only newFiles misses a later patch adding
+ * `import "./TargetHelper.sys.mjs"` to an existing file. Uses the shared
+ * specifier extractor so dynamic `import()` and
+ * `ChromeUtils.defineESModuleGetters` are picked up: the forward-import lint
+ * rule already covers those forms, and removal safety must match the same
+ * set or it silently drops dependencies.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param command - Names for the "queue changed" refusal, e.g.
+ *   `{ noun: 'deletion', verb: 'delete' }`
+ * @returns One description per dependent patch
+ */
+export declare function collectRemovalDependents(baseCtx: PatchQueueContext, target: PatchMetadata, command: {
+    noun: string;
+    verb: string;
+}): string[];
+/**
+ * Warns once per patch whose staged forward-import names `target` as its
+ * 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.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param verb - Command name used in the warning ("delete", "retire")
+ */
+export declare function warnDanglingStagedOwners(baseCtx: PatchQueueContext, target: PatchMetadata, verb: string): void;
+/**
+ * The structural conflict a removal with dependents raises.
+ *
+ * The wording spells out the runtime impact: `git apply` does not resolve
+ * imports and succeeds even when a later patch imports a file the target
+ * created, so the queue re-imports cleanly. The breakage surfaces at
+ * browser startup when `ChromeUtils.importESModule` cannot locate the
+ * deleted module. Operators who plan to re-introduce the imported files
+ * (rename, refactor) need to know this is the impact model rather than a
+ * patch-application failure.
+ *
+ * @param dependents - Result of {@link collectRemovalDependents}
+ * @param target - The patch about to leave the queue
+ */
+export declare function removalConflict(dependents: readonly string[], target: PatchMetadata): ConflictReport | null;
+/**
+ * Snapshot of the queue inputs a removal's dependency scan read, compared
+ * again under the lock so a change between the prompt and the commit
+ * refuses instead of committing an unreviewed removal.
+ */
+export declare function queueSnapshot(context: PatchQueueContext): string;

package/dist/src/commands/patch/removal-dependents.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The dependency scan `patch delete` and `patch retire` share: which later
+ * patches import a file the removed patch creates, and which staged
+ * declarations name it as their owner. Both commands take the patch out of
+ * the queue, so both must refuse and warn on exactly the same evidence.
+ */
+import { basename } from 'node:path';
+import { extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
+import { GeneralError } from '../../errors/base.js';
+import { warn } from '../../utils/logger.js';
+/**
+ * Lists every later patch site that imports a file `target` creates.
+ *
+ * Both source-site maps are covered: `newFiles` (files the later patch
+ * creates) and `modifiedFileAdditions` (added lines against files that
+ * already exist). Scanning only newFiles misses a later patch adding
+ * `import "./TargetHelper.sys.mjs"` to an existing file. Uses the shared
+ * specifier extractor so dynamic `import()` and
+ * `ChromeUtils.defineESModuleGetters` are picked up: the forward-import lint
+ * rule already covers those forms, and removal safety must match the same
+ * set or it silently drops dependencies.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param command - Names for the "queue changed" refusal, e.g.
+ *   `{ noun: 'deletion', verb: 'delete' }`
+ * @returns One description per dependent patch
+ */
+export function collectRemovalDependents(baseCtx, target, command) {
+    const targetEntry = baseCtx.entries.find((e) => e.filename === target.filename);
+    if (!targetEntry || JSON.stringify(targetEntry.metadata) !== JSON.stringify(target)) {
+        throw new GeneralError(`Patch queue changed while preparing ${command.noun}. Re-run patch ${command.verb} to review the current target.`);
+    }
+    const targetNewFileLeaves = new Set();
+    for (const fullPath of targetEntry.newFiles.keys()) {
+        targetNewFileLeaves.add(basename(fullPath));
+    }
+    const dependents = [];
+    const scanSite = (entryFilename, sitePath, content) => {
+        if (!isForwardImportableFile(sitePath))
+            return false;
+        const ignoredLines = findForwardImportIgnoreLines(content);
+        const specifiers = extractImportSpecifiersWithLines(content);
+        for (const { specifier, line } of specifiers) {
+            if (ignoredLines.has(line))
+                continue;
+            const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
+            const leaf = basename(cleaned);
+            if (!leaf || !isForwardImportableFile(leaf))
+                continue;
+            if (targetNewFileLeaves.has(leaf)) {
+                dependents.push(`${entryFilename} (${sitePath}) imports "${specifier}" which would be deleted`);
+                return true;
+            }
+        }
+        return false;
+    };
+    for (const entry of baseCtx.entries) {
+        if (entry.filename === target.filename)
+            continue;
+        if (entry.order < target.order)
+            continue;
+        let matched = false;
+        for (const [newFile, content] of entry.newFiles) {
+            if (scanSite(entry.filename, newFile, content)) {
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            continue;
+        for (const [modifiedPath, addedContent] of entry.modifiedFileAdditions) {
+            if (scanSite(entry.filename, modifiedPath, addedContent))
+                break;
+        }
+    }
+    return dependents;
+}
+/**
+ * Warns once per patch whose staged forward-import names `target` as its
+ * 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.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param verb - Command name used in the warning ("delete", "retire")
+ */
+export function warnDanglingStagedOwners(baseCtx, target, verb) {
+    const holders = baseCtx.entries.filter((entry) => entry.filename !== target.filename &&
+        (entry.metadata?.stagedDependencies?.forwardImports ?? []).some((fi) => fi.owner === target.filename));
+    for (const holder of holders) {
+        warn(`${holder.filename} declares a staged dependency with owner ${target.filename}; ` +
+            `after the ${verb}, update it via "fireforge patch staged-dependency ${holder.filename} --remove ..." ` +
+            'or re-point the owner at the patch that will create the file.');
+    }
+}
+/**
+ * The structural conflict a removal with dependents raises.
+ *
+ * The wording spells out the runtime impact: `git apply` does not resolve
+ * imports and succeeds even when a later patch imports a file the target
+ * created, so the queue re-imports cleanly. The breakage surfaces at
+ * browser startup when `ChromeUtils.importESModule` cannot locate the
+ * deleted module. Operators who plan to re-introduce the imported files
+ * (rename, refactor) need to know this is the impact model rather than a
+ * patch-application failure.
+ *
+ * @param dependents - Result of {@link collectRemovalDependents}
+ * @param target - The patch about to leave the queue
+ */
+export function removalConflict(dependents, target) {
+    if (dependents.length === 0)
+        return null;
+    return {
+        reason: `${dependents.length} later patch(es) contain import statements that reference files created by ${target.filename}. Patch application itself will still succeed, but runtime imports will fail at browser startup until those files are re-introduced.`,
+        details: [...dependents],
+    };
+}
+/**
+ * Snapshot of the queue inputs a removal's dependency scan read, compared
+ * again under the lock so a change between the prompt and the commit
+ * refuses instead of committing an unreviewed removal.
+ */
+export function queueSnapshot(context) {
+    return JSON.stringify(context.entries.map(({ filename, order, diff, metadata }) => ({
+        filename,
+        order,
+        diff,
+        metadata,
+    })));
+}

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

@@ -26,6 +26,7 @@ import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '.
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from '../../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy, getPatchPolicyCategories, isCategoryAllowedByConfig, } from '../../core/patch-policy.js';
+import { carryRetiredSlots } from '../../core/patch-retired.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -115,6 +116,12 @@ async function commitRenameUnderLock(input) {
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
         }
+        // A rename onto a retired order fills that slot.
+        const retired = carryRetiredSlots(fresh, fresh.patches);
+        if (retired === undefined)
+            delete fresh.retired;
+        else
+            fresh.retired = retired;
         enforcePatchPolicy({
             config: input.config,
             manifest: buildProjectedManifest(fresh, fresh.patches),

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

@@ -0,0 +1,34 @@
+/**
+ * `fireforge patch retire <name>`: removes a patch from the queue and keeps
+ * its order number spent as a retired slot in `patches.json#retired`.
+ *
+ * The case it exists for: a rename leaves a patch owning only files that no
+ * longer exist. `patch delete` opens a numeric gap that
+ * `patchPolicy.allowGaps: false` refuses, and `patch compact` renumbers
+ * every later patch, including ones a peer session has in flight. Retiring
+ * removes the patch file and row like a delete, and records the order as a
+ * placeholder the gap check counts as occupied. Nothing else reads the
+ * placeholder (see `core/patch-retired.ts`), and a later
+ * `export --order <n>` that takes the number fills it.
+ *
+ * Shares the delete's dependency refusal, dry-run, confirmation and history
+ * contract, so the two differ only in what happens to the order number.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchRetireOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch retire` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest name to retire
+ * @param options - Command options
+ */
+export declare function patchRetireCommand(projectRoot: string, identifier: string, options?: PatchRetireOptions): Promise<void>;
+/**
+ * Registers the `patch retire` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchRetire(parent: Command, context: CommandContext): void;