@hominis/fireforge 0.18.1 → 0.18.2

package/README.md

@@ -210,7 +210,11 @@ This re-exports the fixed patch and clears the conflict state. The command is de
 
 The optional `lintIgnore` field lists lint check IDs to suppress for that patch specifically. Useful for the class of patch that is advisory-noisy by nature — a cohesive branding bundle, a localised-resource pack, an auto-generated manifest — where `--skip-lint` is too blunt and a per-line marker cannot exist (the `.patch` body is regenerated on every export). Threaded through `export`, `re-export`, `re-export --files`, and `lint --per-patch`. Unknown check IDs are a no-op.
 
-The optional `tier` field (only `"branding"` recognised) forces the branding threshold tier for the `large-patch-lines` rule regardless of what `filesAffected` looks like. The automatic branding-tier detection already fires when every file is under `browser/branding/` plus a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) — covering the canonical Firefox fork shape. Declare `tier: "branding"` only when the patch legitimately also touches a non-allowlisted sibling the auto-detector cannot reach (a fork-specific theme override under `browser/themes/<name>/`, a vendor-specific icon resource, etc.). Precedence is `test > branding > general`: a patch of all-tests always gets the more permissive test-tier thresholds even if it declares `tier: "branding"`. Unknown tier values are rejected at load time rather than silently stripped, so a typo surfaces as a loader error. Prefer `tier` over `lintIgnore: ["large-patch-lines"]` when the patch is legitimately branding-shaped — `tier` keeps the rule running at the correct thresholds (so the warning still surfaces if the patch crosses them); `lintIgnore` drops the rule entirely.
+Settable through the CLI in two places. `fireforge export --lint-ignore <check-id>` (repeatable) writes the field on creation; `fireforge re-export <name> --lint-ignore <check-id>` (repeatable, append/union semantics, de-duplicated) adds entries to an existing patch on the next refresh. For metadata-only edits that should **not** regenerate the `.patch` body — including the inverse `--remove` and `--clear` modes that re-export's append-only flag cannot express — use `fireforge patch lint-ignore <name> --add <id> | --remove <id> | --clear`.
+
+The optional `tier` field (only `"branding"` recognised) forces the branding threshold tier for the `large-patch-files` and `large-patch-lines` rules regardless of what `filesAffected` looks like. The automatic branding-tier detection already fires when every file is under `browser/branding/` plus a narrow allowlist of branding-registration siblings (`browser/moz.configure`, `browser/confvars.sh`) — covering the canonical Firefox fork shape. Declare `tier: "branding"` only when the patch legitimately also touches a non-allowlisted sibling the auto-detector cannot reach (a fork-specific theme override under `browser/themes/<name>/`, a vendor-specific icon resource, etc.). Precedence is `test > branding > general`: a patch of all-tests always gets the more permissive test-tier thresholds even if it declares `tier: "branding"`. Unknown tier values are rejected at load time rather than silently stripped, so a typo surfaces as a loader error. Prefer `tier` over `lintIgnore: ["large-patch-lines"]` when the patch is legitimately branding-shaped — `tier` keeps the rule running at the correct thresholds (so the warning still surfaces if the patch crosses them); `lintIgnore` drops the rule entirely.
+
+Settable via `fireforge export --tier branding` on creation, `fireforge re-export <name> --tier branding` on refresh, and `fireforge patch tier <name> --tier branding | --clear` for a metadata-only edit that does not rewrite the `.patch` body. The CLI rejects values other than `branding` up-front (matching the validator's strictness), and `re-export --tier` / `--lint-ignore` refuse `--all` because mass tier/ignore edits across a heterogeneous queue are virtually always footguns.
 
 If the manifest drifts after an interrupted export or manual edits, `fireforge import` will stop rather then silently applying a stale stack. Use `fireforge doctor --repair-patches-manifest` to rebuild it from disk. Because the rebuild is deterministic, the result will always be consistent with what is actually on the filesystem.
 
@@ -223,24 +227,24 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
 
-| Check                          | Scope                                                                                           | Severity                 |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------ |
-| `missing-license-header`       | New files (JS/CSS/FTL)                                                                          | error                    |
-| `relative-import`              | JS/MJS files                                                                                    | error                    |
-| `token-prefix-violation`       | CSS files (with furnace)                                                                        | error                    |
-| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                       | error                    |
-| `duplicate-new-file-creation`  | Same path created by multiple patches                                                           | error                    |
-| `forward-import`               | Patch imports from a later-patch file                                                           | error                    |
-| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                               | error                    |
-| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                 | error                    |
-| `missing-modification-comment` | Modified upstream JS/MJS                                                                        | warning                  |
-| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                            | warning                  |
-| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                    | notice / warning / error |
-| `observer-topic-naming`        | Observer topics with binaryName                                                                 | warning                  |
-| `large-patch-files`            | Patches affecting >5 files                                                                      | warning                  |
-| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 3000/8000/20000 branding) | notice / warning / error |
+| Check                          | Scope                                                                                            | Severity                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| `missing-license-header`       | New files (JS/CSS/FTL)                                                                           | error                    |
+| `relative-import`              | JS/MJS files                                                                                     | error                    |
+| `token-prefix-violation`       | CSS files (with furnace)                                                                         | error                    |
+| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                        | error                    |
+| `duplicate-new-file-creation`  | Same path created by multiple patches                                                            | error                    |
+| `forward-import`               | Patch imports from a later-patch file                                                            | error                    |
+| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                  | error                    |
+| `missing-modification-comment` | Modified upstream JS/MJS                                                                         | warning                  |
+| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                             | warning                  |
+| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                     | notice / warning / error |
+| `observer-topic-naming`        | Observer topics with binaryName                                                                  | warning                  |
+| `large-patch-files`            | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                         | warning                  |
+| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding) | notice / warning / error |
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
@@ -436,11 +440,21 @@ fireforge patch reorder 003-ui-sidebar.patch --before 001-branding-logo.patch
 
 # Close ordinal gaps after deletes or splits (e.g. 1, 3, 7 → 1, 2, 3)
 fireforge patch compact
