@hominis/fireforge 0.49.1 → 0.50.0

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

@@ -3,10 +3,13 @@ import { join } from 'node:path';
 import { loadConfig } from '../core/config.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { withPrivateGitIndex } from '../core/git-readonly-index.js';
-import { buildPatchQueueContext, countNonBinaryDiffLines, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, measurePatchSize, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/patch-lint-cache.js';
+import { buildLintIgnoreChecks, evaluateLintIgnoreCeilings, formatLintIgnoreEntry, isLintIgnoreCeiling, lintIgnoreCacheTokens, removableCeilingIssues, } from '../core/patch-lint-ignore.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
+import { evaluatePatchPolicyContent } from '../core/patch-policy-content.js';
+import { selectPatchSubset } from '../core/patch-subset.js';
 import { GeneralError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
@@ -47,7 +50,7 @@ async function lintQueuedPatch(patch, lintCtx) {
             usedCheckJs: false,
         };
     }
-    const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+    const ignore = buildLintIgnoreChecks(patch.lintIgnore);
     let cacheKey;
     if (cache) {
         cacheKey = await buildPerPatchLintCacheKey({
@@ -60,7 +63,7 @@ async function lintQueuedPatch(patch, lintCtx) {
             queueContext: ctx,
             ...(engineHeadSha === undefined ? {} : { engineHeadSha }),
         });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, ignore);
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, lintIgnoreCacheTokens(ignore));
         if (cached) {
             // Returning before the empty-diff probe below is safe: the cache key
             // hashes every affected engine file's content plus engineHeadSha, so
@@ -106,8 +109,13 @@ async function lintQueuedPatch(patch, lintCtx) {
         }
         lintOptions.precomputedCheckJs = precomputedCheckJs;
     }
+    // Measured from the working tree, like every other rule here: the files
+    // on disk are the would-be export, so a size tier fires mid-edit rather
+    // than first at the re-export.
+    const patchSize = await measurePatchSize(paths.engine, diff, existing, config);
     const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, {
         ...lintOptions,
+        patchSizeMeasurement: patchSize,
         patchQueueCtx: ctx,
         ...(ignore ? { ignoreChecks: ignore } : {}),
         ...(patch.tier ? { patchTier: patch.tier } : {}),
@@ -117,11 +125,11 @@ async function lintQueuedPatch(patch, lintCtx) {
         existingFiles: existing,
         rawIssues: patchIssues,
         suppressedIssues,
-        lineCount: countNonBinaryDiffLines(diff).textLines,
+        lineCount: patchSize.lines,
         usedCheckJs,
     };
     if (cache && cacheKey) {
-        result.cacheWrite = { key: cacheKey, lintIgnore: [...(ignore ?? [])] };
+        result.cacheWrite = { key: cacheKey, lintIgnore: lintIgnoreCacheTokens(ignore) };
     }
     return result;
 }
@@ -183,6 +191,9 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache, hel
         for (const issue of result.rawIssues) {
             issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
         }
+        // A ceiling the patch no longer needs is reported as a notice naming
+        // the command that drops it.
+        issues.push(...removableCeilingIssues(patch.filename, evaluateLintIgnoreCeilings(patch.lintIgnore, [...result.rawIssues, ...result.suppressedIssues], { lines: result.lineCount, files: patch.filesAffected.length })));
         // A waived size finding still reports its measurement: the finding stays
         // suppressed (no exit-code / --max-warnings effect) but the current count
         // is readable from the tool that enforces it, so a waiver's cited size
@@ -194,7 +205,9 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache, hel
                 heldNotices.push({ check: suppressedIssue.check, patch: patch.filename, suppressed: true });
                 continue;
             }
-            info(`NOTICE [${suppressedIssue.check}] ${patch.filename}: suppressed by lintIgnore — ${suppressedIssue.message}`);
+            const ceiling = patch.lintIgnore?.find((entry) => isLintIgnoreCeiling(entry) && entry.rule === suppressedIssue.check);
+            const waiver = ceiling === undefined ? 'lintIgnore' : `lintIgnore (${formatLintIgnoreEntry(ceiling)})`;
+            info(`NOTICE [${suppressedIssue.check}] ${patch.filename}: suppressed by ${waiver} — ${suppressedIssue.message}`);
         }
         totals.suppressed += result.suppressedIssues.length;
         if (result.status === 'cached')
