mandrel 2.59.0 → 2.61.0

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;

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

@@ -1,11 +1,6 @@
 /**
- * pipeline.js — Phase 7 of the check-baselines pipeline (Story #2466).
- *
- * Orchestrates the per-kind dispatch: filter enabled kinds, fan-out via
- * `Promise.all`, aggregate exit codes through the shared helper, run
- * friction emission, and assemble the final structured report.
- *
- * Extracted from `check-baselines.js` without behavior change.
+ * check-baselines dispatch: enabled kinds in parallel, aggregated exit
+ * codes, friction emission, final report.
  *
  * @module lib/orchestration/check-baselines/phases/pipeline
  */
@@ -58,7 +53,7 @@ function dispatchPerKind({ wanted, quality, env, cwd, configPath }) {
   return Promise.all(
     wanted.map((kind) => {
       const gateBlock = quality.gates[kind];
-      const scope = resolveDispatchScope({ kind, quality, env });
+      const scope = resolveDispatchScope({ kind, env });
       return evaluateKind({ kind, gateBlock, scope, cwd, configPath, env });
     }),
   );

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

@@ -1,11 +1,6 @@
 /**
- * refresh-ack.js — the one-shot baseline refresh acknowledgment (Story #5179).
- *
- * Extracted from `evaluate.js`, where it grew from a bundle-size env flag
- * (Story #151) through a maintainability env-or-commit-tag pair (Story #4731)
- * into the kind-generic trigger (Story #4802). Story #5179 narrowed the
- * commit-tag arm from a whole-run blanket to the rows the tagged commit
- * actually refreshed, which is enough logic to own its own module.
+ * One-shot baseline refresh acknowledgment, scoped to the rows a tagged
+ * commit actually refreshed.
  *
  * @module lib/orchestration/check-baselines/phases/refresh-ack
  */
@@ -20,8 +15,8 @@ import { Logger } from '../../../Logger.js';
 import { applyTolerance } from './compare.js';
 import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
 
-/** Default refresh-tag substring when the gate omits `refreshTag`. */
-const DEFAULT_REFRESH_TAG = 'baseline-refresh:';
+/** Commit-subject substring that acknowledges a deliberate refresh. */
+const REFRESH_TAG = 'baseline-refresh:';
 
 function resolveBaselinePath(kind, gateBlock) {
   const configured =
@@ -31,34 +26,11 @@ function resolveBaselinePath(kind, gateBlock) {
   return configured ?? DEFAULT_BASELINE_PATHS[kind] ?? null;
 }
 
-function resolveRefreshTag(gateBlock) {
-  return typeof gateBlock?.refreshTag === 'string' &&
-    gateBlock.refreshTag.length
-    ? gateBlock.refreshTag
-    : DEFAULT_REFRESH_TAG;
-}
-
 /**
- * Resolve the one-shot refresh trigger for any ratcheted kind. Two paths, either
- * of which acknowledges:
- *
- *   1. Env parity: `<KIND>_REFRESH=1` (the manual override) — upper-snaked, so
- *      the two pre-existing names (`BUNDLE_SIZE_REFRESH`,
- *      `MAINTAINABILITY_REFRESH`) keep working unchanged.
- *   2. Commit tag: a commit in the compared range `<baseRef>..HEAD` whose
- *      subject contains the configured `refreshTag` AND whose diff touches that
- *      kind's baseline file. One-shot by construction — once merged, the
- *      refreshed baseline becomes the base and the tag leaves the range.
- *
- * The tag is matched as a plain substring of a conventional commit subject, so
- * commitlint stays satisfied (e.g. `chore(baselines): baseline-refresh: …`).
- *
- * The two arms are reported separately because Story #5179 scopes them
- * differently: see `applyRefreshAcknowledgment`.
- *
- * Fails closed: a kind whose baseline path is neither configured nor present in
- * `DEFAULT_BASELINE_PATHS` simply skips the commit-tag path rather than
- * throwing, leaving that arm un-acknowledged.
+ * Refresh trigger: env `<KIND>_REFRESH=1`, or a commit in `<baseRef>..HEAD`
+ * whose subject contains the tag (a substring, so commitlint still passes) and
+ * whose diff touches the kind's baseline. One-shot: after merge the tag leaves
+ * the range. A kind with no known baseline path skips the commit arm.
  *
  * @returns {{ triggered: boolean, reasons: string[], envAcknowledged: boolean,
  *   refreshCommits: { sha: string, subject: string }[], baselinePath: string | null }}
@@ -73,15 +45,14 @@ function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
   const refreshCommits = [];
   const baseRef = cmp?.baseRef ?? null;
   if (baseRef && typeof baselinePath === 'string' && baselinePath.length) {
-    const refreshTag = resolveRefreshTag(gateBlock);
     const commits = readRangeCommitsTouchingFile(baseRef, baselinePath, {
       cwd,
     });
     for (const commit of commits) {
-      if (!commit.subject.includes(refreshTag)) continue;
+      if (!commit.subject.includes(REFRESH_TAG)) continue;
       refreshCommits.push(commit);
       reasons.push(
-        `refresh commit "${commit.subject}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
+        `refresh commit "${commit.subject}" (subject contains ${JSON.stringify(REFRESH_TAG)}, touches ${baselinePath})`,
       );
     }
   }
@@ -96,20 +67,9 @@ function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
 }
 
 /**
- * Read the baseline rows as of one git ref.
- *
- * Returns `null` — never throws and never a partial row set — when the blob is
- * unreadable or unparseable at that ref. The caller treats `null` as "this
- * commit acknowledges nothing", which keeps the ratchet at full strength rather
- * than acknowledging on a guess.
- *
- * A blob that is genuinely ABSENT at the ref reads as `{ rows: [] }`, not
- * `null`. The distinction only matters for the `sha^` read below: the commit
- * that CREATES a baseline has no blob at its parent, and treating that as
- * unreadable would make the first refresh of any kind acknowledge nothing.
- * `readBaseFromGit` already draws exactly this line — `null` for git's exit
- * 128 "path does not exist in this revision", a throw for everything else — so
- * the two cases are distinguishable rather than guessed at.
+ * Baseline rows at a ref; `null` (acknowledge nothing) when unreadable. An
+ * absent blob reads as `{ rows: [] }` so a baseline-creating commit's `sha^`
+ * read still works.
  *
  * @returns {{ rows: Array<object> }|null}
  */
@@ -130,24 +90,11 @@ function readRowsAtRef(ref, baselinePath, cwd) {
 }
 
 /**
- * Which row identities did the tagged commit itself REWRITE (Story #5277)?
- *
- * This is the half Story #5179 left open. It scoped the acknowledgment to the
- * rows present in the baseline blob *at* the tagged commit — but a blob is a
- * whole-file snapshot, so it also contains every row an EARLIER, untagged
- * commit on the same branch lowered. Such a row is present at the refresh
- * commit and unchanged at head, so it classified as `ok` and was acknowledged
- * by a commit that never touched it. The observed shape: a branch lowers a
- * maintainability row while refactoring, later refreshes an unrelated CRAP row
- * with a `baseline-refresh:` commit, and the first regression is waved through.
+ * Row keys the tagged commit itself rewrote (`sha^ → sha`, no tolerance). The
+ * blob at the commit is a whole-file snapshot that also carries rows earlier
+ * untagged commits lowered; only this diff attributes a row to the commit.
  *
- * Diffing `sha^ → sha` is what makes the acknowledgment a statement about the
- * COMMIT rather than about the branch's accumulated state. No tolerance is
- * applied: any movement at all means the commit re-scored that identity, which
- * is the only question being asked here.
- *
- * @returns {Set<string>|null} null when the diff is unusable, which
- *   acknowledges nothing from this commit.
+ * @returns {Set<string>|null} null (acknowledge nothing) when unusable.
  */
 function keysTouchedByCommit({ mod, rowsAtSha, rowsAtParent }) {
   try {
@@ -165,25 +112,10 @@ function keysTouchedByCommit({ mod, rowsAtSha, rowsAtParent }) {
 }
 
 /**
- * Classify the head rows against one refresh commit's rows, using the kind's
- * own classifier and the gate's own tolerance.
- *
- * Row identity is deliberately never derived here. A kind's `keyField` names
- * the row property the kind is *about*, which is not always its compare key:
- * CRAP declares `keyField: 'path'` but keys rows as `path::method@startLine`,
- * because one file holds many methods. Reading `row[keyField]` would produce a
- * key matching no regression, silently acknowledging nothing for that kind.
- * `compare()` is the one thing that knows a kind's key, so every key here comes
- * back out of it — the same reason direction and tolerance are delegated rather
- * than reimplemented.
- *
- * That also collapses both tests into one classification:
- *
- *   - `regressions` — present in both, worse at head: post-refresh drift.
- *   - `improvements` / `unchanged` — present in both, no worse: the rows this
- *     commit vouches for.
- *   - `additions` — present at head but absent from the refresh blob, i.e.
- *     never refreshed by this commit, so deliberately in neither set.
+ * Classify head rows against a refresh commit's rows with the kind's own
+ * `compare()` and tolerance. Keys always come out of `compare()`: `keyField`
+ * is not the compare key (CRAP keys `path::method@startLine`). `ok` =
+ * no worse since refresh; `drifted` = worse; additions are in neither.
  *
  * @returns {{ ok: string[], drifted: string[] } | null} null when the
  *   classifier is unusable, which acknowledges nothing.
@@ -210,29 +142,8 @@ function classifyAgainstRefresh({ mod, headRows, refreshRows, tolerance }) {
 }
 
 /**
- * Which regression keys are acknowledgeable by the tagged commits (Story #5179)?
- *
- * The acknowledgment is a statement about what a refresh commit re-scored, so a
- * key is acknowledgeable only when the commit both covered it and recorded a
- * value the head has not since fallen below. Both tests come out of
- * `classifyAgainstRefresh` above:
- *
- *   1. **Row membership** — a key absent from the refresh blob lands in
- *      `additions`, never in `ok`. This was the larger half of the leak: a
- *      single tagged commit cleared regressions on rows in directories it never
- *      touched.
- *   2. **No post-refresh drift** — a key worse at head than the commit recorded
- *      lands in `drifted`. Drift from commits landing AFTER the refresh is what
- *      "the baseline commit must be the branch's last score-moving commit" asks
- *      for by convention and nothing enforced.
- *   3. **The commit actually rewrote it** (Story #5277) — `keysTouchedByCommit`
- *      diffs `sha^ → sha`. Tests 1 and 2 both read the blob AT the commit,
- *      which is a whole-file snapshot and therefore also carries rows an
- *      earlier untagged commit lowered; those rows passed both tests without
- *      the tagged commit having touched them.
- *
- * Fails closed at every step: an unreadable blob, a missing `compare`, or a
- * classifier that throws contributes nothing, so those regressions stand.
+ * Regression keys a tagged commit acknowledges: in its blob, not drifted worse
+ * since, and actually rewritten by that commit. Fails closed at every step.
  *
  * @returns {Set<string>}
  */
@@ -258,9 +169,7 @@ function acknowledgeableKeys({
   if (typeof mod?.compare !== 'function') return acknowledgeable;
 
   const headRows = Array.isArray(headBaseline?.rows) ? headBaseline.rows : [];
-  // `readRangeCommitsTouchingFile` returns newest-first, and a key the newest
-  // refresh already ruled on is not reopened by an older one: the newest is the
-  // state the branch is asking to be held to.
+  // Newest-first: an older refresh never reopens a key a newer one ruled on.
   const decided = new Set();
   for (const { sha } of refreshCommits) {
     const atSha = readRowsAtRef(sha, baselinePath, cwd);
@@ -313,27 +222,10 @@ function logAcknowledgment({ kind, reasons, acknowledged, kept }) {
 }
 
 /**
- * One-shot baseline refresh/acknowledge for any ratcheted kind. When triggered,
- * demote acknowledged head-vs-base regressions to `unchanged` for this run only
- * — floors still apply, so a row below its floor still breaches. The trigger is
- * read fresh every run and never persisted: post-merge the refreshed baseline is
- * the new base and the tag leaves the range, so the ratchet returns to full
- * strength automatically.
- *
- * The two trigger arms are scoped differently, deliberately:
- *
- * - **Commit tag** — scoped to the rows the tagged commits actually rewrote,
- *   per `acknowledgeableKeys`. Before Story #5179 this cleared every regression
- *   in the range, so a branch merged carrying a stale row and the ratchet ran
- *   loose on that file; the failure recurred six times. Story #5277 closed the
- *   remainder: the scoping read the blob at the tagged commit, which still
- *   carried rows an earlier untagged commit had lowered.
- * - **Env parity** (`<KIND>_REFRESH=1`) — stays whole-run. There is no commit to
- *   anchor row-scoping to, and setting the variable is an explicit, deliberate
- *   operator act rather than a signal inferred from history.
- *
- * A no-op absent a trigger, so an unacknowledged run of any kind reports its
- * regressions exactly as before.
+ * When triggered, demote acknowledged regressions to `unchanged` for this run
+ * only (floors still apply; nothing persists). The commit-tag arm is scoped to
+ * rewritten rows; the env arm stays whole-run, as an explicit operator act
+ * with no commit to anchor to.
  *
  * @returns {{ compareOutput: object, acknowledged: boolean, acknowledgedKeys: string[] }}
  */

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

@@ -1,9 +1,5 @@
 /**
- * report.js — Phase 6 of the check-baselines pipeline (Story #2466).
- *
- * Formats the structured report for stdout. Pure. Extracted verbatim from
- * `check-baselines.js`; the public `formatReport(report, format)` named
- * export is preserved on the CLI shell for test consumers.
+ * Formats the check-baselines report for stdout.
  *
  * @module lib/orchestration/check-baselines/phases/report
  */
@@ -27,18 +23,12 @@ function formatGateLine(g) {
     ? ''
     : ` [kernel drift ${g.kernelBaseline} → ${g.kernelCurrent}]`;
   const baseRef = g.baseRef ? ` [baseRef=${g.baseRef}]` : '';
-  // Story #4914 — a compare arm that never read its base reports zero
-  // regressions and zero additions, which is indistinguishable from a clean
-  // run unless the text report says so out loud.
+  // A compare that never ran would otherwise read as a clean run.
   const baseRead =
     g.baseRef && g.baseRead === false
       ? ' [baseRead=false — compare skipped]'
       : '';
-  // Story #5179 — a refresh commit acknowledges only the rows it refreshed, so
-  // the count says how much was cleared and the status ahead of it still shows
-  // FAIL when regressions outside those rows survived. `buildGateReport` always
-  // sets `acknowledgedKeys` alongside `acknowledged` from the same result
-  // object, so the array needs no guard of its own here.
+  // `acknowledgedKeys` is always set alongside `acknowledged`.
   const ack = g.acknowledged
     ? ` [ACKNOWLEDGED ${g.acknowledgedKeys.length} row(s) — this run only]`
     : '';

package/.agents/scripts/lib/orchestration/check-state.js

@@ -0,0 +1,92 @@
+// .agents/scripts/lib/orchestration/check-state.js
+/**
+ * check-state.js — the one CI check-state classifier and rerun rule; the
+ * merge wait and recovery watch keep separate sources but adapt through here
+ * so a GitHub state means the same on both sides. Pure.
+ */
+
+/** A `Map` so a key like `constructor` cannot hit a prototype member. */
+const RAW_TO_OUTCOME = new Map([
+  // Still running — the only non-terminal outcome.
+  ['', 'pending'],
+  ['pending', 'pending'],
+  ['queued', 'pending'],
+  ['in_progress', 'pending'],
+  ['requested', 'pending'],
+  ['waiting', 'pending'],
+  ['expected', 'pending'],
+  ['success', 'success'],
+  ['completed', 'success'],
+  ['pass', 'success'],
+  ['failure', 'failure'],
+  ['startup_failure', 'failure'],
+  ['error', 'failure'],
+  ['fail', 'failure'],
+  ['neutral', 'neutral'],
+  ['cancelled', 'cancelled'],
+  ['cancel', 'cancelled'],
+  ['timed_out', 'timed_out'],
+  ['action_required', 'action_required'],
+  ['stale', 'stale'],
+  ['skipped', 'skipped'],
+  ['skipping', 'skipped'],
+]);
+
+const NON_FAILING_OUTCOMES = new Set(['success', 'neutral', 'skipped']);
+
+/**
+ * Unknown → `skipped`, so a new GitHub state cannot wedge a poll loop.
+ *
+ * @param {unknown} raw
+ * @returns {string}
+ */
+function classifyCheckState(raw) {
+  const key = String(raw ?? '')
+    .trim()
+    .toLowerCase();
+  return RAW_TO_OUTCOME.get(key) ?? 'skipped';
+}
+
+/**
+ * @param {string} outcome A {@link classifyCheckState} result.
+ * @returns {'pass'|'fail'|'pending'}
+ */
+export function checkVerdict(outcome) {
+  if (outcome === 'pending') return 'pending';
+  return NON_FAILING_OUTCOMES.has(outcome) ? 'pass' : 'fail';
+}
+
+/**
+ * CheckRun (`status`/`conclusion`) or legacy StatusContext (`state`).
+ *
+ * @param {{ status?: string, conclusion?: string, state?: string }} [check]
+ * @returns {string}
+ */
+export function classifyRollupEntry(check) {
+  const conclusion = String(check?.conclusion ?? '').trim();
+  if (conclusion) return classifyCheckState(conclusion);
+  const status = String(check?.status ?? '').trim();
+  if (status && status.toUpperCase() !== 'COMPLETED') return 'pending';
+  return classifyCheckState(check?.state ?? status);
+}
+
+/**
+ * @param {{ state?: string, bucket?: string }} [entry]
+ * @returns {string}
+ */
+export function classifyRequiredCheck(entry) {
+  return classifyCheckState(entry?.state || entry?.bucket || '');
+}
+
+/**
+ * A red required check is never re-run by automation (fix on a new head)
+ * unless a `file-ci-gap.js` verdict is recorded for this head; an advisory
+ * check may be. Anything not `required: false` counts as required.
+ *
+ * @param {{ required?: boolean, allowanceRecorded?: boolean }} [check]
+ * @returns {boolean}
+ */
+export function isRerunPermitted({ required, allowanceRecorded = false } = {}) {
+  if (required === false) return true;
+  return allowanceRecorded === true;
+}