@hominis/fireforge 0.46.0 → 0.46.2

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

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `fireforge patch rename <name>`: relabels a patch's filename, manifest
  * `name`, and (optionally) `description` without rewriting the `.patch` file
  * body.
  *
  * Companion to `re-export --files <subset>`. Re-export shrinks the body and
  * `filesAffected` but leaves the patch's identity describing the pre-shrink
  * scope. The only alternative for that drift is `delete` + re-export, which
- * briefly removes the patch from the queue — any forward-import dependent
- * then refuses the re-export until the deleted patch's siblings are
- * rewritten.
+ * briefly removes the patch from the queue, and any forward-import
+ * dependent then refuses the re-export until the deleted patch's siblings
+ * are rewritten.
  *
  * The filename rename and the manifest mutation happen under the patch
  * directory lock so concurrent exports cannot allocate the new filename, and
@@ -54,7 +54,7 @@ function splitPatchFilename(filename) {
  * renames the `.patch` file on disk (when applicable), writes the
  * updated manifest, and appends a history entry. Filesystem rename
  * happens before the manifest save so an interrupted run never leaves
- * the manifest pointing at a missing file; a manifest-save failure
+ * the manifest pointing at a missing file. A manifest-save failure
  * rolls the filesystem rename back.
  */
 async function commitRenameUnderLock(input) {
@@ -102,7 +102,7 @@ async function commitRenameUnderLock(input) {
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
             // Staged-dependency owners on other patches reference the old
-            // filename; remap them so forward-import declarations survive the
+            // filename. Remap them so forward-import declarations survive the
             // rename instead of dangling.
             const ownerLookup = (old) => old === target.filename ? newFilename : undefined;
             fresh.patches = fresh.patches.map((p) => rewriteStagedDependencyOwners(p, ownerLookup));
@@ -182,7 +182,7 @@ function resolveRenamePlan(target, options, config) {
     if (newSlug === '') {
         throw new InvalidArgumentError('--to must contain at least one alphanumeric character after sanitisation.', 'patch rename');
     }
-    // Preserve the ordinal's zero-padding width; a wider order simply
+    // Preserve the ordinal's zero-padding width. A wider order simply
     // prints unpadded-longer.
     const newOrdinalStr = options.order !== undefined
         ? String(options.order).padStart(split.ordinalStr.length, '0')
@@ -203,7 +203,7 @@ function resolveRenamePlan(target, options, config) {
 }
 /**
  * Pre-flight refusals: order collision (with a pointer to the verb that
- * renumbers siblings — `--order` means "this exact unused sparse slot",
+ * renumbers siblings, and `--order` means "this exact unused sparse slot",
  * mirroring `export --order`), projected cross-patch lint on an order
  * change (forward imports resolve by queue position), and the
  * filename collision. The authoritative collision checks run again inside

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

@@ -41,10 +41,10 @@ export function rebuildFilenameForOrder(existing, newOrder) {
  * blocks the destination slot is renumbered, so intentional gaps left by
  * prior `patch delete` calls survive the reorder.
  *
- * Algorithm: remove target from the sorted list, then cascade: if any
- * patch sits at the destination order, bump it to order+1; if that
- * collides with the next patch, bump that one too; continue until a free
- * slot is reached. The direction is symmetric — moving a patch earlier
+ * Algorithm: remove target from the sorted list, then cascade. If any
+ * patch sits at the destination order, bump it to order+1. If that
+ * collides with the next patch, bump that one too. Continue until a free
+ * slot is reached. The direction is symmetric: moving a patch earlier
  * and moving it later both reduce to "find a free slot at destination by
  * shifting the contiguous conflicting run upward".
  */
@@ -62,7 +62,7 @@ function computeRenameMap(manifestPatches, target, destinationOrder) {
     if (clampedDest === target.order)
         return renames;
     // Build a mutable order-for-each map so cascading bumps compose. Keys are
-    // filenames; values start as current order and get rewritten as bumps
+    // filenames. Values start as current order and get rewritten as bumps
     // propagate. Only patches whose value changes end up in the rename map.
     const currentOrder = new Map();
     for (const patch of withoutTarget)
@@ -70,7 +70,7 @@ function computeRenameMap(manifestPatches, target, destinationOrder) {
     // Cascade from the destination: while any surviving patch occupies the
     // slot we want, bump it to slot+1 and advance. Patches are processed in
     // ascending order so each bump's collision (if any) is with the immediate
-    // successor in the sort — no back-tracking needed.
+    // successor in the sort, so no back-tracking is needed.
     let slot = clampedDest;
     for (const patch of withoutTarget) {
         const order = currentOrder.get(patch.filename);
@@ -109,7 +109,7 @@ export function projectReorder(base, renameMap) {
     const ownerLookup = (oldFilename) => renameMap.get(oldFilename)?.newFilename;
     const projectedEntries = base.entries.map((entry) => {
         // Project staged-dependency owner references through the rename map on
-        // every entry — owners point at *other* patches' filenames, so a
+        // every entry. Owners point at other patches' filenames, so a
         // projection that skips non-renamed entries would lint against stale
         // owners and report false forward-import regressions.
         const metadata = entry.metadata
@@ -152,7 +152,7 @@ function resolveDestination(target, manifestPatches, options) {
             throw new InvalidArgumentError(`--before anchor "${options.before}" not found.`, '--before');
         }
         // Reject self-reference. `--before <target>` resolves to the target's
-        // current order, so computeRenameMap would take its no-op branch — but
+        // current order, so computeRenameMap would take its no-op branch, but
         // that masks a user-facing typo or scripted mistake instead of
         // surfacing it. The symmetric `--after` case is worse (mutates the
         // queue), so both reject for consistency.
@@ -275,7 +275,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
         return;
     }
     // Project the reorder through cross-patch lint. Forward-import violations
-    // that are introduced *by* the reorder become hard refusals.
+    // that the reorder itself introduces become hard refusals.
     const baseCtx = await buildPatchQueueContext(paths.patches);
     const projected = projectReorder(baseCtx, renameMap);
     const projectedIssues = lintPatchQueue(projected);
@@ -317,7 +317,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
     if (!proceedAfterDecision(decision, 'Reorder cancelled'))
         return;
     // The history entry is built inside commitReorderPlan (still under the
-    // lock) from the *final* rename map, not the pre-confirmation one, so
+    // lock) from the final rename map rather than the pre-confirmation one, so
     // the destinationOrder and renames mirror what actually landed on disk.
     const buildHistoryEntry = (finalRenameMap) => {
         const finalEntries = getSortedRenameEntries(finalRenameMap);

package/dist/src/commands/patch/split-plan.d.ts

@@ -3,7 +3,7 @@
  * construction from the worktree, staged-dependency owner-rewrite
  * discovery, cross-patch lint projection, and policy-manifest projection.
  * Split out of `split.ts` to keep both files within the per-file line
- * budget; consumed only by the split command.
+ * budget. It is consumed only by the split command.
  */
 import { type ConflictReport } from '../../core/destructive.js';
 import type { PatchQueueContext } from '../../core/patch-lint-cross.js';
@@ -33,7 +33,7 @@ export interface SplitPlan {
     /**
      * Staged forward-import declarations the split introduces, keyed by the
      * importing patch's post-rename filename. These are the new forward edges
-     * from existing patches into the freshly-created patch (owner known); they
+     * from existing patches into the freshly-created patch (owner known). They
      * are injected into the projected lint so dry-run matches the real gate,
      * and persisted on commit so the real per-patch gate stays clean.
      */
@@ -82,7 +82,7 @@ export declare function projectSplitManifest(manifest: {
  */
 export declare function buildNewPatchMetadata(plan: SplitPlan, config: FireForgeConfig): PatchMetadata;
 /**
- * Renders the operator-facing summary lines for a planned split — the text
+ * Renders the operator-facing summary lines for a planned split: the text
  * shown by `--dry-run` and by the destructive-operation confirmation prompt.
  */
 export declare function buildSplitSummary(plan: SplitPlan): string[];

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

@@ -4,7 +4,7 @@
  * construction from the worktree, staged-dependency owner-rewrite
  * discovery, cross-patch lint projection, and policy-manifest projection.
  * Split out of `split.ts` to keep both files within the per-file line
- * budget; consumed only by the split command.
+ * budget. It is consumed only by the split command.
  */
 import { join } from 'node:path';
 import {} from '../../core/destructive.js';
@@ -111,11 +111,12 @@ function buildProjectedSplitEntries(baseCtx, plan) {
 /**
  * Computes the staged forward-import declarations the split introduces:
  * forward edges from existing patches into the freshly-created patch (its
- * `creates` files are the moved files; the owner is the new patch, so it is
- * known). Keyed by the importing patch's projected (post-rename) filename.
+ * `creates` files are the moved files, and the owner is the new patch, so
+ * it is known). Keyed by the importing patch's projected (post-rename)
+ * filename.
  *
  * These edges did not exist before the split (importer and imported file
- * lived in the same patch), so they have no declaration yet — without this
+ * lived in the same patch), so they have no declaration yet. Without this
  * the projected lint flags them while the real per-patch gate would resolve
  * them once declared. Auto-declaring keeps the two in lock-step and lets a
  * sound split read as sound.
@@ -233,7 +234,7 @@ export function buildNewPatchMetadata(plan, config) {
     };
 }
 /**
- * Renders the operator-facing summary lines for a planned split — the text
+ * Renders the operator-facing summary lines for a planned split: the text
  * shown by `--dry-run` and by the destructive-operation confirmation prompt.
  */
 export function buildSplitSummary(plan) {

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

@@ -1,11 +1,11 @@
 /**
- * `fireforge patch split <source> --files <p...> --name <n>` — moves files
+ * `fireforge patch split <source> --files <p...> --name <n>` moves files
  * out of an existing patch into a brand-new patch as one transaction.
  *
  * Splitting a patch whose files have inbound forward-imports otherwise
  * requires a precise manual order: re-point each staged-dependency owner at
  * a not-yet-created patch, shrink the source via
- * `re-export --files --allow-shrink`, then `export --order` — any other
+ * `re-export --files --allow-shrink`, then `export --order`. Any other
  * order refuses or needs `--force-unsafe`. Split performs the shrink, the
  * new-patch creation, and the dependent owner rewrites under one
  * patch-directory lock with rollback, validating only the final projection.

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

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch split <source> --files <p...> --name <n>` — moves files
+ * `fireforge patch split <source> --files <p...> --name <n>` moves files
  * out of an existing patch into a brand-new patch as one transaction.
  *
  * Splitting a patch whose files have inbound forward-imports otherwise
  * requires a precise manual order: re-point each staged-dependency owner at
  * a not-yet-created patch, shrink the source via
- * `re-export --files --allow-shrink`, then `export --order` — any other
+ * `re-export --files --allow-shrink`, then `export --order`. Any other
  * order refuses or needs `--force-unsafe`. Split performs the shrink, the
  * new-patch creation, and the dependent owner rewrites under one
  * patch-directory lock with rollback, validating only the final projection.
@@ -111,7 +111,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
             }, `patch split committed`);
         }
         catch (error) {
-            // Reverse-order rollback; each step warns on its own failure so the
+            // Reverse-order rollback. Each step warns on its own failure so the
             // original error stays visible.
             if (sourceRewritten) {
                 try {
@@ -160,7 +160,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
  */
 export async function patchSplitCommand(projectRoot, sourceId, options) {
     intro(options.dryRun ? 'FireForge patch split (dry run)' : 'FireForge patch split');
-    // Refuse a prompt-less run BEFORE the diff/lint work, not after it.
+    // Refuse a prompt-less run before doing the diff/lint work.
     assertConfirmationAvailable('patch split', options);
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
@@ -193,7 +193,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
             (options.order === undefined && options.before === undefined ? source.filename : undefined),
     });
     const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
-    // The filename slug pipeline strips redundant category prefixes; the
+    // The filename slug pipeline strips redundant category prefixes. The
     // manifest display name must agree with the bare-slug naming policy,
     // exactly as `export --name` already does.
     const displayName = normalizePatchDisplayName(options.name, category);

package/dist/src/commands/patch/staged-dependency-validate.d.ts

@@ -7,7 +7,7 @@ interface StagedDependencyShape {
 }
 /**
  * Validates the `--add` declaration fields against the loaded queue.
- * Throws on a clear flag mixup; warns (only) when `--owner` is
+ * Throws on a clear flag mixup. Warns (only) when `--owner` is
  * well-formed but absent from the queue, because the owner may
  * legitimately be exported moments later and renumbering rewrites owners.
  */

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

@@ -2,8 +2,8 @@
 /**
  * Shape validation for `patch staged-dependency --add`.
  *
- * `--creates`/`--file` take engine-relative FILE paths and `--owner` takes a
- * patch FILENAME. Accepting all three as arbitrary strings lets a
+ * `--creates`/`--file` take engine-relative file paths, while `--owner`
+ * takes a patch filename. Accepting all three as arbitrary strings lets a
  * `--creates <patch-name>` mixup produce a declaration nothing can ever
  * discharge, surfacing only later as a `staged-dependency-unused` warning.
  * Refusals here fire only on a clear patch-name shape (slash-free values
@@ -28,7 +28,7 @@ function refusePatchShapedPath(flag, value, role, queuePatches) {
 }
 /**
  * Validates the `--add` declaration fields against the loaded queue.
- * Throws on a clear flag mixup; warns (only) when `--owner` is
+ * Throws on a clear flag mixup. Warns (only) when `--owner` is
  * well-formed but absent from the queue, because the owner may
  * legitimately be exported moments later and renumbering rewrites owners.
  */

package/dist/src/commands/patch/staged-dependency.d.ts

@@ -1,5 +1,5 @@
 /**
- * `fireforge patch staged-dependency <name>` — edits
+ * `fireforge patch staged-dependency <name>` edits
  * PatchMetadata.stagedDependencies without rewriting the .patch body.
  */
 import { Command } from 'commander';

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch staged-dependency <name>` — edits
+ * `fireforge patch staged-dependency <name>` edits
  * PatchMetadata.stagedDependencies without rewriting the .patch body.
  */
 import { Command } from 'commander';
@@ -85,7 +85,7 @@ function requireRegistrationOptions(options) {
 /**
  * Resolves the `--remove` target for forward-imports:
  * `--file` + `--specifier` suffice when they identify at most one staged
- * entry — `--creates` is inferred from a unique match, an ambiguous match
+ * entry. `--creates` is inferred from a unique match, an ambiguous match
  * refuses with the candidate list, and no match falls through to the
  * honest "no staged forward-import matched" summary.
  */
@@ -217,7 +217,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
     const kind = kindFromOptions(options);
-    // The patch queue loads BEFORE the declaration fields resolve so
+    // The patch queue loads before the declaration fields resolve so
     // `--remove` can infer `--creates` from the target patch's staged
     // entries.
     const { paths, manifest } = await requirePatchQueue(projectRoot);
@@ -232,9 +232,9 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
         : mode === 'add'
             ? requireRegistrationOptions(options)
             : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
-    // Shape-check --add declarations against the loaded queue:
-    // a patch-name-shaped --creates/--file is refused HERE instead of
-    // surfacing later as an undischargeable staged-dependency-unused.
+    // Shape-check --add declarations against the loaded queue: a
+    // patch-name-shaped --creates/--file is refused now instead of surfacing
+    // later as an undischargeable staged-dependency-unused.
     if (mode === 'add') {
         const added = importDependency ?? registrationDependency;
         if (added !== undefined) {

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

@@ -1,9 +1,9 @@
 /**
- * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on a
+ * `fireforge patch tier <name>` sets or clears `PatchMetadata.tier` on a
  * single patch without rewriting the `.patch` file body.
  *
  * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is the
- * right tool when the patch body itself needs regenerating; this subcommand
+ * right tool when the patch body itself needs regenerating. This subcommand
  * covers the metadata-only adjustment, where the operator has discovered
  * (from a `lint --per-patch` warning, say) that the threshold-tier override
  * should be set but the patch body is already correct. Avoiding the

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

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on a
+ * `fireforge patch tier <name>` sets or clears `PatchMetadata.tier` on a
  * single patch without rewriting the `.patch` file body.
  *
  * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is the
- * right tool when the patch body itself needs regenerating; this subcommand
+ * right tool when the patch body itself needs regenerating. This subcommand
  * covers the metadata-only adjustment, where the operator has discovered
  * (from a `lint --per-patch` warning, say) that the threshold-tier override
  * should be set but the patch body is already correct. Avoiding the
@@ -35,8 +35,8 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge patch tier (dry run)' : 'FireForge patch tier');
     // Mode mutex: a single invocation either sets or clears the tier.
-    // Combining both is ambiguous — the operator's intent is not obvious
-    // and silently picking one would mask the typo.
+    // Combining both is ambiguous: the operator's intent is not obvious and
+    // silently picking one would mask the typo.
     const setting = options.tier !== undefined;
     const clearing = options.clear === true;
     if (setting && clearing) {
@@ -75,7 +75,7 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
     if (!proceedAfterDecision(decision, 'Cancelled — no changes made'))
         return;
     // Single write under the patch directory lock (delegated inside
-    // updatePatchMetadata). Setting routes through `updates`; clearing
+    // updatePatchMetadata). Setting routes through `updates`. Clearing
     // routes through `unsetFields` so TypeScript's exact optional types
     // do not have to carry an explicit `undefined` on the `tier` field.
     if (after !== undefined) {

package/dist/src/commands/patch-rename-map.d.ts

@@ -2,7 +2,7 @@
  * Structural equality for patch rename maps, shared by the placement-mode
  * export preview/commit check (`export-flow.ts`) and `patch reorder`'s
  * under-lock drift check. Both previously carried a byte-identical copy of
- * the sorted-entries comparison; one helper keeps the two commit gates from
+ * the sorted-entries comparison. One helper keeps the two commit gates from
  * drifting.
  */
 import type { PatchRenameEntry } from '../core/patch-manifest.js';

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

@@ -3,7 +3,7 @@
  * Structural equality for patch rename maps, shared by the placement-mode
  * export preview/commit check (`export-flow.ts`) and `patch reorder`'s
  * under-lock drift check. Both previously carried a byte-identical copy of
- * the sorted-entries comparison; one helper keeps the two commit gates from
+ * the sorted-entries comparison. One helper keeps the two commit gates from
  * drifting.
  */
 /**

package/dist/src/commands/pending-resolution.d.ts

@@ -3,11 +3,11 @@
  *
  * Five commands (`doctor --clear-resolution`, `resolve`, `rebase --continue`,
  * `rebase --abort`, and the rebase patch loop) had each copied the same
- * spread-then-`delete` updater. Routing the clear through `updateState` rather
- * than a load/modify/save pair is the load-bearing part: the updater runs
- * inside the state-file lock against the freshest on-disk state, so a
- * concurrent write to an unrelated key (`buildMode`, `baseCommit`) is not
- * clobbered by a stale reload. Copies of that reasoning drift; one does not.
+ * spread-then-`delete` updater. The clear routes through `updateState` instead
+ * of a load/modify/save pair so the updater runs inside the state-file lock
+ * against the freshest on-disk state: a concurrent write to an unrelated key
+ * (`buildMode`, `baseCommit`) is then not clobbered by a stale reload. Keeping
+ * it in one place stops the copies from drifting apart.
  *
  * A no-op when nothing is pending, so callers need no guard of their own.
  * @param projectRoot - Project root holding `.fireforge/state.json`.

package/dist/src/commands/pending-resolution.js

@@ -5,11 +5,11 @@ import { updateState } from '../core/config.js';
  *
  * Five commands (`doctor --clear-resolution`, `resolve`, `rebase --continue`,
  * `rebase --abort`, and the rebase patch loop) had each copied the same
- * spread-then-`delete` updater. Routing the clear through `updateState` rather
- * than a load/modify/save pair is the load-bearing part: the updater runs
- * inside the state-file lock against the freshest on-disk state, so a
- * concurrent write to an unrelated key (`buildMode`, `baseCommit`) is not
- * clobbered by a stale reload. Copies of that reasoning drift; one does not.
+ * spread-then-`delete` updater. The clear routes through `updateState` instead
+ * of a load/modify/save pair so the updater runs inside the state-file lock
+ * against the freshest on-disk state: a concurrent write to an unrelated key
+ * (`buildMode`, `baseCommit`) is then not clobbered by a stale reload. Keeping
+ * it in one place stops the copies from drifting apart.
  *
  * A no-op when nothing is pending, so callers need no guard of their own.
  * @param projectRoot - Project root holding `.fireforge/state.json`.

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

@@ -20,7 +20,7 @@ export interface AdjacentUnmanagedContext {
     approvedSeen: Set<string>;
     /**
      * Offenders collected across the loop. `files` stays the bare paths that
-     * downstream consumers already read; `anchored` carries the same entries
+     * downstream consumers already read. `anchored` carries the same entries
      * with the owned directory that made each one adjacent, so the run-level
      * refusal can name the anchor without re-deriving it.
      */
@@ -36,7 +36,7 @@ export declare function findMissingFiles(engineDir: string, files: readonly stri
  * One unmanaged file and the owned directory that made it adjacent.
  *
  * The anchor is what an unattended run could not previously recover: the
- * notice named the offending file and the patch, but not WHICH of the
+ * notice named the offending file and the patch, but not which of the
  * patch's owned locations the file sits beside, so triaging a refusal on a
  * patch that owns files in several directories meant re-deriving the
  * adjacency by hand from the manifest.
@@ -51,7 +51,7 @@ export interface AdjacentUnmanagedFile {
  * Emits the scan-less advisory for one patch: missing manifest files and
  * unmanaged files adjacent to the patch's ownership. When
  * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
- * exists, records the patch into `ctx.refusals` and returns true — the
+ * exists, records the patch into `ctx.refusals` and returns true. The
  * caller then skips the write for this patch and converts the collection
  * into one run-level non-zero refusal after the loop.
  */

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

@@ -6,12 +6,12 @@
  * brand-new file an author just created beside a patch's owned files is
  * silently left out of the refreshed body. This module detects such adjacent
  * files, filters out tool-managed paths (branding, furnace) so the notice
- * names only genuinely unmanaged candidates, and — under
- * `--refuse-adjacent-unmanaged` — lets the caller turn the notice into a
+ * names only genuinely unmanaged candidates, and, under
+ * `--refuse-adjacent-unmanaged`, lets the caller turn the notice into a
  * non-zero refusal.
  *
- * Split out of re-export.ts to keep that file inside the max-lines budget;
- * exports helpers consumed by re-export.ts, no registrar.
+ * Split out of re-export.ts to keep that file inside the max-lines budget.
+ * Exports helpers consumed by re-export.ts, no registrar.
  */
 import { dirname, join } from 'node:path';
 import { isBrandingManagedPath } from '../core/branding.js';
@@ -30,7 +30,7 @@ export async function findMissingFiles(engineDir, files) {
 }
 function isToolManagedPath(file, isNewFile, ctx) {
     // Mirrors status-classify: a generated branding path is tool-managed
-    // outright; a brand-new unowned file under the branding root is still a
+    // outright. A brand-new unowned file under the branding root is still a
     // patch candidate (the Assets.car precedent) and must stay listed.
     if (isBrandingManagedPath(file, ctx.binaryName) &&
         (!isNewFile || isGeneratedBrandingPath(file, ctx.binaryName))) {
@@ -72,8 +72,8 @@ async function findAdjacentUnmanagedFiles(args) {
 /**
  * Splits the candidates into the ones that refuse and the ones a
  * `--expect-unmanaged` carve-out admits. Approved paths are recorded as seen
- * so an unused carve-out can be reported, and are RETURNED rather than
- * dropped: an exception nobody can see is how a carve-out quietly widens.
+ * so an unused carve-out can be reported, and are returned rather than
+ * dropped, so the exception stays visible instead of quietly widening.
  */
 function partitionApproved(files, ctx) {
     const refusing = [];
@@ -97,7 +97,7 @@ function describeAnchored(entry) {
  * Emits the scan-less advisory for one patch: missing manifest files and
  * unmanaged files adjacent to the patch's ownership. When
  * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
- * exists, records the patch into `ctx.refusals` and returns true — the
+ * exists, records the patch into `ctx.refusals` and returns true. The
  * caller then skips the write for this patch and converts the collection
  * into one run-level non-zero refusal after the loop.
  */

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

@@ -7,9 +7,9 @@ export declare function loadScanFilesAssignments(manifestPath: string, manifest:
  * a dry-run changed anything it promised only to inspect. That turns a
  * "dry-run reverted a just-written export" incident into a hard, named
  * failure instead of silent data loss discovered only when a later gate
- * fails. The post-fingerprint runs whether `operation` resolves or rejects —
- * a dry-run that mutates state and THEN fails is exactly the case where a
- * rollback defect must not go unreported; a rejection with a purity
+ * fails. The post-fingerprint runs whether `operation` resolves or rejects,
+ * because a dry-run that mutates state and then fails is exactly the case
+ * where a rollback defect must not go unreported. A rejection with a purity
  * violation surfaces the violation with the original error as `cause`.
  * No-op outside dry-run.
  */

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

@@ -54,7 +54,7 @@ export async function loadScanFilesAssignments(manifestPath, manifest) {
     for (const assignment of parsed.assignments) {
         const patch = resolvePatchIdentifier(assignment.patch, manifest.patches);
         if (!patch) {
-            // Suggest, never dump.
+            // Suggest close matches instead of dumping the whole queue.
             throw new InvalidArgumentError(`--scan-files: ${formatPatchNotFoundError(assignment.patch, manifest.patches)}`, '--scan-files');
         }
         const patchFiles = filesByPatch.get(patch.filename) ?? new Set();
@@ -75,23 +75,23 @@ export async function loadScanFilesAssignments(manifestPath, manifest) {
  * Fingerprints every piece of state a `re-export --dry-run` promises not to
  * disturb: the engine's commit + working-tree status (via the same
  * generation token `fireforge test` uses) and the byte content of every
- * regular file under `patches/` — ALL of them, not just the selected
- * patches, because a dry-run of patch B can revert a just-written export of
- * patch A.
+ * regular file under `patches/`. That covers all of them, not just the
+ * selected patches, because a dry-run of patch B can revert a just-written
+ * export of patch A.
  *
- * A missing patches directory (ENOENT/ENOTDIR) fingerprints as empty — there
- * is nothing there to protect — but any other listing failure (EACCES, EIO,
+ * A missing patches directory (ENOENT/ENOTDIR) fingerprints as empty, since
+ * there is nothing there to protect. Any other listing failure (EACCES, EIO,
  * …) throws: an unreadable directory is not evidence it is empty, and
  * treating it as such lets the guard silently vouch for state it never saw.
  * The same rule covers an unmeasurable engine generation and an unreadable
- * individual patch file; a before-pass failure aborts the dry run before it
+ * individual patch file. A before-pass failure aborts the dry run before it
  * starts, since a guard that measured nothing cannot vouch for anything.
  */
 async function fingerprintDryRunState(engineDir, patchesDir) {
     const fingerprint = new Map();
     const generation = await snapshotEngineGeneration(engineDir);
     if (isUnavailableGenerationToken(generation)) {
-        // A failed probe measured nothing — hashing the failure token would let
+        // A failed probe measured nothing. Hashing the failure token would let
         // two identical failures compare "unchanged" (vouching for unmeasured
         // state) and two differing messages report a spurious violation.
         throw new GeneralError(`[dry-run] cannot fingerprint the engine working tree for the purity guard: ` +
@@ -107,9 +107,9 @@ async function fingerprintDryRunState(engineDir, patchesDir) {
             .sort();
     }
     catch (error) {
-        // No patches directory — nothing there to protect; the same condition on
-        // the post-run pass produces the same empty set, and a directory that
-        // appears mid-dry-run correctly reports as a violation. Any OTHER failure
+        // No patches directory, so nothing there to protect. The same condition
+        // on the post-run pass produces the same empty set, and a directory that
+        // appears mid-dry-run correctly reports as a violation. Any other failure
         // must not read as "empty": the guard would be vouching for state it
         // never saw.
         const code = getNodeErrorCode(error);
@@ -125,7 +125,7 @@ async function fingerprintDryRunState(engineDir, patchesDir) {
         }
         catch (error) {
             // A file that vanished between the listing and the read is omitted, so
-            // a dry run that DELETED a patch artifact reports as the violation it
+            // a dry run that deleted a patch artifact reports as the violation it
             // is (key present before, absent after) instead of hiding behind a
             // fingerprinting error. Every other failure fails closed: a constant
             // placeholder would make unreadable-before equal unreadable-after even
@@ -155,9 +155,9 @@ async function fingerprintDryRunState(engineDir, patchesDir) {
  * a dry-run changed anything it promised only to inspect. That turns a
  * "dry-run reverted a just-written export" incident into a hard, named
  * failure instead of silent data loss discovered only when a later gate
- * fails. The post-fingerprint runs whether `operation` resolves or rejects —
- * a dry-run that mutates state and THEN fails is exactly the case where a
- * rollback defect must not go unreported; a rejection with a purity
+ * fails. The post-fingerprint runs whether `operation` resolves or rejects,
+ * because a dry-run that mutates state and then fails is exactly the case
+ * where a rollback defect must not go unreported. A rejection with a purity
  * violation surfaces the violation with the original error as `cause`.
  * No-op outside dry-run.
  */
@@ -181,9 +181,9 @@ export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, ope
     }
     catch (fingerprintError) {
         // The post-run fingerprint failing must not swallow the dry run's own
-        // failure — an operation that mutated state, broke it, AND made it
+        // failure: an operation that mutated state, broke it, and made it
         // unreadable is exactly the case where both facts matter. The combined
-        // message carries both; the operation error stays the `cause`.
+        // message carries both. The operation error stays the `cause`.
         if (failed) {
             throw new GeneralError(`[dry-run] this dry run failed (${toError(operationError).message}), and its purity could ` +
                 `not be verified afterwards: ${toError(fingerprintError).message}. Inspect engine/ and ` +