@@ -309,57 +322,9 @@ function reportNoticeSummary(heldNotices, issues) {
         info(`NOTICE [${check}]: ${entry.count} across ${entry.patches.size} patch(es)${suppressed} (see --report)`);
     }
 }
-/**
- * Resolves the `--patches <name…>` subset filter against the manifest,
- * matching each requested name tolerantly (exact filename, filename ±
- * `.patch`, the bare order number, or the manifest `name` field). Throws listing the available
- * patches when a requested name matches none, so a typo fails loud rather
- * than silently linting nothing.
- */
-function selectPatchSubset(manifest, requested) {
-    const normalizedRequests = requested
-        .flatMap((entry) => entry.split(','))
-        .map((entry) => entry.trim())
-        .filter((entry) => entry.length > 0);
-    const patchAliases = (p) => {
-        const aliases = new Set([p.filename, p.filename.replace(/\.patch$/, ''), p.name]);
-        // The bare order number, both as the manifest records it and as the
-        // filename spells it (`2` and `002`). The refusal message offers stems,
-        // and an operator reading `102-ui-canvas-tiles.patch` in a lint finding
-        // reaches for `102` first.
-        aliases.add(String(p.order));
-        const match = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(p.filename);
-        if (match?.[1])
-            aliases.add(match[1]);
-        if (match?.[2] && match[3]) {
-            aliases.add(`${match[2]}-${match[3]}`);
-            aliases.add(match[3]);
-        }
-        return aliases;
-    };
-    const matches = (p, name) => {
-        const stem = name.replace(/\.patch$/, '');
-        return (patchAliases(p).has(name) || patchAliases(p).has(stem) || patchAliases(p).has(`${stem}.patch`));
-    };
-    const selected = [];
-    const seen = new Set();
-    for (const name of normalizedRequests) {
-        const found = manifest.patches.filter((p) => matches(p, name));
-        if (found.length === 0) {
-            const available = manifest.patches.map((p) => p.filename).join(', ');
-            throw new GeneralError(`No patch in the queue matches "${name}". In --per-patch mode, positional arguments ` +
-                `and --patches select patches (filename, stem, order number, manifest name, or slug) — not engine ` +
-                `files; drop --per-patch to lint engine paths. Available patches: ${available}`);
-        }
-        for (const p of found) {
-            if (!seen.has(p.filename)) {
-                seen.add(p.filename);
-                selected.push(p);
-            }
-        }
-    }
-    return selected;
-}
+/** The refusal sentence `selectPatchSubset` adds for a `lint --per-patch` miss. */
+const PER_PATCH_SUBSET_HINT = 'In --per-patch mode, positional arguments and --patches select patches (filename, stem, ' +
+    'order number, manifest name, or slug) — not engine files; drop --per-patch to lint engine paths.';
 /**
  * Lints each patch in the queue as its own isolated diff, honouring
  * per-patch `lintIgnore` entries. Cross-patch rules still run once over
@@ -382,7 +347,7 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
         return;
     }
     const subset = options.patches && options.patches.length > 0
-        ? selectPatchSubset(manifest, options.patches)
+        ? selectPatchSubset(manifest, options.patches, PER_PATCH_SUBSET_HINT)
         : manifest.patches;
     const subsetNames = new Set(subset.map((p) => p.filename));
     const isSubset = subset.length !== manifest.patches.length;
@@ -405,7 +370,11 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
     const cache = options.noCache === true ? undefined : await loadPerPatchLintCache(projectRoot);
     const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
     const issues = [];
-    for (const issue of evaluatePatchPolicy(config, manifest)) {
+    const policyIssues = [
+        ...evaluatePatchPolicy(config, manifest),
+        ...(await evaluatePatchPolicyContent(config, projectRoot, manifest, ctx.entries)),
+    ];
+    for (const issue of policyIssues) {
         if (isSubset && !subsetNames.has(issue.filename))
             continue;
         issues.push({
@@ -433,10 +402,12 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
     });
     const heldNotices = options.notices === 'summary' ? [] : undefined;
     const { linted, skipped, cacheDirty, reusedCacheEntries, suppressed } = await applyPerPatchResults(subset, results, issues, checkJs, cache, heldNotices);
+    const queueIssues = [];
     for (const issue of lintPatchQueue(ctx)) {
         if (isSubset && !subsetTouchedFiles.has(issue.file))
             continue;
         issues.push(issue);
+        queueIssues.push(issue);
     }
     if (cache && cacheDirty)
         await savePerPatchLintCache(projectRoot, cache);
@@ -447,7 +418,7 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
         info(`Suppressed ${suppressed} issue(s) via per-patch lintIgnore.`);
     }
     if (options.report !== undefined) {
-        await writePerPatchLintReport(options.report, subset, results);
+        await writePerPatchLintReport(options.report, subset, results, config, queueIssues);
     }
     reportPerPatchOutcome(issues, linted, skipped, options, heldNotices);
 }

package/dist/src/commands/lint-report.d.ts

@@ -1,4 +1,5 @@
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
 /**
  * Structural view of one per-patch lint outcome. Mirrors the relevant
  * fields of lint-per-patch's QueuedPatchResult without importing it:
@@ -14,8 +15,11 @@ export interface PerPatchReportResult {
 }
 /**
  * Writes the per-patch lint report JSON. Called after the per-patch
- * results are assembled in patch order. Queue-level and policy findings
- * are patch-attributed by their `file`/`filename` fields upstream and
- * are not duplicated here. The report is the per-patch view.
+ * results are assembled in patch order. Policy findings are
+ * patch-attributed by their `filename` field upstream and are not
+ * duplicated here. Cross-patch findings (`forward-import`,
+ * `forward-registration`, …) go in `queueIssues`, with the
+ * `stagedDeclarations` that discharge them, so the report can be handed to
+ * `patch staged-dependency --from` as is.
  */
