@hominis/fireforge 0.37.0 → 0.39.0

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

@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Transactional file-ownership move into an EXISTING patch (FORGE F4).
+ *
+ * Before 0.39.0, `patch move-files <from> <to>` with an existing target was
+ * preview-only: it printed two `re-export --files` commands whose real
+ * execution cost three further refusals (`--allow-shrink`, `--yes`, and a
+ * projected `duplicate-new-file-creation` unless the SHRINK landed first —
+ * while the printed plan listed the grow first). This module performs the
+ * same shrink→grow as one transaction under the patch-directory lock with
+ * rollback, mirroring `patch split` / `move-files --create`.
+ *
+ * Preconditions match `re-export`: the engine worktree must currently
+ * reflect both patches' content, because both bodies are regenerated from
+ * the worktree.
+ */
+import { join } from 'node:path';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { computeProjectedLintRegressions } from '../../core/lint-projection.js';
+import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
+import { extractNewFileContentFromDiff } from '../../core/patch-transform.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readText, writeText } from '../../utils/fs.js';
+import { info, outro, success, warn } from '../../utils/logger.js';
+import { runPatchLint } from '../export-shared.js';
+import { buildSplitDiff, findOwnerRewriteHolders, mergeStagedForwardImports, rewriteSplitOwners, } from './split-plan.js';
+function projectEntryBody(diff) {
+    const newFiles = new Map();
+    for (const path of detectNewFilesInDiff(diff)) {
+        newFiles.set(path, extractNewFileContentFromDiff(diff, path));
+    }
+    return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
+}
+/**
+ * Projects the post-move queue through cross-patch lint, auto-declaring the
+ * forward edges the move introduces into the target (an importer that used
+ * to live in the same patch as the moved file gains a forward edge when the
+ * target is later-ordered). Reports only regressions the move itself adds.
+ */
+async function runProjectedMoveLint(patchesDir, plan) {
+    const movedSet = new Set(plan.movedFiles);
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const entries = baseCtx.entries.map((entry) => {
+        let metadata = entry.metadata;
+        if (metadata) {
+            metadata = rewriteSplitOwners(metadata, plan.source.filename, movedSet, plan.target.filename);
+        }
+        if (entry.filename === plan.source.filename) {
+            return { ...entry, metadata, ...projectEntryBody(plan.sourceDiff) };
+        }
+        if (entry.filename === plan.target.filename) {
+            return { ...entry, metadata, ...projectEntryBody(plan.targetDiff) };
+        }
+        return { ...entry, metadata };
+    });
+    const stagedDependencyAdditions = new Map();
+    for (const edge of collectForwardImportEdges({ entries })) {
+        if (edge.owner !== plan.target.filename || !movedSet.has(edge.creates))
+            continue;
+        const decl = {
+            file: edge.sitePath,
+            specifier: edge.specifier,
+            creates: edge.creates,
+            owner: plan.target.filename,
+        };
+        const list = stagedDependencyAdditions.get(edge.entry) ?? [];
+        if (!list.some((d) => d.file === decl.file && d.specifier === decl.specifier && d.creates === decl.creates)) {
+            list.push(decl);
+        }
+        stagedDependencyAdditions.set(edge.entry, list);
+    }
+    for (const entry of entries) {
+        const decls = stagedDependencyAdditions.get(entry.filename);
+        if (decls?.length && entry.metadata) {
+            entry.metadata = mergeStagedForwardImports(entry.metadata, decls);
+        }
+    }
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({
+        entries,
+        ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
+    }).filter((i) => i.severity === 'error');
+    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
+    if (baselineIssues.length > 0 && regressions.length === 0) {
+        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing cross-patch ` +
+            'error(s) unrelated to this move. Run "fireforge verify" to list them.');
+    }
+    const conflicts = regressions.length === 0
+        ? null
+        : {
+            reason: `move would introduce ${regressions.length} cross-patch lint error(s)`,
+            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        };
+    return { conflicts, stagedDependencyAdditions };
+}
+/**
+ * Commits a confirmed move under the patch-directory lock: write both
+ * rewritten bodies, then one manifest rewrite (filesAffected on both rows +
+ * owner rewrites + auto-declared forward imports). Rolled back in reverse
+ * order on any failure.
+ */
+async function commitMoveInto(patchesDir, plan) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            throw new GeneralError('Manifest disappeared while waiting for lock.');
+        const currentSource = manifest.patches.find((p) => p.filename === plan.source.filename);
+        const currentTarget = manifest.patches.find((p) => p.filename === plan.target.filename);
+        if (!currentSource ||
+            !currentTarget ||
+            currentSource.filesAffected.join('\n') !== plan.source.filesAffected.join('\n') ||
+            currentTarget.filesAffected.join('\n') !== plan.target.filesAffected.join('\n')) {
+            throw new InvalidArgumentError('Patch queue changed while waiting for move confirmation. Re-run the command.', 'patch move-files');
+        }
+        const movedSet = new Set(plan.movedFiles);
+        const sourcePath = join(patchesDir, plan.source.filename);
+        const targetPath = join(patchesDir, plan.target.filename);
+        const originalSourceBody = await readText(sourcePath);
+        const originalTargetBody = await readText(targetPath);
+        let sourceWritten = false;
+        let targetWritten = false;
+        try {
+            await writeText(sourcePath, normalizePatchArtifact(plan.sourceDiff));
+            sourceWritten = true;
+            await writeText(targetPath, normalizePatchArtifact(plan.targetDiff));
+            targetWritten = true;
+            const updatedPatches = manifest.patches.map((patch) => {
+                let updated = rewriteSplitOwners(patch, plan.source.filename, movedSet, plan.target.filename);
+                const decls = plan.stagedDependencyAdditions.get(updated.filename);
+                if (decls?.length)
+                    updated = mergeStagedForwardImports(updated, decls);
+                if (updated.filename === plan.source.filename) {
+                    return { ...updated, filesAffected: plan.sourceAfter };
+                }
+                if (updated.filename === plan.target.filename) {
+                    return { ...updated, filesAffected: plan.targetAfter };
+                }
+                return updated;
+            });
+            const updated = validatePatchesManifest({ ...manifest, patches: updatedPatches });
+            await savePatchesManifest(patchesDir, updated);
+            try {
+                await appendHistory(patchesDir, {
+                    operation: 'patch-move-files',
+                    args: {
+                        source: plan.source.filename,
+                        target: plan.target.filename,
+                        files: plan.movedFiles,
+                        ownerRewrites: plan.ownerRewrites,
+                    },
+                    result: 'ok',
+                });
+            }
+            catch (historyError) {
+                warn(`History log append failed after patch move-files committed: ${toError(historyError).message}`);
+            }
+        }
+        catch (error) {
+            if (targetWritten) {
+                try {
+                    await writeText(targetPath, originalTargetBody);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore target body: ${toError(rollbackError).message}`);
+                }
+            }
+            if (sourceWritten) {
+                try {
+                    await writeText(sourcePath, originalSourceBody);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore source body: ${toError(rollbackError).message}`);
+                }
+            }
+            try {
+                await savePatchesManifest(patchesDir, manifest);
+            }
+            catch (rollbackError) {
+                warn(`Rollback warning: could not restore manifest: ${toError(rollbackError).message}`);
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Plans, lints, confirms, and commits a file-ownership move into an
+ * existing patch. Called by `patchMoveFilesCommand` after its ownership
+ * pre-checks resolved and validated both patches.
+ */
+export async function runMoveFilesInto(args) {
+    const { enginePath, patchesDir, source, target, files, sourceAfter, targetAfter, options } = args;
+    const sourceDiff = await buildSplitDiff(enginePath, sourceAfter, 'remaining', source.filename);
+    const targetDiff = await buildSplitDiff(enginePath, targetAfter, 'moved', target.filename);
+    // Per-patch lint both projected bodies with each patch's own waivers.
+    await runPatchLint(enginePath, sourceAfter, sourceDiff, args.config, options.skipLint, undefined, source.lintIgnore ? new Set(source.lintIgnore) : undefined, source.tier);
+    await runPatchLint(enginePath, targetAfter, targetDiff, args.config, options.skipLint, undefined, target.lintIgnore ? new Set(target.lintIgnore) : undefined, target.tier);
+    const manifest = await loadPatchesManifest(patchesDir);
+    const plan = {
+        source,
+        target,
+        movedFiles: files,
+        sourceAfter,
+        targetAfter,
+        sourceDiff,
+        targetDiff,
+        ownerRewrites: findOwnerRewriteHolders(manifest?.patches ?? [], source.filename, new Set(files)),
+        stagedDependencyAdditions: new Map(),
+    };
+    const { conflicts, stagedDependencyAdditions } = await runProjectedMoveLint(patchesDir, plan);
+    plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    const decision = await confirmDestructive({
+        operation: 'patch-move-files',
+        title: `Move ${files.length} file(s) from ${source.filename} to ${target.filename}`,
+        summary: [
+            `moved files (${files.length}): ${files.join(', ')}`,
+            `${source.filename} keeps (${sourceAfter.length}): ${sourceAfter.join(', ')}`,
+            `${target.filename} grows to (${targetAfter.length}): ${targetAfter.join(', ')}`,
+            ...(plan.ownerRewrites.length > 0
+                ? [`staged-dependency owners re-pointed in: ${plan.ownerRewrites.join(', ')}`]
+                : []),
+        ],
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
+        conflicts,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Move cancelled');
+        return;
+    }
+    await commitMoveInto(patchesDir, plan);
+    success(`Moved ${files.length} file(s) from ${source.filename} to ${target.filename}`);
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    outro('Move complete');
+}

package/dist/src/commands/patch/move-files.d.ts

@@ -1,6 +1,8 @@
 /**
  * `fireforge patch move-files <from> <to>` previews the explicit
- * re-export choreography needed to move file ownership between two patches.
+ * re-export choreography needed to move file ownership between two
+ * patches. With `--create --order <n>` the target patch is created and
+ * the files move into it as one transaction (see move-files-create.ts).
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

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

@@ -1,16 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch move-files <from> <to>` previews the explicit
- * re-export choreography needed to move file ownership between two patches.
+ * re-export choreography needed to move file ownership between two
+ * patches. With `--create --order <n>` the target patch is created and
+ * the files move into it as one transaction (see move-files-create.ts).
  */
 import { relative } from 'node:path';
 import { Command } from 'commander';
-import { getProjectPaths } from '../../core/config.js';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { pathExists } from '../../utils/fs.js';
-import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { info, intro, note, warn } from '../../utils/logger.js';
+import { commanderArgParser, pickDefined } from '../../utils/options.js';
+import { patchMoveFilesCreateCommand } from './move-files-create.js';
+import { runMoveFilesInto } from './move-files-into.js';
 function collectOption(value, previous) {
     previous.push(value);
     return previous;
@@ -67,6 +72,19 @@ function computeFileMovePlan(source, target, files) {
  * @param options - Files to move and display mode
  */
 export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdentifier, options = {}) {
+    if (options.create === true && options.order === undefined) {
+        throw new InvalidArgumentError('--create requires --order <n> to place the new patch.', '--create');
+    }
+    if (options.create !== true && options.order !== undefined) {
+        throw new InvalidArgumentError('--order is only valid together with --create.', '--order');
+    }
+    if (options.create === true && options.order !== undefined) {
+        await patchMoveFilesCreateCommand(projectRoot, fromIdentifier, toIdentifier, {
+            ...options,
+            order: options.order,
+        });
+        return;
+    }
     intro('FireForge patch move-files');
     if (fromIdentifier === toIdentifier) {
         throw new InvalidArgumentError('Source and target patch identifiers must be different.', 'patch move-files');
@@ -106,20 +124,34 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
         }
     }
     const relativePatchesDir = relative(projectRoot, paths.patches) || 'patches';
-    info(`Planning ownership move in ${relativePatchesDir}/patches.json.`);
+    info(`Moving ownership in ${relativePatchesDir}/patches.json.`);
     info(`Move ${files.length} file(s) from ${source.filename} to ${target.filename}:`);
     note(formatFiles(files), 'Files');
     note(formatFiles(sourceAfter), `${source.filename} files after move`);
     note(formatFiles(targetAfter), `${target.filename} files after move`);
-    const dryRunSource = formatReExportCommand(source.filename, sourceAfter, ['--dry-run']);
-    const dryRunTarget = formatReExportCommand(target.filename, targetAfter, ['--dry-run']);
-    const applySource = formatReExportCommand(source.filename, sourceAfter, ['--yes']);
-    const applyTarget = formatReExportCommand(target.filename, targetAfter, []);
-    note(`${dryRunSource}\n${dryRunTarget}`, 'Preview commands');
-    note(`${applySource}\n${applyTarget}`, 'Apply commands');
-    info('Tip: to move files into a brand-new patch in one transaction (including ' +
-        'staged-dependency owner rewrites), use "fireforge patch split" instead.');
-    outro('Move plan complete - no changes made');
+    // Manual fallback (e.g. when the worktree cannot carry both patches'
+    // content right now): the equivalent re-export choreography, in
+    // EXECUTABLE order — the shrink must land before the grow, or the
+    // projected cross-patch lint refuses the pair with
+    // duplicate-new-file-creation (FORGE F4).
+    const applySource = formatReExportCommand(source.filename, sourceAfter, [
+        '--allow-shrink',
+        '--yes',
+    ]);
+    const applyTarget = formatReExportCommand(target.filename, targetAfter, ['--yes']);
+    note(`1. ${applySource}\n2. ${applyTarget}\n(the shrink must land first)`, 'Equivalent manual commands');
+    const config = await loadConfig(projectRoot);
+    await runMoveFilesInto({
+        enginePath: paths.engine,
+        patchesDir: paths.patches,
+        source,
+        target,
+        files,
+        sourceAfter,
+        targetAfter,
+        options,
+        config,
+    });
 }
 /**
  * Registers the preview-only `patch move-files` subcommand.
@@ -131,9 +163,36 @@ export function registerPatchMoveFiles(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
     parent
         .command('move-files <from> <to>')
-        .description('Preview the re-export commands needed to move file ownership between patches.')
+        .description('Preview the re-export commands needed to move file ownership between patches, ' +
+        '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)', collectOption, [])
+        .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) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new InvalidArgumentError(`--order must be a positive integer, got "${raw}".`, '--order');
+        }
+        return n;
+    }))
+        .option('--category <category>', "Category for the created patch (default: the source patch's)")
+        .option('--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')
         .action(withErrorHandling(async (from, to, options) => {
-        await patchMoveFilesCommand(getProjectRoot(), from, to, options);
+        await patchMoveFilesCommand(getProjectRoot(), from, to, {
+            ...pickDefined({
+                file: options.file,
+                create: options.create,
+                order: options.order,
+                category: options.category,
+                description: options.description,
+                dryRun: options.dryRun,
+                yes: options.yes,
+                forceUnsafe: options.forceUnsafe,
+                skipLint: options.skipLint,
+            }),
+        });
     }));
 }

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

@@ -173,7 +173,10 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
     const nameChanging = options.to !== target.name;
     const descriptionChanging = options.description !== undefined && options.description !== target.description;
     if (!filenameChanging && !nameChanging && !descriptionChanging) {
-        info(`${target.filename}: name and description already match — nothing to change.`);
+        info(`${target.filename}: nothing to change — filename already "${target.filename}" ` +
+            `(slug of "${options.to}" is "${newSlug}"), name already "${target.name}"` +
+            (options.description !== undefined ? ', description already matches' : '') +
+            '.');
         outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
         return;
     }

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

@@ -18,7 +18,17 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-import type { PatchSplitOptions } from '../../types/commands/index.js';
+import type { PatchMetadata, PatchSplitOptions } from '../../types/commands/index.js';
+import type { FireForgeConfig } from '../../types/config.js';
+import { type SplitPlan } from './split-plan.js';
+/**
+ * Commits a confirmed split under the patch directory lock: renumber →
+ * write new patch body → write shrunken source body → single manifest
+ * rewrite (new row + shrunken source row + owner rewrites). On any
+ * failure the steps are rolled back in reverse order. Exported for
+ * `patch move-files --create`, which commits the same transaction shape.
+ */
+export declare function commitPatchSplit(patchesDir: string, plan: SplitPlan, newMetadata: PatchMetadata, options: Pick<PatchSplitOptions, 'yes' | 'forceUnsafe'>, config: FireForgeConfig): Promise<void>;
 /**
  * Runs the `patch split` command: plans the split, lints the projection,
  * confirms, and commits transactionally.

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

@@ -38,9 +38,10 @@ import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSpli
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest
  * rewrite (new row + shrunken source row + owner rewrites). On any
- * failure the steps are rolled back in reverse order.
+ * failure the steps are rolled back in reverse order. Exported for
+ * `patch move-files --create`, which commits the same transaction shape.
  */
-async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
+export async function commitPatchSplit(patchesDir, plan, newMetadata, options, config) {
     await withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifest(patchesDir);
         if (!manifest)
@@ -49,7 +50,7 @@ async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
         if (!current || current.filesAffected.join('\n') !== plan.source.filesAffected.join('\n')) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
         }
-        const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name);
+        const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name, config);
         if (!placementPlansEqual(currentPlacement, plan.placement)) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
         }