+
+# Set or clear the threshold-tier override on a single patch
+# (no .patch body rewrite — manifest entry only)
+fireforge patch tier 001-branding-assets.patch --tier branding
+fireforge patch tier 001-branding-assets.patch --clear
+
+# Edit the lintIgnore list on a single patch (one mode per invocation)
+fireforge patch lint-ignore 001-branding-assets.patch --add large-patch-lines --add large-patch-files
+fireforge patch lint-ignore 001-branding-assets.patch --remove large-patch-lines
+fireforge patch lint-ignore 001-branding-assets.patch --clear
 ```
 
-`delete` and `reorder` accept three identifier forms for their target: the ordinal number (`fireforge patch reorder 3 --to 1`), the full filename (`003-ui-sidebar-tweaks.patch`), or the manifest `name` handle the patch was exported with (`ui-sidebar-tweaks`). Anchors passed to `--before` / `--after` accept the same three forms.
+All `patch <verb>` subcommands accept three identifier forms for their target: the ordinal number (`fireforge patch reorder 3 --to 1`), the full filename (`003-ui-sidebar-tweaks.patch`), or the manifest `name` handle the patch was exported with (`ui-sidebar-tweaks`). Anchors passed to `--before` / `--after` accept the same three forms. All subcommands support `--dry-run` and `--yes`.
 
-All subcommands support `--dry-run` and `--yes`.
+`patch tier` and `patch lint-ignore` are metadata-only edits: they update `patches/patches.json` under the patch directory lock and never rewrite the `.patch` body. Reach for them when an operator-visible advisory (e.g. `large-patch-files` firing on a 56-file fresh-fork branding bundle) needs the threshold-tier override or a per-patch lint suppression but the patch body is already correct — running `re-export` for that case wastes an engine read + diff regeneration. `patch lint-ignore` modes (`--add` / `--remove` / `--clear`) are mutually exclusive; `patch tier` rejects `--tier` and `--clear` together. The history log records each invocation under `operation: "patch-tier"` / `"patch-lint-ignore"` for audit.
 
 ### Additional workflow commands
 

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

@@ -82,6 +82,10 @@ export interface DryRunPreviewInput {
     filesAffected: string[];
     sourceEsrVersion: string;
     explicitSupersede: boolean;
+    /** Optional `PatchMetadata.tier` opt-in carried from the CLI. */
+    tier?: 'branding';
+    /** Optional `PatchMetadata.lintIgnore` carried from the CLI. */
+    lintIgnore?: string[];
 }
 /**
  * Renders the plain (non-placement) dry-run preview: calls planExport,

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

@@ -314,12 +314,20 @@ export async function renderDryRunPreview(input) {
         description: input.description,
         filesAffected: input.filesAffected,
         sourceEsrVersion: input.sourceEsrVersion,
+        ...(input.tier !== undefined ? { tier: input.tier } : {}),
+        ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
     });
     info(`\n[dry-run] Would write: patches/${plan.patchFilename}`);
     info(`  category: ${plan.metadata.category}`);
     info(`  order: ${plan.metadata.order}`);
     info(`  description: ${plan.metadata.description || '(none)'}`);
     info(`  filesAffected (${plan.metadata.filesAffected.length}): ${plan.metadata.filesAffected.join(', ')}`);
+    if (plan.metadata.tier !== undefined) {
+        info(`  tier: ${plan.metadata.tier}`);
+    }
+    if (plan.metadata.lintIgnore !== undefined && plan.metadata.lintIgnore.length > 0) {
+        info(`  lintIgnore: ${plan.metadata.lintIgnore.join(', ')}`);
+    }
     if (supersedeDetails.length > 0) {
         info(`\n[dry-run] Would supersede ${supersedeDetails.length} existing patch(es):`);
         for (const detail of supersedeDetails) {

package/dist/src/commands/export.js

@@ -172,7 +172,15 @@ export async function exportCommand(projectRoot, files, options) {
     try {
         // Extract affected files from diff
         const filesAffected = extractAffectedFiles(diff);
-        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Apply the just-set --tier and --lint-ignore on the lint pass so the
+        // operator's intent takes effect on this invocation, not only on the
+        // next one. Without this, a fresh export with `--tier branding` would
+        // still hit general thresholds because the lint runs before the
+        // metadata is committed.
+        const exportIgnoreChecks = options.lintIgnore && options.lintIgnore.length > 0
+            ? new Set(options.lintIgnore)
+            : undefined;
+        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint, undefined, exportIgnoreChecks, options.tier);
         // Resolve placement (if any flag was given). Placement is mutually
         // exclusive with supersede — the semantics overlap confusingly.
         let placementPlan = null;
@@ -225,6 +233,10 @@ export async function exportCommand(projectRoot, files, options) {
                 filesAffected,
                 sourceEsrVersion: config.firefox.version,
                 explicitSupersede: options.supersede === true,
+                ...(options.tier !== undefined ? { tier: options.tier } : {}),
+                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                    ? { lintIgnore: options.lintIgnore }
+                    : {}),
             });
             outro('Dry run complete — no changes made');
             return;
@@ -243,6 +255,10 @@ export async function exportCommand(projectRoot, files, options) {
                 createdAt: new Date().toISOString(),
                 sourceEsrVersion: config.firefox.version,
                 filesAffected,
+                ...(options.tier !== undefined ? { tier: options.tier } : {}),
+                ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                    ? { lintIgnore: options.lintIgnore }
+                    : {}),
             };
             const committedPlan = await commitPlacementExport({
                 patchesDir: paths.patches,
@@ -314,6 +330,10 @@ export async function exportCommand(projectRoot, files, options) {
             diff,
             filesAffected,
             sourceEsrVersion: config.firefox.version,
+            ...(options.tier !== undefined ? { tier: options.tier } : {}),
+            ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
+                ? { lintIgnore: options.lintIgnore }
+                : {}),
         });
         for (const oldPatch of superseded) {
             info(`Superseded: ${oldPatch.filename}`);
@@ -348,11 +368,15 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
         .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
         .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the new patch (only "branding" recognised)').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (paths, options) => {
-        const { category, ...rest } = options;
+        const { category, tier, lintIgnore, ...rest } = options;
         await exportCommand(getProjectRoot(), paths, {
             ...pickDefined(rest),
             ...(category !== undefined ? { category: category } : {}),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
         });
     }));
 }

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

@@ -1,14 +1,16 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`delete`, `reorder`) so they do not clutter the top-level
- * command list. Queue-level verbs like `lint`, `export`, `verify`, and
- * `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
+ * they do not clutter the top-level command list. Queue-level verbs
+ * like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
+export { patchLintIgnoreCommand } from './lint-ignore.js';
 export { patchReorderCommand } from './reorder.js';
