@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -2,9 +2,9 @@
 /**
  * `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
- * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
- * and `status` stay flat.
+ * `reorder`, `reserve`, `retire`, `split`, `stage`, `staged-dependency`,
+ * `tier`) so they do not clutter the top-level command list. Queue-level
+ * verbs like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { Command } from 'commander';
 import { registerPatchCompact } from './compact.js';
@@ -13,7 +13,10 @@ import { registerPatchLintIgnore } from './lint-ignore.js';
 import { registerPatchMoveFiles } from './move-files.js';
 import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
+import { registerPatchReserve } from './reserve.js';
+import { registerPatchRetire } from './retire.js';
 import { registerPatchSplit } from './split.js';
+import { registerPatchStage } from './stage.js';
 import { registerPatchStagedDependency } from './staged-dependency.js';
 import { registerPatchTier } from './tier.js';
 /**
@@ -25,7 +28,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, reserve, retire, split, stage, 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,7 +43,10 @@ export function registerPatch(program, context) {
     registerPatchMoveFiles(patch, context);
     registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchReserve(patch, context);
+    registerPatchRetire(patch, context);
     registerPatchSplit(patch, context);
+    registerPatchStage(patch, context);
     registerPatchStagedDependency(patch, context);
     registerPatchTier(patch, context);
 }

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

@@ -0,0 +1,44 @@
+/**
+ * Batch and per-entry input for `patch lint-ignore --add`. Split out of
+ * `lint-ignore.ts` for the per-file line budget.
+ *
+ * A rebaseline that sets a ceiling per rule used to take one call per rule,
+ * each taking the patch lock and rewriting `patches.json` (138 calls on one
+ * consumer's queue), because `--max` applied to every `--add` of a call.
+ * Two forms lift that:
+ *
+ * - `--add <rule>=<max>` gives each entry its own ceiling in one call.
+ * - `--from <json-file>` reads every entry from a file, under one lock hold
+ *   and one write. The file is a JSON array of entries (a check ID string,
+ *   or `{ rule, max, reason?, share?, meta?, patch? }`), or a
+ *   `lint --per-patch --report` document, whose `lintIgnoreCeilings` rows
+ *   for the target patch are rebaselined to their current measurement.
+ */
+import type { LintIgnoreEntry, PatchLintIgnoreOptions, PatchSizeShare } from '../../types/commands/index.js';
+/**
+ * Turns `--add` values into entries: `<rule>=<max>` is a ceiling at `max`,
+ * a bare ID is a ceiling at `--max` when that is given and a bare waiver
+ * otherwise. Every ceiling takes `--reason` (required) and `--share`.
+ *
+ * @param ids - The `--add` values
+ * @param options - Command options (`max`, `reason`, `share`)
+ * @returns The entries to upsert
+ */
+export declare function resolveAddEntries(ids: readonly string[], options: Pick<PatchLintIgnoreOptions, 'max' | 'reason' | 'share'>): LintIgnoreEntry[];
+/** Entries read from a `--from` file for one target patch. */
+export interface LintIgnoreBatch {
+    entries: LintIgnoreEntry[];
+    /** Entries naming a different patch, left out. */
+    skippedForOtherPatches: number;
+}
+/**
+ * Reads a `--from` file into entries for `targetFilename`.
+ *
+ * @param path - JSON file path
+ * @param targetFilename - The patch the command edits
+ * @param defaultReason - `--reason`, used for object entries without one
+ * @returns The validated entries and the count left out for other patches
+ */
+export declare function readLintIgnoreBatch(path: string, targetFilename: string, defaultReason: string | undefined): Promise<LintIgnoreBatch>;
+/** Parses `--share`. */
+export declare function parseShare(value: string): PatchSizeShare;

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

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Batch and per-entry input for `patch lint-ignore --add`. Split out of
+ * `lint-ignore.ts` for the per-file line budget.
+ *
+ * A rebaseline that sets a ceiling per rule used to take one call per rule,
+ * each taking the patch lock and rewriting `patches.json` (138 calls on one
+ * consumer's queue), because `--max` applied to every `--add` of a call.
+ * Two forms lift that:
+ *
+ * - `--add <rule>=<max>` gives each entry its own ceiling in one call.
+ * - `--from <json-file>` reads every entry from a file, under one lock hold
+ *   and one write. The file is a JSON array of entries (a check ID string,
+ *   or `{ rule, max, reason?, share?, meta?, patch? }`), or a
+ *   `lint --per-patch --report` document, whose `lintIgnoreCeilings` rows
+ *   for the target patch are rebaselined to their current measurement.
+ */
+import { LINT_IGNORE_CEILING_RULES, parseLintIgnoreEntries } from '../../core/patch-lint-ignore.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readJson } from '../../utils/fs.js';
+import { isArray, isObject } from '../../utils/validation.js';
+const RULE_MAX_PATTERN = /^(?<rule>[^=\s]+)=(?<max>[1-9]\d*)$/;
+/**
+ * Turns `--add` values into entries: `<rule>=<max>` is a ceiling at `max`,
+ * a bare ID is a ceiling at `--max` when that is given and a bare waiver
+ * otherwise. Every ceiling takes `--reason` (required) and `--share`.
+ *
+ * @param ids - The `--add` values
+ * @param options - Command options (`max`, `reason`, `share`)
+ * @returns The entries to upsert
+ */
+export function resolveAddEntries(ids, options) {
+    const parsed = ids.map((id) => {
+        if (id.includes('=')) {
+            const match = RULE_MAX_PATTERN.exec(id);
+            if (match?.groups === undefined) {
+                throw new InvalidArgumentError(`--add ${id}: expected <rule>=<max> with a positive integer max.`, '--add');
+            }
+            return { rule: match.groups['rule'], max: Number(match.groups['max']) };
+        }
+        return { rule: id, max: options.max };
+    });
+    const ceilings = parsed.filter((entry) => entry.max !== undefined);
+    if (ceilings.length === 0) {
+        if (options.reason !== undefined || options.share !== undefined) {
+            throw new InvalidArgumentError('--reason and --share apply to ceilings: pass --max <n> or --add <rule>=<max>.', options.reason !== undefined ? '--reason' : '--share');
+        }
+        return parsed.map((entry) => entry.rule);
+    }
+    if (options.reason === undefined || options.reason.trim() === '') {
+        throw new InvalidArgumentError('A lintIgnore ceiling needs --reason <text> (with --max <n> or --add <rule>=<max>).', '--reason');
+    }
+    const unmeasured = ceilings.filter((entry) => !LINT_IGNORE_CEILING_RULES.includes(entry.rule));
+    if (unmeasured.length > 0) {
+        throw new InvalidArgumentError(`A ceiling only applies to the measured size rules (${LINT_IGNORE_CEILING_RULES.join(', ')}); ` +
+            `got ${unmeasured.map((entry) => entry.rule).join(', ')}.`, '--max');
+    }
+    const { reason, share } = options;
+    return validated(parsed.map((entry) => entry.max === undefined
+        ? entry.rule
+        : { rule: entry.rule, max: entry.max, reason, ...(share !== undefined ? { share } : {}) }), '--add');
+}
+/** Runs the manifest validator over CLI-built entries, as an argument error. */
+function validated(entries, flag) {
+    try {
+        return parseLintIgnoreEntries(entries, flag);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(toError(error).message, flag);
+    }
+}
+/** The target patch's ceiling rows of a lint report, rebaselined to their measurement. */
+function rebaselineFromReport(data, targetFilename) {
+    const patches = isArray(data['patches']) ? data['patches'] : [];
+    const row = patches.find((patch) => isObject(patch) && patch['filename'] === targetFilename);
+    const ceilings = isObject(row) && isArray(row['lintIgnoreCeilings']) ? row['lintIgnoreCeilings'] : [];
+    const raw = [];
+    for (const ceiling of ceilings) {
+        if (!isObject(ceiling) || typeof ceiling['measurement'] !== 'number')
+            continue;
+        if (ceiling['measurement'] <= 0)
+            continue;
+        const { measurement, rule, reason, share, meta } = ceiling;
+        raw.push({
+            rule,
+            max: measurement,
+            reason,
+            ...(share !== undefined ? { share } : {}),
+            ...(meta !== undefined ? { meta } : {}),
+        });
+    }
+    return { raw, skipped: patches.length - (row === undefined ? 0 : 1) };
+}
+/**
+ * Reads a `--from` file into entries for `targetFilename`.
+ *
+ * @param path - JSON file path
+ * @param targetFilename - The patch the command edits
+ * @param defaultReason - `--reason`, used for object entries without one
+ * @returns The validated entries and the count left out for other patches
+ */
+export async function readLintIgnoreBatch(path, targetFilename, defaultReason) {
+    let data;
+    try {
+        data = await readJson(path);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`Cannot read --from ${path}: ${toError(error).message}`, '--from');
+    }
+    if (isObject(data)) {
+        const { raw, skipped } = rebaselineFromReport(data, targetFilename);
+        return { entries: validated(raw, '--from'), skippedForOtherPatches: skipped };
+    }
+    if (!isArray(data)) {
+        throw new InvalidArgumentError('--from must hold a JSON array of lintIgnore entries or a "lint --per-patch --report" document.', '--from');
+    }
+    const raw = [];
+    let skipped = 0;
+    for (const entry of data) {
+        if (!isObject(entry)) {
+            raw.push(entry);
+            continue;
+        }
+        const { patch, ...rest } = entry;
+        if (patch !== undefined && patch !== targetFilename) {
+            skipped++;
+            continue;
+        }
+        raw.push(rest['reason'] === undefined && defaultReason !== undefined
+            ? { ...rest, reason: defaultReason }
+            : rest);
+    }
+    return { entries: validated(raw, '--from'), skippedForOtherPatches: skipped };
+}
+/** Parses `--share`. */
+export function parseShare(value) {
+    if (value !== 'test' && value !== 'product') {
+        throw new InvalidArgumentError(`--share must be "test" or "product" (got "${value}").`, '--share');
+    }
+    return value;
+}

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

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

