@hominis/fireforge 0.52.0 → 0.53.0

package/docs/machine-output.md

@@ -2,12 +2,9 @@
 
 # Machine-readable output contract (internal)
 
-The `--json` surface is a contract with scripted consumers. Before 0.44.0 it
-was four unrelated shapes: `status --json` and `tree list --json` shared a
-`schemaVersion: 1` envelope but disagreed on failure, `test` emitted a
-`FIREFORGE-VERDICT:` line, and `lint --per-patch --report` wrote a versioned
-file that nothing ever reads back. This file states what a `--json` command
-has to do, so the next one added does not invent a fifth shape.
+The `--json` surface is a contract with scripted consumers. This file states
+what a `--json` command has to do, so the next one added does not invent a
+shape of its own.
 
 ## The rules
 
@@ -56,11 +53,11 @@ if (options.json === true) {
 | Surface                            | Shape                                                                                                                                                                                                                                                                             | Notes                                                                                                                                                                                                                              |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `status --json`                    | `{ schemaVersion: 1, … }`                                                                                                                                                                                                                                                         | Error envelope on three engine preconditions                                                                                                                                                                                       |
-| `status --json` under `--check`    | adds `check: { enabled, failOn, allow?, failOnUnknown?, failed, offenders }`                                                                                                                                                                                                      | Since 0.50.0 on the full payload too, not only `--summary`. `allow` and `failOnUnknown` appear only when set. An offender failing only through `--fail-on-unknown` carries `unnamed: true`. `--patches` adds `scope: { patches }`  |
+| `status --json` under `--check`    | adds `check: { enabled, failOn, allow?, failOnUnknown?, failed, offenders }`                                                                                                                                                                                                      | On the full payload too, not only `--summary`. `allow` and `failOnUnknown` appear only when set. An offender failing only through `--fail-on-unknown` carries `unnamed: true`. `--patches` adds `scope: { patches }`               |
 | `furnace validate --json`          | `{ schemaVersion: 1, passed, summary, maxWarnings?, components, issues, excepted, staleExceptions }`                                                                                                                                                                              | `issues` counts after `validationExceptions`, stale-exception warnings included. `excepted` carries each suppressed finding with its `reason`                                                                                      |
 | `check --json`                     | `{ schemaVersion: 1, verdict, reason?, summary, steps }`                                                                                                                                                                                                                          | One entry per step: `name`, `kind`, `command`, `status` (`pass`/`fail`/`skipped`), `exitCode`, `durationMs`, `detail`, and on failure `outputTail` (`timedOut` when killed at its budget). No verdict line under `--json`          |
 | `check` verdict line               | `FIREFORGE-VERDICT: PASS\|FAIL [reason=step-failures\|lock-timeout\|skipped-steps failed=<steps>] steps=<n> skipped=<n> [skipped-steps=<steps>]`                                                                                                                                  | Not JSON. The last stdout line, after the step table, sealed like `test`'s. Its `reason=` set is its own, not `test`'s                                                                                                             |
-| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                                                                                                                                                                                                                     | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                                                                                                                                                                                                                     | Error envelope on failure                                                                                                                                                                                                          |
 | `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                                                                                                                                                                                                                                 | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
 | `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                                                                                                                                                                                                                              | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
 | `token lint --json`                | `{ schemaVersion: 1, tokensCssPath, tokenPrefix, filesScanned, findings }`                                                                                                                                                                                                        | Each finding has `check`, `file`, `line`, `token`, `message`. The document is written even when findings exist; the exit is then non-zero, as with `status --check --json`                                                         |
@@ -80,7 +77,7 @@ it. Follow the rules above rather than inventing a shape.
 
 The run logs behind `log=` are specified in [`run-logs.md`](run-logs.md).
 
-Additive keys since 0.51.0 outside `test`:
+Additive keys outside `test`:
 
 - `check --json`: a skipped step carries `skipKind`, `config` when
   `check.skip` names it and `unavailable` when the project has nothing for
@@ -92,7 +89,7 @@ Additive keys since 0.51.0 outside `test`:
   `@click`). An exception that matched an error adds a
   `validation-exception-on-error` error, and a full run under
   `furnace.json#minComponents` a `component-floor` error on `furnace.json`.
