@hominis/fireforge 0.38.0 → 0.40.0

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

@@ -3,14 +3,15 @@ import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
-import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
-import { invokePatchLintCheckJsGrouped, } from '../core/patch-lint-checkjs.js';
-import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { invokePatchLintCheckJsGrouped, runCheckJsTestFilesGrouped, } from '../core/patch-lint-checkjs.js';
+import { isTestScriptFile, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from '../core/patch-lint-ownership.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
+import { writePerPatchLintReport } from './lint-report.js';
 function buildPerPatchMaxWarningsMessage(count, maxWarnings, linted) {
     return (`Patch lint found ${count} warning(s) across ${linted} patch(es), exceeding --max-warnings ${maxWarnings}.` +
         ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
@@ -39,7 +40,14 @@ async function lintQueuedPatch(patch, lintCtx) {
             existing.push(f);
     }
     if (existing.length === 0) {
-        return { status: 'skipped', existingFiles: [], rawIssues: [], usedCheckJs: false };
+        return {
+            status: 'skipped',
+            existingFiles: [],
+            rawIssues: [],
+            suppressedIssues: [],
+            lineCount: 0,
+            usedCheckJs: false,
+        };
     }
     const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
     let cacheKey;
@@ -56,16 +64,38 @@ async function lintQueuedPatch(patch, lintCtx) {
         });
         const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
         if (cached) {
-            return { status: 'cached', existingFiles: existing, rawIssues: cached, usedCheckJs: false };
+            // Returning before the empty-diff probe below is safe: the cache key
+            // hashes every affected engine file's content plus engineHeadSha, so
+            // an engine-side revert that would empty the diff always changes the
+            // key and misses the cache (pinned by the "engine-side content
+            // revert invalidates the per-patch cache" test — FORGE F5).
+            return {
+                status: 'cached',
+                existingFiles: existing,
+                rawIssues: cached.issues,
+                suppressedIssues: cached.suppressed,
+                lineCount: cached.lineCount,
+                usedCheckJs: false,
+            };
         }
     }
     const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
     if (!diff.trim()) {
-        return { status: 'skipped', existingFiles: [], rawIssues: [], usedCheckJs: false };
+        return {
+            status: 'skipped',
+            existingFiles: [],
+            rawIssues: [],
+            suppressedIssues: [],
+            lineCount: 0,
+            usedCheckJs: false,
+        };
     }
     // checkJs: instead of rebuilding the program per patch, slice this patch's
     // findings out of the one queue-wide program (built lazily on first miss).
-    let lintOptions;
+    const suppressedIssues = [];
+    const lintOptions = {
+        onSuppressed: (suppressed) => suppressedIssues.push(...suppressed),
+    };
     let usedCheckJs = false;
     if (lintCtx.checkJs) {
         const grouped = await lintCtx.checkJs.getGrouped();
@@ -76,20 +106,28 @@ async function lintQueuedPatch(patch, lintCtx) {
             for (const rel of owned)
                 precomputedCheckJs.push(...(grouped.byFile.get(rel) ?? []));
         }
-        lintOptions = { precomputedCheckJs };
+        lintOptions.precomputedCheckJs = precomputedCheckJs;
     }
     const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier, lintOptions);
     const result = {
         status: 'linted',
         existingFiles: existing,
         rawIssues: patchIssues,
+        suppressedIssues,
+        lineCount: countNonBinaryDiffLines(diff).textLines,
         usedCheckJs,
     };
     if (cache && cacheKey) {
-        result.cacheWrite = { key: cacheKey, issues: patchIssues };
+        result.cacheWrite = { key: cacheKey };
     }
     return result;
 }
