mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/orchestration/behind-recovery.js

@@ -1,45 +1,12 @@
 /**
- * behind-recovery.js — the one bounded `BEHIND` → `gh pr update-branch`
- * recovery decision (Story #5006).
- *
- * Two loops watch an open PR and both must fast-forward it when GitHub
- * reports `mergeStateStatus: BEHIND`:
- *
- *   - the CI-watch loop (`pr-watch.js#watchPrToTerminal`),
- *     which probes with a synchronous `gh pr view` spawn and re-enters its
- *     poll loop after each update; and
- *   - the merge wait (`single-story-close/phases/confirm-merge.js`), which
- *     probes with an async `gh` facade and simply re-reads on the next tick.
- *
- * They had two copies of the same three-way decision — *is it BEHIND, is
- * there update budget left, did the update land* — differing only in
- * incidental ordering, which is exactly the shape that drifts. This module
- * owns the decision; the callers keep their own probe source, their own
- * timing model, and their own operator-facing wording (supplied as the
- * `on*` callbacks).
- *
- * Deliberately NOT owned here: probing `mergeStateStatus`, counting the
- * budget across iterations, and deciding what a caller does next with the
- * verdict. The helper is a single bounded step, not a loop.
+ * behind-recovery.js — one bounded `BEHIND` → `gh pr update-branch` step,
+ * shared by both merge loops; callers own probing, budget and wording.
  */
 