-export declare function writePerPatchLintReport(reportPath: string, subset: readonly PatchMetadata[], results: readonly PerPatchReportResult[]): Promise<void>;
+export declare function writePerPatchLintReport(reportPath: string, subset: readonly PatchMetadata[], results: readonly PerPatchReportResult[], config: Pick<FireForgeConfig, 'patchLint'>, queueIssues?: readonly PatchLintIssue[]): Promise<void>;

package/dist/src/commands/lint-report.js

@@ -10,16 +10,21 @@
  * none is wanted.
  */
 import { getPatchSizeThresholds, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { evaluateLintIgnoreCeilings, } from '../core/patch-lint-ignore.js';
 import { writeJson } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
 const LINT_REPORT_SCHEMA_VERSION = 1;
 /**
  * Writes the per-patch lint report JSON. Called after the per-patch
- * results are assembled in patch order. Queue-level and policy findings
- * are patch-attributed by their `file`/`filename` fields upstream and
- * are not duplicated here. The report is the per-patch view.
+ * results are assembled in patch order. Policy findings are
+ * patch-attributed by their `filename` field upstream and are not
+ * duplicated here. Cross-patch findings (`forward-import`,
+ * `forward-registration`, …) go in `queueIssues`, with the
+ * `stagedDeclarations` that discharge them, so the report can be handed to
+ * `patch staged-dependency --from` as is.
  */
-export async function writePerPatchLintReport(reportPath, subset, results) {
+export async function writePerPatchLintReport(reportPath, subset, results, config, queueIssues = []) {
+    const metric = config.patchLint?.patchSizeMetric ?? 'diff';
     const patches = [];
     let errors = 0;
     let warnings = 0;
@@ -36,12 +41,16 @@ export async function writePerPatchLintReport(reportPath, subset, results) {
             filename: patch.filename,
             name: patch.name,
             status: result.status,
+            metric,
             lineCount: result.lineCount,
             filesAffected: patch.filesAffected.length,
             tier,
-            thresholds: getPatchSizeThresholds(tier.tier),
+            thresholds: getPatchSizeThresholds(tier.tier, config),
             issues: result.rawIssues,
             suppressedIssues: result.suppressedIssues,
+            lintIgnoreCeilings: result.status === 'skipped'
+                ? []
+                : evaluateLintIgnoreCeilings(patch.lintIgnore, [...result.rawIssues, ...result.suppressedIssues], { lines: result.lineCount, files: patch.filesAffected.length }),
         });
         if (result.status === 'skipped')
             skipped++;
@@ -55,6 +64,7 @@ export async function writePerPatchLintReport(reportPath, subset, results) {
         schemaVersion: LINT_REPORT_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
         patches,
+        queueIssues,
         totals: { linted, skipped, errors, warnings, suppressed },
     });
     info(`Per-patch lint report written to ${reportPath}.`);

package/dist/src/commands/lint.js

@@ -10,9 +10,10 @@ import { getStatusWithCodes, hasChanges } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildPatchQueueContext, countNonBinaryDiffLines, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, lintPatchSize, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, lintPatchSize, measurePatchSize, } from '../core/patch-lint.js';
 import { clearPerPatchLintCache } from '../core/patch-lint-cache.js';
 import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