+/** Size-rule check IDs whose waived measurement is still reported (FORGE G10). */
+const SUPPRESSED_SIZE_CHECKS = new Set([
+    'large-patch-lines',
+    'large-patch-files',
+    'file-too-large',
+]);
 /**
  * Applies the per-patch results in patch order so the bounded concurrency
  * cannot reorder output: emits each tier notice, the once-only run-level
@@ -103,6 +141,7 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
         skipped: 0,
         cacheDirty: false,
         reusedCacheEntries: 0,
+        suppressed: 0,
     };
     let globalCheckJsEmitted = false;
     for (let i = 0; i < subset.length; i++) {
@@ -115,19 +154,34 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
             continue;
         }
         emitTierNotice(patch.filename, result.existingFiles, patch.tier);
-        // Run-level checkJs errors are emitted once, before the first freshly
-        // linted patch's own issues — matching the serial emit point.
-        if (result.usedCheckJs && checkJs && !globalCheckJsEmitted) {
+        // Run-level checkJs errors are emitted once, before the first
+        // non-skipped patch's own issues — matching the serial emit point.
+        // Deliberately NOT gated on `result.usedCheckJs`: global findings are
+        // run-level, never cached, and an all-cache-hit run previously dropped
+        // them entirely, letting a warm run report fewer errors than a cold
+        // one (FORGE F5 hardening). PerRunCheckJs builds its program lazily,
+        // so the cost only materialises when checkJs is configured.
+        if (checkJs && !globalCheckJsEmitted) {
             globalCheckJsEmitted = true;
             issues.push(...(await checkJs.getGlobal()));
         }
         if (result.cacheWrite && cache) {
-            setCachedPerPatchLintIssues(cache, patch.filename, result.cacheWrite.key, result.cacheWrite.issues);
+            setCachedPerPatchLintIssues(cache, patch.filename, result.cacheWrite.key, result.rawIssues, result.suppressedIssues, result.lineCount);
             totals.cacheDirty = true;
         }
         for (const issue of result.rawIssues) {
             issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
         }
+        // A waived size finding still reports its MEASUREMENT (FORGE G10):
+        // the finding stays suppressed (no exit-code / --max-warnings effect)
+        // but the current count is readable from the tool that enforces it,
+        // so a waiver's cited size can be calibrated without hand-measuring.
+        for (const suppressedIssue of result.suppressedIssues) {
+            if (!SUPPRESSED_SIZE_CHECKS.has(suppressedIssue.check))
+                continue;
+            info(`NOTICE [${suppressedIssue.check}] ${patch.filename}: suppressed by lintIgnore — ${suppressedIssue.message}`);
+        }
+        totals.suppressed += result.suppressedIssues.length;
         if (result.status === 'cached')
             totals.reusedCacheEntries++;
         totals.linted++;
@@ -238,7 +292,9 @@ function selectPatchSubset(manifest, requested) {
         const found = manifest.patches.filter((p) => matches(p, name));
         if (found.length === 0) {
             const available = manifest.patches.map((p) => p.filename).join(', ');
-            throw new GeneralError(`--patches: no patch in the queue matches "${name}". Available patches: ${available}`);
+            throw new GeneralError(`No patch in the queue matches "${name}". In --per-patch mode, positional arguments ` +
+                `and --patches select patches (filename, stem, manifest name, or slug) — not engine ` +
+                `files; drop --per-patch to lint engine paths. Available patches: ${available}`);
         }
         for (const p of found) {
             if (!seen.has(p.filename)) {
@@ -259,24 +315,41 @@ function buildPerRunCheckJs(projectRoot, paths, config, ctx) {
     const patchLint = config.patchLint;
     if (!patchLint?.checkJs)
         return undefined;
+    const testFilesEnabled = patchLint.checkJsTestFiles === true;
     const ownedByPatch = new Map();
     for (const entry of ctx.entries) {
         const owned = new Set();
         for (const f of entry.newFiles.keys()) {
             if (f.endsWith('.sys.mjs'))
                 owned.add(f);
+            else if (testFilesEnabled && isTestScriptFile(f))
+                owned.add(f);
         }
         if (owned.size > 0)
             ownedByPatch.set(entry.filename, owned);
     }
+    // One build for the whole run: the queue-wide `.sys.mjs` program plus —
+    // when `patchLint.checkJsTestFiles` is on (FORGE G5) — one small
+    // script-scope program per patch-owned test file, merged by file.
+    const buildAll = async () => {
+        const sys = await invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot);
+        if (!testFilesEnabled)
+            return sys;
+        const tests = await runCheckJsTestFilesGrouped(paths.engine, resolvePatchOwnedTestScripts(new Set(), ctx), patchLint, projectRoot);
+        const byFile = new Map(sys.byFile);
+        for (const [rel, list] of tests.byFile) {
+            byFile.set(rel, [...(byFile.get(rel) ?? []), ...list]);
+        }
+        return { byFile, global: [...sys.global, ...tests.global] };
+    };
     // Memoise the *promise*, not the resolved value: under the bounded pool
     // several patches can reach `getGrouped` before the first build resolves, and
     // `??=` on the promise (a synchronous expression) guarantees a single build.
     let groupedPromise;
     return {
         ownedByPatch,
-        getGrouped: () => (groupedPromise ??= invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot)),
-        getGlobal: async () => (groupedPromise ? (await groupedPromise).global : []),
+        getGrouped: () => (groupedPromise ??= buildAll()),
+        getGlobal: async () => (await (groupedPromise ??= buildAll())).global,
     };
 }
 /**
@@ -299,7 +372,7 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
     const subsetNames = new Set(subset.map((p) => p.filename));
     const isSubset = subset.length !== manifest.patches.length;
     const config = await loadConfig(projectRoot);
-    const ctx = await buildPatchQueueContext(paths.patches);
+    const ctx = await buildPatchQueueContext(paths.patches, config);
     // Queue-level findings (policy, cross-patch) are scoped to the requested
     // subset: a 5-patch slice should not fail on a policy or forward-import
     // problem owned entirely by patches the operator did not target.
@@ -340,7 +413,7 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
         engineHeadSha,
         checkJs,
     });
-    const { linted, skipped, cacheDirty, reusedCacheEntries } = await applyPerPatchResults(subset, results, issues, checkJs, cache);
+    const { linted, skipped, cacheDirty, reusedCacheEntries, suppressed } = await applyPerPatchResults(subset, results, issues, checkJs, cache);
     for (const issue of lintPatchQueue(ctx)) {
         if (isSubset && !subsetTouchedFiles.has(issue.file))
             continue;
@@ -351,5 +424,11 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
     if (reusedCacheEntries > 0) {
         info(`Reused lint cache for ${reusedCacheEntries} patch${reusedCacheEntries === 1 ? '' : 'es'}.`);
     }
+    if (suppressed > 0) {
+        info(`Suppressed ${suppressed} issue(s) via per-patch lintIgnore.`);
+    }
+    if (options.report !== undefined) {
+        await writePerPatchLintReport(options.report, subset, results);
+    }
     reportPerPatchOutcome(issues, linted, skipped, options);
 }

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

@@ -0,0 +1,21 @@
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Structural view of one per-patch lint outcome. Mirrors the relevant
+ * fields of lint-per-patch's QueuedPatchResult without importing it —
+ * that module imports this one, and a type back-edge would trip the
+ * dpdm cycle gate.
+ */
+export interface PerPatchReportResult {
+    status: 'skipped' | 'cached' | 'linted';
+    existingFiles: string[];
+    rawIssues: PatchLintIssue[];
+    suppressedIssues: PatchLintIssue[];
+    lineCount: number;
+}
+/**
+ * Writes the per-patch lint report JSON. Called after the per-patch
+ * results are assembled in patch order; queue-level and policy findings
+ * are patch-attributed by their `file`/`filename` fields upstream and
+ * are NOT duplicated here — the report is the per-patch view.
+ */
+export declare function writePerPatchLintReport(reportPath: string, subset: readonly PatchMetadata[], results: readonly PerPatchReportResult[]): Promise<void>;

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

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Machine-readable per-patch lint report (`lint --per-patch --report
+ * <path>`, FORGE G9 + G10). One mechanism serves both observability
+ * gaps: consumers get each patch's size metrics against the SAME
+ * thresholds the size rules fire on (no more mirroring
+ * `countNonBinaryDiffLines`), and lintIgnore-suppressed issues stay
+ * visible with their measurements instead of vanishing.
+ *
+ * Helper module consumed by lint-per-patch.ts; no registrar is exported
+ * and none is wanted.
+ */
+import { getPatchSizeThresholds, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { writeJson } from '../utils/fs.js';
+import { info } from '../utils/logger.js';
+const LINT_REPORT_SCHEMA_VERSION = 1;
+/**
+ * Writes the per-patch lint report JSON. Called after the per-patch
+ * results are assembled in patch order; queue-level and policy findings
+ * are patch-attributed by their `file`/`filename` fields upstream and
+ * are NOT duplicated here — the report is the per-patch view.
+ */
+export async function writePerPatchLintReport(reportPath, subset, results) {
+    const patches = [];
+    let errors = 0;
+    let warnings = 0;
+    let suppressed = 0;
+    let linted = 0;
+    let skipped = 0;
+    for (let i = 0; i < subset.length; i++) {
+        const patch = subset[i];
+        const result = results[i];
+        if (!patch || !result)
+            continue;
+        const tier = resolvePatchSizeTier(result.existingFiles, patch.tier);
+        patches.push({
+            filename: patch.filename,
+            name: patch.name,
+            status: result.status,
+            lineCount: result.lineCount,
+            filesAffected: patch.filesAffected.length,
+            tier,
+            thresholds: getPatchSizeThresholds(tier.tier),
+            issues: result.rawIssues,
+            suppressedIssues: result.suppressedIssues,
+        });
+        if (result.status === 'skipped')
+            skipped++;
+        else
+            linted++;
+        errors += result.rawIssues.filter((issue) => issue.severity === 'error').length;
+        warnings += result.rawIssues.filter((issue) => issue.severity === 'warning').length;
+        suppressed += result.suppressedIssues.length;
+    }
+    await writeJson(reportPath, {
+        schemaVersion: LINT_REPORT_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        patches,
+        totals: { linted, skipped, errors, warnings, suppressed },
+    });
+    info(`Per-patch lint report written to ${reportPath}.`);
+}

package/dist/src/commands/lint.js

@@ -217,11 +217,12 @@ export function applyAggregateLintIgnoreSuppression(issues, ctx) {
 }
 /**
  * Up-front flag validation for `lintCommand`: rejects `--only-introduced`
- * without `--since`, non-integer `--max-warnings`, and `--per-patch`
- * combined with explicit file paths — each a misconfiguration that should
- * fail loud rather than silently narrow the result.
+ * without `--since` and non-integer `--max-warnings` — each a
+ * misconfiguration that should fail loud rather than silently narrow the
+ * result. Positional arguments in per-patch mode are patch selectors
+ * (FORGE G14) and are validated downstream by `selectPatchSubset`.
  */
-function validateLintFlags(options, files) {
+function validateLintFlags(options) {
     // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
     // without a revision to anchor the diff there is no "introduced" subset
     // to scope to — reject the combination up-front so a misconfigured CI
@@ -234,22 +235,16 @@ function validateLintFlags(options, files) {
         (!Number.isInteger(options.maxWarnings) || options.maxWarnings < 0)) {
         throw new GeneralError('--max-warnings must be a non-negative integer.');
     }
-    // `--per-patch` rescopes the diff from "aggregate engine state" to "each
-    // patch's own filesAffected". Mixing in explicit engine file paths would
-    // produce an ambiguous set — is the file list an additional filter, or
-    // does it replace the per-patch scope? Reject up-front, but point at the
-    // first-class subset filter so an operator who wanted to target patches
-    // (not engine files) knows the supported syntax.
-    if (options.perPatch && files.length > 0) {
-        throw new GeneralError('--per-patch cannot be combined with explicit engine file paths. ' +
-            'To lint a subset of patches, use `--per-patch --patches <name…>`; ' +
-            'to lint specific engine files, drop --per-patch.');
-    }
     // `--patches` only means something in per-patch mode (it filters the
     // queue); in aggregate/file-list mode there is no patch loop to narrow.
     if (options.patches !== undefined && !options.perPatch) {
         throw new GeneralError('--patches requires --per-patch.');
     }
+    // The JSON report is a per-patch artifact (per-patch size metrics and
+    // suppressed issues); aggregate mode has no per-patch rows to report.
+    if (options.report !== undefined && !options.perPatch) {
+        throw new GeneralError('--report requires --per-patch.');
+    }
 }
 /**
  * Aggregate-mode patch-size softening: when the linted diff is every
@@ -429,7 +424,7 @@ async function reportLintOutcome(engineDir, issues, options) {
  */
 export async function lintCommand(projectRoot, files, options = {}) {
     intro('FireForge Lint');
-    validateLintFlags(options, files);
+    validateLintFlags(options);
     const paths = getProjectPaths(projectRoot);
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
@@ -438,7 +433,12 @@ export async function lintCommand(projectRoot, files, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     if (options.perPatch) {
-        await lintPerPatch(projectRoot, paths, options);
+        // Positional arguments in per-patch mode select PATCHES through the
+        // same alias resolution as --patches (FORGE G14) — a non-matching
+        // positional fails loud against the queue listing, so an engine path
+        // can never silently lint. Explicit --patches entries come first.
+        const perPatchOptions = files.length > 0 ? { ...options, patches: [...(options.patches ?? []), ...files] } : options;
+        await lintPerPatch(projectRoot, paths, perPatchOptions);
         return;
     }
     // Load the config before resolving the diff so we can pass
@@ -461,7 +461,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     // per-patch ownership resolver and the cross-patch rules.
     let ctx;
     if (await pathExists(paths.patches)) {
-        ctx = await buildPatchQueueContext(paths.patches);
+        ctx = await buildPatchQueueContext(paths.patches, config);
     }
     // Ad-hoc explicit-file-list mode evaluates the patch-size rules per
     // owning patch (see `lintOwningPatchSizes`), so suppress the synthetic
@@ -511,9 +511,10 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
-        .option('--patches <names...>', 'With --per-patch, lint only the named patches. Accepts repeated flags, comma lists, full filenames/stems, manifest names, category-prefixed slugs, or bare slugs.')
+        .option('--patches <names...>', 'With --per-patch, lint only the named patches. Accepts repeated flags, comma lists, full filenames/stems, manifest names, category-prefixed slugs, or bare slugs. Positional arguments after --per-patch are treated the same way.')
         .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes.')
+        .option('--report <path>', 'With --per-patch, write a machine-readable JSON report (per-patch size metrics, tier, thresholds, issues, and lintIgnore-suppressed issues) to <path>.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -538,6 +539,9 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.cache === false) {
             lintOptions.noCache = true;
         }
+        if (options.report !== undefined) {
+            lintOptions.report = options.report;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
     const lintCache = lint

package/dist/src/commands/manifest.js

@@ -22,6 +22,7 @@ import { registerSource } from './source.js';
 import { registerStatus } from './status.js';
 import { registerTest } from './test-register.js';
 import { registerToken } from './token.js';
+import { registerTree } from './tree.js';
 import { registerTypecheck } from './typecheck.js';
 import { registerVerify } from './verify.js';
 import { registerWatch } from './watch.js';
@@ -50,6 +51,7 @@ export const COMMAND_MANIFEST = [
     { name: 'package', group: 'workflow', register: registerPackage },
     { name: 'watch', group: 'workflow', register: registerWatch },
     { name: 'test', group: 'workflow', register: registerTest },
+    { name: 'tree', group: 'workflow', register: registerTree },
     { name: 'config', group: 'project', register: registerConfig },
     { name: 'doctor', group: 'diagnostics', register: registerDoctor },
     { name: 'register', group: 'workflow', register: registerRegister },

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

@@ -26,6 +26,16 @@ 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';
+/**
+ * Printed whenever `--add` lands a new check id. The waiver this command
+ * writes turns per-patch lint green immediately, but consumer projects
+ * commonly audit lintIgnore lists against a reviewed allow-map — the
+ * discovery that the map also needs updating otherwise costs a full
+ * downstream gate run (FORGE F6).
+ */
+const LINT_IGNORE_REVIEW_WARNING = "This lint waiver is subject to the project's patch-policy review process. " +
+    'Downstream policy audits that mirror lintIgnore lists in a reviewed allow-map ' +
+    'will refuse this patch until the map is updated to include the new ID(s).';
 /**
  * Computes the post-mutation `lintIgnore` list for a given mode.
  * Returns `undefined` when the result should drop the field from the
@@ -114,7 +124,10 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     // the flag only appeared in the history record — and suppressing lint
     // findings is precisely the mutation an operator should consciously
     // approve.
-    const projectedSummary = describeChange(target.lintIgnore ?? [], applyMode(target.lintIgnore ?? [], mode, values) ?? [], mode, values);
+    const currentList = target.lintIgnore ?? [];
+    const projectedList = applyMode(currentList, mode, values) ?? [];
+    const addsNewIds = mode === 'add' && projectedList.length > currentList.length;
+    const projectedSummary = describeChange(currentList, projectedList, mode, values);
     const decision = await confirmDestructive({
         operation: 'patch-lint-ignore',
         title: `Patch lint-ignore: ${target.filename}`,
@@ -123,6 +136,9 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         dryRun: isDryRun,
     });
     if (decision === 'dry-run') {
+        if (addsNewIds) {
+            warn(LINT_IGNORE_REVIEW_WARNING);
+        }
         outro('Dry run complete — no changes made');
         return;
     }
@@ -148,6 +164,9 @@ 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) {
+        warn(LINT_IGNORE_REVIEW_WARNING);
+    }
     try {
         await appendHistory(paths.patches, {
             operation: 'patch-lint-ignore',

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

@@ -0,0 +1,47 @@
+/**
+ * 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 type { PatchMetadata, PatchMoveFilesOptions, PatchStagedForwardImport } from '../../types/commands/index.js';
+import type { FireForgeConfig } from '../../types/config.js';
+/** Everything the commit step needs, computed and confirmed up front. */
+export interface MoveIntoPlan {
+    source: PatchMetadata;
+    target: PatchMetadata;
+    movedFiles: string[];
+    sourceAfter: string[];
+    targetAfter: string[];
+    sourceDiff: string;
+    targetDiff: string;
+    /** Patches (by filename) whose staged-dependency owners re-point to the target. */
+    ownerRewrites: string[];
+    /** Forward-import declarations the move introduces, keyed by importing patch. */
+    stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+}
+/**
+ * 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 declare function runMoveFilesInto(args: {
+    enginePath: string;
+    patchesDir: string;
+    source: PatchMetadata;
+    target: PatchMetadata;
+    files: string[];
+    sourceAfter: string[];
+    targetAfter: string[];
+    options: PatchMoveFilesOptions;
+    config: FireForgeConfig;
+}): Promise<void>;