@hominis/fireforge 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.40.0
+
+- **Dependencies: adopted all five open dependabot PRs (#48, #47, #45, #44, #42) after Go-based TypeScript 6 compatibility review** — the pinned `typescript ~6.0.0` (6.0.3 installed) constrained which upgrades were feasible; every bumped tool checked out: `typescript-eslint` declares peer `typescript >=4.8.4 <6.1.0`, `knip` carries no TypeScript dependency at all (oxc parser), and `dpdm` bundles its own nested TypeScript 5.9.3, so none touch the root compiler. Production: `acorn` 8.17.0→8.18.0 (lockfile-only) and `magic-string` 0.30.21→**1.1.0** — a major that only drops the CJS/UMD builds for pure ESM (FireForge is pure ESM; the five `MagicString` call sites use the unchanged core API). Dev: `@types/node` 26.1.2, `dpdm` 4.3.0, `eslint` 10.8.0, `eslint-plugin-jsdoc` 63.3.3, `knip` 6.29.0, `lint-staged` 17.3.0, `prettier` 3.9.6, `typescript-eslint` 8.66.0, `vite` 8.2.1, and `eslint-plugin-simple-import-sort` 13→**14** (breaking only for string-literal export names, which the codebase does not use); four of these resolved one patch/minor past PR #48's snapshot within the existing caret ranges (typescript-eslint 8.66.0 re-verified against the same `<6.1.0` peer window). CI: the SHA-pinned actions group (checkout 7.0.1 with `--unset`-escaping and branch-trim fixes, setup-node, codeql init/analyze). knip 6.29's stricter re-export tracking flagged seven type re-exports (`PatchCoverage`, `ClearablePatchMetadataField`, `PatchMetadataMutation{,Result}` in `patch-export.ts`; `ForwardImportEdge` in `patch-lint-reexports.ts`; `PatchManifestRowMutation{,Result}` in `patch-manifest.ts`) that no module, test, or public-API entry consumed via the barrel hop — a real 6.26 blind spot, so the dead re-exports were removed (the types stay exported from their defining modules). Verified by a full green `release:check`.
+- **New `fireforge tree` command: copy-on-write verification clones for concurrent read-mostly work** (FORGE G15, feature — every consumer parallelisation attempt dead-ended on the ONE applied engine tree: `engine/` is gitignored by design so git worktrees provide no isolation, and the repo-root build lock plus one objdir kept all fix/test/export work serial; measured on APFS, `engine/browser` — 11,513 files, 156 MB — clones via clonefile in ~3 s): `tree create <name>` snapshots the project (fireforge.json, configs, src, patches, components, and `engine/` with `obj-*` excluded) into `.fireforge/trees/<name>` via filesystem CoW (APFS clonefile / btrfs-XFS reflink, probed BY DOING in the destination directory), taken under the primary engine-session lock so a mid-mutation state is never captured; filesystems without CoW REFUSE honestly, with `--force-copy` opting into a full physical copy explicitly (never silently). A tree is a full project root, so `status`, `lint`, `typecheck`, `verify`, `doctor`, and `export --dry-run` run inside it unmodified with their own per-tree locks — while every mutating command (`export`, `re-export`, `patch *`, `token *`, `furnace *`, `build`, headed `run`, …) is refused via the `.fireforge/tree.json` marker and a default-deny verdict table enforced in one commander preAction hook (a drift test forces every new command to be classified); patches and exports stay strictly serial in the primary tree with no merge-back model. `tree list [--json]` reports staleness against the primary engine HEAD and `patches.json` fingerprint; `tree remove` refuses while a live process holds a tree lock and path-contains its delete; `tree exec <name> -- <cmd>` runs a command inside a tree; Windows is refused (POSIX clonefile/reflink only). **Deferred to 0.41.0 with the design recorded: `--with-objdir` and in-tree `test`** — mach objdirs embed absolute `topsrcdir`/`topobjdir` paths (FireForge's own `mach-build-artifacts.ts` parses them), so a cloned objdir would silently operate against the primary tree; a `mozinfo.json` preflight is the planned gate. New invariant 7 in `docs/lifecycle-invariants.md`. Pinned by `tree-cow.test.ts` (per-platform cp argv, probe verdicts), `tree-store.integration.test.ts` (snapshot contents/exclusions, independence, staleness, live-holder refusal), `tree-guard.test.ts` (verdict drift gate), and `tree.integration.test.ts` (real clone + real-program guard refusal).
+- **Previously deferred items, re-adjudicated for 0.40.0**: auto-`caffeinate` for headed macOS dispatches stays deferred (the 0.39.0 F17 message + operator rule works; auto-wrap adds TTY/permission complexity for little gain); real co-ownership of one upstream file by two patches stays deferred (design-level — shared-file diffs are pristine-baseline so co-ownership remains unrepresentable; the consumer's single-owner consolidation plus audit-side per-patch entry lists stands); `furnace create` maintaining the consumer jsconfig path mapping for new widget modules stays deferred this release (the JSONC-preserving edit machinery exists, but the mapping shape is consumer-project-specific — revisit with a concrete config contract).
+- **Concurrent xpcshell runs no longer collide on Firefox's fixed profile directory** (FORGE G15b, bug — the harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a fixed `$TMPDIR/firefox/xpcshellprofile`, so two overlapping `fireforge test` invocations corrupted each other's profiles; FireForge itself never set the variable): every harness invocation that can dispatch xpcshell (single runs, each shard, and generic `mach test` runs) now exports a fresh `mkdtemp` profile dir (`fireforge-xpcshell-profile-*`) into the mach environment via the new `withXpcshellProfileDir` helper and removes it after the run (best-effort — a cleanup failure warns and leaves the dir to the OS tmp reaper); the crash/symlink-repair retries within one invocation deliberately reuse the same directory, an operator-provided `XPCSHELL_TEST_PROFILE_DIR` is respected verbatim (and never deleted), and pure mochitest dispatches keep a byte-identical env. This is the independently-shippable half of the G15 verification-tree design — it also unblocks concurrent test runs from separate checkouts today. Pinned by uniqueness/opt-out/override/retry-reuse cases in `test-run-suite-dispatch.test.ts` and the lifecycle cases in `xpcshell-profile-dir.test.ts`.
+- **Per-patch lint can now typecheck patch-adopted test `.js` files against a consumer-configurable harness shim: `patchLint.checkJsTestFiles` + `patchLint.checkJsTestShim`** (FORGE G5, enforcement gap — honest framing: the consumer's seven TS2339s on `TestUtils.waitForCondition` were invisible to `lint --per-patch --max-warnings 0` not because the shim differed from the jsconfig projects', but because test `.js` files were never in the checkJs program at all — only new `.sys.mjs` modules were; the harness global that does not exist should fail at the patch boundary where the test was authored): opt-in (`checkJsTestFiles` requires `checkJs`; new failure surface, nonzero compile cost) extends the check set to patch-owned `browser_*`/`test_*`/`xpcshell_*` and `/test/`-path `.js` files, each checked as its OWN small script-scope program (mochitest scripts share top-level scope only with their directory's `head*.js` helpers, which are included as roots) against the built-in Firefox shim, a new loose built-in test-harness shim (`TestUtils`, `BrowserTestUtils`, `add_task`, `ok`/`is`, …), and the consumer's `checkJsTestShim` `.d.ts` — whose typed declarations compose BEFORE the loose baseline and therefore win, so a typed `TestUtils` there is exactly what turns the consumer's case into an export-time error. Wired identically into `lint --per-patch` (one merged lazy build per run) and the export/re-export path so the two agree; `typecheck.projectOverrides` remains typecheck-only by design (loading real jsconfig projects into per-patch lint's empty-tree compiler host would pull the Firefox tree in). Pinned by the was-never-checked gap pin, the TS2339-surfaces case, and the loose-baseline pass in `lint-per-patch-checkjs.integration.test.ts`, plus config cross-field validation in `config.test.ts`.
+- **Patch size metrics are now on the public API — `countNonBinaryDiffLines`, `resolvePatchSizeTier`, and the new `getPatchSizeThresholds` — plus a machine-readable per-patch report via `lint --per-patch --report <path>`** (FORGE G9, feature — the size counter `large-patch-lines` fires on was unreachable programmatically (`"./*": null` blocks deep imports and `src/index.ts` never exported it), so the consumer MIRRORED it to build waiver-freshness checks, a silent-divergence risk by construction): the three functions and the `PatchSizeTierDecision` type join the entry exports (pinned by `public-api.test.ts`), and the `--report` JSON (schemaVersion 1; requires `--per-patch`) carries per patch: filename, name, status (`linted`/`cached`/`skipped`), `lineCount` (non-binary diff lines), `filesAffected` count, the tier decision, the ACTIVE thresholds for that tier, the surfaced issues, and the lintIgnore-suppressed issues, plus run totals. Pinned by the report-shape assertions in `lint.integration.test.ts`.
+- **A size finding waived by `lintIgnore` no longer vanishes without a trace in per-patch mode** (FORGE G10, observability — the waiver filter dropped the whole issue including the measurement embedded in its message, so a waived patch's CURRENT size could not be read back from the tool that enforces it and waiver-cited counts had to be calibrated by hand; aggregate mode printed a suppressed count while per-patch printed nothing): the finding stays suppressed (no exit-code or `--max-warnings` effect) but its measurement is reported as `NOTICE [large-patch-lines] <patch>: suppressed by lintIgnore — Patch is N lines (hard limit: M) …` (likewise `large-patch-files` / `file-too-large`), the run summary adds `Suppressed k issue(s) via per-patch lintIgnore.` mirroring the aggregate wording, and suppressed issues plus the measured line count are carried through the per-patch lint cache (schema bump to v2, one-time cold cache) so a warm run can never report less than a cold one — the same F5-class hazard the run-level checkJs fix closed. Also available structurally in the `--report` JSON. Pinned by the waived-measurement case in `lint.integration.test.ts` and the cache round-trip in `lint-cache.test.ts`.
+- **Smoke-run summaries now attribute allowlist hits per entry, with zero-hit entries flagged as removal candidates** (FORGE G8, observability — `matchesAllowlist` returned a bare boolean and `compileAllowlistFromFile` discarded source line numbers, so an allowlist entry that silently stopped matching was undetectable and the consumer rebuilt per-entry replay in ~190 lines against a retained capture): compiled entries now carry their verbatim source and origin (`allow.txt:12`, `--console-allow #2` — file origins keep the ORIGINAL line numbers, comments included) via the new `CompiledAllowlistEntry` shape, `matchAllowlist` returns the first matching index (deterministic first-match attribution, replacing the boolean `matchesAllowlist`), and the post-run summary prints one `N×  <origin>  <source>` row per entry with `0×` rows suffixed `(never matched — candidate for removal)`. The three scalar counters and the exit contract (12/13) are unchanged; the human summary is the supported surface (no JSON sidecar this release). Pinned by the attribution rows in `run.test.ts` and the origin/first-match cases in `smoke-patterns.test.ts`.
+- **`lint --per-patch <patch…>` now works: positional arguments in per-patch mode select patches through the same alias resolution as `--patches`** (FORGE G14, ergonomics — the natural invocation `lint --per-patch a.patch b.patch` was rejected with the misleading "cannot be combined with explicit engine file paths" while the suggested form required retyping the list behind a flag): positionals are appended after explicit `--patches` entries and resolved tolerantly (filename, stem, manifest name, category-prefixed slug, or bare slug); a non-matching positional fails loud with `No patch in the queue matches "…". In --per-patch mode, positional arguments and --patches select patches … drop --per-patch to lint engine paths.` plus the available-patches listing, so an engine path can never silently lint the wrong thing. The `--patches` help notes the positional equivalence. Pinned by the positional-subset and unmatched-positional cases in `lint.test.ts`.
+- **`patch staged-dependency --remove` now accepts `--file` + `--specifier` alone, inferring `--creates` from a unique match; missing-flag errors name the actually-missing flags** (FORGE G12, ergonomics + message — the remove path demanded the full triple even when file+specifier identified exactly one entry, and every `Invalid Argument` printed `Argument: patch staged-dependency`, restating the command instead of the offending flag): a unique file+specifier(+`--owner`) match infers its `creates` with an `Inferred --creates …` notice; an ambiguous match refuses listing every candidate (`pass --creates to pick one`); no match keeps the honest exit-0 "no staged forward-import matched" summary. `--kind registration` gets the identical treatment keyed on `--line`. All `Argument:` lines in this command now name flags (`--specifier, --creates`, `--kind`, `--add/--remove/--clear`, …), and the `-y/--yes` help no longer claims a confirmation prompt exists (message-only — the command never prompted; the flag records scripted consent in the history log). Pinned by the inference, ambiguity, no-match, and attribution cases in `patch-tier-and-lint-ignore.integration.test.ts`.
+- **`token add` can no longer silently strand or skip a token when its category is wrong — every bypass around the missing-category refusal is closed** (FORGE G3, bug + claim partially REFUTED — the reported plain-path "missing category exits 0" is contradicted by the pre-existing `assertTokenCategoryExists` throw, pinned since before 0.39.0; the 19 observed silent no-ops reproduce only through three real bypasses, all fixed): (1) category banners now match EXACTLY (`/* = Name = */` text equality, multi-line block-line equality) instead of by substring, so a TOC comment mentioning "Colors — Terminal" or a `Colors — Canvas` banner can no longer satisfy a lookup for a different name — assert and writer share the matcher (new `token-category.ts`); (2) the whole-file idempotency check is replaced by a per-category one — a token already in the TARGET category skips with its location named (`already exists in category "X" (line N)`), while a token declared elsewhere in the base `:root` block REFUSES with `Token "…" is already declared outside category "…" (<file>:<line>, section "…")` instead of silently skipping and discarding `--create-category`; dark-`@media`/variant companion blocks are excluded from ownership; the exact name must match (`--foo` no longer collides with `--x-foo`); (3) `--variant` now validates `--category` against the file instead of silently discarding it, and `--variant` + `--create-category` is refused. Dry-run agrees with the real run on all three. Behavior change: loose banner matches that previously "worked" now fail loud with the existing available-categories listing. Pinned by the bypass matrix in `token-manager.test.ts`.
+- **Patch-lint `raw-color-value` no longer fires on hex colors inside CSS comments that span the context/added-line boundary** (FORGE G4, bug — the per-patch comment stripper only saw the joined added lines, so a `/*` opened on an unchanged context line never suppressed a hex mention on an added line; two prose references to a vendored sheet's black paint inside comments tripped the rule for the consumer on 2026-07-30): the diff branch now masks comments across the full post-patch file (spaces preserve line numbers; an unclosed trailing `/*` masks to EOF) via the new `extractAddedLineNumbersPerFile` diff walker, then scans only the patch's added line numbers. Inline `fireforge-ignore: raw-color-value` waivers keep matching against pre-strip text; the no-diff branch is unchanged; and when the diff's line numbers fall outside the on-disk file (drifted patch) the scan falls back to the previous joined-added-lines behavior instead of misattributing lines. Pinned by the boundary-spanning, still-fails-in-declaration, waiver, and drift-fallback cases in `patch-lint.test.ts`.
+- **`export --name ui-foo --category ui` now lands manifest `name: "foo"` in one step, and `--name <stem>.patch` no longer trips the dot validator** (FORGE G13, bug + message — the filename slug pipeline has stripped redundant category prefixes since 0.33.0 (and `.patch` suffixes since 0.39.0's F9) but the manifest display name kept the raw flag value, so a bare-filename-slug naming policy required a follow-up `patch rename --to` after every export): display names are normalized after category resolution with the same require-the-category-token rule as filenames via the new `normalizePatchDisplayName` (`NNN-ui-` / `ui-` prefixes stripped case-insensitively and repeatedly; a bare leading number is never stripped, so `2-step-verification` survives; the strip falls back to the stem rather than emptying the name), announced with `Patch name normalized: "ui-foo" → "foo" (the filename carries the order and category prefix).`; a trailing `.patch` is stripped before `validatePatchName` runs. Applies to `export` and `export-all`. `patch rename` additionally gains `-d` as an alias for `--description`; multi-target `re-export --scan --scan-file` remains deferred (file→patch assignment would be ambiguous — `--scan-files <manifest>` already serves bulk assignment). Pinned in `export-shared.test.ts` and `validation.test.ts`.
+- **New `status --check` (and `--fail-on <class,...>`) turns classification drift into a CI-enforceable non-zero exit** (FORGE G1, enforcement gap — every 0.39.0 status variant exited 0 even while reporting unmanaged/drifted/conflicted files, so "refuse if dirty" required every consumer to parse `--json` and re-implement the classification policy; combined with the G2 gap this let two manifest-registered proving suites ship into no patch while every advertised gate stayed green): `--check` fails with exit 1 whenever any `unmanaged`, `patch-owned-drift`, or `conflict` file exists, naming each offending classification with its first three paths (`status --check failed: 2 unmanaged (a, b), 1 patch-owned-drift (c). …`); `--fail-on` replaces the policy set (implying `--check`, refusing unknown values by naming the valid six); composes with the default view and `--json` (the JSON stays parseable on stdout, the refusal routes to stderr) and is refused alongside `--raw`/`--unmanaged`/`--ownership`/`--test-coverage`. A clean tree passes. Pinned by `status-check.test.ts` and the `--check` cases in `status.test.ts`.
+- **`status --json` files[] entries now carry a `patch` field naming the owning patch filename (`null` when unowned)** (FORGE G11, feature — the classifier resolved every file's owner at classify time and then discarded it for non-conflict entries, so resolving 16 drifted files to their patches meant scraping the human `--ownership` box table with `awk`): single-owner `patch-backed`, `patch-owned-drift`, and healthy single-owner `furnace` entries name their owner; `branding`, unowned `furnace`, and `conflict` entries report `null` (conflicts keep the existing `claimedBy` array — a single-owner field must not misrepresent a multi-claim). Additive to `schemaVersion: 1`, so consumers pinning the schema keep parsing; the post-slice re-export loop is now scriptable straight off `--json`. Pinned by the owner-matrix case in `status.test.ts`.
+- **Scan-less `re-export`'s adjacency notice is now classification-aware, and the new `--refuse-adjacent-unmanaged` flag upgrades it to a non-zero refusal that skips the write** (FORGE G2, bug + message — the claim that 0.39.0 was fully silent is partially REFUTED: the v0.27.2 sibling advisory did fire for the reported shape, a new test created beside a patch's owned tests, and is pinned by the pre-fix reproduction in `re-export.integration.test.ts`; but it counted tool-managed paths as "unowned siblings" and offered no enforcement). The notice now names only genuinely unmanaged adjacent files — generated branding paths and furnace-managed prefixes are excluded, while a brand-new unowned file under the branding root stays listed (the Assets.car precedent) — with the wording `found N unmanaged file(s) adjacent to this patch's ownership (<first 3>)`. Under `--refuse-adjacent-unmanaged` (scan-less path only; refused alongside `--scan`/`--files`) each offending patch is skipped unwritten and the run fails with one refusal naming every offender, so CI cannot ship a patch refresh past an unadopted file. Residual blind spot documented in-test: a new file in a cousin directory no owned file lives in is still unreported (recursive scans are too noisy on Firefox-sized trees). Pinned in `re-export.test.ts` (branding/furnace exclusion, skip-and-refuse) and `re-export.integration.test.ts`.
+- **`re-export` now retries once, after a 300 ms backoff, when a patch fails on transient git `index.lock` contention** (FORGE G7, bug — an external git process touching `engine/.git/index.lock` during the binary-staging `git add -N`/`git diff --binary` window permanently failed that patch while the run reported `Re-exported 1 of 2` and exited 0; the identical immediate rerun succeeded with no hand cleanup, which is exactly the shape an internal retry should absorb): lock-class failures are detected via the new `isGitIndexLockConflict` heuristic in `errors/git.ts` (a `GitIndexLockError`, or a `GitError` whose message pairs `index.lock` with lock phrasing), the retry re-enters the per-patch export from the top so it re-reads clean state, and a second failure keeps the honest `N of M` summary. Non-lock failures never retry. Partial-failure exit code is intentionally unchanged this release; a non-zero exit (or `--strict`) for partial runs is the recommended follow-up. Pinned by the retry, double-failure, partial-success, and no-retry cases in `re-export.test.ts` and the heuristic table in `git-index-lock.test.ts`.
+- **`export --before/--after` no longer refuses placements whose renumber never actually reaches a reserved range** (FORGE G6, bug — `computePlacementPlan` shifted every patch at or above the insertion point by +1, so any positional insert below a `patchPolicy.reservedRanges` block dragged the reserved patches into the rename map and tripped the up-front refusal even with free ordinals in between; in a ~230-patch tree with a 900-999 reserved block, `--before`/`--after` were effectively unavailable and every insert needed an explicit `--order`): the +1 cascade now stops at the first unoccupied ordinal — a gap absorbs the insert, so the tail beyond it (including any reserved block) keeps its numbering — while a genuinely contiguous run into the block still refuses with the same single up-front error. The same cascade serves `patch split` and `patch move-files --create` placements. Pinned by the stop-at-gap and contiguous-refusal cases in `export-placement-policy.test.ts` and the rewritten sparse-queue case in `export-flow.test.ts`.
+
 ## 0.39.0
 
 - **`fireforge discard` restores patch-claimed paths to their PATCH-APPLIED baseline instead of pristine upstream, and re-materializes patch-created files instead of deleting them** (FORGE F1, P0 data-loss bug — 15 `patch-backed`/`owned` engine files discarded with `--yes` came back as upstream Firefox artwork, `jar.mn` lost all 134 fork entries, and patch-created files like `hominis-start.html` were deleted outright, all under the message "File restored to original state"; recovery cost a full `reset` + 207-patch `import` + rebuild): discard now consults the manifest's ownership claims per status entry and restores claimed files by folding HEAD content through every affecting patch in order (`computePatchedContent`), leaving the post-`import` worktree convention intact (patch edits stay unstaged ` M`, patch creations stay untracked `??`); patch-deleted files are removed to match the baseline. The legacy semantics are an explicit opt-in via the new `--to-upstream` flag. Success messages name the baseline (`File restored to patch baseline (0001-ui-edit.patch)`, `File re-materialized from patch baseline (…)`, `File restored to pristine upstream (HEAD)`); directory mode applies the same rule per file and its outro buckets the outcomes (`3 file(s) restored: 1 to patch baseline, 1 re-materialized, 1 to upstream state`); dry-run lines annotate each path with its restore target. A corrupt manifest or an unreconstructible baseline REFUSES (naming `--to-upstream`) rather than silently reverting to HEAD; multi-owner (conflict) claims restore the cumulative baseline with a warning pointing at `status --ownership`. Pinned by `discard-patch-baseline.integration.test.ts` (the exact handoff shape: edit-patch + create-patch, dirty both, discard each, assert patch content and git state) and `discard-baseline.test.ts`.

package/README.md

@@ -131,7 +131,31 @@ contaminates the console capture (headed non-CI launches print a warning saying
 Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals shim that
 tracks upstream WebIDL additions per release; a project's `patchLint.checkJsExtraShim` can
 add members to the structured shim globals via TypeScript interface merging (e.g.
-`interface ChromeUtilsShim { newApi(): any }`).
+`interface ChromeUtilsShim { newApi(): any }`). Opting into
+`patchLint.checkJsTestFiles: true` extends the pass to patch-owned test `.js` files
+(`browser_*`/`test_*`/`xpcshell_*` and `/test/` paths), each checked as its own small
+script-scope program against a loose built-in harness shim; `patchLint.checkJsTestShim`
+points at a project `.d.ts` whose typed declarations (e.g. a real `TestUtils` interface)
+override the loose baseline so calls to nonexistent harness members fail at export time.
+
+For CI enforcement, `fireforge status --check` exits non-zero when any unmanaged,
+drifted, or conflicted file exists (`--fail-on <class,...>` tunes the policy set, and
+`--json` composes — the JSON stays parseable and its `files[]` entries name the owning
+`patch`). `lint --per-patch --report <path>` writes a machine-readable JSON report with
+each patch's line count, tier, active size thresholds, issues, and lintIgnore-suppressed
+issues; the size metrics (`countNonBinaryDiffLines`, `resolvePatchSizeTier`,
+`getPatchSizeThresholds`) are also exported on the programmatic API.
+
+For concurrent read-mostly verification beside a busy primary checkout,
+`fireforge tree create <name>` snapshots the project — applied engine tree included,
+`obj-*` excluded — into `.fireforge/trees/<name>` using filesystem copy-on-write (APFS
+clonefile / btrfs-XFS reflink; ~3 s for a 156 MB applied browser tree). Inside a tree,
+`status`, `lint`, `typecheck`, `verify`, `doctor`, and `export --dry-run` work unmodified
+with their own locks, while every mutating command is refused — patches and exports stay
+strictly serial in the primary tree. `tree list` reports staleness, `tree remove` deletes
+(refusing while a live process holds a tree lock), and `tree exec <name> -- <cmd>` runs a
+command inside a tree. Filesystems without CoW support refuse unless `--force-copy`
+explicitly accepts a full physical copy.
 
 ## Rebasing Firefox Source
 

package/dist/src/cli.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Command, Help } from 'commander';
 import { COMMAND_MANIFEST } from './commands/manifest.js';
+import { runTreeGuardHook } from './core/tree-guard.js';
 import { CancellationError, CommandError, FireForgeError } from './errors/base.js';
 import { ExitCode } from './errors/codes.js';
 import { ConfigNotFoundError } from './errors/config.js';
@@ -250,6 +251,12 @@ export function createProgram() {
         if (opts['verbose']) {
             setVerbose(true);
         }
+    })
+        // Verification-tree guard (FORGE G15): when the cwd resolves into a
+        // tree snapshot, refuse mutating commands before their action runs —
+        // one hook covers every command regardless of how the cwd got there.
+        .hook('preAction', async (thisCommand, actionCommand) => {
+        await runTreeGuardHook(thisCommand.name(), actionCommand);
     });
     const groupedFormatter = buildGroupedHelpFormatter(COMMAND_MANIFEST);
     program.configureHelp({

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

@@ -74,14 +74,22 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
     const sorted = [...manifestPatches].sort((a, b) => a.order - b.order);
     const renameMap = new Map();
     const prefixWidth = prefixWidthForPatches(sorted, requestedOrder);
-    // Every existing patch at requestedOrder or later shifts up by one.
+    // Patches at requestedOrder or later shift up by one, but only until the
+    // cascade reaches a free ordinal — a gap absorbs the insert, so the tail
+    // beyond it (including any reserved block) keeps its numbering.
+    let cursor = requestedOrder;
     for (const patch of sorted) {
-        if (patch.order >= requestedOrder) {
-            const newOrder = patch.order + 1;
-            const currentRest = patch.filename.replace(/^\d+-/, '');
-            const newFilename = `${String(newOrder).padStart(prefixWidth, '0')}-${currentRest}`;
-            renameMap.set(patch.filename, { newOrder, newFilename });
+        if (patch.order < requestedOrder) {
+            continue;
         }
+        if (patch.order > cursor) {
+            break;
+        }
+        const newOrder = cursor + 1;
+        const currentRest = patch.filename.replace(/^\d+-/, '');
+        const newFilename = `${String(newOrder).padStart(prefixWidth, '0')}-${currentRest}`;
+        renameMap.set(patch.filename, { newOrder, newFilename });
+        cursor = newOrder;
     }
     const newFilename = buildFilenameForPlacement(newPatchCategory, newPatchName, requestedOrder, prefixWidth);
     return {

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

@@ -10,7 +10,7 @@ import { getPatchPolicyCategories, isCategoryAllowedByConfig } from '../core/pat
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
-import { PATCH_CATEGORIES, validatePatchName } from '../utils/validation.js';
+import { normalizePatchDisplayName, PATCH_CATEGORIES, validatePatchName, } from '../utils/validation.js';
 /**
  * Runs the full patch lint pipeline and reports results.
  * Warnings are always displayed. Errors block the export unless skipLint is true.
@@ -101,7 +101,10 @@ export async function runPatchLint(engineDir, filesAffected, diffContent, config
  */
 export async function promptExportPatchMetadata(options, isInteractive, commandName, config) {
     const categories = config !== undefined ? getPatchPolicyCategories(config) : [...PATCH_CATEGORIES];
-    let patchName = options.name;
+    // A filename-shaped `--name foo.patch` must not die on the dot rule —
+    // strip the extension before validation so the one-step flow works for
+    // both name shapes (FORGE G13).
+    let patchName = options.name?.trim().replace(/\.patch$/i, '');
     if (patchName) {
         const validationError = validatePatchName(patchName);
         if (validationError) {
@@ -156,8 +159,16 @@ export async function promptExportPatchMetadata(options, isInteractive, commandN
             description = String(descResult);
         }
     }
+    // The filename slug pipeline strips redundant category prefixes; the
+    // manifest display name must agree, or every `export --name ui-foo`
+    // needs a follow-up `patch rename` to satisfy bare-slug naming policy
+    // (FORGE G13).
+    const normalized = normalizePatchDisplayName(patchName, category);
+    if (normalized !== patchName) {
+        info(`Patch name normalized: "${patchName}" → "${normalized}" (the filename carries the order and category prefix).`);
+    }
     return {
-        patchName,
+        patchName: normalized,
         selectedCategory: category,
         description,
     };

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

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

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

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

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

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

package/dist/src/commands/lint.js

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

package/dist/src/commands/manifest.js

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

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

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