mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/baselines/merge-envelopes.js

@@ -1,45 +1,12 @@
 /**
- * merge-envelopes.js — pure 3-way merge of baseline envelopes by row
- * identity (Story #5215).
+ * Pure 3-way merge of baseline envelopes by row identity. A line-based git
+ * merge either conflicts on disjoint work (the `generatedAt` line) or splices
+ * both sides into a row set no scorer produced.
  *
- * ## Why this exists
- *
- * Every baseline write stamps `generatedAt`, and the stamp sits on line 4 of
- * every envelope. Two branches that each refresh a baseline therefore always
- * differ on that line, even when they moved completely disjoint rows — so
- * git's LINE-based merge has to reconcile it. Whether it can separate that
- * hunk from the moved rows is an accident of proximity, and both outcomes
- * are bad:
- *
- *   - it cannot → a conflict on work that never actually overlapped;
- *   - it can → it splices both sides' row lines together into a row set
- *     NEITHER side ever scored. That silent one is the worse failure: the
- *     ratchet then guards a number no scorer produced.
- *
- * A baseline is not a text file. It is a set of rows keyed by identity plus
- * a rollup DERIVED from those rows, so merging it as text is a category
- * error. This module merges it as what it is.
- *
- * ## Contract
- *
- * Pure: no filesystem, no process, no clock. `assertEnvelope` is deliberately
- * NOT called here (it compiles schemas off disk on first use) — the driver
- * validates what this returns.
- *
- * Per row identity, the standard 3-way rule: the side that differs from base
- * wins; when both sides differ from base AND from each other, that identity
- * is a conflict. Absence is a value, so a row deleted on one side and
- * untouched on the other merges to deleted.
- *
- * Two invariants are load-bearing:
- *
- *   1. **The rollup is recomputed, never merged.** Merging two rollups is
- *      the same splice hazard compressed into a single number, and unlike a
- *      spliced row set it leaves no evidence. It is always derived from the
- *      merged rows via the kind's own `rollup()`.
- *   2. **Identity comes from the kind module** (`rowIdentity`), never from
- *      `keyField`. CRAP groups by file and identifies by method; keying on
- *      `keyField` would drop every method in a file but one.
+ * Per identity the side that differs from base wins; both differing is a
+ * conflict; absence is a value. The rollup is always recomputed from the
+ * merged rows, never merged. Identity comes from the kind's `rowIdentity`,
+ * never `keyField`. No I/O: the driver validates the result.
  *
  * @module lib/baselines/merge-envelopes
  */
@@ -48,22 +15,11 @@ import { deepEqual } from '../json-utils.js';
 import { KNOWN_KINDS } from './envelope.js';
 import { getKindModule } from './kernel.js';
 