+import { buildLintIgnoreChecks, filterLintIgnoredByOwners, partitionLintIgnoredIssues, } from '../core/patch-lint-ignore.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
@@ -186,25 +187,7 @@ function buildMaxWarningsMessage(count, maxWarnings, scope) {
  * @returns Filtered issue list and the count of dropped findings.
  */
 export function applyAggregateLintIgnoreSuppression(issues, ctx) {
-    const suppressionsByFile = new Map();
-    for (const entry of ctx.entries) {
-        const ignoreList = entry.metadata?.lintIgnore;
-        if (!ignoreList || ignoreList.length === 0)
-            continue;
-        for (const f of entry.metadata?.filesAffected ?? []) {
-            let bucket = suppressionsByFile.get(f);
-            if (!bucket) {
-                bucket = new Set();
-                suppressionsByFile.set(f, bucket);
-            }
-            for (const id of ignoreList)
-                bucket.add(id);
-        }
-    }
-    if (suppressionsByFile.size === 0) {
-        return { issues, dropped: 0 };
-    }
-    const filtered = issues.filter((issue) => !suppressionsByFile.get(issue.file)?.has(issue.check));
+    const filtered = filterLintIgnoredByOwners(issues, ctx.entries.map((entry) => entry.metadata));
     return { issues: filtered, dropped: issues.length - filtered.length };
 }
 /**
@@ -283,7 +266,7 @@ function downgradeAggregateSizeRules(issues, files, ctx) {
  * @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) {
+async function lintOwningPatchSizes(engineDir, filesAffected, ctx, config) {
     const listed = new Set(filesAffected);
     const owners = new Map();
     const ownedListed = new Set();
@@ -302,26 +285,24 @@ async function lintOwningPatchSizes(engineDir, filesAffected, ctx) {
             owners.set(entry.filename, entry);
     }
     const issues = [];
-    const lineCountForFiles = async (relPaths) => {
+    const sizeForFiles = 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;
+        const diff = existing.length > 0 ? await getDiffForFilesAgainstHead(engineDir, existing) : '';
+        // The file count stays the owner's whole `filesAffected`, as before.
+        return measurePatchSize(engineDir, diff, relPaths, config);
     };
     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;
+        const size = await sizeForFiles(md.filesAffected);
+        const ignore = buildLintIgnoreChecks(md.lintIgnore);
+        const sized = lintPatchSize(md.filesAffected, size, md.tier, config);
+        for (const issue of partitionLintIgnoredIssues(sized, ignore).kept) {
             issues.push({ ...issue, message: `${entry.filename}: ${issue.message}` });
         }
     }
@@ -329,8 +310,8 @@ async function lintOwningPatchSizes(engineDir, filesAffected, ctx) {
     // 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));
+        const size = await sizeForFiles(unowned);
+        issues.push(...lintPatchSize(unowned, size, undefined, config));
     }
     return issues;
 }
@@ -460,7 +441,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
         })),
     ];
     if (files.length > 0 && ctx) {
-        issues.push(...(await lintOwningPatchSizes(paths.engine, filesAffected, ctx)));
+        issues.push(...(await lintOwningPatchSizes(paths.engine, filesAffected, ctx, config)));
     }
     // Cross-patch rules operate over the whole queue, so run them whenever a
     // patches directory exists. They surface duplicate /dev/null creations

package/dist/src/commands/manifest.js

@@ -1,5 +1,6 @@
 import { registerBootstrap } from './bootstrap.js';
 import { registerBuild } from './build.js';
+import { registerCheck } from './check.js';
 import { registerConfig } from './config.js';
 import { registerDiscard } from './discard.js';
 import { registerDoctor } from './doctor.js';
@@ -60,5 +61,6 @@ export const COMMAND_MANIFEST = [
     { name: 'lint', group: 'diagnostics', register: registerLint },
     { name: 'typecheck', group: 'diagnostics', register: registerTypecheck },
     { name: 'verify', group: 'diagnostics', register: registerVerify },
+    { name: 'check', group: 'diagnostics', register: registerCheck },
     { name: 'furnace', group: 'components', register: registerFurnace },
 ];

package/dist/src/commands/patch/delete-gap-notice.js

@@ -42,5 +42,7 @@ function formatGapNotice(targetFilename, message) {
     const where = orders ? `a gap at ${orders}` : 'a numeric gap';
     return (`deleting ${targetFilename} leaves ${range} with ${where}; the queue will fail ` +
         'numeric-gap (patchPolicy.allowGaps is false) until ' +
-        `"fireforge export --order ${fill}" fills it or "fireforge patch compact" renumbers.`);
+        `"fireforge export --order ${fill}" fills it or "fireforge patch compact" renumbers. ` +
+        `"fireforge patch retire ${targetFilename}" removes the patch and keeps its order as a ` +
+        'retired slot instead, so no gap opens.');
 }

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

@@ -4,7 +4,7 @@
  * Destructive: refuses when a later patch imports a module owned by the
  * target (that would leave a dangling forward import), prompts for
  * confirmation interactively, requires `--yes` for non-TTY, supports
- * `--dry-run`, and appends to `patches/.fireforge-history.jsonl` on success.
+ * `--dry-run`, and appends to the patch history log on success.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

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

@@ -5,14 +5,13 @@
  * Destructive: refuses when a later patch imports a module owned by the
  * target (that would leave a dangling forward import), prompts for
  * confirmation interactively, requires `--yes` for non-TTY, supports
- * `--dry-run`, and appends to `patches/.fireforge-history.jsonl` on success.
+ * `--dry-run`, and appends to the patch history log on success.
  */
-import { basename } from 'node:path';
 import { Command } from 'commander';
 import { loadConfig } from '../../core/config.js';
 import { confirmDestructive } from '../../core/destructive.js';
 import { appendHistoryBestEffort } from '../../core/history-log.js';
-import { buildPatchQueueContext, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
+import { buildPatchQueueContext } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { removePatchFileAndManifest } from '../../core/patch-manifest.js';
 import { GeneralError } from '../../errors/base.js';
@@ -21,6 +20,7 @@ import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../ut
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { describeProjectedGaps } from './delete-gap-notice.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { collectRemovalDependents, queueSnapshot, removalConflict, warnDanglingStagedOwners, } from './removal-dependents.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
@@ -37,81 +37,15 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     });
     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.
