@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/core/patch-manifest-io.js

@@ -20,6 +20,7 @@ import { warn } from '../utils/logger.js';
 import { isArray, isObject } from '../utils/validation.js';
 import { assertPatchDirectoryLockHeld } from './patch-lock.js';
 import { validatePatchesManifest } from './patch-manifest-validate.js';
+import { manifestWithRetiredSlots } from './patch-retired.js';
 /** Filename for the patches manifest */
 export const PATCHES_MANIFEST = 'patches.json';
 /**
@@ -171,7 +172,8 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
     // Add new entry and sort by order
     manifest.patches.push(metadata);
     manifest.patches.sort((a, b) => a.order - b.order);
-    await savePatchesManifest(patchesDir, manifest);
+    // A patch landing on a retired order fills that slot.
+    await savePatchesManifest(patchesDir, manifestWithRetiredSlots(manifest, manifest.patches));
 }
 /**
  * Removes a single patch entry from the manifest by filename. Leaves the
@@ -184,10 +186,11 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
  *
  * @param patchesDir - Path to the patches directory
  * @param filename - Filename of the patch to remove from the manifest
+ * @param retiredSlot - Optional placeholder to record for the removed order
  * @returns True when the manifest was written (i.e. an entry was removed),
  *   false when no matching entry existed
  */