-/**
- * Envelope keys that are NOT merged side-by-side: `rows` merge by identity,
- * `rollup` is recomputed from them, and `generatedAt` resolves to the later
- * of the two stamps rather than conflicting (it is metadata about when a
- * scorer ran, not a scored value — treating it as content is the whole bug).
- */
+/** Keys not merged 3-way: rows by identity, rollup derived, stamp = later. */
 const DERIVED_KEYS = Object.freeze(['rows', 'rollup', 'generatedAt']);
 
 /**
- * Identify an envelope's kind from its `$schema` reference.
- *
- * Derived from `KNOWN_KINDS` rather than pattern-matched, so a file that is
- * not a known per-kind envelope answers `null` — which is how the driver
- * knows to hand it back to git's text merge instead of guessing at a shape
- * it does not understand. `baselines/*.json` also matches several
- * non-envelope baselines (arch-cycles, cyclomatic, dead-exports, …).
+ * Kind from `$schema`, or `null` for anything not a known per-kind envelope.
  *
  * @param {unknown} envelope
  * @returns {string|null}
@@ -79,8 +35,7 @@ export function kindFromEnvelope(envelope) {
 }
 
 /**
- * The 3-way choice for one value. `undefined` means "absent on this side",
- * which makes deletion just another value rather than a special case.
+ * `undefined` = absent on that side, so deletion is just another value.
  *
  * @param {unknown} base
  * @param {unknown} ours
@@ -95,10 +50,7 @@ function choose(base, ours, theirs) {
 }
 
 /**
- * Index rows by the kind's `rowIdentity`. A duplicate identity within one
- * side is fatal rather than last-write-wins: it means the incoming file
- * already violates the identity contract, and merging it would silently
- * drop a row.
+ * A duplicate identity on one side throws; last-write-wins would drop a row.
  *
  * @param {Array<object>} rows
  * @param {(row: object) => string} rowIdentity
@@ -125,10 +77,6 @@ function indexRows(rows, rowIdentity, side) {
 }
 
 /**
- * Resolve `generatedAt` to the later of the two sides. A stamp is metadata,
- * so it never conflicts: the merged file describes a tree scored as recently
- * as the newer of its inputs.
- *
  * @param {string|undefined} ours
  * @param {string|undefined} theirs
  * @returns {string|undefined}
@@ -143,10 +91,8 @@ function laterStamp(ours, theirs) {
 }
 
 /**
- * Merge the envelope-level stamps (`$schema`, `kernelVersion`, and per-kind
- * extras like `scoringSemantics`) by the same 3-way rule as rows. A double
- * bump to different values is a genuine conflict — two branches disagreeing
- * about which scorer produced the file.
+ * 3-way merge of envelope stamps; a double bump to different values is a
+ * real conflict (two scorers).
  *
  * @param {object} base
  * @param {object} ours
@@ -180,11 +126,6 @@ function mergeStamps(base, ours, theirs) {
 }
 
 /**
- * The row half of a 3-way merge, shared by the envelope path and the plain
- * row-baseline path below. Both merge a set of rows keyed by identity against
- * a common ancestor; they differ only in where the identity comes from and in
- * what they assemble around the result.
- *
  * @param {{
  *   baseEnv: object,
  *   ours: object|null|undefined,
@@ -218,8 +159,7 @@ function mergeRowSets({ baseEnv, ours, theirs, rowIdentity }) {
         ours: o,
         theirs: t,
       });
-      // Keep the ours-side value so the row set stays well-formed; the
-      // driver renders the conflict markers around it from this record.
+      // Keep ours so the row set stays well-formed; the driver adds markers.
       if (o !== undefined) rows.push(o);
       else if (t !== undefined) rows.push(t);
       continue;
@@ -230,7 +170,8 @@ function mergeRowSets({ baseEnv, ours, theirs, rowIdentity }) {
 }
 
 /**
- * 3-way merge two baseline envelopes against their common ancestor.
+ * `base` is `null` when the file was added on both sides. `components`
+ * defaults to `[]`, matching what a refresh writes.
  *
  * @param {{
  *   base: object|null,
@@ -239,11 +180,6 @@ function mergeRowSets({ baseEnv, ours, theirs, rowIdentity }) {
  *   kind?: string,
  *   components?: Array<object>,
  * }} params
- *   - `base` — the merge ancestor; `null` (or a rowless object) when the
- *     file was added on both sides.
- *   - `components` — passed straight to the kind's `rollup()`. Defaults to
- *     `[]`, which is what `refreshBaseline` effectively uses, so a merged
- *     envelope carries the same `{'*': …}` rollup shape a refresh writes.
  * @returns {{
  *   kind: string,
  *   envelope: object,
@@ -296,14 +232,8 @@ export function mergeEnvelopes({
 }
 
 /**
- * Emit the object's keys in a declared order, then anything left over.
- *
- * The invariant this serves is "a clean driver merge stays byte-identical to
- * a regeneration": both generators below write
- * `JSON.stringify(envelope, null, 2)`, which preserves insertion order, so a
- * merged file whose keys are in a different order than the generator's is a
- * spurious diff on every subsequent refresh. Unknown keys are appended rather
- * than dropped — a merge is never the place to lose a field.
+ * Declared key order, then leftovers (never dropped), so a clean merge stays
+ * byte-identical to the generator's insertion-ordered output.
  *
  * @param {object} obj
  * @param {string[]} order
@@ -321,15 +251,9 @@ function orderKeys(obj, order) {
 }
 
 /**
- * Derive `cyclomatic`'s rollup from its merged rows — the same arithmetic
- * `cyclomatic-ceiling.js#buildCyclomaticEnvelope` applies at generation time.
- *
- * Deriving rather than merging matters more here than anywhere: the rollup is
- * three counts over the whole row set, so two branches that each add one row
- * BOTH write `filesAboveCeiling: n + 1`. A 3-way merge sees two identical
- * values and resolves them clean — to a number that is wrong by one, with no
- * conflict and no evidence. That is the silent splice this module exists to
- * refuse, compressed into a single field.
+ * Same arithmetic as `buildCyclomaticEnvelope`. Must be derived: two branches
+ * each adding a row both write `n + 1`, which a 3-way merge resolves cleanly
+ * and wrongly.
  *
  * @param {Array<object>} rows
  * @returns {{ '*': { filesAboveCeiling: number, methodsAboveCeiling: number, maxCyclomatic: number } }}
@@ -352,23 +276,8 @@ function cyclomaticRollup(rows) {
 }
 
 /**
- * Baselines that are row sets but NOT per-kind envelopes (Story #5277).
- *
- * `baselines/*.json` matches more than the eight kernel kinds. Three of the
- * extras are row sets with a real identity, and before this registry the
- * driver handed all three straight back to `git merge-file` — so `.gitattributes`
- * declared them driver-merged while they were still text-merged, with exactly
- * the two failure modes the driver replaces. `dead-exports*.json` in particular
- * is a long, uniform list of two-key objects: the shape git splices most
- * happily and least visibly.
- *
- * `rollup: null` is a genuine absence, not an omission — the dead-export
- * generator writes no rollup key at all, so deriving one would invent a field
- * the checker never reads and the generator would strip on the next refresh.
- * `cyclomatic` does carry one, and derives it (see {@link cyclomaticRollup}).
- *
- * `keyOrder` mirrors each generator's own insertion order; see
- * {@link orderKeys}.
+ * Row-set baselines that are not per-kind envelopes. `rollup: null` is real:
+ * the dead-export generator writes none. `keyOrder` mirrors each generator.
  */
 const PLAIN_BASELINE_KINDS = Object.freeze({
   cyclomatic: Object.freeze({
@@ -398,11 +307,8 @@ const PLAIN_SCHEMA_KINDS = Object.freeze({
 });
 
 /**
- * Identify a plain row baseline from its `$schema`, or `null`.
- *
- * The production dead-export pass reports as its own kind so the regenerate
- * remedy can name the right command, even though the two share a schema and
- * merge identically.
+ * The production dead-export pass reports as its own kind so the remedy
+ * names the right command.
  *
  * @param {unknown} envelope
  * @returns {string|null}
@@ -417,7 +323,6 @@ export function plainKindFromEnvelope(envelope) {
   return kind;
 }
 
-/** The merge spec for a plain kind, collapsing the two dead-export passes. */
 function plainSpec(kind) {
   return PLAIN_BASELINE_KINDS[
     kind === 'dead-exports-production' ? 'dead-exports' : kind
@@ -425,11 +330,7 @@ function plainSpec(kind) {
 }
 
 /**
- * 3-way merge a plain row baseline by row identity.
- *
- * Same contract as {@link mergeEnvelopes} — rows merge by identity, stamps
- * merge 3-way, `generatedAt` resolves to the later of the two — minus the
- * kernel protocol these kinds do not participate in.
+ * Same contract as {@link mergeEnvelopes}, without the kernel protocol.
  *
  * @param {{ base: object|null, ours: object, theirs: object, kind?: string }} params
  * @returns {{ kind: string, envelope: object, conflicts: Array<object> }}
@@ -472,7 +373,6 @@ export function mergePlainBaseline({ base, ours, theirs, kind } = {}) {
   };
 }
 
-/** Per-kind regeneration commands; anything unlisted follows the convention. */
 const REGENERATE_COMMANDS = Object.freeze({
   'dead-exports': 'npm run dead-exports:update',
   'dead-exports-production': 'npm run dead-exports:update',
@@ -480,14 +380,8 @@ const REGENERATE_COMMANDS = Object.freeze({
 });
 
 /**
- * The command that re-derives a baseline from the tree.
- *
- * A conflicted merge leaves the rollup describing a row set nobody scored:
- * the driver derives it from rows that still carry conflict markers around
- * them, and no hand-resolution of those markers updates it. Resolving the
- * rows is therefore only half the job, and the half operators skip — so the
- * driver says the other half out loud rather than leaving a plausible-looking
- * number behind.
+ * After a conflicted merge, hand-resolving rows never updates the rollup, so
+ * the driver must name the regeneration command.
  *
  * @param {string} kind
  * @returns {string}
@@ -497,18 +391,8 @@ export function baselineRegenerateRemedy(kind) {
 }
 
 /**
- * Wrap each conflicted envelope-level stamp in git conflict markers.
- *
- * Envelope conflicts used to be reported on stderr alone, and the file was
- * left holding the ours-side value with no marker in it. Git reads the
- * driver's non-zero exit as "conflicted" and leaves the path unmerged, so the
- * operator opens a file that looks cleanly merged and has to reconstruct from
- * a scrollback line which stamp disagreed. A `kernelVersion` double-bump is
- * exactly the case where the two sides mean different scorers and picking one
- * silently is wrong.
- *
- * Operates on the canonical text the merged projection already produced, so
- * every unconflicted line stays byte-identical to a clean merge.
+ * Wrap each conflicted stamp in git conflict markers so the unmerged file
+ * shows which stamp disagreed. Unconflicted lines stay byte-identical.
  *
  * @param {string} text Canonical serialization of the merged envelope.
  * @param {Array<{ identity: string, ours?: unknown, theirs?: unknown }>} conflicts

package/.agents/scripts/lib/baselines/path-canon.js

@@ -1,49 +1,9 @@
 /**
- * path-canon.js — single canonicalisation authority for every path written
- * into (or compared against) a Mandrel baseline (Story #1891, Epic #1786).
- *
- * This module is the one place baseline path canonicalisation lives. It
- * exposes three helpers tuned to two boundaries (Story #3345 folded the
- * formerly separate `canonicalize-path.js` permissive coercer in here so
- * there is a single import surface):
- *
- *   - `canonicalise(p)` — the **strict** repo-relative canonicaliser. It
- *     rejects input it considers unsafe to key a baseline by, then
- *     normalises what it accepts.
- *   - `assertCanonical(p)` — the **throw-on-reject** writer-boundary check.
- *     It runs the same rejection checks as `canonicalise` but never
- *     transforms the input.
- *   - `canonicalizeBaselinePath(p)` — the **permissive coercer** used by the
- *     refresh service. It never throws on absolute / drive-letter / UNC
- *     input; instead it transforms those shapes into a repo-relative key,
- *     because its caller funnels raw `git diff` and tool output through a
- *     single point that must always yield a canonical key.
- *
- * `canonicalise` enforces, in order:
- *
- *   1. Rejects absolute paths (Windows `C:\...` or POSIX `/...`) — baselines
- *      that key by absolute paths break the moment they're checked out on a
- *      different machine, in a worktree, or in CI.
- *   2. Rejects `..` segments — baselines must not name files outside the
- *      repo root, and the loader's signed-int comparison can otherwise be
- *      fooled by a traversal-shaped key.
- *   3. Strips a leading `.worktrees/<workspace>/` prefix so a refresh run
- *      from inside `.worktrees/story-1891/...` produces the same key as a
- *      refresh from the main checkout. This is the defensive policy that
- *      stops a future worktree-based refresh from reintroducing the
- *      maintainability worktree-prefix regression that prompted Story #1891.
- *   4. Normalises Windows backslashes to forward slashes.
- *   5. Strips a leading `./` for cosmetic stability — `./src/a.js` and
- *      `src/a.js` are the same path and should serialise to the same key.
- *
- * Both `canonicalise` and `canonicalizeBaselinePath` are **idempotent**:
- * feeding either function's output back in produces the same string. Tests
- * pin this property explicitly.
- *
- * `assertCanonical` is the throw-on-reject variant. It runs the same checks
- * but does not transform the input — used at the writer boundary to assert
- * a row's `path` has already been canonicalised by the caller (so the writer
- * never silently rewrites a row's identity).
+ * The single authority for baseline path keys: `canonicalise` (strict,
+ * rejects absolute and `..` paths), `assertCanonical` (writer-boundary check,
+ * never transforms), and `canonicalizeBaselinePath` (permissive, coerces raw
+ * tool output). All strip a leading `.worktrees/<workspace>/` so worktree and
+ * main-checkout refreshes key identically. Both transformers are idempotent.
  *
  * @module lib/baselines/path-canon
  */
@@ -51,9 +11,7 @@
 const WORKTREE_PREFIX = /^\.worktrees\/[^/\\]+[/\\]/;
 
 /**
- * Test whether `value` is a Windows or POSIX absolute path. Windows absolute
- * paths have a drive letter (`C:`) or start with a backslash-separator
- * (`\\server\share`). POSIX absolute paths start with a forward slash.
+ * Windows or POSIX absolute (including drive-relative `C:foo`).
  *
  * @param {string} value
  * @returns {boolean}
@@ -61,16 +19,12 @@ const WORKTREE_PREFIX = /^\.worktrees\/[^/\\]+[/\\]/;
 function isAbsolute(value) {
   if (value.startsWith('/')) return true;
   if (value.startsWith('\\')) return true;
-  // Drive-letter form: `C:\...` or `C:/...` or even bare `C:foo` (rare but
-  // still absolute in Windows semantics — refuse it).
   if (/^[A-Za-z]:[\\/]?/.test(value)) return true;
   return false;
 }
 
 /**
- * Test whether `value` contains a `..` segment. We tokenise on both `/` and
- * `\` so a Windows-shaped path like `src\..\evil.js` is caught before
- * normalisation rewrites the separators.
+ * Splits on both separators so `src\..\x` is caught before normalisation.
  *
  * @param {string} value
  * @returns {boolean}
@@ -81,12 +35,8 @@ function hasTraversal(value) {
 }
 
 /**
- * Canonicalise a path for use as a baseline row key.
- *
- * @param {string} input  A repo-relative path. May use `\` or `/` separators
- *                        and may carry a leading `./` or
- *                        `.worktrees/<workspace>/` prefix.
- * @returns {string}      The canonical, forward-slash, repo-relative form.
+ * @param {string} input  A repo-relative path.
+ * @returns {string}
  * @throws {TypeError}    When `input` is not a string.
  * @throws {Error}        When `input` is absolute or contains a `..` segment.
  */
@@ -110,22 +60,12 @@ export function canonicalise(input) {
     );
   }
 
-  // 1. Normalise separators first so the worktree-prefix regex sees a
-  //    forward-slash form regardless of platform.
   let working = input.replace(/\\/g, '/');
 
-  // 2. Strip `.worktrees/<workspace>/` prefix (defensive policy — see
-  //    module preamble).
   working = working.replace(WORKTREE_PREFIX, '');
 
-  // 3. Strip a leading `./` after worktree-prefix removal so
-  //    `./.worktrees/story-1/src/a.js` and `.worktrees/story-1/src/a.js`
-  //    converge.
   if (working.startsWith('./')) working = working.slice(2);
 
-  // 4. Collapse any accidental double-slashes introduced by upstream
-  //    string concat — leaves leading `/` alone since we've already
-  //    rejected absolute paths.
   working = working.replace(/\/{2,}/g, '/');
 
   if (working.length === 0) {
@@ -138,10 +78,8 @@ export function canonicalise(input) {
 }
 
 /**
- * Assert that `input` is already in canonical form. Throws on any deviation;
- * never transforms the input. Used at the writer boundary as a defensive
- * check that callers have funnelled their rows through `canonicalise` before
- * handing them to `write()`.
+ * Throw unless `input` is already canonical, so the writer never silently
+ * rewrites a row's identity.
  *
  * @param {string} input
  * @returns {void}
@@ -189,46 +127,12 @@ export function assertCanonical(input) {
 }
 
 /**
- * Permissively coerce a raw filesystem path into the POSIX, repo-relative
- * key shape used by the Unified Baseline Refresh Service (Story #2192,
- * Epic #2173). Unlike `canonicalise`, this helper never throws on absolute,
- * drive-letter, or UNC input — it transforms those shapes into a
- * repo-relative key because its caller (the refresh service) receives raw
- * paths from `git diff` and tool output and needs a single funnel that
- * always produces a canonical key.
- *
- * Rules, in order:
- *   1. Reject non-string input with `TypeError`.
- *   2. Swap every `\` for `/` so the rest of the pipeline sees a single
- *      separator style regardless of platform.
- *   3. Strip a UNC prefix (`//server/share/`) so paths surfaced by tools
- *      that resolved a network share collapse to a repo-relative key.
- *   4. Strip a Windows drive-letter prefix (`C:` / `C:/`) so paths
- *      surfaced by Windows tools collapse to the same key as the
- *      equivalent Linux path.
- *   5. Strip a single leading `/` so a path that was absolute after
- *      drive-letter stripping becomes repo-relative.
- *   6. Strip a leading `.worktrees/<workspace>/` prefix so a refresh run
- *      from inside a worktree produces the same key as a refresh from the
- *      main checkout. This MUST match the equivalent step in
- *      `canonicalise()` (Story #3695): the strict canonicaliser used by the
- *      per-kind `projectRow` strips this prefix, so the permissive coercer
- *      that builds the diff-scope `scope.files` set MUST strip it too —
- *      otherwise a scored row's path (`src/new.js`) never matches its
- *      worktree-prefixed scope entry (`.worktrees/story-1/src/new.js`) and
- *      a brand-new file's row is silently dropped from the scoped baseline.
- *   7. Strip a leading `./` for cosmetic stability.
- *   8. Collapse any `/{2,}` run to a single `/`.
- *
- * The function is **idempotent**: feeding its own output back in produces
- * the same string. Downstream consumers (the refresh service and the gate
- * reader) rely on this property so a row written on Windows compares equal
- * to the same row written on Linux.
+ * Coerce raw `git diff` / tool output into a repo-relative key; never throws
+ * on absolute, drive-letter or UNC input. Idempotent, so Windows and Linux
+ * rows compare equal.
  *
- * @param {string} input  A raw filesystem path. May use `\` or `/`
- *                        separators, may carry a Windows drive letter, may
- *                        be absolute or relative.
- * @returns {string}      The canonical, forward-slash, repo-relative key.
+ * @param {string} input  A raw filesystem path.
+ * @returns {string}
  * @throws {TypeError}    When `input` is not a string.
  */
 export function canonicalizeBaselinePath(input) {
@@ -238,41 +142,28 @@ export function canonicalizeBaselinePath(input) {
     );
   }
 
-  // 1. Normalize separators first.
   let working = input.replace(/\\/g, '/');
 
-  // 2. Strip UNC share prefix (`//server/share/...`) before generic
-  //    double-slash collapse so the share name is preserved as a regular
-  //    path segment, not eaten.
+  // Before the double-slash collapse, which would eat the UNC prefix.
   const uncMatch = working.match(/^\/\/([^/]+)\/([^/]+)(\/|$)/);
   if (uncMatch) {
     working = working.slice(uncMatch[0].length);
   }
 
-  // 3. Strip Windows drive-letter prefix (`C:` or `C:/`).
   working = working.replace(/^[A-Za-z]:\/?/, '');
 
-  // 4. Strip a single leading `/` so an absolute path becomes
-  //    repo-relative.
   if (working.startsWith('/')) {
     working = working.replace(/^\/+/, '');
   }
 
-  // 5. Strip a leading `.worktrees/<workspace>/` prefix (Story #3695) so a
-  //    worktree-rooted path collapses to the same repo-relative key the
-  //    strict `canonicalise()` produces. Without this, a scored row path and
-  //    its diff-scope `scope.files` entry diverge inside a worktree and the
-  //    scope-aware merge drops brand-new files. Only a single leading
-  //    segment is stripped — a legitimate inner `.worktrees/` directory the
-  //    user named themselves is preserved (mirrors `canonicalise`).
+  // Must match `canonicalise`, or scope entries miss their rows inside a
+  // worktree and the scoped merge drops brand-new files.
   working = working.replace(WORKTREE_PREFIX, '');
 
-  // 6. Strip a leading `./`.
   if (working.startsWith('./')) {
     working = working.slice(2);
   }
 
-  // 7. Collapse redundant separators.
   working = working.replace(/\/{2,}/g, '/');
 
   return working;

package/.agents/scripts/lib/baselines/preview-gates.js

@@ -1,20 +1,7 @@
 /**
- * preview-gates.js — `quality-preview` / `quality-watch` per-kind runners.
- *
- * Hoisted from the per-kind CLI shells (Story #1981, Task #2005) so the
- * quality-preview surface no longer depends on the to-be-deleted
- * `check-maintainability.js` and `check-crap.js` CLI scripts. Each
- * exported runner takes a parsed scope ref + an optional `--staged`
- * flag, runs the same scan → compare → report-builder pipeline the CLIs
- * used internally, and returns:
- *
- *   {
- *     exitCode,                 // 0 = pass, 1 = regression / floor break
- *     envelope,                 // the same `--json` envelope the CLI emitted
- *   }
- *
- * No I/O beyond the scan itself; no friction signals (preview is a
- * developer-facing tool, not a gate); no `process.exit`.
+ * `quality-preview` / `quality-watch` per-kind runners: scan, compare, and
+ * return `{ exitCode, envelope }` (1 = regression or floor break). No
+ * friction signals and no `process.exit`.
  */
 
 import path from 'node:path';
@@ -36,21 +23,11 @@ import {
   MAINTAINABILITY_EXCLUSIONS,
 } from './kinds/maintainability.js';
 
-/**
- * Framework default MI preview tolerance, used only when neither an explicit
- * override nor a configured `quality.maintainability.tolerance` is present.
- * Mirrors the historical preview default.
- */
 export const MI_PREVIEW_DEFAULT_TOLERANCE = 0.5;
 
 /**
- * Resolve the effective maintainability tolerance for the preview gate so it
- * agrees with the authoritative `check-baselines` gate. Precedence: an explicit
- * caller override → the configured `quality.maintainability.tolerance` (already
- * resolved to a scalar by `getQuality`) → the framework default. Previously the
- * preview hardcoded the default and ignored the configured value, so a project
- * that raised its tolerance (e.g. to 12) still saw the local pre-commit/pre-push
- * gate flag sub-tolerance drops that `check-baselines` accepted.
+ * Explicit override, then configured tolerance, then the default — so the
+ * preview agrees with `check-baselines`.
  *
  * @param {{ explicit?: number | null, configured?: number, fallback?: number }} opts
  * @returns {number}
@@ -193,8 +170,7 @@ export async function runMaintainabilityPreview({
   });
 
   const rawScores = await calculateAll(scopedFiles);
-  // Story #2467 / Task #2494: drop parse-unscorable files so they cannot
-  // surface as phantom MI=0 regressions in the preview envelope.
+  // Excluded files would surface as phantom MI=0 regressions.
   const scores = {};
   for (const [key, mi] of Object.entries(rawScores)) {
     const rel = path.isAbsolute(key) ? path.relative(cwd, key) : key;
@@ -237,13 +213,8 @@ export async function runCrapPreview({
     return { exitCode: 0, envelope: emptyCrapEnvelope({ scope, diffRef }) };
   }
 
-  // Story #4866 (AC-6): judge the loaded envelope BEFORE comparing anything
-  // against it. A baseline whose scoring semantics or transpiler coordinates
-  // predate the running scorer cannot yield a meaningful per-method verdict,
-  // and emitting regressions from it asks the operator to fix code that is
-  // not broken. Fail open — the authoritative `check-baselines` gate still
-  // gates the merge, so a permissive pre-commit hook costs no real coverage
-  // while a blocking one costs a provably defect-free commit.
+  // An incompatible baseline yields no meaningful verdict. Fail open:
+  // `check-baselines` still gates the merge.
   const incompatible = assertBaselineCompatible(baseline);
   if (incompatible) {
     return {