-/**
- * The `gh pr view --json mergeStateStatus` value that licenses a recovery.
- * Module-private: both call sites reach it through {@link applyBehindUpdate},
- * so exporting it would only add a symbol the reachability ratchet scores
- * dead.
- */
 const BEHIND_MERGE_STATE = 'BEHIND';
 
 /**
- * Normalise an `updateBranch()` settlement into `{ ok, detail }`.
- *
- * Both callers' invokers signal failure differently — the merge wait's `gh`
- * facade **throws**, the watcher's `spawnSync` port **resolves** a non-zero
- * status — so both shapes are accepted: a throw is a failure, and so is a
- * resolved object carrying `ok === false`. Anything else resolved (including
- * `undefined`) is a success, which is what a facade that only throws on
- * failure returns.
+ * Failure is a throw or a resolved `{ ok: false }`; anything else succeeds.
  *
  * @param {() => Promise<unknown>} updateBranch
  * @returns {Promise<{ ok: boolean, detail: string }>}
@@ -57,22 +24,14 @@ async function settleUpdate(updateBranch) {
 }
 
 /**
- * Apply at most one bounded `gh pr update-branch` to a PR that is BEHIND its
- * base.
- *
- * The order of the two guards is load-bearing: **not-BEHIND is checked
- * first**, so the budget-spent callback fires only for a PR that actually
- * wanted an update. Reversing them would announce an exhausted budget on
- * every poll of a perfectly up-to-date PR.
+ * Not-BEHIND is checked before the budget so an up-to-date PR never reports
+ * an exhausted budget; an unreadable probe never licenses a write.
  *
  * @param {object} args
- * @param {string|undefined|null} args.mergeStateStatus  As probed by the
- *   caller. Anything other than `BEHIND` (including a degraded/unknown probe)
- *   is a no-op — an unreadable merge state must never license a write.
- * @param {number} [args.updatesUsed=0]   Updates already applied this wait.
- * @param {number} [args.maxUpdates=0]    Hard cap on updates per wait.
- * @param {() => Promise<unknown>} args.updateBranch  Invoker that issues the
- *   fast-forward. See {@link settleUpdate} for the accepted settlements.
+ * @param {string|undefined|null} args.mergeStateStatus
+ * @param {number} [args.updatesUsed=0]
+ * @param {number} [args.maxUpdates=0]
+ * @param {() => Promise<unknown>} args.updateBranch
  * @param {(args: { maxUpdates: number }) => void} [args.onBudgetSpent]
  * @param {(args: { updatesUsed: number, maxUpdates: number }) => void} [args.onUpdated]
  * @param {(detail: string) => void} [args.onUpdateFailed]
@@ -81,11 +40,7 @@ async function settleUpdate(updateBranch) {
  *   updated: boolean,
  *   outcome: 'not-behind'|'budget-spent'|'updated'|'update-failed',
  * }>}
- *   `attempted` is true whenever the invoker ran — a failed update still
- *   counts as an attempt (the merge wait treats it as a consumed tick and
- *   re-reads the real state next poll). `updated` is true only when the
- *   fast-forward actually landed, which is the signal a caller needs before
- *   invalidating a terminal check outcome and re-polling.
+ *   `updated` means terminal check outcomes must be re-polled.
  */
 export async function applyBehindUpdate({
   mergeStateStatus,

package/.agents/scripts/lib/orchestration/ceremony-routing.js

@@ -1,53 +1,8 @@
 /**
- * lib/orchestration/ceremony-routing.js — ceremony-profile acceptance
- * ceremony resolver.
- *
- * The sibling of `review-depth.js#resolveDepth`: it folds the operator
- * ceremony profile into a per-Story ceremony decision for the acceptance
- * verdict — **fresh-context spawn** vs the contract-identical **inline**
- * self-eval. It does NOT invent a risk score, and it no longer routes off
- * anything the diff says.
- *
- * ## The profile is the whole decision (Story #5343)
- *
- *   - `minimal`  — `inline`.
- *   - `standard` — `inline` (the **default**).
- *   - `strict`   — `fresh`.
- *
- * A frontier-model worker scoring its own `acceptance[]` items against the
- * `verify[]` output it just produced is the default the delivery diet settled
- * on: the fresh critic's isolation bought a second full-context boot per
- * Story and, measured across the run, changed no verdict the inline pass did
- * not already reach. `strict` keeps the fresh-context critic for
- * high-assurance surfaces, and is the one profile that spawns one.
- *
- * **The derived change level is not an input here (Story #5366).** It is
- * still derived and still printed by `ceremony-derive.js`, because **review
- * depth** reads it — `review-depth.js#resolveDepth` continues to resolve
- * `deep` for any sensitive class, and that is untouched. What changed with
- * #5343 is which of the two decisions the level feeds: review depth, not the
- * verdict owner. Story #5366 finished the job by removing it (and the
- * per-cluster index beside it) from this function's signature: a decision
- * function that accepts what it ignores reads, to every caller and every
- * reviewer, as though the input still mattered. An unenumerable diff is
- * therefore not a fail-safe escalation here at all; it escalates review
- * depth instead, where the evidence it withholds actually matters.
- *
- * ## One verdict-owner per Story (Story #4723, narrowed by #5343)
- *
- * The resolved decision names the Story's **single verdict owner** via
- * `verdictOwner`: `'fresh-critic'` when the mode is `fresh`,
- * `'inline-self-eval'` when the mode is `inline`. Exactly one pass authors
- * the Story's verdict — the fresh maker-blind critic OR the
- * contract-identical inline self-eval, never both, and never an additional
- * pre-pass self-assessment before the owner runs. `acceptance-eval.js` is
- * the deterministic SCORER of that one authored verdict (schema validation,
- * round cap, proceed/redraft/block) — it is not a third pass over the
- * criteria. The verdict is **one file per Story**, scored in one gate call;
- * the cluster protocol that used to split it was retired with #5343.
- *
- * Pure and total: inputs in, decision out. No I/O, no throws. `null` /
- * `undefined` / malformed inputs degrade to the default profile.
+ * lib/orchestration/ceremony-routing.js — the acceptance verdict owner from
+ * the ceremony profile alone: `strict` → fresh critic, else inline self-eval.
+ * The change level is deliberately not an input (it feeds review depth).
+ * Exactly one pass authors the verdict. Pure and total.
  *
  * @typedef {'fresh'|'inline'} CeremonyMode
  * @typedef {'fresh-critic'|'inline-self-eval'} VerdictOwner
@@ -55,10 +10,6 @@
  */
 
 /**
- * Map a resolved ceremony mode to the Story's single verdict owner
- * (Story #4723). Total: any non-`fresh` value maps to the inline
- * self-eval owner, mirroring how the mode itself degrades.
- *
  * @param {CeremonyMode} mode
  * @returns {VerdictOwner}
  */
@@ -66,23 +17,12 @@ export function verdictOwnerForMode(mode) {
   return mode === 'fresh' ? 'fresh-critic' : 'inline-self-eval';
 }
 
-/**
- * The ceremony-profile vocabulary — the **single** place the three profile
- * names are written. `normalizeCeremonyProfile` is its reader and the
- * `CeremonyProfile` typedef is derived from it, so adding a profile is a
- * one-line change here (Story #4926).
- *
- * @type {readonly ['minimal', 'standard', 'strict']}
- */
+/** @type {readonly ['minimal', 'standard', 'strict']} */
 const CEREMONY_PROFILES = Object.freeze(['minimal', 'standard', 'strict']);
 
-/** The profile an absent or unrecognized value degrades to. */
 const DEFAULT_CEREMONY_PROFILE = 'standard';
 
 /**
- * The one routing table: profile → mode + the reason the decision carries.
- * `strict` is the only profile that spawns a fresh critic.
- *
  * @type {Readonly<Record<CeremonyProfile, { mode: CeremonyMode, reason: string }>>}
  */
 const PROFILE_DECISIONS = Object.freeze({
@@ -102,9 +42,6 @@ const PROFILE_DECISIONS = Object.freeze({
 });
 
 /**
- * Normalize an operator/config ceremony profile. Unknown values degrade to
- * `standard` (fail toward the documented default, not toward less ceremony).
- *
  * @param {unknown} value
  * @returns {CeremonyProfile}
  */
@@ -115,10 +52,6 @@ function normalizeCeremonyProfile(value) {
 }
 
 /**
- * Resolve the acceptance ceremony for one Story from the ceremony profile —
- * its one and only input. See the module header for the profile table and why
- * the derived change level is not among them.
- *
  * @param {{
  *   ceremonyProfile?: (CeremonyProfile|string|null|undefined),
  * }} [input]
@@ -130,9 +63,6 @@ function normalizeCeremonyProfile(value) {
  * }}
  */
 export function resolveCeremonyForRisk(input = {}) {
-  // Optional chaining rather than a typeof guard: `normalizeCeremonyProfile`
-  // is already total over anything that is not one of the three names, so a
-  // non-object input degrades to `standard` through the same door.
   const profile = normalizeCeremonyProfile(input?.ceremonyProfile);
   const { mode, reason } = PROFILE_DECISIONS[profile];
   return { mode, reason, profile, verdictOwner: verdictOwnerForMode(mode) };

package/.agents/scripts/lib/orchestration/change-set.js

@@ -1,33 +1,12 @@
 /**
- * lib/orchestration/change-set.js — the **one** Story change-set enumerator
- * (Story #4593).
+ * lib/orchestration/change-set.js — the one Story change-set enumerator.
+ * Computed once and injected so ceremony, review depth and lens roster all
+ * route off the same file list.
  *
- * ## Why this exists
- *
- * A single Story delivery used to enumerate `git diff --name-only
- * <base>...<head>` three to four separate times: once for the ceremony
- * derivation in `helpers/deliver-story`, once inside `runCodeReview` (to derive
- * the review depth), once for the Story-scope local-lens roster, and once more
- * per fresh acceptance critic. Every one of those consumers must agree about
- * *what changed* — ceremony level and review depth both flow from
- * `deriveChangeLevel`, so two enumerations straddling a commit could route the
- * same Story two different ways. Computing the set once and injecting it closes
- * that window and drops the redundant git calls.
- *
- * ## Contract
- *
- * {@link computeChangeSet} is **total**: it never throws. A diff it cannot
- * enumerate (git failure, missing ref, spawn error) yields
- * `{ files: null, enumerated: false }` — the neutral "diff unknown" signal that
- * `deriveChangeLevel` / `resolveDepth` already fail safe on (`standard` depth, a
- * `fresh` critic). `null` is deliberately distinct from `[]`: an empty array is
- * the *fact* that nothing changed, whereas `null` is the *absence* of evidence,
- * and only the latter must never buy a change less checking.
- *
- * The returned `files` are trimmed, de-duplicated, and sorted, so two consumers
- * comparing the same change set compare byte-identical lists. The refs the set
- * was computed against ride along on the envelope so a downstream consumer can
- * report (or assert) its provenance rather than re-deriving it.
+ * Total: an unenumerable diff yields `{ files: null, enumerated: false }`.
+ * `null` (no evidence) is distinct from `[]` (nothing changed) — only the
+ * former must never buy less checking. `files` is trimmed, de-duplicated and
+ * sorted.
  *
  * @typedef {{
  *   baseRef: string,
@@ -42,9 +21,6 @@
 import { gitSpawn } from '../git-utils.js';
 
 /**
- * Trim, drop empties, de-duplicate, and sort raw `git diff --name-only` output.
- * Pure.
- *
  * @param {string} stdout
  * @returns {string[]}
  */
@@ -58,11 +34,6 @@ function normalizeFileList(stdout) {
 }
 
 /**
- * Compute the change set for the `baseRef...headRef` diff **once**, for every
- * consumer that needs to know what a Story touched.
- *
- * Total — never throws; see the module header for the `null` vs `[]` contract.
- *
  * @param {{
  *   baseRef: string,
  *   headRef: string,

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -1,10 +1,6 @@
 /**
- * compare.js — Phase 3 of the check-baselines pipeline (Story #2466).
- *
- * Owns the head-vs-base compare stage: scope resolution, base-baseline
- * read, per-kind classifier dispatch, and tolerance application.
- *
- * Extracted from `check-baselines.js` without behavior change.
+ * Head-vs-base compare stage of check-baselines: scope, base read, per-kind
+ * classifier, tolerance.
  *
  * @module lib/orchestration/check-baselines/phases/compare
  */
@@ -25,12 +21,9 @@ function baselineRelativePath(kind, gateBlock) {
   return configured ?? DEFAULT_BASELINE_PATHS[kind];
 }
 
-export function resolveDispatchScope({ kind, quality, env }) {
-  const cfg = quality?.gateScoping ?? {};
+export function resolveDispatchScope({ kind, env }) {
   return resolveScope({
     kind,
-    configScope: cfg.scope,
-    configRef: cfg.diffRef,
     envScope: env?.BASELINE_SCOPE,
     envRef: env?.BASELINE_REF,
   });
@@ -41,19 +34,8 @@ function emptyCompareResult(baseRef) {
 }
 
 /**
- * Story #4914 — a base read that FAILS is not a base that is ABSENT.
- *
- * `readBaseFromGit` already draws that line itself: it returns `null` only
- * for git exit 128 ("path does not exist in this revision") and throws on
- * everything else. Swallowing the throw conflated the two, so a broken read
- * silently emptied the whole head-vs-base arm — regressions AND additions —
- * while the floors arm kept the run at exit 0. A gate that fails open is
- * worse than no gate, because it is trusted.
- *
- * So the read failure fails CLOSED as `EXIT_CONFIG` (3) — "the gate could
- * not even start", the same code `assertFloorAxesExist` uses for a
- * misconfigured floor axis. `check-baselines.js#main` maps any throw out of
- * the pipeline onto that code.
+ * A failed base read is not an absent base: it fails closed as `EXIT_CONFIG`
+ * rather than silently emptying the compare arm to a trusted exit 0.
  */
 function buildBaseReadError({ kind, ref, file, cause }) {
   const detail = cause?.message ?? String(cause);
@@ -83,14 +65,7 @@ function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
   try {
     return JSON.parse(raw);
   } catch (cause) {
-    // Story #5277 — the same distinction one line above, applied to the
-    // second way a base read fails. `null` here means "no baseline at the base
-    // ref", which empties the head-vs-base arm on purpose; an UNPARSEABLE base
-    // blob is a read that failed, and reporting it as "no base" made a
-    // corrupted or half-merged `baselines/*.json` on the base branch report
-    // zero regressions at exit 0. Text-merged baselines are exactly how such a
-    // blob gets onto the base branch, which is the failure this Story removes
-    // upstream — this arm is what stops it being silent when it happens anyway.
+    // An unparseable (e.g. text-merged) base blob is a failed read too.
     throw buildBaseReadError({ kind, ref: scope.ref, file: rel, cause });
   }
 }
@@ -107,21 +82,9 @@ export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
 }
 
 /**
- * Is the base baseline comparable to the head baseline (Story #4775)?
- *
- * A kind can change its SCORING SEMANTICS — how it derives a row's metric —
- * without moving `kernelVersion`. Across that boundary the same row can carry
- * a different score for reasons that have nothing to do with the branch's
- * changes, so a head-vs-base diff manufactures phantom regressions (and can
- * hide real ones behind them).
- *
- * The head-side stamp is already a fail-closed gate: a stale HEAD baseline
- * never reaches this point. What reaches here is the opposite and legitimate
- * case — a branch that DOES carry a re-derived baseline, compared against a
- * base that predates the change. The only honest verdict is "no comparison";
- * floors still run, so a genuine ceiling breach is still caught, and once the
- * refreshed baseline is the base the ratchet returns to full strength on the
- * very next run without anything to remember to reset.
+ * Rows scored under different `scoringSemantics` are incomparable (phantom
+ * regressions), so a branch carrying a re-derived baseline skips compare
+ * against an older base; floors still run.
  */
 function baseIsComparable(headBaseline, basePayload) {
   const head = headBaseline?.scoringSemantics ?? null;

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -1,8 +1,6 @@
 /**
- * evaluate.js — Phase 4 of the check-baselines pipeline (Story #2466).
- *
- * Runs the per-kind pipeline: load → floor → compare → tolerance → report.
- * Extracted from `check-baselines.js` without behavior change.
+ * Per-kind check-baselines pipeline: load → floor → compare → tolerance →
+ * acknowledgment → report.
  *
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
@@ -19,33 +17,13 @@ import { applyFloors, flattenBreaches } from './floors.js';
 import { applyRefreshAcknowledgment } from './refresh-ack.js';
 
 /**
- * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
- * incident). The generation path already drops `ignoreGlobs`-matched files
- * before they reach `rows` (both the canonical `buildDefaultMaintainabilityScorer`
- * and the story-close `buildKindScorer`), so a freshly-generated baseline's
- * `rollup["*"]` never includes an ignored file. But the floor check trusts the
- * *stored* `rollup["*"]`: if a baseline is poisoned by some other route — a
- * stale branch's older tooling, a hand-edit, a future generation bug — an
- * ignored file's metric can still drag the global floor axis (e.g.
- * maintainability `min`) below its floor and block every downstream close.
- *
- * This recomputes the global `*` aggregate over the baseline rows that are NOT
- * matched by the gate's `ignoreGlobs`, using the kind's own canonical
- * `rollup()` aggregator, so the floor axis reflects only the files the gate is
- * meant to police. It is a **no-op for a correctly-generated baseline** (no
- * ignored file is present in `rows`, so the filtered set is identical and the
- * stored `rollup["*"]` is returned unchanged) and only affects the `*`
- * component the incident poisons; named-component rollups are left as stored.
- * The compare/regression stage is untouched — this only reshapes the floor
- * input. All three `ignoreGlobs`-configured gates (maintainability, crap,
- * duplication) are `path`-keyed, so the shared path matcher applies uniformly.
- *
- * Kept module-local (not exported): the poison-exclusion behaviour is covered
- * end-to-end through `evaluateKind` by the `check-baselines.min-floor` suite,
- * so there is no external consumer to justify widening the surface.
+ * Recompute the `*` floor rollup without `ignoreGlobs` rows, in case a
+ * baseline was poisoned by some route other than generation (which already
+ * drops them); an ignored file could otherwise breach a global floor. A no-op
+ * for a correct baseline; compare is untouched.
  *
  * @param {{ kind: string, baseline: { rollup?: object, rows?: object[] }, ignoreGlobs?: string[], cwd?: string }} args
- * @returns {object} the effective rollup to feed the floor check
+ * @returns {object}
  */
 function rollupExcludingIgnored({ kind, baseline, ignoreGlobs, cwd }) {
   const rollup = baseline?.rollup;
@@ -64,8 +42,6 @@ function rollupExcludingIgnored({ kind, baseline, ignoreGlobs, cwd }) {
     const p = row?.path;
     return typeof p !== 'string' || !isIgnoredByGlobs(p, ignoreGlobs, cwd);
   });
-  // Nothing ignored is present → the stored rollup already excludes ignored
-  // files (the correct-baseline fast path); return it untouched.
   if (kept.length === rows.length) return rollup;
   const recomputed = mod.rollup(kept);
   return { ...rollup, '*': recomputed?.['*'] ?? rollup?.['*'] };
@@ -109,17 +85,11 @@ function buildGateReport({
     additions: compareOutput.additions ?? [],
     regressionCount: compareOutput.regressions.length,
     baseRef: cmp.baseRef ?? null,
-    // Story #4914 — the compare arm's read status was internal to compare.js,
-    // which is why a dead compare arm looked byte-identical to a clean run.
-    // Surfacing it makes "the head-vs-base arm did not run" diagnosable from
-    // the JSON report alone.
+    // Without this a compare arm that never ran looks identical to a clean run.
     baseRead: cmp.baseRead === true,
     generatedAt: baseline.generatedAt,
     acknowledged: ack.acknowledged,
-    // Story #5179 — `acknowledged` is now a PARTIAL statement: a refresh commit
-    // clears only the rows it actually refreshed, so a run can acknowledge some
-    // regressions and still fail on others. Naming the acknowledged keys makes
-    // which-half-was-which readable from the JSON report without re-walking git.
+    // Acknowledgment can be partial; name which regressions it cleared.
     acknowledgedKeys: ack.acknowledgedKeys,
   };
 }
@@ -135,11 +105,8 @@ export async function evaluateKind({
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
   const baseline = headLoad.baseline;
-  // Story #4775 — scoring-semantics gate. A baseline whose rows were produced
-  // by superseded scoring semantics is structurally valid but semantically
-  // incomparable, so schema validation alone would wave it through. Fail
-  // closed on the `semantics` tag rather than compare across the boundary;
-  // the message names the exact re-baseline command.
+  // Rows from superseded scoring semantics pass schema but are incomparable;
+  // fail closed.
   const semanticsError = checkBaselineSemantics(kind, baseline);
   if (semanticsError) {
     return {

package/.agents/scripts/lib/orchestration/check-baselines/phases/floors.js

@@ -1,9 +1,5 @@
 /**
- * floors.js — Phase 2 of the check-baselines pipeline (Story #2466).
- *
- * Pure floor-comparison helpers. Extracted verbatim from `check-baselines.js`
- * so `compareToFloor`, `assertFloorAxesExist`, and `applyFloors` keep their
- * named-export contracts for the existing unit tests.
+ * Pure floor-comparison helpers for check-baselines.
  *
  * @module lib/orchestration/check-baselines/phases/floors
  */
@@ -11,11 +7,7 @@
 import { EXIT_CONFIG } from '../../../baselines/exit-codes.js';
 
 /**
- * Which way a floor axis is compared: `gte` means the measured value must be
- * at or above the floor, `lte` at or below it. Exported (Story #4902) so the
- * baseline hotspot engine reports floor headroom with the same polarity the
- * gate enforces — a second copy of this table would let the two disagree
- * about which direction is "better" for a given axis.
+ * Floor polarity per axis; the single table every consumer must share.
  *
  * @param {string} kind
  * @param {string} axis
@@ -33,10 +25,7 @@ export function axisDirection(kind, axis) {
   return 'gte';
 }
 
-/**
- * Compare a single rollup component against a single floor object. Returns
- * the array of axis violations (empty when every axis meets its floor).
- */
+/** Axis violations of one rollup component against its floor. */
 export function compareToFloor(kind, aggregate, floor) {
   const out = [];
   if (!floor || typeof floor !== 'object') return out;
@@ -52,10 +41,6 @@ export function compareToFloor(kind, aggregate, floor) {
   return out;
 }
 
-/**
- * Tiny helper to suggest the closest available axis when an operator
- * misnamed a floor axis. Substring containment is enough.
- */
 function suggestAxis(unknownAxis, availableKeys) {
   if (availableKeys.length === 0) return null;
   const target = unknownAxis.toLowerCase();
@@ -85,9 +70,8 @@ function buildAxisMismatchError({ kind, component, axis, availableKeys }) {
 }
 
 /**
- * Story #2193 / AC-6: fail closed when a configured floor axis is not
- * present in the rollup. See the original module docstring for the full
- * rationale (typo in `.agentrc.json` → exit code 3 instead of silent pass).
+ * Fail closed (exit 3) on a floor axis absent from the rollup, so a config
+ * typo never silently passes.
  */
 export function assertFloorAxesExist(kind, component, aggregate, floor) {
   if (!floor || typeof floor !== 'object') return;
@@ -119,9 +103,6 @@ function evaluateComponentFloor(kind, component, rollup, floors) {
   return { component, violations };
 }
 
-/**
- * Apply the floor policy across every component in a rollup. Pure.
- */
 export function applyFloors(kind, rollup, floors) {
   const out = [];
   for (const component of collectComponentNames(rollup, floors)) {

package/.agents/scripts/lib/orchestration/check-baselines/phases/friction.js

@@ -1,16 +1,7 @@
 /**
- * friction.js — Phase 5 of the check-baselines pipeline (Story #2466).
- *
- * Centralised friction emission. The dispatcher is the single emission
- * site: per (kind, severity) tuple, exactly one friction event with the
- * canonical payload `{tool:'check-baselines', kind, severity, file?,
- * method?, delta?, baseRef}`.
- *
- * Severities:
- *   - `floor`            — at least one floor breach.
- *   - `regression`       — at least one head-vs-base regression.
- *   - `schema`           — head baseline failed schema validation / read.
- *   - `kernel-mismatch`  — baseline kernelVersion ≠ running kernel.
+ * The single check-baselines friction emission site: exactly one event per
+ * (kind, severity), severity one of `floor | regression | schema |
+ * kernel-mismatch`.
  *
  * @module lib/orchestration/check-baselines/phases/friction
  */

package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js

@@ -1,14 +1,5 @@
 /**
- * parse-args.js — Phase 1 of the check-baselines pipeline (Story #2466).
- *
- * Owns CLI flag parsing and the canned `--help` text. Migrated in Story
- * #2989 to delegate the bulk of argv walking to
- * `parseStandardCliArgs`; the wrapper preserves the legacy parsed shape
- * (storyId / epicId are now numbers, the rest of the keys are unchanged).
- *
- * `parseArgs(argv)` is re-exported from `check-baselines.js` and exercised
- * directly by the unit tests, so the function name and signature are
- * load-bearing.
+ * check-baselines CLI flag parsing and `--help` text.
  *
  * @module lib/orchestration/check-baselines/phases/parse-args
  */
@@ -16,23 +7,19 @@
 import { parseStandardCliArgs } from '../../../cli/standard-args.js';
 
 export const KNOWN_KINDS = Object.freeze([
-  'lint',
   'coverage',
   'crap',
   'maintainability',
   'mutation',
-  'lighthouse',
   'bundle-size',
   'duplication',
 ]);
 
 export const DEFAULT_BASELINE_PATHS = Object.freeze({
-  lint: 'baselines/lint.json',
   coverage: 'baselines/coverage.json',
   crap: 'baselines/crap.json',
   maintainability: 'baselines/maintainability.json',
   mutation: 'baselines/mutation.json',
-  lighthouse: 'baselines/lighthouse.json',
   'bundle-size': 'baselines/bundle-size.json',
   duplication: 'baselines/duplication.json',
 });
@@ -55,8 +42,8 @@ Env vars:
                          re-enforces the ratchet at full strength.
 
                          Equivalent commit-tagged trigger: a commit in the
-                         compared range whose subject contains the gate's
-                         'refreshTag' (default 'baseline-refresh:') AND whose
+                         compared range whose subject contains
+                         'baseline-refresh:' AND whose
                          diff touches that kind's baseline file. One-shot by
                          construction — once merged the refreshed baseline is
                          the new base and the tag leaves the range.
@@ -81,13 +68,7 @@ export function helpReport() {
   };
 }
 
-/**
- * Comma-split + repeat-aggregate the raw `--gate` tokens collected by
- * the shared parser. The original walker accepted both
- * `--gate coverage,lint` and `--gate coverage --gate lint` and
- * concatenated the values; we replicate that here in a single pass over
- * the `string-multi` array the shared parser produces.
- */
+/** Accept both `--gate a,b` and repeated `--gate a --gate b`. */
 function flattenGateTokens(raw) {
   if (!Array.isArray(raw) || raw.length === 0) return null;
   const parts = [];
@@ -102,15 +83,6 @@ function flattenGateTokens(raw) {
 }
 
 /**
- * Parse the CLI flags. Pure — exported for tests.
- *
- * Note: the migration to `parseStandardCliArgs` (Story #2989) changes
- * `storyId` / `epicId` from string to number — both `parseTicketId`
- * (positive integer, leading `#` stripped, `null` on invalid). The
- * downstream `emitFrictionSignal` short-circuits on falsy, and
- * `signals-writer` documents `storyId` / `epicId` as `number`, so the
- * type alignment fixes a latent string-vs-number mismatch.
- *
  * @param {string[]} argv  process.argv.slice(2)
  * @returns {{
  *   configPath: string | null,
@@ -123,12 +95,8 @@ function flattenGateTokens(raw) {
  * }}
  */
 export function parseArgs(argv) {
-  // `--help` / `-h` is a side-channel: the shared parser does not (yet)
-  // surface a help flag; pre-scan and short-circuit before delegating.
+  // The shared parser has no help flag and accepts any `--format` string.
   const helpRequested = argv.some((t) => t === '--help' || t === '-h');
-  // Pre-validate `--format` so the legacy "expects json/text" message
-  // shape survives. The shared parser would accept any string for an
-  // extras `string` flag.
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] !== '--format') continue;
     const v = argv[i + 1];
@@ -151,7 +119,6 @@ export function parseArgs(argv) {
     });
   } catch (err) {
     if (err && err.code === 'UNKNOWN_FLAG') {
-      // Preserve the legacy `unknown flag "--foo"` phrasing.
       throw new Error(`unknown flag "--${err.flag}"`);
     }
     throw err;