-export async function removePatchFromManifest(patchesDir, filename) {
+export async function removePatchFromManifest(patchesDir, filename, retiredSlot) {
     const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest)
         return false;
@@ -196,6 +199,14 @@ export async function removePatchFromManifest(patchesDir, filename) {
     if (manifest.patches.length === originalLength) {
         return false;
     }
+    if (retiredSlot !== undefined) {
+        // `patch retire`: the row leaves and its order stays spent, in the
+        // same write, so no reader ever sees the gap in between.
+        manifest.retired = [
+            ...(manifest.retired ?? []).filter((slot) => slot.order !== retiredSlot.order),
+            retiredSlot,
+        ].sort((a, b) => a.order - b.order);
+    }
     await savePatchesManifest(patchesDir, manifest);
     return true;
 }
@@ -436,10 +447,8 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         // try, so a violation unwinds through the Phase 3 rollback that puts the
         // filenames back.
         assertRenumberedOrderIsWellFormed(updatedPatches);
-        await savePatchesManifest(patchesDir, {
-            ...manifest,
-            patches: updatedPatches,
-        });
+        // A patch renumbered onto a retired order fills that slot.
+        await savePatchesManifest(patchesDir, manifestWithRetiredSlots(manifest, updatedPatches));
     }
     catch (error) {
         // Phase 3 rollback: reverse every completed rename. The manifest
@@ -504,14 +513,16 @@ export class PatchDeleteRollbackError extends FireForgeError {
  *
  * @param patchesDir - Path to the patches directory
  * @param filename - Patch filename to delete
+ * @param retiredSlot - When set (`patch retire`), the placeholder written in
+ *   the same manifest update that removes the row
  */
-export async function removePatchFileAndManifest(patchesDir, filename) {
+export async function removePatchFileAndManifest(patchesDir, filename, retiredSlot) {
     await assertPatchDirectoryLockHeld(patchesDir, 'deleting a patch and its manifest row');
     const patchPath = join(patchesDir, filename);
     // ForWrite: deleting the patch file while a corrupt manifest still
     // references it would strand the queue. Abort on corruption instead.
     const originalManifest = await loadPatchesManifestForWrite(patchesDir);
-    const removedFromManifest = await removePatchFromManifest(patchesDir, filename);
+    const removedFromManifest = await removePatchFromManifest(patchesDir, filename, retiredSlot);
     try {
         if (await pathExistsStrict(patchPath)) {
             await removeFile(patchPath);

package/dist/src/core/patch-manifest-validate.js

@@ -4,6 +4,7 @@
  */
 import { parseObject } from '../utils/parse.js';
 import { isArray, isObject, isValidFirefoxProduct, isValidFirefoxVersion, PATCH_CATEGORIES, } from '../utils/validation.js';
+import { parseLintIgnoreEntries } from './patch-lint-ignore.js';
 import { checkDocumentVersion, describeNewerDocument } from './state-file.js';
 function parseForwardImports(data, label) {
     if (!isArray(data)) {
@@ -99,7 +100,11 @@ function validatePatchMetadata(data, index) {
     // `lintIgnore` to suppress a rule is quietly re-tripped the next time the
     // manifest validates. Preserve both `lintIgnore` and `tier` here. Future
     // optional fields follow the same template.
-    const lintIgnore = rec.optionalStringArray('lintIgnore');
+    // Entries are bare check IDs or `{ rule, max, reason }` ceilings.
+    const rawLintIgnore = rec.raw('lintIgnore');
+    const lintIgnore = rawLintIgnore === undefined
+        ? undefined
+        : parseLintIgnoreEntries(rawLintIgnore, `patches[${index}].lintIgnore`);
     const rawTier = rec.raw('tier');
     let tier;
     if (rawTier !== undefined) {
@@ -131,6 +136,30 @@ function validatePatchMetadata(data, index) {
     }
     return result;
 }
+/**
+ * Validates the `retired` placeholders `patch retire` leaves behind. Kept on
+ * the manifest so every write that round-trips a loaded manifest carries
+ * them; dropping them would silently reopen the gaps they were retired to
+ * close.
+ */
+function parseRetiredSlots(data) {
+    if (!isArray(data)) {
+        throw new Error('patches.json field "retired" must be an array');
+    }
+    return data.map((entry, index) => {
+        const rec = parseObject(entry, `retired[${index}]`);
+        const slot = {
+            order: rec.nonNegativeInteger('order'),
+            category: rec.validatedString('category', (value) => /^[a-z][a-z0-9-]*$/.test(value), 'a lowercase category identifier (letters, numbers, hyphens)'),
+            filename: rec.string('filename'),
+            retiredAt: rec.string('retiredAt'),
+        };
+        const reason = rec.optionalString('reason');
+        if (reason !== undefined)
+            slot.reason = reason;
+        return slot;
+    });
+}
 /** Manifest schema version this build writes and understands. */
 const PATCHES_MANIFEST_VERSION = 1;
 /**
@@ -156,10 +185,13 @@ export function validatePatchesManifest(data) {
     if (!isArray(data['patches'])) {
         throw new Error('patches.json field "patches" must be an array');
     }
-    return {
+    const manifest = {
         version: 1,
         patches: data['patches'].map((patch, index) => validatePatchMetadata(patch, index)),
     };
+    if (data['retired'] !== undefined)
+        manifest.retired = parseRetiredSlots(data['retired']);
+    return manifest;
 }
 /**
  * Infers patch metadata from a filename pattern.

package/dist/src/core/patch-order-legal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The earliest order a new patch can take after a given order, under the
+ * queue's occupancy and `patchPolicy`.
+ *
+ * A refusal that says "export it as its own later patch" leaves the
+ * operator to find a number that is free, inside the category's range, and
+ * (with `allowGaps: false`) does not open a gap. Each wrong guess costs a
+ * full export attempt. This answers it once, with the same policy
+ * evaluation the export itself will run.
+ */
+import type { PatchesManifest } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Smallest order strictly greater than `after` that no patch occupies and
+ * that adds no order-related `patchPolicy` finding (collision, category
+ * range, reserved range, numeric gap) for a `category` patch. A retired
+ * slot counts as free, since a patch may fill it. Returns null when no such
+ * order exists inside the category's configured ranges.
+ *
+ * @param config - Project config (only `patchPolicy` is read)
+ * @param manifest - Current manifest
+ * @param category - Category the new patch would carry
+ * @param after - The order the new patch must come after
+ */
+export declare function earliestLegalOrderAfter(config: Pick<FireForgeConfig, 'patchPolicy'>, manifest: PatchesManifest, category: string, after: number): number | null;

package/dist/src/core/patch-order-legal.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The earliest order a new patch can take after a given order, under the
+ * queue's occupancy and `patchPolicy`.
+ *
+ * A refusal that says "export it as its own later patch" leaves the
+ * operator to find a number that is free, inside the category's range, and
+ * (with `allowGaps: false`) does not open a gap. Each wrong guess costs a
+ * full export attempt. This answers it once, with the same policy
+ * evaluation the export itself will run.
+ */
+import { formatPatchOrder } from './patch-parse.js';
+import { evaluatePatchPolicy } from './patch-policy.js';
+/** Policy codes an order choice alone can trip. */
+const ORDER_CODES = new Set([
+    'order-collision',
+    'category-range',
+    'reserved-range',
+    'numeric-gap',
+]);
+/** Upper bound on the search when no policy range bounds it. */
+const UNBOUNDED_SEARCH = 1000;
+const GAP_ORDERS_PATTERN = /numeric gap\(s\): (?<orders>[^.]+)\./;
+/**
+ * Order-related findings as comparable keys. A `numeric-gap` finding
+ * becomes one key per missing order, so filling one gap of several reads as
+ * removing a key rather than as a new, differently worded finding.
+ */
+function orderIssueKeys(config, manifest) {
+    const keys = new Set();
+    for (const issue of evaluatePatchPolicy(config, manifest)) {
+        if (!ORDER_CODES.has(issue.code))
+            continue;
+        const gaps = issue.code === 'numeric-gap' ? GAP_ORDERS_PATTERN.exec(issue.message) : null;
+        if (gaps?.groups?.['orders'] === undefined) {
+            keys.add(`${issue.code}|${issue.message}`);
+            continue;
+        }
+        for (const order of gaps.groups['orders'].split(',')) {
+            keys.add(`numeric-gap|${issue.filename}|${order.trim()}`);
+        }
+    }
+    return keys;
+}
+/**
+ * Smallest order strictly greater than `after` that no patch occupies and
+ * that adds no order-related `patchPolicy` finding (collision, category
+ * range, reserved range, numeric gap) for a `category` patch. A retired
+ * slot counts as free, since a patch may fill it. Returns null when no such
+ * order exists inside the category's configured ranges.
+ *
+ * @param config - Project config (only `patchPolicy` is read)
+ * @param manifest - Current manifest
+ * @param category - Category the new patch would carry
+ * @param after - The order the new patch must come after
+ */
+export function earliestLegalOrderAfter(config, manifest, category, after) {
+    const occupied = new Set(manifest.patches.map((patch) => patch.order));
+    const ranges = config.patchPolicy?.ranges.filter((range) => range.category === category) ?? [];
+    const limit = ranges.length > 0 ? Math.max(...ranges.map((range) => range.to)) : after + UNBOUNDED_SEARCH;
+    const baseline = config.patchPolicy ? orderIssueKeys(config, manifest) : new Set();
+    for (let order = after + 1; order <= limit; order++) {
+        if (occupied.has(order))
+            continue;
+        if (!config.patchPolicy)
+            return order;
+        const probe = {
+            filename: `${formatPatchOrder(order)}-${category}-probe.patch`,
+            order,
+            category,
+            name: 'probe',
+            description: 'probe',
+            createdAt: '',
+            sourceEsrVersion: '',
+            filesAffected: [],
+        };
+        const projected = { ...manifest, patches: [...manifest.patches, probe] };
+        const introduced = [...orderIssueKeys(config, projected)].filter((key) => !baseline.has(key));
+        if (introduced.length === 0)
+            return order;
+    }
+    return null;
+}

package/dist/src/core/patch-policy-content.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Registration-only patch policy: the `patchPolicy` rules that need the
+ * patch bodies, not just the manifest.
+ *
+ * - `upstreamAllowlist`: which upstream files (files no patch in the queue
+ *   creates) a non-reserved patch may modify.
+ * - `addOnly` allowlist entries: for shared registration files, a patch may
+ *   only add lines, and each non-blank added line must carry the marker.
+ * - `scopeRules`: limit a class of patch (a category, or a filename pattern
+ *   such as `-tests\.patch$`) to the files its globs name.
+ * - `verifyDocumentPaths`: every reserved allowlist entry's `adr` /
+ *   `documentation` path must exist.
+ *
+ * Every rule is opt-in, and none can be evaluated from `patches.json`
+ * alone, which is why they live apart from `patch-policy.ts`: that module
+ * answers synchronously over a (possibly projected) manifest, this one reads
+ * patch bodies and the filesystem. `verify` and `lint --per-patch` run both.
+ */
+import type { PatchesManifest } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type PatchQueueEntry } from './patch-lint-cross.js';
+import type { PatchPolicyIssue } from './patch-policy.js';
+/** True when the policy sets any rule this module evaluates. */
+export declare function hasPatchPolicyContentRules(config: FireForgeConfig): boolean;
+/**
+ * Evaluates the body-dependent `patchPolicy` rules over a patch queue.
+ *
+ * @param config - Project configuration
+ * @param projectRoot - Project root, for the document-path check
+ * @param manifest - Current manifest (category and order per patch)
+ * @param entries - Patch queue entries with their bodies
+ * @returns Findings, in the same shape {@link evaluatePatchPolicy} returns
+ */
+export declare function evaluatePatchPolicyContent(config: FireForgeConfig, projectRoot: string, manifest: PatchesManifest, entries: readonly PatchQueueEntry[]): Promise<PatchPolicyIssue[]>;
+/**
+ * {@link evaluatePatchPolicyContent} for a caller without a queue context
+ * in hand (`verify`): reads the patch bodies only when a body-dependent
+ * rule is configured.
+ */
+export declare function evaluatePatchPolicyContentForQueue(config: FireForgeConfig, projectRoot: string, patchesDir: string, manifest: PatchesManifest): Promise<PatchPolicyIssue[]>;

package/dist/src/core/patch-policy-content.js

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Registration-only patch policy: the `patchPolicy` rules that need the
+ * patch bodies, not just the manifest.
+ *
+ * - `upstreamAllowlist`: which upstream files (files no patch in the queue
+ *   creates) a non-reserved patch may modify.
+ * - `addOnly` allowlist entries: for shared registration files, a patch may
+ *   only add lines, and each non-blank added line must carry the marker.
+ * - `scopeRules`: limit a class of patch (a category, or a filename pattern
+ *   such as `-tests\.patch$`) to the files its globs name.
+ * - `verifyDocumentPaths`: every reserved allowlist entry's `adr` /
+ *   `documentation` path must exist.
+ *
+ * Every rule is opt-in, and none can be evaluated from `patches.json`
+ * alone, which is why they live apart from `patch-policy.ts`: that module
+ * answers synchronously over a (possibly projected) manifest, this one reads
+ * patch bodies and the filesystem. `verify` and `lint --per-patch` run both.
+ */
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { matchesAnyGlob } from '../utils/path-glob.js';
+import { buildPatchQueueContext } from './patch-lint-cross.js';
+import { parseDiffSections } from './patch-parse.js';
+/** True when the policy sets any rule this module evaluates. */
+export function hasPatchPolicyContentRules(config) {
+    const cfg = config.patchPolicy;
+    return (cfg !== undefined &&
+        (cfg.upstreamAllowlist !== undefined ||
+            cfg.scopeRules !== undefined ||
+            cfg.verifyDocumentPaths === true));
+}
+function normalizeAllowEntry(entry) {
+    return typeof entry === 'string' ? { path: entry } : entry;
+}
+function isReservedOrder(cfg, order) {
+    return (cfg.reservedRanges ?? []).some((range) => order >= range.from && order <= range.to);
+}
+/**
+ * The upstream files a patch body edits, keyed by path: every section that
+ * does not create its file, minus paths some patch in the queue creates. A
+ * rename counts against both of its paths.
+ */
+function collectUpstreamEdits(diff, queueCreated) {
+    const edits = new Map();
+    for (const section of parseDiffSections(diff)) {
+        if (section.isNewFile)
+            continue;
+        const paths = new Set([section.sourcePath, section.targetPath]);
+        for (const path of paths) {
+            if (queueCreated.has(path))
+                continue;
+            const edit = edits.get(path) ?? { added: [], removed: [], deleted: false, binary: false };
+            edit.deleted ||= section.isDeletedFile;
+            edit.binary ||= section.isBinary;
+            for (const hunk of section.hunks) {
+                for (const line of hunk.lines) {
+                    if (line.startsWith('+'))
+                        edit.added.push(line.slice(1));
+                    else if (line.startsWith('-'))
+                        edit.removed.push(line.slice(1));
+                }
+            }
+            edits.set(path, edit);
+        }
+    }
+    return edits;
+}
+/**
+ * Why an add-only file's edit breaks the mode, or undefined when it holds.
+ * Blank lines are free in both directions: they carry no registration.
+ */
+function addOnlyViolation(edit, marker) {
+    if (edit.deleted)
+        return 'deletes the file';
+    if (edit.binary)
+        return 'carries a binary change';
+    const removed = edit.removed.filter((line) => line.trim() !== '');
+    if (removed.length > 0) {
+        return `removes ${String(removed.length)} line(s), first: ${JSON.stringify(removed[0])}`;
+    }
+    const needle = marker.toLowerCase();
+    const unmarked = edit.added.filter((line) => line.trim() !== '' && !line.toLowerCase().includes(needle));
+    if (unmarked.length > 0) {
+        return (`adds ${String(unmarked.length)} line(s) without the "${marker}" marker, ` +
+            `first: ${JSON.stringify(unmarked[0])}`);
+    }
+    return undefined;
+}
+function evaluateUpstreamEdits(cfg, filename, edits, severity) {
+    const allowlist = (cfg.upstreamAllowlist ?? []).map(normalizeAllowEntry);
+    const issues = [];
+    const outside = [];
+    for (const [path, edit] of [...edits].sort(([a], [b]) => a.localeCompare(b))) {
+        const matches = allowlist.filter((entry) => matchesAnyGlob(path, [entry.path]));
+        if (matches.length === 0) {
+            outside.push(path);
+            continue;
+        }
+        // Strictest wins: any add-only match makes the file add-only.
+        const addOnly = matches.find((entry) => entry.addOnly === true);
+        if (!addOnly)
+            continue;
+        const marker = addOnly.marker ?? cfg.addOnlyMarker ?? '';
+        const violation = addOnlyViolation(edit, marker);
+        if (violation !== undefined) {
+            issues.push({
+                code: 'add-only',
+                filename,
+                severity,
+                message: `${filename} edits ${path}, which patchPolicy.upstreamAllowlist marks add-only ` +
+                    `(added lines carrying "${marker}"), but ${violation}.`,
+            });
+        }
+    }
+    if (outside.length > 0) {
+        issues.push({
+            code: 'upstream-allowlist',
+            filename,
+            severity,
+            message: `${filename} modifies upstream file(s) outside patchPolicy.upstreamAllowlist: ` +
+                `${outside.join(', ')}. Move the change into a fork-owned file, or add a reviewed allowlist entry.`,
+        });
+    }
+    return issues;
+}
+function evaluateScopeRules(cfg, filename, category, files, severity) {
+    const issues = [];
+    for (const [index, rule] of (cfg.scopeRules ?? []).entries()) {
+        if (rule.category !== undefined && rule.category !== category)
+            continue;
+        if (rule.filenamePattern !== undefined && !new RegExp(rule.filenamePattern).test(filename)) {
+            continue;
+        }
+        const outside = files.filter((file) => !matchesAnyGlob(file, rule.files));
+        if (outside.length === 0)
+            continue;
+        issues.push({
+            code: 'scope',
+            filename,
+            severity,
+            message: `${filename} is scoped by patchPolicy.scopeRules[${String(index)}] to ` +
+                `${rule.files.join(', ')}, but touches: ${outside.join(', ')}. ` +
+                'Move those files to a patch of the class that owns them.',
+        });
+    }
+    return issues;
+}
+async function evaluateDocumentPaths(cfg, projectRoot, severity) {
+    if (cfg.verifyDocumentPaths !== true)
+        return [];
+    const issues = [];
+    for (const range of cfg.reservedRanges ?? []) {
+        for (const allowed of range.allowed) {
+            for (const [field, path] of [
+                ['adr', allowed.adr],
+                ['documentation', allowed.documentation],
+            ]) {
+                if (path === undefined || (await pathExists(join(projectRoot, path))))
+                    continue;
+                issues.push({
+                    code: 'reserved-document-missing',
+                    filename: allowed.filename,
+                    severity,
+                    message: `${allowed.filename}'s reserved-range allowlist entry names ${field} "${path}", ` +
+                        'which does not exist. Restore the document or correct the path.',
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Evaluates the body-dependent `patchPolicy` rules over a patch queue.
+ *
+ * @param config - Project configuration
+ * @param projectRoot - Project root, for the document-path check
+ * @param manifest - Current manifest (category and order per patch)
+ * @param entries - Patch queue entries with their bodies
+ * @returns Findings, in the same shape {@link evaluatePatchPolicy} returns
+ */
+export async function evaluatePatchPolicyContent(config, projectRoot, manifest, entries) {
+    const cfg = config.patchPolicy;
+    if (!cfg || !hasPatchPolicyContentRules(config))
+        return [];
+    const severity = cfg.mutationMode === 'warn' ? 'warning' : 'error';
+    const queueCreated = new Set();
+    for (const entry of entries)
+        for (const file of entry.createdFiles)
+            queueCreated.add(file);
+    const bodies = new Map(entries.map((entry) => [entry.filename, entry.diff]));
+    const issues = [];
+    for (const patch of manifest.patches) {
+        const diff = bodies.get(patch.filename);
+        if (cfg.upstreamAllowlist !== undefined && diff !== undefined) {
+            if (!isReservedOrder(cfg, patch.order)) {
+                const edits = collectUpstreamEdits(diff, queueCreated);
+                issues.push(...evaluateUpstreamEdits(cfg, patch.filename, edits, severity));
+            }
+        }
+        issues.push(...evaluateScopeRules(cfg, patch.filename, patch.category, patch.filesAffected, severity));
+    }
+    issues.push(...(await evaluateDocumentPaths(cfg, projectRoot, severity)));
+    return issues;
+}
+/**
+ * {@link evaluatePatchPolicyContent} for a caller without a queue context
+ * in hand (`verify`): reads the patch bodies only when a body-dependent
+ * rule is configured.
+ */
+export async function evaluatePatchPolicyContentForQueue(config, projectRoot, patchesDir, manifest) {
+    if (!hasPatchPolicyContentRules(config))
+        return [];
+    const { entries } = await buildPatchQueueContext(patchesDir);
+    return evaluatePatchPolicyContent(config, projectRoot, manifest, entries);
+}

package/dist/src/core/patch-policy.d.ts

@@ -9,7 +9,7 @@
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig, PatchPolicyConfig, PatchPolicyRange } from '../types/config.js';
 /** Stable issue codes returned by patch policy evaluation. */
-export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
+export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap' | 'upstream-allowlist' | 'add-only' | 'scope' | 'reserved-document-missing';
 /** A single patch policy validation finding. */
 export interface PatchPolicyIssue {
     code: PatchPolicyIssueCode;
@@ -30,6 +30,15 @@ export interface PatchPolicyEnforcementInput {
      * `patch move-files --create`).
      */
     hints?: Partial<Record<PatchPolicyIssueCode, string>>;
+    /**
+     * Patch filenames whose findings this mutation answers for. When set, only
+     * issues attributed to these rows are enforced: queue-level findings
+     * (order collisions, numeric gaps) and other patches' findings are left to
+     * `verify` and `lint --per-patch`. For mutations that change only the
+     * scoped rows' contents (`re-export`), so one patch's stale row cannot fail
+     * an unrelated patch refreshed in the same call.
+     */
+    scope?: readonly string[];
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
@@ -49,8 +58,12 @@ export declare function categoryRangeLabel(ranges: readonly PatchPolicyRange[],
  */
 export declare function categoryRangeForOrder(cfg: PatchPolicyConfig, category: string, order: number): PatchPolicyRange | null;
 /** Evaluates an entire patch manifest against the configured policy. */
-export declare function evaluatePatchPolicy(config: FireForgeConfig, manifest: PatchesManifest): PatchPolicyIssue[];
-/** Builds a sorted manifest snapshot from projected patch metadata. */
+export declare function evaluatePatchPolicy(config: Pick<FireForgeConfig, 'patchPolicy'>, manifest: PatchesManifest): PatchPolicyIssue[];
+/**
+ * Builds a sorted manifest snapshot from projected patch metadata. Retired
+ * slots of `current` carry over unless a projected patch fills them, so a
+ * projection judges gaps the way the written manifest will.
+ */
 export declare function buildProjectedManifest(current: PatchesManifest | null, patches: PatchMetadata[]): PatchesManifest;
 /** Applies a filename/order rename projection to a manifest without mutating it. */
 export declare function applyRenameMapToManifest(manifest: PatchesManifest, renameMap: ReadonlyMap<string, {

package/dist/src/core/patch-policy.js

@@ -12,6 +12,7 @@ import { warn } from '../utils/logger.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
 import { rewriteStagedDependencyOwners } from './patch-manifest-io.js';
 import { formatOrderRange, formatPatchOrder } from './patch-parse.js';
+import { manifestWithRetiredSlots, retiredOrderSet } from './patch-retired.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
 const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
 function policy(config) {
@@ -222,7 +223,7 @@ function evaluatePatchMetadata(cfg, patch, severity) {
     }
     return issues;
 }
-function evaluateGaps(cfg, patches, severity) {
+function evaluateGaps(cfg, patches, severity, retiredOrders = new Set()) {
     if (cfg.allowGaps !== false)
         return [];
     const issues = [];
@@ -243,7 +244,11 @@ function evaluateGaps(cfg, patches, severity) {
         const last = occupied[occupied.length - 1];
         const missing = [];
         for (let order = first; order <= last; order++) {
-            if (!occupiedSet.has(order) && reservedRangeForOrder(cfg, order) === null) {
+            // A retired slot (`patch retire`) is an occupied order with no
+            // patch behind it: the number stays spent, so it is not a gap.
+            if (!occupiedSet.has(order) &&
+                !retiredOrders.has(order) &&
+                reservedRangeForOrder(cfg, order) === null) {
                 missing.push(order);
             }
         }
@@ -290,18 +295,19 @@ export function evaluatePatchPolicy(config, manifest) {
     const severity = mutationMode(config) === 'warn' ? 'warning' : 'error';
     const issues = manifest.patches.flatMap((patch) => evaluatePatchMetadata(cfg, patch, severity));
     issues.push(...evaluateOrderCollisions(manifest.patches, severity));
-    issues.push(...evaluateGaps(cfg, manifest.patches, severity));
+    issues.push(...evaluateGaps(cfg, manifest.patches, severity, retiredOrderSet(manifest)));
     return issues;
 }
-/** Builds a sorted manifest snapshot from projected patch metadata. */
+/**
+ * Builds a sorted manifest snapshot from projected patch metadata. Retired
+ * slots of `current` carry over unless a projected patch fills them, so a
+ * projection judges gaps the way the written manifest will.
+ */
 export function buildProjectedManifest(current, patches) {
     const next = patches
         .map((patch) => ({ ...patch, filesAffected: [...patch.filesAffected] }))
         .sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    return {
-        version: current?.version ?? 1,
-        patches: next,
-    };
+    return manifestWithRetiredSlots(current, next);
 }
 /** Applies a filename/order rename projection to a manifest without mutating it. */
 export function applyRenameMapToManifest(manifest, renameMap) {
@@ -325,7 +331,8 @@ export function applyRenameMapToManifest(manifest, renameMap) {
 export function enforcePatchPolicy(input) {
     if (policy(input.config) === undefined)
         return;
-    const issues = evaluatePatchPolicy(input.config, input.manifest);
+    const scope = input.scope === undefined ? undefined : new Set(input.scope);
+    const issues = evaluatePatchPolicy(input.config, input.manifest).filter((issue) => scope === undefined || scope.has(issue.filename));
     if (issues.length === 0)
         return;
     const mode = mutationMode(input.config);

package/dist/src/core/patch-retired.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Retired order slots: the placeholders `patch retire` leaves in
+ * `patches.json#retired` so a patch can leave the queue without opening a
+ * numeric gap or renumbering its successors.
+ *
+ * A slot is not a patch. It has no `.patch` file and no row in `patches`,
+ * so everything that applies, exports, lints or rebases the queue walks past
+ * it without knowing it exists. The one reader is the
+ * `patchPolicy.allowGaps: false` gap check, which counts a retired order as
+ * occupied. A patch that later takes the same order fills the slot, and
+ * {@link carryRetiredSlots} drops it on that write, so the manifest never
+ * holds a slot and a patch at one order.
+ */
+import type { PatchesManifest, PatchMetadata, PatchRetiredSlot } from '../types/commands/index.js';
+/**
+ * The retired slots of `current` that no patch in `patches` occupies, or
+ * undefined when none remain. Every manifest write that rebuilds the
+ * `patches` list routes the slots through here, so a slot survives the
+ * rewrite and a filled one does not.
+ *
+ * @param current - Manifest the slots come from (null or slot-free: none)
+ * @param patches - The rows the written manifest will hold
+ */
+export declare function carryRetiredSlots(current: Pick<PatchesManifest, 'retired'> | null | undefined, patches: readonly Pick<PatchMetadata, 'order'>[]): PatchRetiredSlot[] | undefined;
+/**
+ * Builds a manifest from `patches` that keeps `current`'s unfilled retired
+ * slots. The `retired` key is omitted entirely when no slot remains, so a
+ * queue that never retired anything writes the same JSON as before.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export declare function manifestWithRetiredSlots(current: Pick<PatchesManifest, 'retired'> | null | undefined, patches: PatchMetadata[]): PatchesManifest;
+/** The set of order numbers held by retired slots. */
+export declare function retiredOrderSet(manifest: Pick<PatchesManifest, 'retired'>): Set<number>;