mandrel 2.59.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,87 +1,15 @@
 /**
- * lib/orchestration/ceremony-routing.js — ceremony-profile + derived-level
- * acceptance ceremony resolver.
- *
- * The sibling of `review-depth.js#resolveDepth`: it folds the operator ceremony
- * profile and the **derived** change level into a per-cluster ceremony decision
- * for the single-delivery acceptance critic — **fresh-context spawn** vs the
- * contract-identical **inline** critic. It does NOT invent a new risk score and
- * it does NOT own clustering.
- *
- * ## One derived source, two decisions (Story #4542)
- *
- * `derivedLevel` comes from `review-depth.js#deriveChangeLevel` — the same call
- * that feeds review depth — so both ceremony decisions read one observable
- * signal: does the change set touch a sensitive path registered in
- * `audit-rules.json`? Previously this consumed the planner's own risk verdict,
- * which meant a confident all-low self-assertion bought *less* independent
- * checking than authoring nothing at all. A derived level cannot be talked down.
- *
- * ## Ceremony profiles (`delivery.routing.ceremonyProfile`)
- *
- *   - `minimal`  — always `inline` (no fresh critic spawn).
- *                  Use for tiny N=1 Stories the operator trusts.
- *   - `standard` — level-routed (default). Low → inline; high or
- *                  underivable → fresh.
- *   - `strict`   — always `fresh` regardless of the derived level.
- *
- * ## The load-bearing invariant (M4-B acceptance floor — DO NOT VIOLATE)
- *
- * Risk-routing chooses fresh-vs-inline **PER CLUSTER**. It NEVER changes the
- * cluster COUNT — the caller owns clustering and hands this module a cluster
- * index. A low-risk Story still gets one verdict per cluster — just possibly
- * authored inline instead of by a fresh sub-agent. This module takes the
- * cluster index as an INPUT and returns a decision for that one cluster; it
- * has no way to add or remove clusters.
- *
- * ## One verdict-owner per cluster (Story #4723)
- *
- * The resolved decision names the cluster'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 cluster'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. This removes a redundant pass only; it never removes a
- * cluster's verdict (the M4-B floor above holds).
- *
- * ## Tier rules (per cluster, `standard` profile)
- *
- *   - `high` level       → `fresh`   (a sensitive path was touched — a
- *                                     fresh-context maker-blind spawn).
- *   - `low` level        → `inline`  (the contract-identical inline critic).
- *   - missing / unknown  → `fresh`   (fail-safe: the diff could not be
- *                                     enumerated, so there is no evidence the
- *                                     change is unremarkable; treat it as
- *                                     needing the full fresh-context ceremony,
- *                                     exactly as `resolveDepth` degrades to
- *                                     `standard` on the same signal).
- *
- * ## No sampling floor (Story #5313)
- *
- * The maker-checker sampling floor (`delivery.routing.freshCriticSampleRate`,
- * `sampledFresh`) bounded independent checking by a cluster-index stride —
- * a count, not a risk signal — and was retired with the delivery diet. The
- * standard profile now routes purely off the derived level, so the decision
- * carries no `sampled` field and `clusterIndex` is accepted only for call-site
- * compatibility (it never changes the outcome).
- *
- * Pure and total: inputs in, decision out. No I/O, no throws. `null` /
- * `undefined` / malformed inputs degrade to `fresh` + `full` ceremony.
+ * 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
- * @typedef {import('./review-depth.js').ChangeLevel} ChangeLevel
  * @typedef {(typeof CEREMONY_PROFILES)[number]} CeremonyProfile
  */
 
 /**
- * Map a resolved ceremony mode to the cluster'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}
  */
@@ -89,23 +17,31 @@ 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';
 
 /**
- * Normalize an operator/config ceremony profile. Unknown values degrade to
- * `standard` (fail toward the documented default, not toward less ceremony).
- *
+ * @type {Readonly<Record<CeremonyProfile, { mode: CeremonyMode, reason: string }>>}
+ */
+const PROFILE_DECISIONS = Object.freeze({
+  minimal: {
+    mode: 'inline',
+    reason: 'ceremonyProfile=minimal: inline self-eval (no fresh spawn)',
+  },
+  standard: {
+    mode: 'inline',
+    reason:
+      'ceremonyProfile=standard: inline self-eval authors the Story verdict',
+  },
+  strict: {
+    mode: 'fresh',
+    reason: 'ceremonyProfile=strict: fresh-context critic',
+  },
+});
+
+/**
  * @param {unknown} value
  * @returns {CeremonyProfile}
  */
@@ -116,16 +52,9 @@ function normalizeCeremonyProfile(value) {
 }
 
 /**
- * Resolve the acceptance ceremony for one cluster from the ceremony profile
- * and the derived change level. See the module header for the tier rules and
- * the untouchable cluster-count invariant.
- *
  * @param {{
- *   derivedLevel?: (ChangeLevel|string|null|undefined),
- *   clusterIndex?: (number|null|undefined),
  *   ceremonyProfile?: (CeremonyProfile|string|null|undefined),
- * }} [input] `clusterIndex` is accepted for call-site compatibility only
- *   (Story #5313 retired the sampling floor that read it).
+ * }} [input]
  * @returns {{
  *   mode: CeremonyMode,
  *   reason: string,
@@ -134,64 +63,7 @@ function normalizeCeremonyProfile(value) {
  * }}
  */
 export function resolveCeremonyForRisk(input = {}) {
-  const decision = resolveCeremonyDecision(input);
-  return { ...decision, verdictOwner: verdictOwnerForMode(decision.mode) };
-}
-
-/**
- * Internal mode/reason resolution — the tier rules. `resolveCeremonyForRisk`
- * decorates the result with the single `verdictOwner` derived from the mode
- * (Story #4723).
- *
- * @param {Parameters<typeof resolveCeremonyForRisk>[0]} [input]
- * @returns {{
- *   mode: CeremonyMode,
- *   reason: string,
- *   profile: CeremonyProfile,
- * }}
- */
-function resolveCeremonyDecision(input = {}) {
-  const derivedLevel =
-    input && typeof input === 'object' ? input.derivedLevel : undefined;
-  const profile = normalizeCeremonyProfile(
-    input && typeof input === 'object' ? input.ceremonyProfile : undefined,
-  );
-
-  if (profile === 'minimal') {
-    return {
-      mode: 'inline',
-      reason: 'ceremonyProfile=minimal: inline critic (no fresh spawn)',
-      profile,
-    };
-  }
-  if (profile === 'strict') {
-    return {
-      mode: 'fresh',
-      reason: 'ceremonyProfile=strict: fresh-context critic',
-      profile,
-    };
-  }
-
-  if (derivedLevel === 'high') {
-    return {
-      mode: 'fresh',
-      reason: 'sensitive path touched: fresh-context critic',
-      profile,
-    };
-  }
-  if (derivedLevel === 'low') {
-    return {
-      mode: 'inline',
-      reason: 'no sensitive path touched: contract-identical inline critic',
-      profile,
-    };
-  }
-  // Missing / unknown / malformed level → fail-safe fresh + full ceremony,
-  // matching how resolveDepth degrades to `standard` on the same signal.
-  return {
-    mode: 'fresh',
-    reason:
-      'change level underivable: fail-safe fresh-context critic + full ceremony',
-    profile,
-  };
+  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
  */