mandrel 2.41.0 → 2.43.0

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

@@ -7,22 +7,16 @@
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
 
-import { resolveKindRefreshOverrides } from '../../../baselines/env-overrides.js';
-import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
   checkBaselineSemantics,
   checkKernelVersion,
   getKindModule,
 } from '../../../baselines/kernel.js';
 import * as reader from '../../../baselines/reader.js';
-import { Logger } from '../../../Logger.js';
 import { isIgnoredByGlobs } from '../../../maintainability-utils.js';
 import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
 import { applyFloors, flattenBreaches } from './floors.js';
-import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
-
-/** Default refresh-tag substring when the gate omits `refreshTag`. */
-const DEFAULT_REFRESH_TAG = 'baseline-refresh:';
+import { applyRefreshAcknowledgment } from './refresh-ack.js';
 
 /**
  * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
@@ -87,97 +81,6 @@ function loadHeadBaseline(kind, cwd, configPath) {
   }
 }
 
-/**
- * Resolve the one-shot refresh trigger for any ratcheted kind (Story #4802,
- * generalizing Story #151's bundle-size env flag and Story #4731's
- * maintainability env-or-commit-tag pair). 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: …`).
- *
- * 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 the run un-acknowledged.
- *
- * @returns {{ triggered: boolean, reasons: string[] }}
- */
-function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
-  const reasons = [];
-  const { acknowledged: envAck, overrides } = resolveKindRefreshOverrides(
-    kind,
-    env,
-  );
-  if (envAck) reasons.push(...overrides);
-
-  const baseRef = cmp?.baseRef ?? null;
-  if (baseRef) {
-    const refreshTag =
-      typeof gateBlock?.refreshTag === 'string' && gateBlock.refreshTag.length
-        ? gateBlock.refreshTag
-        : DEFAULT_REFRESH_TAG;
-    const baselinePath =
-      typeof gateBlock?.baselinePath === 'string' &&
-      gateBlock.baselinePath.length
-        ? gateBlock.baselinePath
-        : DEFAULT_BASELINE_PATHS[kind];
-    if (typeof baselinePath === 'string' && baselinePath.length) {
-      const subjects = readRangeSubjectsTouchingFile(baseRef, baselinePath, {
-        cwd,
-      });
-      const match = subjects.find((s) => s.includes(refreshTag));
-      if (match) {
-        reasons.push(
-          `refresh commit "${match}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
-        );
-      }
-    }
-  }
-
-  return { triggered: reasons.length > 0, reasons };
-}
-
-/**
- * One-shot baseline refresh/acknowledge for any ratcheted kind (Story #4802).
- * When triggered (env flag OR a `baseline-refresh:`-tagged range commit
- * touching that kind's baseline), demote every head-vs-base regression 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.
- *
- * A no-op absent a trigger, so an unacknowledged run of any kind reports its
- * regressions exactly as before.
- */
-function applyRefreshAcknowledgment(kind, compareOutput, ctx) {
-  const { triggered, reasons } = resolveRefreshTrigger({ ...ctx, kind });
-  if (!triggered || compareOutput.regressions.length === 0) {
-    return { compareOutput, acknowledged: false };
-  }
-  Logger.warn(
-    `[${kind}] ⚠ ${reasons.join('; ')} — ` +
-      `${compareOutput.regressions.length} regression(s) acknowledged for this run only; ` +
-      'floors still enforced. This does not persist: once the refresh is the ' +
-      'new base the ratchet re-enforces at full strength.',
-  );
-  return {
-    acknowledged: true,
-    compareOutput: {
-      ...compareOutput,
-      regressions: [],
-      unchanged: [...compareOutput.unchanged, ...compareOutput.regressions],
-    },
-  };
-}
-
 function buildGateReport({
   kind,
   gateBlock,
@@ -186,7 +89,7 @@ function buildGateReport({
   breaches,
   compareOutput,
   cmp,
-  acknowledged,
+  ack,
 }) {
   const kernel = checkKernelVersion(kind, baseline.kernelVersion);
   return {
@@ -212,7 +115,12 @@ function buildGateReport({
     // the JSON report alone.
     baseRead: cmp.baseRead === true,
     generatedAt: baseline.generatedAt,
-    acknowledged,
+    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.
+    acknowledgedKeys: ack.acknowledgedKeys,
   };
 }
 
@@ -258,17 +166,16 @@ export async function evaluateKind({
     cmp,
     cwd,
     env,
+    headBaseline: baseline,
   });
-  const compareOutput = ack.compareOutput;
-  const acknowledged = ack.acknowledged;
   return buildGateReport({
     kind,
     gateBlock,
     baseline,
     findings,
     breaches,
-    compareOutput,
+    compareOutput: ack.compareOutput,
     cmp,
-    acknowledged,
+    ack,
   });
 }

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

@@ -0,0 +1,320 @@
+/**
+ * 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.
+ *
+ * @module lib/orchestration/check-baselines/phases/refresh-ack
+ */
+
+import { resolveKindRefreshOverrides } from '../../../baselines/env-overrides.js';
+import {
+  readBaseFromGit,
+  readRangeCommitsTouchingFile,
+} from '../../../baselines/git-base.js';
+import { getKindModule } from '../../../baselines/kernel.js';
+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:';
+
+function resolveBaselinePath(kind, gateBlock) {
+  const configured =
+    typeof gateBlock?.baselinePath === 'string' && gateBlock.baselinePath.length
+      ? gateBlock.baselinePath
+      : null;
+  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.
+ *
+ * @returns {{ triggered: boolean, reasons: string[], envAcknowledged: boolean,
+ *   refreshCommits: { sha: string, subject: string }[], baselinePath: string | null }}
+ */
+function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
+  const reasons = [];
+  const { acknowledged: envAcknowledged, overrides } =
+    resolveKindRefreshOverrides(kind, env);
+  if (envAcknowledged) reasons.push(...overrides);
+
+  const baselinePath = resolveBaselinePath(kind, gateBlock);
+  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;
+      refreshCommits.push(commit);
+      reasons.push(
+        `refresh commit "${commit.subject}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
+      );
+    }
+  }
+
+  return {
+    triggered: reasons.length > 0,
+    reasons,
+    envAcknowledged,
+    refreshCommits,
+    baselinePath,
+  };
+}
+
+/**
+ * Read the baseline rows as of one refresh commit. Returns `null` — never
+ * throws and never a partial row set — when the blob is absent, unreadable or
+ * unparseable at that SHA. The caller treats `null` as "this commit
+ * acknowledges nothing", which keeps the ratchet at full strength rather than
+ * acknowledging on a guess.
+ */
+function readRowsAtCommit(sha, baselinePath, cwd) {
+  let raw;
+  try {
+    raw = readBaseFromGit(sha, baselinePath, { cwd });
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  try {
+    const payload = JSON.parse(raw);
+    return Array.isArray(payload?.rows) ? payload.rows : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @returns {{ ok: string[], drifted: string[] } | null} null when the
+ *   classifier is unusable, which acknowledges nothing.
+ */
+function classifyAgainstRefresh({ mod, headRows, refreshRows, tolerance }) {
+  try {
+    const result = mod.compare({ rows: headRows }, { rows: refreshRows });
+    const tolerated = applyTolerance(
+      {
+        regressions: result?.regressions ?? [],
+        improvements: result?.improvements ?? [],
+        unchanged: result?.unchanged ?? [],
+        additions: result?.additions ?? [],
+      },
+      tolerance ?? null,
+    );
+    return {
+      ok: [...tolerated.improvements, ...tolerated.unchanged].map((r) => r.key),
+      drifted: tolerated.regressions.map((r) => r.key),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ *
+ * Fails closed at every step: an unreadable blob, a missing `compare`, or a
+ * classifier that throws contributes nothing, so those regressions stand.
+ *
+ * @returns {Set<string>}
+ */
+function acknowledgeableKeys({
+  kind,
+  headBaseline,
+  refreshCommits,
+  baselinePath,
+  cwd,
+  tolerance,
+}) {
+  const acknowledgeable = new Set();
+  if (refreshCommits.length === 0) return acknowledgeable;
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0)
+    return acknowledgeable;
+
+  let mod;
+  try {
+    mod = getKindModule(kind);
+  } catch {
+    return acknowledgeable;
+  }
+  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.
+  const decided = new Set();
+  for (const { sha } of refreshCommits) {
+    const refreshRows = readRowsAtCommit(sha, baselinePath, cwd);
+    if (refreshRows === null) continue;
+    const verdict = classifyAgainstRefresh({
+      mod,
+      headRows,
+      refreshRows,
+      tolerance,
+    });
+    if (verdict === null) continue;
+    for (const key of verdict.ok) {
+      if (decided.has(key)) continue;
+      decided.add(key);
+      acknowledgeable.add(key);
+    }
+    for (const key of verdict.drifted) decided.add(key);
+  }
+  return acknowledgeable;
+}
+
+function partitionRegressions(regressions, isAcknowledgeable) {
+  const acknowledged = [];
+  const kept = [];
+  for (const reg of regressions) {
+    if (isAcknowledgeable(reg)) acknowledged.push(reg);
+    else kept.push(reg);
+  }
+  return { acknowledged, kept };
+}
+
+function logAcknowledgment({ kind, reasons, acknowledged, kept }) {
+  const held =
+    kept.length > 0
+      ? `${kept.length} regression(s) NOT acknowledged (outside the refreshed rows, or drifted further after the refresh) and still fail the gate; `
+      : '';
+  Logger.warn(
+    `[${kind}] ⚠ ${reasons.join('; ')} — ` +
+      `${acknowledged.length} regression(s) acknowledged for this run only; ` +
+      `${held}floors still enforced. This does not persist: once the refresh is ` +
+      'the new base the ratchet re-enforces at full strength.',
+  );
+}
+
+/**
+ * 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 refreshed,
+ *   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.
+ * - **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.
+ *
+ * @returns {{ compareOutput: object, acknowledged: boolean, acknowledgedKeys: string[] }}
+ */
+export function applyRefreshAcknowledgment(kind, compareOutput, ctx) {
+  const trigger = resolveRefreshTrigger({ ...ctx, kind });
+  if (!trigger.triggered || compareOutput.regressions.length === 0) {
+    return { compareOutput, acknowledged: false, acknowledgedKeys: [] };
+  }
+
+  let isAcknowledgeable;
+  if (trigger.envAcknowledged) {
+    isAcknowledgeable = () => true;
+  } else {
+    const keys = acknowledgeableKeys({
+      kind,
+      headBaseline: ctx.headBaseline,
+      refreshCommits: trigger.refreshCommits,
+      baselinePath: trigger.baselinePath,
+      cwd: ctx.cwd,
+      tolerance: ctx.gateBlock?.tolerance ?? null,
+    });
+    isAcknowledgeable = (reg) => keys.has(reg.key);
+  }
+
+  const { acknowledged, kept } = partitionRegressions(
+    compareOutput.regressions,
+    isAcknowledgeable,
+  );
+  if (acknowledged.length === 0) {
+    return { compareOutput, acknowledged: false, acknowledgedKeys: [] };
+  }
+
+  logAcknowledgment({ kind, reasons: trigger.reasons, acknowledged, kept });
+
+  return {
+    acknowledged: true,
+    acknowledgedKeys: acknowledged.map((reg) => reg.key),
+    compareOutput: {
+      ...compareOutput,
+      regressions: kept,
+      unchanged: [...compareOutput.unchanged, ...acknowledged],
+    },
+  };
+}

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

@@ -34,7 +34,14 @@ function formatGateLine(g) {
     g.baseRef && g.baseRead === false
       ? ' [baseRead=false — compare skipped]'
       : '';
-  const ack = g.acknowledged ? ' [ACKNOWLEDGED — this run only]' : '';
+  // 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.
+  const ack = g.acknowledged
+    ? ` [ACKNOWLEDGED ${g.acknowledgedKeys.length} row(s) — this run only]`
+    : '';
   return `  - ${g.kind}: ${status}${drift}${baseRef}${baseRead}${ack}`;
 }
 

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -912,6 +912,10 @@ async function gatherEnvelopeInputs({
             epic: { id: 0, title: epicTitle, body: seed },
             github: config.github ?? null,
             cwd,
+            // Story #5182 — the memory-hygiene advisory's two thresholds.
+            // They live on `planning`, not the `project` block `settings`
+            // carries, so they ride the opts bag rather than that legacy one.
+            memoryPool: config.planning?.memoryPool ?? null,
           },
         ),
       () =>

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -165,7 +165,15 @@ export async function buildAuthoringContext(
       () => buildPlanningDocsContext({ seedIssueId: epic.id, settings, cwd }),
       () => verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT }),
       () => scanBddScenariosBestEffort(),
-      () => buildMemoryPoolAdvisory({ cwd: PROJECT_ROOT }),
+      () =>
+        buildMemoryPoolAdvisory({
+          cwd: PROJECT_ROOT,
+          // Story #5182 — `planning.memoryPool` thresholds. Spread so an
+          // unset block, or a block setting only one key, leaves the other
+          // on its framework default rather than passing `undefined` in as
+          // a value the builder would have to re-defaults itself.
+          ...(opts.memoryPool ?? {}),
+        }),
       () =>
         fetchPriorFeedback({
           owner: githubCfg?.owner,