@hominis/fireforge 0.21.3 → 0.22.0

package/dist/src/commands/doctor-furnace-manifest-sync.js

@@ -15,7 +15,7 @@
  * Lives in a sibling module to keep `doctor-furnace.ts` under the
  * per-file LOC budget.
  */
-import { readdir } from 'node:fs/promises';
+import { readdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig } from '../core/furnace-config.js';
 import { toError } from '../utils/errors.js';
@@ -120,6 +120,37 @@ async function repairOrphanOverrides(projectRoot, orphans) {
     }
     return { restored, unrecoverable };
 }
+async function repairCustomOrphans(projectRoot, customNames) {
+    const deleted = [];
+    const retained = [];
+    const errors = [];
+    if (customNames.length === 0)
+        return { deleted, retained, errors };
+    const furnacePaths = getFurnacePaths(projectRoot);
+    for (const name of customNames) {
+        const dir = join(furnacePaths.customDir, name);
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            errors.push(`${name}: ${toError(err).message}`);
+            continue;
+        }
+        if (entries.length > 0) {
+            retained.push(name);
+            continue;
+        }
+        try {
+            await rm(dir);
+            deleted.push(name);
+        }
+        catch (err) {
+            errors.push(`${name}: ${toError(err).message}`);
+        }
+    }
+    return { deleted, retained, errors };
+}
 export const furnaceManifestSyncCheck = {
     name: 'Furnace manifest sync',
     dependsOn: ['Furnace configuration'],
@@ -142,6 +173,7 @@ export const furnaceManifestSyncCheck = {
         if (repairResult.writeError) {
             return failure('Furnace manifest sync', `Repair failed while writing furnace.json: ${repairResult.writeError}`, 'Fix the underlying filesystem error and retry the doctor command.');
         }
+        const customRepair = await repairCustomOrphans(ctx.projectRoot, orphans.customNames);
         const { restored, unrecoverable } = repairResult;
         const restoreDetail = restored.length > 0
             ? `Re-registered ${restored.length} override${restored.length === 1 ? '' : 's'} (${restored.join(', ')}) from their override.json sidecars.`
@@ -149,10 +181,16 @@ export const furnaceManifestSyncCheck = {
         const unrecoverableDetail = unrecoverable.length > 0
             ? ` Could not recover ${unrecoverable.length} override${unrecoverable.length === 1 ? '' : 's'} without a valid override.json (${unrecoverable.join(', ')}) — delete components/overrides/<name> or re-run "fireforge furnace override" to restore the entry.`
             : '';
-        const customDetail = customCount > 0
-            ? ` ${customCount} custom ${customCount === 1 ? 'directory requires' : 'directories require'} manual action: re-run "fireforge furnace create" or delete components/custom/<name>/ to reconcile.`
+        const customDetail = customRepair.deleted.length > 0
+            ? ` Deleted ${customRepair.deleted.length} empty custom orphan ${customRepair.deleted.length === 1 ? 'directory' : 'directories'} (${customRepair.deleted.join(', ')}).`
+            : '';
+        const retainedCustomDetail = customRepair.retained.length > 0
+            ? ` ${customRepair.retained.length} non-empty custom orphan ${customRepair.retained.length === 1 ? 'directory requires' : 'directories require'} manual action (${customRepair.retained.join(', ')}): re-run "fireforge furnace create" or delete components/custom/<name>/ to reconcile.`
+            : '';
+        const customErrorDetail = customRepair.errors.length > 0
+            ? ` Could not inspect or delete ${customRepair.errors.length} custom orphan ${customRepair.errors.length === 1 ? 'directory' : 'directories'} (${customRepair.errors.join('; ')}).`
             : '';
-        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}`.trim() ||
+        return warning('Furnace manifest sync', `${restoreDetail}${unrecoverableDetail}${customDetail}${retainedCustomDetail}${customErrorDetail}`.trim() ||
             'Nothing to repair (orphans surfaced but all were already recoverable).');
     },
 };

package/dist/src/commands/doctor.js

@@ -1,4 +1,4 @@
-import { configExists, getProjectPaths, loadConfig, loadState } from '../core/config.js';
+import { configExists, getProjectPaths, loadConfig, loadState, updateState, } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists } from '../core/furnace-config.js';
 import { getCurrentBranch, getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { ensureGit } from '../core/git-base.js';
@@ -13,6 +13,7 @@ import { findExecutable } from '../utils/process.js';
 import { failure, ok, warning } from './doctor-check-core.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
+import { collectPatchQueueHealth } from './verify.js';
 /**
  * Runs a single check definition, converting thrown errors into
  * DoctorCheck failure rows. Always returns an array so the caller can
@@ -184,9 +185,21 @@ const DOCTOR_CHECKS = [
     {
         name: 'Pending Resolution',
         skipIf: (ctx) => !ctx.state.pendingResolution,
-        run: (ctx) => {
+        run: async (ctx) => {
             const patchFilename = ctx.state.pendingResolution?.patchFilename ?? 'unknown';
-            return failure('Pending Resolution', `You are currently resolving a conflict for patch ${patchFilename}.`, 'Build and Export commands may behave unexpectedly until "fireforge resolve" is completed.');
+            if (ctx.options.clearResolution) {
+                const health = await collectPatchQueueHealth(ctx.projectRoot);
+                if (health.errorCount > 0) {
+                    return failure('Pending Resolution', `Refusing to clear pending resolution for ${patchFilename}: patch queue health check found ${health.errorCount} error(s).`, 'Run "fireforge verify" for details, fix the queue, then retry "fireforge doctor --clear-resolution".');
+                }
+                await updateState(ctx.projectRoot, (current) => {
+                    const next = { ...current };
+                    delete next.pendingResolution;
+                    return next;
+                });
+                return ok('Pending Resolution');
+            }
+            return failure('Pending Resolution', `You are currently resolving a conflict for patch ${patchFilename}.`, 'Build and Export commands may behave unexpectedly until "fireforge resolve" is completed. If the queue now verifies cleanly, run "fireforge doctor --clear-resolution" to discard the stale marker.');
         },
     },
     {
@@ -452,6 +465,7 @@ export function registerDoctor(program, { getProjectRoot, withErrorHandling }) {
         .description('Diagnose project issues')
         .option('--repair-patches-manifest', 'Rebuild patches/patches.json from the current patch files before reporting results')
         .option('--repair-furnace', 'Reconcile furnace state: clear stale furnace-state.json entries, re-run furnace apply to fix engine drift, and clear the pending-repair marker set by a failed preview teardown')
+        .option('--clear-resolution', 'Clear stale pendingResolution state after the patch queue health check reports no errors')
         .action(withErrorHandling(async (options) => {
         const result = await doctorCommand(getProjectRoot(), options);
         if (result.exitCode !== 0) {

package/dist/src/commands/download.js

@@ -269,7 +269,7 @@ export async function downloadCommand(projectRoot, options) {
         // CI job notes the expected duration. The progress callbacks below
         // still fire as usual; this is an additional up-front signal, not a
         // replacement.
-        info('Indexing downloaded source into git (one-time; typically 1–3 minutes on a ~600 MB Firefox tree)...');
+        info('Indexing downloaded source into git (one-time; typically 3–5 minutes on a ~600 MB Firefox tree)...');
         // Initialize git repository
         const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
         let baseCommit;

package/dist/src/commands/export-flow.d.ts

@@ -24,6 +24,13 @@ export interface PlacementPlan {
  * slot to make room for a new patch at `requestedOrder`.
  */
 export declare function computePlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
+/**
+ * Computes an exact sparse placement plan for `--order <N>`. Unlike
+ * positional insertion, this never renumbers existing patches: the order
+ * must be unused, and policy validation decides whether the requested
+ * category/order is allowed.
+ */
+export declare function computeExactPlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
  */

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

@@ -18,11 +18,18 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
 function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
     return `${padded}-${category}-${sanitizeName(name)}.patch`;
 }
+function prefixWidthForPatches(manifestPatches, requestedOrder) {
+    return manifestPatches.reduce((width, patch) => {
+        const match = /^(\d+)-/.exec(patch.filename);
+        return Math.max(width, match?.[1]?.length ?? 3, String(requestedOrder).length);
+    }, 3);
+}
 function getSortedRenameEntries(renameMap) {
     return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
 }
@@ -59,12 +66,7 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
     }
     const sorted = [...manifestPatches].sort((a, b) => a.order - b.order);
     const renameMap = new Map();
-    // Decide the canonical prefix width by inspecting the widest existing
-    // filename (falling back to 3). Keeps zero-padding consistent post-shift.
-    const prefixWidth = sorted.reduce((w, p) => {
-        const match = /^(\d+)-/.exec(p.filename);
-        return match ? Math.max(w, match[1]?.length ?? 3) : w;
-    }, 3);
+    const prefixWidth = prefixWidthForPatches(sorted, requestedOrder);
     // Every existing patch at requestedOrder or later shifts up by one.
     for (const patch of sorted) {
         if (patch.order >= requestedOrder) {
@@ -81,6 +83,27 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
         renameMap,
     };
 }
+/**
+ * Computes an exact sparse placement plan for `--order <N>`. Unlike
+ * positional insertion, this never renumbers existing patches: the order
+ * must be unused, and policy validation decides whether the requested
+ * category/order is allowed.
+ */
+export function computeExactPlacementPlan(manifestPatches, newPatchCategory, newPatchName, requestedOrder) {
+    if (!Number.isInteger(requestedOrder) || requestedOrder <= 0) {
+        throw new InvalidArgumentError(`--order must be a positive integer, got ${String(requestedOrder)}.`, '--order');
+    }
+    const occupied = manifestPatches.find((patch) => patch.order === requestedOrder);
+    if (occupied) {
+        throw new InvalidArgumentError(`--order ${String(requestedOrder)} is already occupied by ${occupied.filename}. ` +
+            'Choose an unused order or use --before/--after for positional insertion.', '--order');
+    }
+    return {
+        insertionOrder: requestedOrder,
+        newFilename: buildFilenameForPlacement(newPatchCategory, newPatchName, requestedOrder, prefixWidthForPatches(manifestPatches, requestedOrder)),
+        renameMap: new Map(),
+    };
+}
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
  */
@@ -95,7 +118,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         if (!Number.isInteger(options.order) || options.order <= 0) {
             throw new InvalidArgumentError(`--order must be a positive integer, got ${String(options.order)}.`, '--order');
         }
-        targetOrder = options.order;
+        return computeExactPlacementPlan(existingPatches, category, name, options.order);
     }
     else if (options.before !== undefined) {
         const anchor = resolvePatchIdentifier(options.before, existingPatches);
@@ -202,6 +225,9 @@ export async function commitPlacementExport(input) {
             throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
         }
         const originalManifest = await loadPatchesManifest(input.patchesDir);
+        if (originalManifest !== null) {
+            assertPlacementPreservesReservedRanges(currentPlan, originalManifest.patches, input.config, input.category);
+        }
         if (input.config !== undefined) {
             const renamed = originalManifest !== null
                 ? applyRenameMapToManifest(originalManifest, currentPlan.renameMap)

package/dist/src/commands/export-placement-policy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Policy-aware checks for export placement plans.
+ */
+import type { PatchCategory, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+export interface PlacementPolicyPlan {
+    insertionOrder: number;
+    renameMap: ReadonlyMap<string, {
+        newFilename: string;
+        newOrder: number;
+    }>;
+}
+/** Refuses positional export plans that would renumber exact reserved patches. */
+export declare function assertPlacementPreservesReservedRanges(plan: PlacementPolicyPlan, manifestPatches: readonly PatchMetadata[], config: FireForgeConfig | undefined, category: PatchCategory): void;

package/dist/src/commands/export-placement-policy.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Policy-aware checks for export placement plans.
+ */
+import { InvalidArgumentError } from '../errors/base.js';
+function reservedRangeLabel(range) {
+    return `${String(range.from).padStart(3, '0')}-${String(range.to).padStart(3, '0')}`;
+}
+function findReservedRange(config, order) {
+    return (config.patchPolicy?.reservedRanges?.find((range) => order >= range.from && order <= range.to) ??
+        null);
+}
+function suggestSparseOrder(config, patches, category, insertionOrder) {
+    const ranges = (config.patchPolicy?.ranges ?? [])
+        .filter((range) => range.category === category)
+        .sort((a, b) => a.from - b.from || a.to - b.to);
+    const occupied = new Set(patches.map((patch) => patch.order));
+    for (const range of ranges) {
+        for (let order = Math.max(insertionOrder, range.from); order <= range.to; order++) {
+            if (!occupied.has(order) && findReservedRange(config, order) === null)
+                return order;
+        }
+    }
+    for (const range of ranges) {
+        for (let order = range.from; order <= range.to; order++) {
+            if (!occupied.has(order) && findReservedRange(config, order) === null)
+                return order;
+        }
+    }
+    return null;
+}
+/** Refuses positional export plans that would renumber exact reserved patches. */
+export function assertPlacementPreservesReservedRanges(plan, manifestPatches, config, category) {
+    if (config?.patchPolicy === undefined || plan.renameMap.size === 0)
+        return;
+    const byFilename = new Map(manifestPatches.map((patch) => [patch.filename, patch]));
+    for (const [filename, rename] of plan.renameMap) {
+        const patch = byFilename.get(filename);
+        if (!patch)
+            continue;
+        const reserved = findReservedRange(config, patch.order);
+        if (reserved === null)
+            continue;
+        const suggestion = suggestSparseOrder(config, manifestPatches, category, plan.insertionOrder);
+        const suggestionText = suggestion !== null
+            ? ` Use --order ${String(suggestion).padStart(3, '0')} to create the new patch in an unused ${category} slot without renumbering reserved patches.`
+            : ` Choose an unused order in the ${category} policy range or adjust patchPolicy.`;
+        throw new InvalidArgumentError(`Positional export would renumber reserved patch ${patch.filename} ` +
+            `from ${String(patch.order).padStart(3, '0')} to ${rename.newFilename} ` +
+            `(reserved range ${reservedRangeLabel(reserved)}).` +
+            suggestionText, 'export placement');
+    }
+}
+//# sourceMappingURL=export-placement-policy.js.map

package/dist/src/commands/export.js

@@ -21,6 +21,7 @@ import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag } from '../utils/validation.js';
 import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
+import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
 import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
@@ -191,8 +192,11 @@ export async function exportCommand(projectRoot, files, options) {
                 throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
             }
             placementPlan = await resolvePlacementPlan(paths.patches, options, selectedCategory, patchName);
-            const conflicts = await projectPlacementForLint(paths.patches, placementPlan, diff);
             const currentManifest = await loadPatchesManifest(paths.patches);
+            if (currentManifest !== null) {
+                assertPlacementPreservesReservedRanges(placementPlan, currentManifest.patches, config, selectedCategory);
+            }
+            const conflicts = await projectPlacementForLint(paths.patches, placementPlan, diff);
             const renamed = currentManifest !== null
                 ? applyRenameMapToManifest(currentManifest, placementPlan.renameMap)
                 : buildProjectedManifest(null, []);
@@ -397,7 +401,7 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--supersede', 'Allow superseding multiple existing patches')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--dry-run', 'Print the export plan (including supersede preview) without writing')
-        .addOption(new Option('--order <N>', 'Place the new patch at this ordinal, shifting subsequent patches up').argParser((v) => parsePositiveIntegerFlag('--order', v)))
+        .addOption(new Option('--order <N>', 'Place the new patch at this exact unused order without renumbering existing patches').argParser((v) => parsePositiveIntegerFlag('--order', v)))
         .option('--before <anchor>', 'Place the new patch immediately before <anchor>')
         .option('--after <anchor>', 'Place the new patch immediately after <anchor>')
         .option('-y, --yes', 'Skip confirmation for placement renumbers (required for non-TTY)')

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -4,6 +4,7 @@ export interface DryRunPlanInput {
     localized: boolean;
     register: boolean;
     composes: string[] | undefined;
+    stockAdditions?: string[];
     /**
      * Feature-scoped Fluent bundle the component participates in (the same
      * value that will be written to `furnace.json`'s `sharedFtl`). When set,

package/dist/src/commands/furnace/create-dry-run.js

@@ -75,7 +75,7 @@ export function formatSuccessNote(args) {
  * `components/custom/` to match the wording of the real success note.
  */
 export function formatDryRunPlan(args) {
-    const { componentName, localized, register, composes, sharedFtl, testStyle, description, binaryName, } = args;
+    const { componentName, localized, register, composes, stockAdditions, sharedFtl, testStyle, description, binaryName, } = args;
     const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
     // A per-component .ftl is scaffolded only when the component does NOT
     // opt into a shared feature-scoped bundle. Mirrors writeComponentFiles.
@@ -92,6 +92,12 @@ export function formatDryRunPlan(args) {
     if (composes && composes.length > 0) {
         plan += `\n  composes: ${composes.join(', ')}`;
     }
+    if (stockAdditions && stockAdditions.length > 0) {
+        plan += `\n\nWould add discovered stock to furnace.json:`;
+        for (const name of stockAdditions) {
+            plan += `\n  ${name}`;
+        }
+    }
     if (sharedFtl) {
         plan += `\n  sharedFtl: ${sharedFtl}`;
     }

package/dist/src/commands/furnace/create-validation.d.ts

@@ -3,4 +3,4 @@ import type { FurnaceConfig } from '../../types/furnace.js';
 /**
  * Validates a proposed custom component against the current furnace config.
  */
-export declare function validateCreateAgainstConfig(config: FurnaceConfig, componentName: string, allowPrefixMismatch: FurnaceCreateOptions['allowPrefixMismatch'], composes: string[] | undefined): void;
+export declare function validateCreateAgainstConfig(config: FurnaceConfig, componentName: string, allowPrefixMismatch: FurnaceCreateOptions['allowPrefixMismatch'], composes: string[] | undefined, stockAdditions?: string[]): void;

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

@@ -11,11 +11,12 @@ function checkNameConflict(config, name) {
     }
     return undefined;
 }
-function validateComposesTargets(config, componentName, composes) {
+function validateComposesTargets(config, componentName, composes, stockAdditions = []) {
     if (!composes || composes.length === 0)
         return;
     const known = new Set([
         ...config.stock,
+        ...stockAdditions,
         ...Object.keys(config.overrides),
         ...Object.keys(config.custom),
     ]);
@@ -42,7 +43,7 @@ function validateComposesTargets(config, componentName, composes) {
 /**
  * Validates a proposed custom component against the current furnace config.
  */
-export function validateCreateAgainstConfig(config, componentName, allowPrefixMismatch, composes) {
+export function validateCreateAgainstConfig(config, componentName, allowPrefixMismatch, composes, stockAdditions = []) {
     const conflict = checkNameConflict(config, componentName);
     if (conflict) {
         throw new FurnaceError(conflict, componentName);
@@ -54,6 +55,6 @@ export function validateCreateAgainstConfig(config, componentName, allowPrefixMi
             `Use a prefixed name (e.g. "${config.componentPrefix}${componentName}"), update ` +
             '`componentPrefix` in furnace.json, or pass --allow-prefix-mismatch to create the component anyway.', 'name');
     }
-    validateComposesTargets(config, componentName, composes);
+    validateComposesTargets(config, componentName, composes, stockAdditions);
 }
 //# sourceMappingURL=create-validation.js.map

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

@@ -7,7 +7,7 @@ import { resolveFtlChromeSubPath, tagNameToClassName } from '../../core/furnace-
 import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
-import { isComponentInEngine } from '../../core/furnace-scanner.js';
+import { isComponentInEngine, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { registerTestManifest } from '../../core/manifest-register.js';
 import { validateSharedFtl } from '../../core/shared-ftl.js';
@@ -29,6 +29,26 @@ async function loadAuthoringFurnaceConfig(projectRoot) {
     }
     return createDefaultFurnaceConfig();
 }
+function knownComponentSet(config) {
+    return new Set([
+        ...config.stock,
+        ...Object.keys(config.overrides),
+        ...Object.keys(config.custom),
+    ]);
+}
+async function resolveComposeStockAdditions(args) {
+    const { engineDir, config, componentName, composes } = args;
+    if (!composes || composes.length === 0)
+        return [];
+    const known = knownComponentSet(config);
+    const unresolved = composes.filter((tag) => tag !== componentName && !known.has(tag));
+    if (unresolved.length === 0 || !(await pathExists(engineDir)))
+        return [];
+    const scanPaths = config.scanPaths && config.scanPaths.length > 0 ? config.scanPaths : undefined;
+    const discovered = await scanWidgetsDirectory(engineDir, undefined, scanPaths);
+    const discoveredTags = new Set(discovered.map((component) => component.tagName));
+    return unresolved.filter((tag, index) => discoveredTags.has(tag) && unresolved.indexOf(tag) === index);
+}
 /**
  * Validates a custom element tag name.
  * @returns Error message if invalid, undefined if valid
@@ -238,7 +258,13 @@ async function performCreateMutations(args) {
     let files;
     try {
         const freshConfig = await loadAuthoringFurnaceConfig(args.projectRoot);
-        validateCreateAgainstConfig(freshConfig, args.componentName, args.allowPrefixMismatch, args.composes);
+        const freshStockAdditions = await resolveComposeStockAdditions({
+            engineDir: args.paths.engine,
+            config: freshConfig,
+            componentName: args.componentName,
+            composes: args.composes,
+        });
+        validateCreateAgainstConfig(freshConfig, args.componentName, args.allowPrefixMismatch, args.composes, freshStockAdditions);
         if (await pathExists(args.componentDir)) {
             throw new FurnaceError(`Directory already exists: components/custom/${args.componentName}`, args.componentName);
         }
@@ -259,6 +285,11 @@ async function performCreateMutations(args) {
         if (args.sharedFtl) {
             customEntry.sharedFtl = args.sharedFtl;
         }
+        for (const name of freshStockAdditions) {
+            if (!freshConfig.stock.includes(name)) {
+                freshConfig.stock.push(name);
+            }
+        }
         freshConfig.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, freshConfig);
@@ -352,7 +383,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // furnace.json behind.
     const config = await loadAuthoringFurnaceConfig(projectRoot);
     const composes = options.compose;
-    validateCreateAgainstConfig(config, componentName, options.allowPrefixMismatch, composes);
+    const stockAdditions = await resolveComposeStockAdditions({
+        engineDir: paths.engine,
+        config,
+        componentName,
+        composes,
+    });
+    validateCreateAgainstConfig(config, componentName, options.allowPrefixMismatch, composes, stockAdditions);
     // Check if it already exists in the engine source tree
     if (await pathExists(paths.engine)) {
         if (await isComponentInEngine(paths.engine, componentName)) {
@@ -407,6 +444,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
             localized,
             register,
             composes,
+            stockAdditions,
             // Spread rather than assign so the key is absent when sharedFtl is
             // undefined — the DryRunPlanInput type uses strict-optional shape.
             ...(sharedFtl !== undefined ? { sharedFtl } : {}),

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

@@ -46,6 +46,12 @@ export interface LintCommandOptions {
      * scope contracts are different.
      */
     perPatch?: boolean;
+    /**
+     * Maximum warning count tolerated before lint exits non-zero. Mirrors
+     * ESLint's `--max-warnings` shape for release gates that want advisory
+     * findings to become blocking without changing default CLI behavior.
+     */
+    maxWarnings?: number;
 }
 /**
  * Result of {@link applyAggregateLintIgnoreSuppression}.

package/dist/src/commands/lint.js

@@ -224,6 +224,10 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (options.onlyIntroduced && !options.since) {
         throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
     }
+    if (options.maxWarnings !== undefined &&
+        (!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 file paths would produce
     // an ambiguous set — is the file list an additional filter, or does it
@@ -240,7 +244,7 @@ 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);
+        await lintPerPatch(projectRoot, paths, options);
         return;
     }
     // Load the config before resolving the diff so we can pass
@@ -367,6 +371,10 @@ export async function lintCommand(projectRoot, files, options = {}) {
             : '';
         throw new GeneralError(`Patch lint found ${failingErrors.length} ${options.onlyIntroduced ? 'introduced ' : ''}error(s). Fix these before exporting.${cumulativeSuppressed}`);
     }
+    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
+        outro('Lint failed');
+        throw new GeneralError(`Patch lint found ${warnings.length} warning(s), exceeding --max-warnings ${options.maxWarnings}.`);
+    }
     // Notices are advisory and don't count as warnings — emitting "passed
     // with warnings" when only notices fired contradicts the preceding
     // `0 warning(s)` summary line and reads as a regression. Distinguish
@@ -398,7 +406,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
  * Sharing a loop would hide the distinction and force the caller to
  * decide semantics mid-function.
  */
-async function lintPerPatch(projectRoot, paths) {
+async function lintPerPatch(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.');
@@ -483,6 +491,10 @@ async function lintPerPatch(projectRoot, paths) {
         outro('Lint failed');
         throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
     }
+    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
+        outro('Lint failed');
+        throw new GeneralError(`Patch lint found ${warnings.length} warning(s) across ${linted} patch(es), exceeding --max-warnings ${options.maxWarnings}.`);
+    }
     if (warnings.length > 0) {
         outro('Lint passed with warnings');
     }
@@ -503,6 +515,7 @@ 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('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -514,6 +527,13 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.perPatch !== undefined) {
             lintOptions.perPatch = options.perPatch;
         }
+        if (options.maxWarnings !== undefined) {
+            const maxWarnings = Number(options.maxWarnings);
+            if (!Number.isInteger(maxWarnings) || maxWarnings < 0) {
+                throw new GeneralError('--max-warnings must be a non-negative integer.');
+            }
+            lintOptions.maxWarnings = maxWarnings;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }

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

@@ -6,10 +6,11 @@
  * This command renumbers all patches to sequential ordinals (1, 2, 3, …)
  * in a single atomic operation, preserving relative order.
  */
-import { getProjectPaths } from '../../core/config.js';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, } from '../../core/patch-manifest.js';
+import { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -44,6 +45,7 @@ function computeCompactRenameMap(patches) {
 export async function patchCompactCommand(projectRoot, options = {}) {
     intro(options.dryRun ? 'FireForge patch compact (dry run)' : 'FireForge patch compact');
     const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
         throw new GeneralError('Patches directory not found.');
     }
@@ -62,12 +64,19 @@ export async function patchCompactCommand(projectRoot, options = {}) {
     for (const [oldFilename, entry] of sorted) {
         summary.push(`  ${oldFilename}  →  ${entry.newFilename}  (order ${entry.newOrder})`);
     }
+    enforcePatchPolicy({
+        config,
+        manifest: applyRenameMapToManifest(manifest, renameMap),
+        command: 'patch compact',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     const decision = await confirmDestructive({
         operation: 'patch-compact',
         title: `Compact ${manifest.patches.length} patches (${renameMap.size} rename(s))`,
         summary,
         yes: options.yes === true,
         dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
     });
     if (decision === 'dry-run') {
         outro('Dry run complete — no changes made');
@@ -87,6 +96,12 @@ export async function patchCompactCommand(projectRoot, options = {}) {
             info('Patch queue was compacted by another process. Nothing to do.');
             return;
         }
+        enforcePatchPolicy({
+            config,
+            manifest: applyRenameMapToManifest(currentManifest, currentRenameMap),
+            command: 'patch compact',
+            forceUnsafe: options.forceUnsafe === true,
+        });
         await renumberPatchesInManifest(paths.patches, currentRenameMap);
         const historyEntry = {
             operation: 'patch-compact',
@@ -100,6 +115,7 @@ export async function patchCompactCommand(projectRoot, options = {}) {
                 })),
             },
             ...(options.yes === true ? { yes: true } : {}),
+            ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
             result: 'ok',
         };
         try {
@@ -125,6 +141,7 @@ export function registerPatchCompact(parent, context) {
         .description('Close ordinal gaps in the patch queue (renumber sequentially)')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals')
         .action(withErrorHandling(async (options) => {
         await patchCompactCommand(getProjectRoot(), pickDefined(options));
     }));