@hominis/fireforge 0.42.0 → 0.43.0

package/dist/src/commands/furnace/chrome-doc-remove.js

@@ -87,6 +87,9 @@ async function performChromeDocRemoveMutations(args) {
         await removeEmptyDirIfPresent(join(args.engineDir, 'browser/base/content/test', `${args.binaryName}-xpcshell`), journal);
     }
     catch (error) {
+        // This body owns its rollback end to end, so tell the lifecycle wrapper
+        // not to restore the same journal again on the way out.
+        args.operationContext.markRolledBack();
         try {
             await restoreRollbackJournalOrThrow(journal, `Failed to remove chrome-doc "${args.name}"`);
         }

package/dist/src/commands/furnace/chrome-doc.js

@@ -274,6 +274,9 @@ async function performChromeDocMutations(args) {
         }
     }
     catch (error) {
+        // This body owns its rollback end to end, so tell the lifecycle wrapper
+        // not to restore the same journal again on the way out.
+        args.operationContext.markRolledBack();
         try {
             await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
         }

package/dist/src/commands/furnace/create.js

@@ -199,6 +199,9 @@ async function performCreateMutations(args) {
         }
     }
     catch (error) {
+        // This body owns its rollback end to end, so tell the lifecycle wrapper
+        // not to restore the same journal again on the way out.
+        args.operationContext?.markRolledBack();
         try {
             await restoreRollbackJournalOrThrow(journal, `Failed to create custom component "${args.componentName}"`);
         }

package/dist/src/commands/furnace/override.js

@@ -137,6 +137,9 @@ async function performOverrideMutations(args) {
             return filesCopied;
         }
         catch (error) {
+            // This body owns its rollback end to end, so tell the lifecycle
+            // wrapper not to restore the same journal again on the way out.
+            ctx.markRolledBack();
             try {
                 await restoreRollbackJournalOrThrow(journal, `Failed to override component "${args.componentName}"`);
             }

package/dist/src/commands/furnace/preview.js

@@ -325,6 +325,9 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
         // message with no guidance. We now collect both failures and, if anything
         // went wrong, persist a `pendingRepair` marker that `fireforge doctor`
         // consumes to finish the reconciliation.
+        // Teardown restores the journal itself, so the lifecycle wrapper must not
+        // restore it again when the throw below propagates out of this body.
+        ctx.markRolledBack();
         const teardownErrors = await runPreviewTeardown(paths.engine, storiesCleanupRequired, previewJournal);
         if (teardownErrors.length > 0) {
             const teardownSummary = teardownErrors.map((err) => err.message).join('; ');

package/dist/src/commands/furnace/refresh.js

@@ -145,6 +145,9 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
         }
         catch (error) {
             if (!dryRun) {
+                // This body owns its rollback end to end, so tell the lifecycle
+                // wrapper not to restore the same journal again on the way out.
+                ctx.markRolledBack();
                 try {
                     await restoreRollbackJournalOrThrow(journal, `Failed to refresh override "${name}"`);
                 }

package/dist/src/commands/furnace/remove.js

@@ -405,6 +405,9 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
             }
         }
         catch (error) {
+            // This body owns its rollback end to end, so tell the lifecycle wrapper
+            // not to restore the same journal again on the way out.
+            ctx.markRolledBack();
             try {
                 await restoreRollbackJournalOrThrow(journal, `Failed to remove component "${name}"`);
             }

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

@@ -308,6 +308,9 @@ async function performRenameMutations(args) {
             info(`Renamed ${componentType} component: ${oldName} → ${newName}`);
         }
         catch (error) {
+            // This body owns its rollback end to end, so tell the lifecycle wrapper
+            // not to restore the same journal again on the way out.
+            ctx.markRolledBack();
             try {
                 if (await pathExists(newDir)) {
                     await removeDir(newDir);

package/dist/src/commands/furnace/scan.js

@@ -92,6 +92,9 @@ async function persistStockComponents(projectRoot, names) {
             await writeFurnaceConfig(projectRoot, config);
         }
         catch (error) {
+            // This body owns its rollback end to end, so tell the lifecycle wrapper
+            // not to restore the same journal again on the way out.
+            ctx.markRolledBack();
             try {
                 await restoreRollbackJournalOrThrow(journal, 'Failed to update furnace.json during scan');
             }

package/dist/src/commands/import.js

@@ -408,7 +408,7 @@ export async function importCommand(projectRoot, options = {}) {
         }
         // The re-applied queue 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).
+        // next test refusal.
         await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('All patches applied successfully!');
     }

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

@@ -2,6 +2,7 @@
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
+import { withPrivateGitIndex } from '../core/git-readonly-index.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
 import { buildPatchQueueContext, countNonBinaryDiffLines, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
@@ -59,13 +60,13 @@ async function lintQueuedPatch(patch, lintCtx) {
             queueContext: ctx,
             ...(engineHeadSha === undefined ? {} : { engineHeadSha }),
         });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, ignore);
         if (cached) {
             // 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).
+            // revert invalidates the per-patch cache" test).
             return {
                 status: 'cached',
                 existingFiles: existing,
@@ -115,11 +116,11 @@ async function lintQueuedPatch(patch, lintCtx) {
         usedCheckJs,
     };
     if (cache && cacheKey) {
-        result.cacheWrite = { key: cacheKey };
+        result.cacheWrite = { key: cacheKey, lintIgnore: [...(ignore ?? [])] };
     }
     return result;
 }
-/** Size-rule check IDs whose waived measurement is still reported (FORGE G10). */
+/** Size-rule check IDs whose waived measurement is still reported. */
 const SUPPRESSED_SIZE_CHECKS = new Set([
     'large-patch-lines',
     'large-patch-files',
@@ -156,20 +157,20 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
         // 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,
+        // one (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.rawIssues, result.suppressedIssues, result.lineCount);
+            setCachedPerPatchLintIssues(cache, patch.filename, result.cacheWrite.key, result.rawIssues, result.suppressedIssues, result.lineCount, result.cacheWrite.lintIgnore);
             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):
+        // A waived size finding still reports its MEASUREMENT:
         // 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.
@@ -310,6 +311,13 @@ function selectPatchSubset(manifest, requested) {
  * queue-level findings are scoped to files those patches touch).
  */
 export async function lintPerPatch(projectRoot, paths, options = {}) {
+    // Read-only to the operator, an index WRITER to git: the per-patch diffs
+    // run `git diff HEAD` (and, for untracked binaries, a real stage/unstage
+    // pair) against the primary checkout. A private index absorbs all of it
+    // so a concurrent `fireforge test` still gets an evidential verdict.
+    return withPrivateGitIndex(paths.engine, () => lintPerPatchInner(projectRoot, paths, options));
+}
+async function lintPerPatchInner(projectRoot, paths, options = {}) {
     const manifest = await loadPatchesManifest(paths.patches);
     if (!manifest || manifest.patches.length === 0) {
         info('No patches in manifest — nothing to lint per-patch.');
@@ -352,7 +360,7 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
     }
     // With `--patches`, the checkJs program roots at only the subset's owned
     // files — the full queue stays resolvable, so a cold subset run costs the
-    // subset's import closure instead of the whole queue (FORGE J1c).
+    // subset's import closure instead of the whole queue.
     const checkJs = buildPerRunCheckJs(projectRoot, paths, config, ctx, isSubset ? subsetNames : undefined);
     // Lint patches concurrently, then apply every side effect in patch order so
     // the issue rows, the run-level checkJs errors, and the saved cache are

package/dist/src/commands/lint-per-run-checkjs.d.ts

@@ -1,6 +1,6 @@
 /**
  * Per-run checkJs program controller, shared by `lint --per-patch` and
- * `re-export` (FORGE J1).
+ * `re-export`.
  *
  * The dominant fixed cost of patch lint is one `ts.createProgram` over the
  * queue's patch-owned `.sys.mjs` files (~37 s on a 290-patch consumer
@@ -13,11 +13,11 @@
  * - **Root scoping** (`rootScopePatches`): with `--patches <subset>` the
  *   program's roots are only the subset's owned files; the full queue
  *   stays resolvable, so cross-patch imports type-check identically while
- *   unrelated files are never parsed (FORGE J1c).
+ * unrelated files are never parsed.
  * - **Warm-run probe**: run-level ("global") checkJs findings come only
  *   from a missing `typescript` package or an unreadable shim — never
  *   from the built program — so an all-cache-hit run satisfies "warm
- *   never reports less than cold" (FORGE F5) via
+ * never reports less than cold" via
  *   `probeCheckJsGlobalIssues` instead of building anything.
  */
 import type { getProjectPaths, loadConfig } from '../core/config.js';
@@ -43,7 +43,7 @@ export interface PerRunCheckJs {
     getGrouped: () => Promise<GroupedCheckJsResult>;
     /** Run-level checkJs errors (e.g. TypeScript missing). When the program
      *  was never built (all-warm run) this probes the two global failure
-     *  sources directly instead of building it — FORGE F5 holds because the
+     * sources directly instead of building it holds because the
      *  built program never contributes globals of its own. */
     getGlobal: () => Promise<PatchLintIssue[]>;
     /** The byFile slices for `files` (globals deliberately EXCLUDED — they

package/dist/src/commands/lint-per-run-checkjs.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Per-run checkJs program controller, shared by `lint --per-patch` and
- * `re-export` (FORGE J1).
+ * `re-export`.
  *
  * The dominant fixed cost of patch lint is one `ts.createProgram` over the
  * queue's patch-owned `.sys.mjs` files (~37 s on a 290-patch consumer
@@ -14,11 +14,11 @@
  * - **Root scoping** (`rootScopePatches`): with `--patches <subset>` the
  *   program's roots are only the subset's owned files; the full queue
  *   stays resolvable, so cross-patch imports type-check identically while
- *   unrelated files are never parsed (FORGE J1c).
+ * unrelated files are never parsed.
  * - **Warm-run probe**: run-level ("global") checkJs findings come only
  *   from a missing `typescript` package or an unreadable shim — never
  *   from the built program — so an all-cache-hit run satisfies "warm
- *   never reports less than cold" (FORGE F5) via
+ * never reports less than cold" via
  *   `probeCheckJsGlobalIssues` instead of building anything.
  */
 import { invokePatchLintCheckJsGrouped, probeCheckJsGlobalIssues, runCheckJsTestFilesGrouped, } from '../core/patch-lint-checkjs.js';
@@ -64,7 +64,7 @@ export function buildPerRunCheckJs(projectRoot, paths, config, ctx, rootScopePat
         }
     }
     // One build for the whole run: the queue-wide `.sys.mjs` program plus —
-    // when `patchLint.checkJsTestFiles` is on (FORGE G5) — one small
+    // when `patchLint.checkJsTestFiles` is on — 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, scopedRoots);

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

@@ -1,7 +1,7 @@
 // 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
+ * <path>`, + 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

package/dist/src/commands/lint.js

@@ -220,7 +220,7 @@ export function applyAggregateLintIgnoreSuppression(issues, ctx) {
  * 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`.
+ * and are validated downstream by `selectPatchSubset`.
  */
 function validateLintFlags(options) {
     // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
@@ -434,7 +434,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     }
     if (options.perPatch) {
         // Positional arguments in per-patch mode select PATCHES through the
-        // same alias resolution as --patches (FORGE G14) — a non-matching
+        // same alias resolution as --patches — 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;

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

@@ -32,7 +32,7 @@ import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
  * 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).
+ * downstream gate run.
  */
 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 ' +

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

@@ -11,7 +11,7 @@
  * new patch's name/slug the way `split --name` does.
  */
 import { getProjectPaths, loadConfig } from '../../core/config.js';
-import { confirmDestructive } from '../../core/destructive.js';
+import { assertConfirmationAvailable, confirmDestructive } from '../../core/destructive.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
@@ -31,6 +31,8 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     intro(options.dryRun === true
         ? 'FireForge patch move-files --create (dry run)'
         : 'FireForge patch move-files --create');
+    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    assertConfirmationAvailable('patch move-files --create', options);
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     const manifest = await loadPatchesManifest(paths.patches);
@@ -64,7 +66,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, newPatchName, config);
     // The filename slug pipeline (resolvePlacementPlan above) strips redundant
     // category prefixes; the manifest display name must agree with the bare-slug
-    // naming policy, exactly as `export --name` already does (FORGE G13/H4).
+    // naming policy, exactly as `export --name` already does.
     const displayName = normalizePatchDisplayName(newPatchName, category);
     if (displayName !== newPatchName) {
         info(`Patch name normalized: "${newPatchName}" → "${displayName}" (the filename carries the order and category prefix).`);
@@ -90,7 +92,7 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
     // same patch-policy shape as the committed `lint --per-patch` gate) makes
     // cross-patch `resource:///` imports and sibling head.js harness roots
     // resolve exactly as they will after the move lands — without it the
-    // projection lint was blind (FORGE I3).
+    // projection lint was blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
     await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);

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

@@ -1,5 +1,5 @@
 /**
- * Transactional file-ownership move into an EXISTING patch (FORGE F4).
+ * Transactional file-ownership move into an EXISTING patch.
  *
  * 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

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Transactional file-ownership move into an EXISTING patch (FORGE F4).
+ * Transactional file-ownership move into an EXISTING patch.
  *
  * 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
@@ -15,7 +15,7 @@
  * the worktree.
  */
 import { join } from 'node:path';
-import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { appendHistory, assertConfirmationAvailable, 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, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
@@ -193,12 +193,14 @@ async function commitMoveInto(patchesDir, plan, waitLockSeconds) {
  */
 export async function runMoveFilesInto(args) {
     const { enginePath, patchesDir, source, target, files, sourceAfter, targetAfter, options } = args;
+    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    assertConfirmationAvailable('patch move-files', options);
     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.
     // The whole-queue context (built once, with the config for committed-gate
     // parity) resolves cross-patch imports and sibling head.js harness roots
-    // instead of linting each projected body blind (FORGE I3).
+    // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(patchesDir, args.config);
     await runPatchLint(enginePath, sourceAfter, sourceDiff, args.config, options.skipLint, patchQueueCtx, source.lintIgnore ? new Set(source.lintIgnore) : undefined, source.tier);
     await runPatchLint(enginePath, targetAfter, targetDiff, args.config, options.skipLint, patchQueueCtx, target.lintIgnore ? new Set(target.lintIgnore) : undefined, target.tier);

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

@@ -133,7 +133,7 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     // 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).
+    // duplicate-new-file-creation.
     const applySource = formatReExportCommand(source.filename, sourceAfter, [
         '--allow-shrink',
         '--yes',

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

@@ -208,7 +208,7 @@ function resolveRenamePlan(target, options, config) {
  * Pre-flight refusals: order collision (with a pointer to the verb that
  * renumbers siblings — `--order` means "this exact unused sparse slot",
  * mirroring `export --order`), projected cross-patch lint on an order
- * change (forward imports resolve by queue position, FORGE J10), and the
+ * change (forward imports resolve by queue position), and the
  * filename collision. The authoritative collision checks run again inside
  * the lock to close the TOCTOU window.
  */

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

@@ -17,8 +17,7 @@ export declare function rebuildFilenameForOrder(existing: PatchMetadata, newOrde
 /**
  * Applies a rename map to a {@link PatchQueueContext} so cross-patch lint
  * can run against the projected state without touching disk. Exported for
- * `patch rename --order`, which projects the same single-row move shape
- * (FORGE J10).
+ * `patch rename --order`, which projects the same single-row move shape.
  */
 export declare function projectReorder(base: PatchQueueContext, renameMap: Map<string, PatchRenameEntry>): PatchQueueContext;
 /**

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

@@ -120,8 +120,7 @@ function renameMapsEqual(left, right) {
 /**
  * Applies a rename map to a {@link PatchQueueContext} so cross-patch lint
  * can run against the projected state without touching disk. Exported for
- * `patch rename --order`, which projects the same single-row move shape
- * (FORGE J10).
+ * `patch rename --order`, which projects the same single-row move shape.
  */
 export function projectReorder(base, renameMap) {
     const ownerLookup = (oldFilename) => renameMap.get(oldFilename)?.newFilename;

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

@@ -20,7 +20,7 @@
 import { join } from 'node:path';
 import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
-import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { appendHistory, assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
 import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
@@ -166,6 +166,8 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
  */
 export async function patchSplitCommand(projectRoot, sourceId, options) {
     intro(options.dryRun ? 'FireForge patch split (dry run)' : 'FireForge patch split');
+    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    assertConfirmationAvailable('patch split', options);
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     const manifest = await loadPatchesManifest(paths.patches);
@@ -199,7 +201,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
     const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
     // The filename slug pipeline strips redundant category prefixes; the
     // manifest display name must agree with the bare-slug naming policy,
-    // exactly as `export --name` already does (FORGE G13/H4).
+    // exactly as `export --name` already does.
     const displayName = normalizePatchDisplayName(options.name, category);
     if (displayName !== options.name) {
         info(`Patch name normalized: "${options.name}" → "${displayName}" (the filename carries the order and category prefix).`);
@@ -223,7 +225,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
     // tier/lintIgnore so an intentional-advisory patch can still split.
     // The whole-queue context (built once, with the config for committed-gate
     // parity) resolves cross-patch imports and sibling head.js harness roots
-    // instead of linting each projected body blind (FORGE I3).
+    // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
     await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Shape validation for `patch staged-dependency --add` (FORGE K10).
+ * Shape validation for `patch staged-dependency --add`.
  *
  * `--creates`/`--file` take engine-relative FILE paths and `--owner`
  * takes a patch FILENAME, but all three were accepted as arbitrary

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

@@ -11,7 +11,7 @@ import { toError } from '../../utils/errors.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
-/** Joins the names of the missing flags for error attribution (FORGE G12). */
+/** Joins the names of the missing flags for error attribution. */
 function missingFlagList(pairs) {
     return pairs
         .filter(([, value]) => value === undefined || value === '')
@@ -83,7 +83,7 @@ function requireRegistrationOptions(options) {
     return dependency;
 }
 /**
- * Resolves the `--remove` target for forward-imports (FORGE G12):
+ * Resolves the `--remove` target for forward-imports:
  * `--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
@@ -219,7 +219,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     const kind = kindFromOptions(options);
     // The patch queue loads BEFORE the declaration fields resolve so
     // `--remove` can infer `--creates` from the target patch's staged
-    // entries (FORGE G12).
+    // entries.
     const { paths, manifest } = await requirePatchQueue(projectRoot);
     const targetPatch = requirePatchTarget(identifier, manifest.patches);
     const importDependency = mode === 'clear' || kind !== 'import'
@@ -232,7 +232,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
         : mode === 'add'
             ? requireRegistrationOptions(options)
             : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
-    // Shape-check --add declarations against the loaded queue (FORGE K10):
+    // Shape-check --add declarations against the loaded queue:
     // a patch-name-shaped --creates/--file is refused HERE instead of
     // surfacing later as an undischargeable staged-dependency-unused.
     if (mode === 'add') {

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Scan-less re-export adjacency advisory (FORGE G2). A plain `re-export`
+ * Scan-less re-export adjacency advisory. 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

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

@@ -2,7 +2,7 @@ import type { PatchesManifest } from '../types/commands/index.js';
 /** Loads and validates a `re-export --scan-files` assignment manifest. */
 export declare function loadScanFilesAssignments(manifestPath: string, manifest: PatchesManifest): Promise<Map<string, string[]>>;
 /**
- * Runtime enforcement of the dry-run purity contract (FORGE H1): fingerprints
+ * Runtime enforcement of the dry-run purity contract: fingerprints
  * the engine tree and every patch artifact before and after `operation`, and
  * throws when a dry-run changed anything it promised only to inspect. This
  * turns any recurrence of the 0.40.0 "dry-run reverted a just-written export"

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

@@ -4,6 +4,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isUnavailableGenerationToken, snapshotEngineGeneration, unavailableGenerationReason, } from '../core/engine-session-lock.js';
 import { createSiblingLockPath, withFileLock } from '../core/file-lock.js';
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
 import { resolvePatchIdentifier } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
@@ -55,8 +56,8 @@ export async function loadScanFilesAssignments(manifestPath, manifest) {
     for (const assignment of parsed.assignments) {
         const patch = resolvePatchIdentifier(assignment.patch, manifest.patches);
         if (!patch) {
-            const available = manifest.patches.map((entry) => entry.filename).join(', ');
-            throw new InvalidArgumentError(`--scan-files patch "${assignment.patch}" not found in manifest.\n\nAvailable patches: ${available}`, '--scan-files');
+            // Suggest, never dump.
+            throw new InvalidArgumentError(`--scan-files: ${formatPatchNotFoundError(assignment.patch, manifest.patches)}`, '--scan-files');
         }
         const patchFiles = filesByPatch.get(patch.filename) ?? new Set();
         filesByPatch.set(patch.filename, patchFiles);
@@ -77,7 +78,7 @@ export async function loadScanFilesAssignments(manifestPath, manifest) {
  * disturb: the engine's commit + working-tree status (via the same generation
  * token `fireforge test` uses) and the byte content of every regular file
  * under `patches/` — ALL of them, not just the selected patches, because the
- * FORGE H1 field incident was a dry-run of patch B reverting a just-written
+ * field incident was a dry-run of patch B reverting a just-written
  * export of patch A. A missing patches directory (ENOENT/ENOTDIR) fingerprints
  * as empty — there is nothing there to protect — but any other listing failure
  * (EACCES, EIO, …) throws: an unreadable directory is not evidence it is
@@ -152,7 +153,7 @@ async function fingerprintDryRunState(engineDir, patchesDir) {
     return fingerprint;
 }
 /**
- * Runtime enforcement of the dry-run purity contract (FORGE H1): fingerprints
+ * Runtime enforcement of the dry-run purity contract: fingerprints
  * the engine tree and every patch artifact before and after `operation`, and
  * throws when a dry-run changed anything it promised only to inspect. This
  * turns any recurrence of the 0.40.0 "dry-run reverted a just-written export"

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

@@ -1,6 +1,5 @@
 /**
- * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`
- * (FORGE J2).
+ * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`.
  *
  * A scan-less re-export rebuilds each patch body as a whole-file
  * `git diff HEAD` over the owned files — so a CONCURRENT session's
@@ -23,11 +22,11 @@
 import type { PatchMetadata } from '../types/commands/index.js';
 /** Why a patch was refused under `--refuse-foreign-drift`. */
 export type ForeignDriftRefusalReason = 'foreign-drift' | 'baseline-unreadable';
-/** Per-run context threaded through the re-export loop (mirrors FORGE G2). */
+/** Per-run context threaded through the re-export loop (mirrors). */
 export interface ForeignDriftContext {
     refuseForeignDrift: boolean;
     /**
-     * Engine-relative files whose drift is expected (`--expect`, FORGE L6):
+     * Engine-relative files whose drift is expected (`--expect`):
      * drift confined to these files does not refuse. Files here that never
      * drift are reported after the run as likely typos.
      */
@@ -69,6 +68,7 @@ export declare function computeForeignDrift(oldBody: string, newBody: string, pr
 export declare function reportForeignDrift(args: {
     patch: PatchMetadata;
     patchesDir: string;
+    engineDir: string;
     newDiffContent: string;
     ctx: ForeignDriftContext;
 }): Promise<boolean>;