@@ -12,20 +12,27 @@
  *   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, 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 { parseShare, readLintIgnoreBatch, resolveAddEntries } from './lint-ignore-from.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Printed whenever `--add` lands a new check id. The waiver this command
@@ -44,19 +51,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 +64,53 @@ 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`
+ * and `<rule>=<max>` to `--add` (see `lint-ignore-from.ts`). Refuses a
+ * ceiling flag without `--add`, a ceiling without a `--reason`, and a
+ * ceiling on a rule that carries no measurement, so a waiver that could
+ * never suppress anything is not written. A `--from` add resolves later,
+ * once the target patch is known.
+ */
+function resolveRequestedEntries(mode, options) {
+    const ceilingFlag = options.max !== undefined ? '--max' : options.share !== undefined ? '--share' : undefined;
+    if ((ceilingFlag !== undefined || options.reason !== undefined) && mode !== 'add') {
+        throw new InvalidArgumentError('--max, --reason and --share only apply to --add.', ceilingFlag ?? '--reason');
+    }
+    if (mode === 'remove')
+        return [...(options.remove ?? [])];
+    if (mode !== 'add')
+        return [];
+    if (options.from !== undefined) {
+        if ((options.add?.length ?? 0) > 0 || ceilingFlag !== undefined) {
+            throw new InvalidArgumentError('--from takes its entries from the file; it combines only with --reason (the default reason).', (options.add?.length ?? 0) > 0 ? '--add' : ceilingFlag);
+        }
+        return [];
+    }
+    return resolveAddEntries(options.add ?? [], options);
 }
 /**
  * Runs the `patch lint-ignore` command: reads the patch's existing
@@ -105,7 +127,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     // `--add foo --remove bar` are rejected: an operator who needs both
     // runs the command twice (clearer audit trail), and `--clear` plus a
     // mode is contradictory.
-    const adding = (options.add?.length ?? 0) > 0;
+    const adding = (options.add?.length ?? 0) > 0 || options.from !== undefined;
     const removing = (options.remove?.length ?? 0) > 0;
     const clearing = options.clear === true;
     const modeCount = [adding, removing, clearing].filter(Boolean).length;
@@ -113,12 +135,22 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch lint-ignore');
     }
     if (modeCount === 0) {
-        throw new InvalidArgumentError('Specify --add <id>, --remove <id>, or --clear.', 'patch lint-ignore');
+        throw new InvalidArgumentError('Specify --add <id>, --from <json-file>, --remove <id>, or --clear.', 'patch lint-ignore');
     }
     const mode = adding ? 'add' : removing ? 'remove' : 'clear';
-    const values = mode === 'add' ? (options.add ?? []) : mode === 'remove' ? (options.remove ?? []) : [];
+    let values = resolveRequestedEntries(mode, options);
     const { paths, manifest } = await requirePatchQueue(projectRoot);
     const target = requirePatchTarget(identifier, manifest.patches);
+    if (options.from !== undefined) {
+        const batch = await readLintIgnoreBatch(options.from, target.filename, options.reason);
+        if (batch.skippedForOtherPatches > 0) {
+            info(`--from: ${batch.skippedForOtherPatches} entry/entries for other patches left out.`);
+        }
+        if (batch.entries.length === 0) {
+            throw new InvalidArgumentError(`--from ${options.from} holds no lintIgnore entry for ${target.filename}.`, '--from');
+        }
+        values = batch.entries;
+    }
     // Destructive-operation contract (docs/lifecycle-invariants.md): manifest
     // metadata mutations get summary + dry-run + confirmation/--yes + history
     // uniformly. Accepting --yes without ever prompting makes the flag appear
@@ -126,7 +158,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 +190,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 +198,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         args: {
             filename: target.filename,
             mode,
-            values: [...values],
+            values: values.map(formatLintIgnoreEntry),
             before: existing,
             after: projected,
         },
@@ -186,9 +218,16 @@ export function registerPatchLintIgnore(parent, context) {
     const command = parent
         .command('lint-ignore <name>')
         .description('Edit PatchMetadata.lintIgnore on a single patch (no .patch body rewrite). One mode per invocation.')
-        .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable)', ...stringListOption())
+        .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable); <rule>=<max> adds a ceiling at <max>', ...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>', 'Why the ceiling exists (required with --max or <rule>=<max>; with --from: the default for entries without one)')
+        .addOption(new Option('--share <share>', 'With a large-patch-lines ceiling: bound only the "product" or "test" share of the measurement').argParser(commanderArgParser(parseShare)))
+        .option('--from <json-file>', 'Add every entry in a JSON file under one lock hold: an array of check IDs or ' +
+        '{ rule, max, reason?, share?, meta?, patch? } objects, or a "lint --per-patch --report" ' +
+        'document, whose ceilings for this patch are rebaselined to their current measurement')
         .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 +242,14 @@ 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.share !== undefined)
+            normalized.share = options.share;
+        if (options.from !== undefined)
+            normalized.from = options.from;
         if (options.dryRun === true)
             normalized.dryRun = true;
         if (options.yes === true)

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

@@ -14,17 +14,20 @@ 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';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro, success } from '../../utils/logger.js';
 import { normalizePatchDisplayName } from '../../utils/validation.js';
+import { withDeclarationsReport } from '../declarations-report.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, splitDeclarationRenamer, } 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 +88,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 +116,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 +137,16 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         ignoreChecks,
         patchTier: source.tier,
     });
-    const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
-    plan.stagedDependencyAdditions = stagedDependencyAdditions;
-    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 projected = runProjectedSplitLint(plan, patchQueueCtx);
+    plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
+    plan.stagedMaintenance = projected.stagedMaintenance;
+    const conflicts = await withDeclarationsReport(projected.conflicts, {
+        projectRoot,
+        regressions: projected.regressions,
+        out: options.declarationsOut,
+        rename: splitDeclarationRenamer(plan),
     });
+    const newMetadata = buildNewPatchMetadata(plan, config);
     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 +161,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

@@ -14,10 +14,11 @@
  * reflect both patches' content, because both bodies are regenerated from
  * the worktree.
  */
-import { join } from 'node:path';
+import { dirname, join, resolve } 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';
@@ -26,10 +27,12 @@ import { toError } from '../../utils/errors.js';
 import { readText, writeText } from '../../utils/fs.js';
 import { info, outro, success, warn } from '../../utils/logger.js';
 import { resolveWaitLockSeconds } from '../../utils/options.js';
+import { withDeclarationsReport } from '../declarations-report.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
@@ -89,7 +92,7 @@ function runProjectedMoveLint(plan, baseCtx) {
             reason: `move would introduce ${regressions.length} cross-patch lint error(s)`,
             details: regressions.map(formatPatchLintIssue),
         };
-    return { conflicts, stagedDependencyAdditions };
+    return { conflicts, regressions, stagedDependencyAdditions };
 }
 /**
  * Commits a confirmed move under the patch-directory lock: write both
@@ -198,7 +201,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 +211,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);
@@ -223,8 +226,13 @@ export async function runMoveFilesInto(args) {
         ownerRewrites: findOwnerRewriteHolders(manifest?.patches ?? [], source.filename, new Set(files)),
         stagedDependencyAdditions: new Map(),
     };
-    const { conflicts, stagedDependencyAdditions } = runProjectedMoveLint(plan, patchQueueCtx);
-    plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    const projected = runProjectedMoveLint(plan, patchQueueCtx);
+    plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
+    const conflicts = await withDeclarationsReport(projected.conflicts, {
+        projectRoot: dirname(resolve(patchesDir)),
+        regressions: projected.regressions,
+        out: options.declarationsOut,
+    });
     const decision = await confirmDestructive({
         operation: 'patch-move-files',
         title: `Move ${files.length} file(s) from ${source.filename} to ${target.filename}`,

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

@@ -164,13 +164,16 @@ 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')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass projected-lint refusals')
-        .option('--skip-lint', 'Skip per-patch lint of the projected bodies');
+        .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
+        .option('--declarations-out <path>', 'Where a refusal writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json)');
     addWaitLockOption(command).action(withErrorHandling(async (from, to, options) => {
         await patchMoveFilesCommand(getProjectRoot(), from, to, {
             ...pickDefined({
@@ -183,6 +186,7 @@ export function registerPatchMoveFiles(parent, context) {
                 yes: options.yes,
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
+                declarationsOut: options.declarationsOut,
                 waitLock: options.waitLock,
             }),
         });