+    // without re-parsing for the dependency check below. Hard refusal: an
+    // import owned by a later patch that points at any of the target's
+    // newly-created files is a dependency on the target.
     const baseCtx = await buildPatchQueueContext(paths.patches);
-    // Hard refusal: an import owned by a later patch that points at any of
-    // the target's newly-created files is a dependency on the target. That
-    // check is built directly from `baseCtx` rather than by diffing lint runs
-    // over a projected state.
-    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 deletion. Re-run patch delete to review the current target.');
-    }
-    const targetNewFileLeaves = new Set();
-    for (const fullPath of targetEntry.newFiles.keys()) {
-        targetNewFileLeaves.add(basename(fullPath));
-    }
-    // Scan every later patch's new files and its added lines on pre-existing
-    // files for import specifiers that resolve to a leaf owned by the target.
-    // Uses the shared specifier extractor so dynamic `import()` and
-    // `ChromeUtils.defineESModuleGetters` are picked up: the forward-import
-    // lint rule already covers those forms, and delete safety must match the
-    // same set or it silently drops dependencies.
-    //
-    // 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.
-    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;
-        }
-    }
-    // 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 dependents = collectRemovalDependents(baseCtx, target, {
+        noun: 'deletion',
+        verb: 'delete',
+    });
+    warnDanglingStagedOwners(baseCtx, target, 'delete');
     // Under `patchPolicy.allowGaps: false` the removal can open a numeric gap
     // that every later lint and re-export refuses on. Naming it here, in
     // dry-run and at the prompt, puts the refill/compact choice in front of