-- `furnace validate --json` (since 0.52.0): a `hardcoded-text` finding
+- `furnace validate --json`: a `hardcoded-text` finding
   carries `files`, the component's module file names it was found in.
 
 ## Versioning
@@ -110,6 +107,7 @@ moved.
 | Reason              | Meaning                                                                                                                                                                                                                                                                                                                                                           |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `crash`             | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                                                                                                                                                                         |
+| `server-startup`    | A mochitest server never came up (`could not start server on port`, `Timed out while waiting for server startup`) before any test ran. An infrastructure failure, retried like `crash` within `--harness-retries`; this reason is what is left once the budget is spent.                                                                                          |
 | `harness-arguments` | Profile or other harness argument setup failed before any tests could run; a rebuild is not the repair.                                                                                                                                                                                                                                                           |
 | `no-tests`          | The run dispatched but nothing ran.                                                                                                                                                                                                                                                                                                                               |
 | `test-failures`     | The suite ran and reported unexpected results.                                                                                                                                                                                                                                                                                                                    |
@@ -126,15 +124,19 @@ developer browser holding the objdir. An unattended reader whose pipe kept
 only the verdict line could not tell those apart, so a preflight refusal that
 can classify itself also emits `note=<class>`.
 
-`note=` is additive, like `log=`, `signal=` and `shards=`. `reason=` is
-unchanged and still comes from the closed set above, so a consumer that
+`note=` is additive, like `log=`, `signal=` and `shards=`. `reason=` always
+comes from the closed set above, so a consumer that
 tokenises `key=value` pairs is unaffected, and a gate that names no class
 emits no `note=` at all. The classes are not a closed set and may grow, so
 consumers should treat an unrecognised one as opaque. Current values:
 `browser-busy`, `stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`, `mochitest-port-busy`,
 `coverage-replaced`, `stale-build`, `stale-components`, `no-launchable-binary`, `negative-control` (the
 control diff was refused), `negative-control-pending` (an interrupted run's
-control could not be undone safely). `note=negative-control-restore` rides a
+control could not be undone safely). Also `stale-compiled`
+(compiled sources changed after the binary under test was linked) and
+`control-built` (the binary still carries a compiled negative control whose
+restore build never ran or failed). An `invalid-build-baseline` refusal
+names the first failing field and its value. `note=negative-control-restore` rides a
 `reason=inconclusive` line whose control could not be restored byte-exact.
 
 ### Multi-run invocations: `FIREFORGE-RUN:`, `runs=` and `control=`
@@ -153,7 +155,7 @@ A `FIREFORGE-RUN:` line is never a verdict: the invocation still ends with
 exactly one `FIREFORGE-VERDICT:` line. With more than one planned run it
 carries `runs=<passed>/<planned>` and no count keys; a failed aggregate takes
 the most structural reason among its runs (`inconclusive`, `preflight`,
-`crash`, `harness-arguments`, `no-tests`, `test-failures`) and that run's
+`crash`, `server-startup`, `harness-arguments`, `no-tests`, `test-failures`) and that run's
 `note=`. A run that never started (the invocation stopped at a refusal)
 counts toward `<planned>` but not `<passed>`.
 
@@ -185,7 +187,7 @@ A sharded run prints one `FIREFORGE-SHARD:` line per finished shard, before
 the verdict line:
 
 ```
-FIREFORGE-SHARD: PASS|FAIL [reason=…] [checks=<n>] [unexpected=<n>] shard=<i>/<n> path=<label> [failed-files=<path>,…]
+FIREFORGE-SHARD: PASS|FAIL [reason=…] [checks=<n>] [unexpected=<n>] shard=<i>/<n> path=<label> [failed-files=<path>,…] [ports=http:<n>,ssl:<n>,ws:<n>]
 ```
 
 `path=` is the shard's path argument (whitespace replaced by `_`), or a
@@ -195,15 +197,31 @@ aggregate verdict appends `failed-shards=<label>,…` after `shards=` when any
 shard did not pass; under `--shard-size` `shards=` counts files and
 `failed-shards=` names files. Both are absent on a green run.
 