@@ -193,7 +194,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         after: options.after ??
             (options.order === undefined && options.before === undefined ? source.filename : undefined),
     });
-    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name);
+    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
     const plan = {
         source,
         movedFiles,
@@ -240,7 +241,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         outro('Split cancelled');
         return;
     }
-    await commitPatchSplit(paths.patches, plan, newMetadata, options);
+    await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
     if (plan.ownerRewrites.length > 0) {
         info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);

package/dist/src/commands/re-export-scan.d.ts

@@ -28,6 +28,23 @@ export declare function confirmBroadScanAdditions(args: {
     yes: boolean;
     isInteractive: boolean;
 }): Promise<boolean>;
+/**
+ * Refuses scan adoptions whose candidate files import modules created by
+ * LATER patches. Modeled on the `re-export --files` cross-patch
+ * projection: the candidates' diffs are projected into the adopting
+ * patch's queue entry, the queue lint runs baseline vs projection, and
+ * only forward-import regressions attributable to the candidates block.
+ * Staged-dependency declarations and inline lint-ignore markers are
+ * honored automatically because the real lint rule evaluates them.
+ * Covers broad `--scan`, `--scan-file`, and the `--scan-files` bulk flow
+ * (all adopt through the same scan result), including dry-run.
+ */
+export declare function assertScanAdoptionsHaveNoForwardImports(args: {
+    patchesDir: string;
+    engineDir: string;
+    patchFilename: string;
+    added: readonly string[];
+}): Promise<void>;
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export declare function assertScanFileAdditionsHaveDiffHunks(args: {
     diffContent: string;

package/dist/src/commands/re-export-scan.js

@@ -1,9 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
 import { confirm } from '@clack/prompts';
+import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
+import { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
 import { getClaimedFiles } from '../core/patch-manifest.js';
+import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
@@ -132,6 +136,53 @@ function scanAdditionsNeedConfirmation(added) {
         return true;
     return new Set(added.map((f) => dirname(f))).size >= SCAN_DIR_COUNT_THRESHOLD;
 }
+/**
+ * Refuses scan adoptions whose candidate files import modules created by
+ * LATER patches. Modeled on the `re-export --files` cross-patch
+ * projection: the candidates' diffs are projected into the adopting
+ * patch's queue entry, the queue lint runs baseline vs projection, and
+ * only forward-import regressions attributable to the candidates block.
+ * Staged-dependency declarations and inline lint-ignore markers are
+ * honored automatically because the real lint rule evaluates them.
+ * Covers broad `--scan`, `--scan-file`, and the `--scan-files` bulk flow
+ * (all adopt through the same scan result), including dry-run.
+ */
+export async function assertScanAdoptionsHaveNoForwardImports(args) {
+    const { patchesDir, engineDir, patchFilename, added } = args;
+    if (added.length === 0)
+        return;
+    const candidateDiff = await getDiffForFilesAgainstHead(engineDir, [...added]);
+    if (!candidateDiff.trim())
+        return;
+    const candidateNewFiles = new Map();
+    for (const path of detectNewFilesInDiff(candidateDiff)) {
+        candidateNewFiles.set(path, extractNewFileContentFromDiff(candidateDiff, path));
+    }
+    const candidateAdditions = buildModifiedFileAdditionsFromDiff(candidateDiff);
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        if (entry.filename !== patchFilename)
+            return entry;
+        return {
+            ...entry,
+            diff: `${entry.diff}\n${candidateDiff}`,
+            newFiles: new Map([...entry.newFiles, ...candidateNewFiles]),
+            modifiedFileAdditions: new Map([...entry.modifiedFileAdditions, ...candidateAdditions]),
+        };
+    });
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const addedSet = new Set(added);
+    const offending = computeProjectedLintRegressions(baselineIssues, projectedIssues).filter((issue) => issue.check === 'forward-import' && addedSet.has(issue.file));
+    if (offending.length === 0)
+        return;
+    const details = offending.map((issue) => `  - ${issue.file}: ${issue.message}`).join('\n');
+    throw new GeneralError(`Refusing to adopt ${offending.length} scanned file${offending.length === 1 ? '' : 's'} into ${patchFilename} ` +
+        `because they import modules created by later patches:\n${details}\n` +
+        'Export those files as their own later patch ("fireforge export --order <n>" / ' +
+        '"fireforge patch split --order <n>") or declare the intentional dependency with ' +
+        '"fireforge patch staged-dependency --add" before re-running the scan.');
+}
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export function assertScanFileAdditionsHaveDiffHunks(args) {
     const { diffContent, patchFilename, previousFilesAffected, scanFiles } = args;

package/dist/src/commands/re-export.js

@@ -18,12 +18,12 @@ import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
-import { assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
+import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
 async function findMissingFiles(engineDir, files) {
     const missingFiles = [];
     for (const file of files) {
@@ -87,6 +87,17 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             isDryRun,
             ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
         });
+        // Forward-import gate at adoption time (runs in dry-run too): refuse
+        // to adopt unmanaged files that import modules created by LATER
+        // patches — the after-the-fact lint failure this leaves behind is the
+        // field-reported footgun. Applies to broad --scan, --scan-file, and
+        // the --scan-files bulk assignments alike.
+        await assertScanAdoptionsHaveNoForwardImports({
+            patchesDir: paths.patches,
+            engineDir: paths.engine,
+            patchFilename: patch.filename,
+            added: scanResult.added,
+        });
         if (options.scanFiles === undefined) {
             const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
             const proceed = await confirmBroadScanAdditions({
@@ -407,7 +418,7 @@ export async function reExportCommand(projectRoot, patches, options) {
 }
 /** Registers the re-export command on the CLI program. */
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const reExport = program
         .command('re-export [patches...]')
         .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
         'state. Does NOT change sourceVersion/sourceProduct by default — use --stamp or run ' +
@@ -428,8 +439,8 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
-        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
-        .action(withErrorHandling(async (patches, options) => {
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], []);
+    addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
         const { tier, lintIgnore, scanFile, scanFiles, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
@@ -438,6 +449,6 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
             ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
-        }));
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/reset.js

@@ -5,6 +5,7 @@ import { getProjectPaths } from '../core/config.js';
 import { clearAppliedFurnaceState } from '../core/furnace-config.js';
 import { getHead, hasChanges, isGitRepository, isMissingHeadError, resetChanges, } from '../core/git.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
+import { warnIfStaticComponentsStale } from '../core/test-stale-check.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
@@ -86,6 +87,10 @@ export async function resetCommand(projectRoot, options) {
         // tree, not the engine checkout, so reset must not silently forget them.
         await clearAppliedFurnaceState(projectRoot);
         s.stop('Changes reset');
+        // The reset may have moved components.conf away from what the last full
+        // build compiled in — surface that now instead of at the next test
+        // refusal (FORGE F13).
+        await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('Working tree restored to clean state');
     }
     catch (error) {