+export { patchTierCommand } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
  *

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

@@ -1,16 +1,20 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`delete`, `reorder`) so they do not clutter the top-level
- * command list. Queue-level verbs like `lint`, `export`, `verify`, and
- * `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
+ * they do not clutter the top-level command list. Queue-level verbs
+ * like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { registerPatchCompact } from './compact.js';
 import { registerPatchDelete } from './delete.js';
+import { registerPatchLintIgnore } from './lint-ignore.js';
 import { registerPatchReorder } from './reorder.js';
+import { registerPatchTier } from './tier.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
+export { patchLintIgnoreCommand } from './lint-ignore.js';
 export { patchReorderCommand } from './reorder.js';
+export { patchTierCommand } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
  *
@@ -20,7 +24,7 @@ export { patchReorderCommand } from './reorder.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, reorder)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, reorder, tier)')
         // Match `fireforge furnace`'s no-args contract: print the group's help and
         // exit 0. Without this default action, commander routes `fireforge patch`
         // (no subcommand) through its own help-then-exit-1 path, so scripts that
@@ -32,6 +36,8 @@ export function registerPatch(program, context) {
     });
     registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
+    registerPatchLintIgnore(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchTier(patch, context);
 }
 //# sourceMappingURL=index.js.map

package/dist/src/commands/patch/lint-ignore.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `fireforge patch lint-ignore <name>` — adds, removes, or clears entries
+ * in `PatchMetadata.lintIgnore` without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --lint-ignore <id>` (which is
+ * append-only). Existence is justified by the cases re-export cannot
+ * express:
+ * - Removing a single entry without dropping the rest of the list.
+ * - Clearing the entire list when the operator wants the rule(s) to
+ *   start firing again.
+ * - Editing metadata when the patch body is already correct, so the
+ *   re-export's engine read + diff regeneration roundtrip is wasted.
+ *
+ * Modes are mutually exclusive: exactly one of `--add`, `--remove`, or
+ * `--clear` must be supplied per invocation. The read-modify-write
+ * happens inside the patch directory lock via {@link mutatePatchMetadata}
+ * so a concurrent writer cannot interleave between the read and the
+ * write — important when an operator scripts repeated invocations or
+ * runs `--add` and `--remove` back-to-back.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchLintIgnoreOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch lint-ignore` command: reads the patch's existing
+ * `lintIgnore`, applies the requested mode, and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (exactly one of `add`/`remove`/`clear`)
+ */
+export declare function patchLintIgnoreCommand(projectRoot: string, identifier: string, options?: PatchLintIgnoreOptions): Promise<void>;
+/**
+ * Registers the `patch lint-ignore` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchLintIgnore(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch lint-ignore <name>` — adds, removes, or clears entries
+ * in `PatchMetadata.lintIgnore` without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --lint-ignore <id>` (which is
+ * append-only). Existence is justified by the cases re-export cannot
+ * express:
+ * - Removing a single entry without dropping the rest of the list.
+ * - Clearing the entire list when the operator wants the rule(s) to
+ *   start firing again.
+ * - Editing metadata when the patch body is already correct, so the
+ *   re-export's engine read + diff regeneration roundtrip is wasted.
+ *
+ * Modes are mutually exclusive: exactly one of `--add`, `--remove`, or
+ * `--clear` must be supplied per invocation. The read-modify-write
+ * happens inside the patch directory lock via {@link mutatePatchMetadata}
+ * so a concurrent writer cannot interleave between the read and the
+ * write — important when an operator scripts repeated invocations or
+ * runs `--add` and `--remove` back-to-back.
+ */
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory } from '../../core/destructive.js';
+import { mutatePatchMetadata } from '../../core/patch-export.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+/**
+ * Computes the post-mutation `lintIgnore` list for a given mode.
+ * Returns `undefined` when the result should drop the field from the
+ * manifest entirely (matching the validator's "preserve only when
+ * present" contract).
+ */
+function applyMode(existing, mode, values) {
+    const existingSet = new Set(existing);
+    if (mode === 'add') {
+        for (const v of values)
+            existingSet.add(v);
+        const merged = [...existingSet];
+        return merged.length > 0 ? merged : undefined;
+    }
+    if (mode === 'remove') {
+        for (const v of values)
+            existingSet.delete(v);
+        const remaining = [...existingSet];
+        return remaining.length > 0 ? remaining : undefined;
+    }
+    // mode === 'clear'
+    return undefined;
+}
+/**
+ * Renders a one-line summary of the planned change for use in
+ * `info()` / dry-run / history args.
+ */
+function describeChange(before, after, mode, values) {
+    const beforeSet = new Set(before);
+    const afterSet = new Set(after);
+    if (mode === 'clear') {
+        return before.length === 0
+            ? 'lintIgnore was already empty — no change'
+            : `lintIgnore cleared (was ${before.join(', ')})`;
+    }
+    if (mode === 'add') {
+        const added = values.filter((v) => !beforeSet.has(v));
+        if (added.length === 0) {
+            return 'lintIgnore unchanged (all requested IDs were already present)';
+        }
+        return `lintIgnore += ${added.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
+    }
+    // mode === 'remove'
+    const removed = values.filter((v) => beforeSet.has(v));
+    if (removed.length === 0) {
+        return 'lintIgnore unchanged (none of the requested IDs were present)';
+    }
+    return `lintIgnore −= ${removed.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
+}
+/**
+ * Runs the `patch lint-ignore` command: reads the patch's existing
+ * `lintIgnore`, applies the requested mode, and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (exactly one of `add`/`remove`/`clear`)
+ */
+export async function patchLintIgnoreCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch lint-ignore (dry run)' : 'FireForge patch lint-ignore');
+    // Mode mutex: exactly one mode per invocation. Combinations like
+    // `--add foo --remove bar` are rejected — an operator who needs both
+    // runs the command twice (clearer audit trail) and `--clear` plus a
+    // mode is contradictory.
+    const adding = (options.add?.length ?? 0) > 0;
+    const removing = (options.remove?.length ?? 0) > 0;
+    const clearing = options.clear === true;
+    const modeCount = [adding, removing, clearing].filter(Boolean).length;
+    if (modeCount > 1) {
+        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch lint-ignore');
+    }
+    if (modeCount === 0) {
+        throw new InvalidArgumentError('Specify --add <id>, --remove <id>, or --clear.', 'patch lint-ignore');
+    }
+    const mode = adding ? 'add' : removing ? 'remove' : 'clear';
+    const values = mode === 'add' ? (options.add ?? []) : mode === 'remove' ? (options.remove ?? []) : [];
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        const available = manifest.patches
+            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
+            .join(', ');
+        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+    }
+    if (isDryRun) {
+        const existing = target.lintIgnore ?? [];
+        const projected = applyMode(existing, mode, values) ?? [];
+        info(`[dry-run] ${target.filename}: ${describeChange(existing, projected, mode, values)}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const result = await mutatePatchMetadata(paths.patches, target.filename, (existing) => {
+        const next = applyMode(existing.lintIgnore ?? [], mode, values);
+        // Either set the new list when non-empty or unset the field
+        // entirely. The mutation API splits these to keep the
+        // exactOptionalPropertyTypes contract clean — only set values land
+        // in the typed `Partial<PatchMetadata>`, and the unset list is
+        // applied via `delete` after spread.
+        return next !== undefined ? { set: { lintIgnore: next } } : { unset: ['lintIgnore'] };
+    });
+    if (!result) {
+        // Race: target vanished between the manifest read above and the
+        // locked mutate. Surfacing as a hard error rather than a silent
+        // no-op — the operator's intent did not land.
+        throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+    }
+    const existing = result.before.lintIgnore ?? [];
+    const projected = result.after.lintIgnore ?? [];
+    info(`${target.filename}: ${describeChange(existing, projected, mode, values)}.`);
+    try {
+        await appendHistory(paths.patches, {
+            operation: 'patch-lint-ignore',
+            args: {
+                filename: target.filename,
+                mode,
+                values: [...values],
+                before: existing,
+                after: projected,
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            result: 'ok',
+        });
+    }
+    catch (historyError) {
+        warn(`History log append failed after patch lint-ignore committed (${target.filename}): ${toError(historyError).message}`);
+    }
+    outro('Patch lint-ignore complete');
+}
+/**
+ * Registers the `patch lint-ignore` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchLintIgnore(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('lint-ignore <name>')
+        .description('Edit PatchMetadata.lintIgnore on a single patch (no .patch body rewrite). One mode per invocation.')
+        .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable)', (value, prev) => [...prev, value], [])
+        .option('--remove <check-id>', 'Lint check ID to remove from the patch lintIgnore list (repeatable)', (value, prev) => [...prev, value], [])
+        .option('--clear', 'Drop the lintIgnore field entirely')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        // Commander defaults `--add`/`--remove` to `[]` so they appear in
+        // the options object even when unused. Strip empty arrays so
+        // `pickDefined` sees them as absent — otherwise the mode-count
+        // mutex would treat zero-length arrays as a present mode.
+        const normalized = {};
+        if (options.add !== undefined && options.add.length > 0)
+            normalized.add = options.add;
+        if (options.remove !== undefined && options.remove.length > 0)
+            normalized.remove = options.remove;
+        if (options.clear === true)
+            normalized.clear = true;
+        if (options.dryRun === true)
+            normalized.dryRun = true;
+        if (options.yes === true)
+            normalized.yes = true;
+        await patchLintIgnoreCommand(getProjectRoot(), name, normalized);
+    }));
+}
+//# sourceMappingURL=lint-ignore.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on
+ * a single patch without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is
+ * the right tool when the patch body itself needs to be regenerated; this
+ * subcommand exists for the metadata-only adjustment, where the operator
+ * has discovered (e.g. from a `lint --per-patch` warning) that the
+ * threshold-tier override should be set but the patch body is already
+ * correct. Avoiding the re-export saves the engine read + diff
+ * regeneration roundtrip and leaves the `.patch` file's mtime alone.
+ *
+ * Modes are mutually exclusive: exactly one of `--tier <branding>` or
+ * `--clear` must be supplied per invocation.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchTierOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch tier` command: updates `PatchMetadata.tier` on the
+ * named patch (or clears the field) and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options
+ */
+export declare function patchTierCommand(projectRoot: string, identifier: string, options?: PatchTierOptions): Promise<void>;
+/**
+ * Registers the `patch tier` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchTier(parent: Command, context: CommandContext): void;