+`ports=` names the mochitest HTTP server, ssltunnel and
+WebSocket ports the shard's harness reported (its "falling back to port"
+lines), in that order and only those it reported; it is absent when the
+harness reported none (an xpcshell shard, or a harness that died before its
+servers). A shard whose server never started says `reason=server-startup`,
+and the aggregate verdict does too when every crashed shard failed that way.
+
 ### Additive keys of parallel and per-file runs
 
 `jobs=<n>` marks a `--jobs` run, `lock=shared` a run that held the engine
-session lock shared, and `results=<path>` names the `--results` document. A
+session lock shared, and `results=<path>` names the `--results` document.
+A `--jobs` run whose caller set `MOZ_UPLOAD_DIR` appends
+`upload-dirs=<dir>,…`, the per-instance upload directories
+(`<MOZ_UPLOAD_DIR>/job-<i>`, one per instance that ran), and a `--results`
+record whose `test` is `automation.py` (a harness-level result) carries
+`shardFiles`, plus `file` when its shard has exactly one file. A
 run whose engine changed mid-run only in files the running browser cannot
 see keeps its verdict and appends `drift-tolerated=<n>`. A negative control
-on compiled source appends `control-build=compiled`. Since 0.52.0 a raw log
+on compiled source appends `control-build=compiled`, and
+`control-restore-build=done|failed` for the full build that recompiles the
+restored source after the last run. Every run that reaches
+dispatch appends `build-id=<BuildID>`, read from the launchable build's
+`application.ini` (absent when that file has no `BuildID`). A raw log
 that starts none of a dispatch's requested files counts as
-`started=0/<m> ... started-source=raw` instead of leaving the run uncounted.
+`started=0/<m> ... started-source=raw`.
 
 ### The additive `shuffle=` key
 
@@ -223,9 +241,8 @@ preflight, survivors of an earlier run in this objdir under `--reap-orphans`
 or `test.reapOrphans: "reap"`; at teardown, helpers this run's harness
 launched (httpd, websocket server, ssltunnel, process bridge, the browser,
 `moz-http2`) that were still alive after mach exited. Summed across the census, every
-retry attempt and every shard. Absent when nothing was reaped, so a green on
-a quiet machine prints the line it always did, and a green after a reap is
-distinguishable from it. A run ended by SIGTERM or by the parent-exit
+retry attempt and every shard. Absent when nothing was reaped, so a green after a reap is
+distinguishable from a green on a quiet machine. A run ended by SIGTERM or by the parent-exit
 watchdog writes its verdict before the teardown reap runs, so that line never
 carries the key; the reap is reported on stderr instead.
 
@@ -243,10 +260,10 @@ and measured CPU. These diagnostics annotate a test failure without changing
 its classifier reason.
 
 Perf runs append `power-source=ac|battery|unknown`. On macOS the source is
-read from `pmset -g ps`, so charging on AC is correctly `ac`. A known source
+read from `pmset -g ps`, so charging on AC reads `ac`. A known source
 transition appends `power-changed=true` and refuses the run as
-`reason=inconclusive`. The producer's sample JSON retains its fields and
-gains `fireforgeHost: { start, end, powerSourceChanged }`, where each host
+`reason=inconclusive`. The producer's sample JSON carries an additional
+`fireforgeHost: { start, end, powerSourceChanged }` object, where each host
 state includes `load`, `power` and an optional `topProcess` with CPU and
 command. Consumers should tolerate this additive object. Unknown power
 state is visible but never treated as a proven transition.

package/docs/patch-workflow.md

@@ -109,7 +109,7 @@ adjacent to it, meaning the re-export would plausibly have to capture it:
   moz.build or test-manifest line, `*` globs included).
 
 A file in a sibling or nested directory is not adjacent, so a peer
-session's unexported test in `test/hominis-tiles/` no longer refuses a
+session's unexported test in `test/hominis-tiles/` does not refuse a
 patch that owns `test/hominis/browser.toml`. The refusal names every file
 with its anchor (`beside engine/<dir>` or `registered by engine/<carrier>`).
 
@@ -139,8 +139,8 @@ fireforge re-export 102 200 --refuse-adjacent-unmanaged --refuse-foreign-drift \
 
 `--expect-from <file>` reads `--expect` paths from a file, one per line,
 with blank lines and `#` comments ignored. Under zsh a list held in one
