@hominis/fireforge 0.38.0 → 0.40.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.js

@@ -7,14 +7,15 @@
  */
 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;
@@ -123,21 +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), re-run with --create --order <n> to create ' +
-        'the target patch and move the files in one step, or use "fireforge patch split".');
-    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.

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;
     }
@@ -260,7 +263,7 @@ export function registerPatchRename(parent, context) {
         .command('rename <name>')
         .description('Rename a patch: filename + manifest name (and optional description) update without rewriting the .patch body.')
         .requiredOption('--to <new-name>', 'New human-readable name, category-prefixed slug, or full filename stem (normalised into the filename slug)')
-        .option('--description <text>', 'Replacement description (omit to leave description unchanged)')
+        .option('-d, --description <text>', 'Replacement description (omit to leave description unchanged)')
         .option('--dry-run', 'Show what would change without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals')

package/dist/src/commands/patch/staged-dependency.js

@@ -10,35 +10,46 @@ import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+/** Joins the names of the missing flags for error attribution (FORGE G12). */
+function missingFlagList(pairs) {
+    return pairs
+        .filter(([, value]) => value === undefined || value === '')
+        .map(([flag]) => flag)
+        .join(', ');
+}
 function modeFromOptions(options) {
     const adding = options.add === true;
     const removing = options.remove === true;
     const clearing = options.clear === true;
     const modeCount = [adding, removing, clearing].filter(Boolean).length;
     if (modeCount > 1) {
-        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch staged-dependency');
+        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', '--add/--remove/--clear');
     }
     if (modeCount === 0) {
-        throw new InvalidArgumentError('Specify --add, --remove, or --clear.', 'patch staged-dependency');
+        throw new InvalidArgumentError('Specify --add, --remove, or --clear.', '--add/--remove/--clear');
     }
     return adding ? 'add' : removing ? 'remove' : 'clear';
 }
 function kindFromOptions(options) {
     const kind = options.kind ?? 'import';
     if (kind !== 'import' && kind !== 'registration') {
-        throw new InvalidArgumentError(`--kind must be "import" or "registration" (got "${kind}").`, 'patch staged-dependency');
+        throw new InvalidArgumentError(`--kind must be "import" or "registration" (got "${kind}").`, '--kind');
     }
     if (kind === 'import' && options.line !== undefined) {
-        throw new InvalidArgumentError('--line only applies to --kind registration; import declarations use --specifier.', 'patch staged-dependency');
+        throw new InvalidArgumentError('--line only applies to --kind registration; import declarations use --specifier.', '--line');
     }
     if (kind === 'registration' && options.specifier !== undefined) {
-        throw new InvalidArgumentError('--specifier only applies to --kind import; registration declarations use --line.', 'patch staged-dependency');
+        throw new InvalidArgumentError('--specifier only applies to --kind import; registration declarations use --line.', '--specifier');
     }
     return kind;
 }
-function requireForwardImportOptions(options, mode) {
+function requireForwardImportOptions(options) {
     if (!options.file || !options.specifier || !options.creates) {
-        throw new InvalidArgumentError(`--${mode} requires --file, --specifier, and --creates.`, 'patch staged-dependency');
+        throw new InvalidArgumentError('--add requires --file, --specifier, and --creates.', missingFlagList([
+            ['--file', options.file],
+            ['--specifier', options.specifier],
+            ['--creates', options.creates],
+        ]));
     }
     const dependency = {
         file: options.file,
@@ -51,9 +62,13 @@ function requireForwardImportOptions(options, mode) {
         dependency.reason = options.reason;
     return dependency;
 }
-function requireRegistrationOptions(options, mode) {
+function requireRegistrationOptions(options) {
     if (!options.file || !options.line || !options.creates) {
-        throw new InvalidArgumentError(`--${mode} --kind registration requires --file, --line, and --creates.`, 'patch staged-dependency');
+        throw new InvalidArgumentError('--add --kind registration requires --file, --line, and --creates.', missingFlagList([
+            ['--file', options.file],
+            ['--line', options.line],
+            ['--creates', options.creates],
+        ]));
     }
     const dependency = {
         file: options.file,
@@ -66,6 +81,70 @@ function requireRegistrationOptions(options, mode) {
         dependency.reason = options.reason;
     return dependency;
 }
+/**
+ * Resolves the `--remove` target for forward-imports (FORGE G12):
+ * `--file` + `--specifier` suffice when they identify at most one staged
+ * entry — `--creates` is inferred from a unique match, an ambiguous match
+ * refuses with the candidate list, and no match falls through to the
+ * honest "no staged forward-import matched" summary.
+ */
+function resolveImportRemovalTarget(options, staged) {
+    if (!options.file || !options.specifier) {
+        throw new InvalidArgumentError('--remove requires --file and --specifier; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
+            ['--file', options.file],
+            ['--specifier', options.specifier],
+        ]));
+    }
+    if (options.creates) {
+        return requireForwardImportOptions(options);
+    }
+    const { file, specifier } = options;
+    const candidates = (staged?.forwardImports ?? []).filter((entry) => entry.file === file &&
+        entry.specifier === specifier &&
+        (options.owner === undefined || entry.owner === options.owner));
+    const single = candidates.length === 1 ? candidates[0] : undefined;
+    if (single !== undefined) {
+        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
+        return { ...single };
+    }
+    if (candidates.length > 1) {
+        const list = candidates
+            .map((entry) => `  - ${dependencyLabel('import', importView(entry))}`)
+            .join('\n');
+        throw new GeneralError(`--remove matches ${String(candidates.length)} staged forward-imports on this patch; ` +
+            `pass --creates to pick one:\n${list}`);
+    }
+    return { file, specifier, creates: '(no match)' };
+}
+/** Registration twin of {@link resolveImportRemovalTarget}, keyed on `--line`. */
+function resolveRegistrationRemovalTarget(options, staged) {
+    if (!options.file || !options.line) {
+        throw new InvalidArgumentError('--remove --kind registration requires --file and --line; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
+            ['--file', options.file],
+            ['--line', options.line],
+        ]));
+    }
+    if (options.creates) {
+        return requireRegistrationOptions(options);
+    }
+    const { file, line } = options;
+    const candidates = (staged?.registrations ?? []).filter((entry) => entry.file === file &&
+        entry.line === line &&
+        (options.owner === undefined || entry.owner === options.owner));
+    const single = candidates.length === 1 ? candidates[0] : undefined;
+    if (single !== undefined) {
+        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
+        return { ...single };
+    }
+    if (candidates.length > 1) {
+        const list = candidates
+            .map((entry) => `  - ${dependencyLabel('registration', registrationView(entry))}`)
+            .join('\n');
+        throw new GeneralError(`--remove matches ${String(candidates.length)} staged registrations on this patch; ` +
+            `pass --creates to pick one:\n${list}`);
+    }
+    return { file, line, creates: '(no match)' };
+}
 function importView(dependency) {
     return { ...dependency, matcher: dependency.specifier };
 }
@@ -137,17 +216,26 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
     const kind = kindFromOptions(options);
-    const importDependency = mode === 'clear' || kind !== 'import' ? undefined : requireForwardImportOptions(options, mode);
+    // The patch queue loads BEFORE the declaration fields resolve so
+    // `--remove` can infer `--creates` from the target patch's staged
+    // entries (FORGE G12).
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const targetPatch = requirePatchTarget(identifier, manifest.patches);
+    const importDependency = mode === 'clear' || kind !== 'import'
+        ? undefined
+        : mode === 'add'
+            ? requireForwardImportOptions(options)
+            : resolveImportRemovalTarget(options, targetPatch.stagedDependencies);
     const registrationDependency = mode === 'clear' || kind !== 'registration'
         ? undefined
-        : requireRegistrationOptions(options, mode);
+        : mode === 'add'
+            ? requireRegistrationOptions(options)
+            : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
     const target = importDependency !== undefined
         ? importView(importDependency)
         : registrationDependency !== undefined
             ? registrationView(registrationDependency)
             : undefined;
-    const { paths, manifest } = await requirePatchQueue(projectRoot);
-    const targetPatch = requirePatchTarget(identifier, manifest.patches);
     const applyToStaged = (staged) => {
         if (mode === 'clear')
             return {};
@@ -219,7 +307,7 @@ export function registerPatchStagedDependency(parent, context) {
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
         .option('--reason <text>', 'Human-readable rationale stored with the declaration')
         .option('--dry-run', 'Show what would change without writing')
-        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('-y, --yes', 'Record scripted consent in the destructive-operation history log. This command never prompts; the flag exists for workflow uniformity with commands that do.')
         .action(withErrorHandling(async (name, options) => {
         await patchStagedDependencyCommand(getProjectRoot(), name, options);
     }));

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

@@ -0,0 +1,34 @@
+import type { getProjectPaths } from '../core/config.js';
+import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Shared per-run context for the adjacency advisory: the classification
+ * inputs computed once by `reExportCommand`, plus the collection of
+ * patches refused under `--refuse-adjacent-unmanaged` (collected across
+ * the loop so a multi-patch run reports every offender in one refusal).
+ */
+export interface AdjacentUnmanagedContext {
+    binaryName: string;
+    furnacePrefixes: ReadonlySet<string>;
+    refuseAdjacentUnmanaged: boolean;
+    refusals: {
+        patchFilename: string;
+        files: string[];
+    }[];
+}
+/** Returns the subset of `files` that no longer exist under `engineDir`. */
+export declare function findMissingFiles(engineDir: string, files: readonly string[]): Promise<string[]>;
+/**
+ * Emits the scan-less advisory for one patch: missing manifest files and
+ * unmanaged files adjacent to the patch's ownership. When
+ * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
+ * exists, records the patch into `ctx.refusals` and returns true — the
+ * caller then skips the write for this patch and converts the collection
+ * into one run-level non-zero refusal after the loop.
+ */
+export declare function reportAdjacentUnmanagedFiles(args: {
+    patch: PatchMetadata;
+    paths: ReturnType<typeof getProjectPaths>;
+    manifest: PatchesManifest;
+    currentFilesAffected: readonly string[];
+    ctx: AdjacentUnmanagedContext;
+}): Promise<boolean>;

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

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Scan-less re-export adjacency advisory (FORGE G2). A plain `re-export`
+ * keeps the manifest's filesAffected unchanged, so a brand-new file an
+ * author just created beside a patch's owned files is silently left out
+ * of the refreshed body. This module detects such adjacent files, filters
+ * out tool-managed paths (branding, furnace) so the notice names only
+ * genuinely unmanaged candidates, and — under
+ * `--refuse-adjacent-unmanaged` — lets the caller turn the notice into a
+ * non-zero refusal.
+ *
+ * Split out of re-export.ts to keep that file inside the max-lines
+ * budget; exports helpers consumed by re-export.ts, no registrar.
+ */
+import { dirname, join } from 'node:path';
+import { isBrandingManagedPath } from '../core/branding.js';
+import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
+import { getClaimedFiles } from '../core/patch-manifest.js';
+import { isGeneratedBrandingPath } from '../core/status-classify.js';
+import { pathExists } from '../utils/fs.js';
+import { info, warn } from '../utils/logger.js';
+/** Returns the subset of `files` that no longer exist under `engineDir`. */
+export async function findMissingFiles(engineDir, files) {
+    const missingFiles = [];
+    for (const file of files) {
+        if (!(await pathExists(join(engineDir, file))))
+            missingFiles.push(file);
+    }
+    return missingFiles;
+}
+function isToolManagedPath(file, isNewFile, ctx) {
+    // Mirrors status-classify: a generated branding path is tool-managed
+    // outright; a brand-new unowned file under the branding root is still a
+    // patch candidate (the Assets.car precedent) and must stay listed.
+    if (isBrandingManagedPath(file, ctx.binaryName) &&
+        (!isNewFile || isGeneratedBrandingPath(file, ctx.binaryName))) {
+        return true;
+    }
+    for (const prefix of ctx.furnacePrefixes) {
+        if (file.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+async function findAdjacentUnmanagedFiles(args) {
+    const { currentFilesAffected, engineDir, manifest, patchFilename, ctx } = args;
+    const parentDirs = [...new Set(currentFilesAffected.map((file) => dirname(file)))];
+    const currentSet = new Set(currentFilesAffected);
+    const claimedByOthers = getClaimedFiles(manifest, patchFilename);
+    const candidates = new Set();
+    for (const dir of parentDirs) {
+        const [modifiedFiles, untrackedFiles] = await Promise.all([
+            getModifiedFilesInDir(engineDir, dir),
+            getUntrackedFilesInDir(engineDir, dir),
+        ]);
+        const untrackedSet = new Set(untrackedFiles);
+        for (const file of [...modifiedFiles, ...untrackedFiles]) {
+            if (currentSet.has(file) || claimedByOthers.has(file))
+                continue;
+            if (isToolManagedPath(file, untrackedSet.has(file), ctx))
+                continue;
+            candidates.add(file);
+        }
+    }
+    return [...candidates].sort();
+}
+/**
+ * Emits the scan-less advisory for one patch: missing manifest files and
+ * unmanaged files adjacent to the patch's ownership. When
+ * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
+ * exists, records the patch into `ctx.refusals` and returns true — the
+ * caller then skips the write for this patch and converts the collection
+ * into one run-level non-zero refusal after the loop.
+ */
+export async function reportAdjacentUnmanagedFiles(args) {
+    const { patch, paths, manifest, currentFilesAffected, ctx } = args;
+    const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
+    if (missingFiles.length > 0) {
+        warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
+            `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
+            `filesAffected unchanged and the missing entries will be preserved — ` +
+            `\`fireforge verify\` may flag manifest inconsistency after this run.\n` +
+            `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
+            `or pass --files <paths> to set the list explicitly.`);
+    }
+    const unmanagedFiles = await findAdjacentUnmanagedFiles({
+        currentFilesAffected,
+        engineDir: paths.engine,
+        manifest,
+        patchFilename: patch.filename,
+        ctx,
+    });
+    if (unmanagedFiles.length === 0)
+        return false;
+    const firstFew = unmanagedFiles.slice(0, 3).join(', ');
+    const more = unmanagedFiles.length > 3 ? `, +${String(unmanagedFiles.length - 3)} more` : '';
+    warn(`${patch.filename}: found ${String(unmanagedFiles.length)} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}); plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files.`);
+    for (const file of unmanagedFiles) {
+        info(`  ${file} — fireforge re-export ${patch.filename} --scan --scan-file ${file}`);
+    }
+    if (ctx.refuseAdjacentUnmanaged) {
+        ctx.refusals.push({ patchFilename: patch.filename, files: unmanagedFiles });
+        return true;
+    }
+    return false;
+}