@@ -120,20 +54,7 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     for (const line of gapNotices) {
         warn(line);
     }
-    const conflicts = dependents.length > 0
-        ? {
-            // 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.
-            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,
-        }
-        : null;
+    const conflicts = removalConflict(dependents, target);
     const summary = [
         `delete ${target.filename}  (category: ${target.category}, order: ${target.order})`,
         `description: ${target.description || '(none)'}`,
@@ -164,15 +85,9 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     // failure to the caller would mislead.
     await withPatchDirectoryLock(paths.patches, async () => {
         const current = await buildPatchQueueContext(paths.patches);
-        const snapshot = (context) => JSON.stringify(context.entries.map(({ filename, order, diff, metadata }) => ({
-            filename,
-            order,
-            diff,
-            metadata,
-        })));
         // A changed body or manifest invalidates the dependency scan approved
         // before the prompt. Recheck all of its inputs while holding the lock.
-        if (snapshot(current) !== snapshot(baseCtx)) {
+        if (queueSnapshot(current) !== queueSnapshot(baseCtx)) {
             throw new GeneralError('Patch queue changed while waiting for confirmation or the lock. Re-run patch delete to review the current dependencies.');
         }
         await removePatchFileAndManifest(paths.patches, target.filename);

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

@@ -1,7 +1,7 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch mutations and
  * planners (`compact`, `delete`, `lint-ignore`, `move-files`, `rename`,
- * `reorder`, `staged-dependency`, `tier`) so they do not clutter the
+ * `reorder`, `retire`, `staged-dependency`, `tier`) so they do not clutter the
  * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
  * and `status` stay flat.
  */

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

@@ -2,7 +2,7 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch mutations and
  * planners (`compact`, `delete`, `lint-ignore`, `move-files`, `rename`,
- * `reorder`, `staged-dependency`, `tier`) so they do not clutter the
+ * `reorder`, `retire`, `staged-dependency`, `tier`) so they do not clutter the
  * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
  * and `status` stay flat.
  */
@@ -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 { registerPatchRetire } from './retire.js';
 import { registerPatchSplit } from './split.js';
 import { registerPatchStagedDependency } from './staged-dependency.js';
 import { registerPatchTier } from './tier.js';
@@ -25,7 +26,7 @@ import { registerPatchTier } from './tier.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, lint-ignore, move-files, rename, reorder, staged-dependency, tier)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, move-files, rename, reorder, retire, staged-dependency, tier)')
         // Match `fireforge furnace`'s no-args contract: print the group's help
         // and exit 0. Without this default action, commander routes
         // `fireforge patch` (no subcommand) through its own help-then-exit-1
@@ -40,6 +41,7 @@ export function registerPatch(program, context) {
     registerPatchMoveFiles(patch, context);
     registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchRetire(patch, context);
     registerPatchSplit(patch, context);
     registerPatchStagedDependency(patch, context);
     registerPatchTier(patch, context);

package/dist/src/commands/patch/lint-ignore.d.ts

@@ -11,7 +11,11 @@
  *   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