-variable reaches FireForge as a single argument, and splitting it by hand
-left every path after the first as a positional patch name.
+variable reaches FireForge as a single argument, and a file avoids splitting
+it by hand.
 
 Arguments are checked before the run queues for the engine lock: an empty
 or unknown patch name, a positional that is an engine file (the refusal
@@ -192,6 +192,11 @@ exception. Removing every file would empty the patch and requires `patch
 delete` (or `patch retire`, which keeps the order number) instead.
 `--expect-removed` cannot combine with `--scan`, `--files` or `--all`.
 
+The same run drops every staged declaration, registration or forward
+import, in any patch of the queue, whose `creates` path it retired and no
+other patch still owns. It prints each one (`would drop` in a dry run) and
+records the drop in the history log (`re-export-staged-prune`).
+
 ### Forward imports and new modules
 
 A re-export (plain or `--scan`) refused because a file imports a module a
@@ -203,14 +208,35 @@ placeholder. A refused `--scan` adoption, `patch move-files` or `patch split`
 also writes every declaration it proposes into one lint-report-shaped JSON
 (`--declarations-out <path>`, by default under `.fireforge/declarations/`)
 and names the single `patch staged-dependency <holder> --add --from <file>`
-call per holding patch that discharges them all. Moving tests out of a patch
-that owns a shared manifest no longer needs one declaration typed per
-manifest line.
+call per holding patch that discharges them all, so moving tests out of a
+patch that owns a shared manifest needs no declaration typed per manifest
+line.
+
+For `patch move-files`, `patch split` and a placed `export`:
+
+- The projection of `patch move-files`, `patch split` and a placed `export`
+  lints with the queue's whole lint configuration, as the committed `lint
+--per-patch` gate does. With `patchLint.forwardRegistration: "extended"`,
+  a shared test manifest's suite entries (`["browser_*.js"]`) are projected
+  with the move and written to the `--declarations-out` report, not only its
+  `support-files` lines. A dry run that reads clean stays clean after the
+  move.
+- A refused `move-files --create` or `split` report names the patch the
+  rerun creates as the `owner` (its planned `<order>-<category>-<name>.patch`).
+- The declarations `move-files` and `split` write, and every entry of their
+  report, carry a `reason` naming the move, such as
+  `"201-ui-tests.patch → 236-ui-suites.patch by patch move-files"`. The
+  `--add --from` call the refusal prints then needs no `--reason`; an
+  entry's own reason wins over the flag.
 
 A re-export also drops a staged registration whose `creates` path no patch
 in the queue owns any more, for example after a merge deleted the file it
 registered. The dry run names the drop, and the write records it in the
-history log (`re-export-staged-prune`).
+history log (`re-export-staged-prune`). A registration whose
+`creates` file exists in engine/, or is an `--expect-new` path of the run,
+is kept and named ("kept: file exists but no patch owns it yet"): the
+manifest owner can re-export after the declaration and before the scan
+that adopts the file, in either order.
 
 An `export --order` (or `--before`/`--after`) refused on a new system
 module that no patch registers in moz.build says "register first". When the
@@ -236,13 +262,61 @@ The re-export policy gate checks the `filesAffected` the export will write,
 and only for the patch being written, so one patch's stale row cannot fail
 the other patches in the same call.
 
+### Registering files
+
+`fireforge register <path>` adds a new file's line to the build manifest
+that packages or runs it: a jar.mn, a moz.build list, a test manifest. Most
+manifests are kept in sorted order, and the entry is inserted
+alphabetically. `--after <entry>` places it after the line containing that
+substring instead, where the manifest's rule supports it. Elsewhere the
+flag is ignored with a warning, and an `--after` that matches nothing falls
+back to sorted order with a warning.
+
+An xpcshell test (`test_*.js` outside `browser/base/content/test/`) goes
+into its directory's `xpcshell.toml` as a `["test_*.js"]` section, placed
+as follows:
+
+- The new section is inserted ahead of the `#` comment lines directly above
+  the entry it precedes, never between a comment and the entry it describes.
+- `--after <entry>` places the new section after the named entry's whole
+  block, with its keys and before the next entry's comment. An exact
+  section name matches first, then a substring.
+
+```sh
+fireforge register browser/components/hominis/test/unit/test_HominisStoreQuota.js \
+  --after test_HominisStore.js
+```
+
+`--create-manifest` scaffolds a missing manifest and wires it into the
+nearest moz.build instead of refusing with "Manifest not found".
+
 ## Queue maintenance
 
 Under `fireforge patch`:
 
 - `patch compact` closes ordinal gaps, and is range-aware when
   `patchPolicy.ranges` is configured.
-- `patch reorder` moves a patch.
+- `patch reorder` moves a patch. `patch reorder --shift <n>
+--from <order> [--through <order>]` (no patch name) renumbers a run of
+  patches up by `n` in one transaction, to open room for inserts.
+  `--through` defaults to the end of the run of consecutive occupied orders
+  of `--from`'s category. Retired and reserved slots inside the run move
+  with it (a moved reservation is named, so its holder can be told). A shift
+  that would land on an order a patch or slot holds past the run is refused.
+  Under `patchPolicy.allowGaps: false` the opened orders are recorded as
+  reservations (owner `patch reorder --shift`), so the queue stays valid,
+  and the `export --order` or `split --order` that takes each one fills it.
+  The shift checks the patch policy, projects the cross-patch lint
+  (refusing only on errors the shift adds), and commits under the patch
+  lock, refusing if the plan changed while it waited for confirmation.
+  `--map-out <file>` on `reorder` (every mode) and on `split` writes the
+  committed old-to-new filename map as a JSON object, so references to the
+  renumbered patches can be rewritten from the file:
+
+  ```sh
+  fireforge patch reorder --shift 4 --from 104 --through 128 --map-out shift-map.json --yes
+  ```
+
 - `patch split <source> --files <paths...> --name <name>` carves files out of
   a patch into a new one as a single transaction, including staged-dependency
   owner rewrites, and supports `--dry-run`. `patch move-files <from> <to>
@@ -253,6 +327,23 @@ Under `fireforge patch`:
   declaration whose declaring file moved goes with it, and a declaration the
   move makes unused is dropped. The patch policy, including the gap rule, is
   checked before any lint runs.
+- `patch move-files` covers a whole split in one call:
+  - `--scan-file <path>` (repeatable) adopts a new engine file that no patch
+    owns into the destination (`<to>`, or the patch `--create` makes) in
+    the same transaction. Both bodies are linted as the transaction leaves
+    them, so the source is never judged on a body grown by an adoption the
+    move would shrink again. An owned or missing path is refused.
+  - `--retire-empty` lets a move into an existing patch take every file of
+    the source: the declarations whose `owner` is the source re-point to the
+    destination, the source's own declarations go with its files (one that
+    becomes self-owned is dropped), and the source is retired as by `patch
+retire`, its order kept as a retired slot. Without the flag, a move that
+    would empty the source is refused and names the flag.
+  - A per-patch size refusal on either side names a tier change behind it,
+    for example `Tier change: the source becomes test tier (it was general
+tier): 9634 lines against 6000.` A source that keeps only test files is
+    held to the test tier's ceiling for every line, so move its test files
+    out before its last product file.
 - `patch rename` also supports `--category` and `--order`.
 - `patch retire <name>` removes a patch like `patch delete` (same dependency
   refusal, `--dry-run` and confirmation) but keeps its order number as a
@@ -268,7 +359,7 @@ compact` renumbers through retired slots like any other gap.
   nothing owns it, so `status` would report it unmanaged. Delete those files
   first, or pass `--delete-created` to remove them as part of the confirmed
   operation (under the engine lock as well). Files the patch only modifies
-  keep their edits and become unmanaged, as before.
+  keep their edits and become unmanaged.
 - `patch reserve <order> --category <c> --owner <label> [--reason <text>]`
   holds an order for a patch a session has agreed to export but has not
   exported yet. The reservation lives in `patches.json#reserved`. Like a
@@ -289,22 +380,32 @@ hash-object` and `git update-index`. A collision (two rows at one order) or
   an invalid result is refused before the index is touched. The working copy
   is never changed and nothing is committed. Name a patch the working copy
   no longer has by its HEAD filename to stage its removal, and name both
-  filenames of a renamed patch.
+  filenames of a renamed patch. Every manifest write, a
+  re-export's row update included, puts every row, changed or not, in the one
+  canonical key order that `patch stage` writes, so after a write the working
+  copy and the index do not differ on key order alone.
 - `patch staged-dependency <name> --remove` names the entries to remove by
   any of `--file`, `--specifier`/`--line`, `--creates` and `--owner`. It needs
   `--creates`, or `--file` with the matcher. `--creates` alone removes every
   declaration for that created path, which is the cleanup after a merge
   deletes it. Registration lines compare whitespace-insensitively, as the
-  lint does. A selection that matches nothing is refused with exit 8 (it used
-  to print "no staged registration matched" and exit 0), on a dry run too.
+  lint does. A selection that matches nothing is refused with exit 8, on a
+  dry run too.
 - `patch staged-dependency <name> --add --from <json-file>` adds many
   declarations in one call under one lock hold. The file is a `lint
 --per-patch --report` document (its findings' `stagedDeclarations` for
   that patch) or a JSON array of `{ file, specifier | line, creates, owner?,
 reason?, patch? }` entries; entries naming another patch are skipped, and
   `--reason` fills entries without one. Every `staged-dependency` call logs
-  only its delta (`added` / `removed`) in the history; records written
-  before 0.50.0 carry the whole `before` / `after` lists instead.
+  only its delta (`added` / `removed`) in the history. A history record may
+  carry the whole `before` / `after` lists instead.
+- `--add` (single or `--from`) on a declaration already present
+  (same file, specifier or line, creates and owner) with a different
+  `reason` replaces the reason in place, keeping the entry's position in its
+  list. The summary counts these apart from additions, as in
+  `updated the reason of 87`, and the history logs each as the old entry
+  removed and the new one added. An `--add` without a reason never clears
+  one.
 
 ### Parking a session's edits
 
@@ -332,7 +433,10 @@ resolves.
 
 `lint --per-patch --patches` accepts repeated flags, comma lists, full
 filenames or stems, bare order numbers, manifest names, category-prefixed
-slugs, and bare slugs.
+slugs, and bare slugs. A list is also split on whitespace, so
+a list held in one shell variable (`--patches "$P"` under zsh) selects every
+patch it names. A name that matches no patch is refused with that name, its
+nearest matches and the queue size, not with every patch in the queue.
 
 `lint --per-patch --max-warnings 0` is the warning-clean form for a release
 gate.
@@ -341,8 +445,8 @@ gate.
 every NOTICE row, for example `NOTICE [large-patch-lines]: 180 across 172
 patch(es), 150 of them suppressed by lintIgnore (see --report)`. On a green
 queue those rows are reviewed waivers and under-threshold measurements, and
-there can be hundreds of them. The default, `--notices full`, prints them
-as before. Errors and warnings always print in full, and the `--report`
+there can be hundreds of them. The default, `--notices full`, prints every
+row. Errors and warnings always print in full, and the `--report`
 JSON is the same in both modes.
 
 `lint --per-patch --report <path>` writes a machine-readable JSON report with
@@ -361,7 +465,7 @@ programmatic API, with the file-size helpers `isTestFile`,
 `file-too-large` measures in a patch: the JS files it creates, and never a
 modified file or a new file of another kind. The rule selects its files
 through that same function, so an audit that uses it cannot drift from the
-rule. Since 0.51.0 the API also exports the measurement the size rules
+rule. The API also exports the measurement the size rules
 themselves take, `measurePatchSize(engineDir, diff, filesAffected, config)`
 (lines, test-file lines, files and registration files under the configured
 metric), `isPatchSizeRegistrationFile(file, globs)`, the per-line
@@ -391,8 +495,8 @@ the real type. See
 [`configuration.md`](configuration.md#patchlint) for the project hooks
 (`checkJsExtraShim`, `checkJsTestFiles`, `checkJsTestShim`).
 
-For release whitespace checks, use `npm run whitespace:check`. It still
-checks source diffs while excluding the diff syntax of generated
+For release whitespace checks, use `npm run whitespace:check`. It checks
+source diffs while excluding the diff syntax of generated
 `patches/*.patch` files.
 
 ### Linting single files
@@ -515,13 +619,14 @@ On a shared engine, `--patches <list>` judges only the named patches:
 `status` keeps the files each one owns or claims (and, with `--ownership` or
 the ownership checks, the rows naming it), and `verify` keeps the findings
 that name it. Patches are named the way `lint --per-patch --patches` names
-them (filename, stem, order number, manifest name or slug). A peer's drifted
-patch then no longer turns this session's gate red. The limit is the
+them (filename, stem, order number, manifest name or slug; repeated, or
+separated by commas or whitespace). A peer's drifted
+patch then does not turn this session's gate red. The limit is the
 point: an unmanaged file belongs to no patch, so a scoped run never judges
 unexported files, this session's included. Run the unscoped gate before a
 commit that should cover them. `lint --per-patch --patches` keeps every
 queue finding that names a scoped patch, even on a file the patch no longer
-touches (a stale `staged-dependency-unused` declaration, since 0.51.0). `verify --patches` keeps findings about the
+touches (a stale `staged-dependency-unused` declaration). `verify --patches` keeps findings about the
 queue as a whole (a `patches.json` that does not parse) whatever the scope.
 
 `verify` resolves every `resource:///modules/…` and `resource://gre/modules/…`
@@ -586,7 +691,7 @@ as possibly cascading from it, since the replay continues without the
 rejected patch. Run it after the download, when HEAD is the new source. The
 header names the previous pin as "from": `firefox.version` in the
 `fireforge.json` committed at the project's HEAD, the tree the queue was
-last applied to (since 0.50.0). The patch stamps follow on their own line
+last applied to. The patch stamps follow on their own line
 (`Patch stamps: 317 at 153.0esr, 5 at 153.3.0esr`), oldest first and
 compared as versions rather than strings, because patches untouched since an
 older hop keep their older stamp. When no committed pin precedes the target

package/docs/run-logs.md

@@ -8,16 +8,15 @@
 
 ## Why the tool holds the log, not the operator
 
-A run's diagnosis used to exist in exactly one place: the terminal. The
-convenient thing to do when output is long is
+Without a log, a run's diagnosis exists in exactly one place: the terminal.
+The convenient thing to do when output is long is
 `fireforge test … 2>&1 | tail -40`, which keeps the summary, discards the
 `TEST-UNEXPECTED-FAIL` lines that say what broke, and launders the exit code
-as well. Nothing else held the output: `runMachCapture` keeps a 2 MB
+as well. Nothing else holds the output: `runMachCapture` keeps a 2 MB
 in-memory tail that dies with the process, and the shard retry loop discards
 earlier attempts outright.
 
-The operator rule ("never pipe a run") was written down three times
-downstream and broken after each writing. That is a sign it is not an
+An operator rule ("never pipe a run") gets broken, so this is not an
 operator problem. The tool is the only party that can make the log survive
 the mistake.
 
@@ -25,7 +24,7 @@ the mistake.
 
 - **Complete output, never the echo filter's collapsed form.** The artifact
   exists so that whoever is diagnosing the run can re-read it. Shortening it
-  would bring back the loss it prevents. The one transformation applied is
+  would lose what it is kept for. The one transformation applied is
   the secret-masking pass below, which changes values but never line
   structure.
 - **Secret-shaped values are masked in the file, and only in the file.** The
@@ -94,11 +93,11 @@ away. The refusal's own explanatory text is written into the log, and to
 stdout, before the verdict line seals stdout.
 
 Both halves matter. The verdict seal routes everything the CLI error boundary
-renders afterwards to stderr, so a run captured with `> file` used to keep
+renders afterwards to stderr, so a run captured with `> file` would keep
 `FIREFORGE-VERDICT: FAIL reason=preflight` and nothing else. That rendering
 also happens after the run log is closed, so the artifact the verdict's own
-`log=` key pointed at held only the pre-test build. Writing before the seal
-fixes both without giving up the contract: the reason lands on both channels,
+`log=` key points at would hold only the pre-test build. Writing before the
+seal avoids both without giving up the contract: the reason lands on both channels,
 and the verdict is still the run's last stdout line.
 
 ## Where the path is announced