mandrel 2.9.0 → 2.11.0

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

@@ -35,6 +35,19 @@
  * 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
@@ -63,10 +76,23 @@
  * `undefined` / malformed inputs degrade to `fresh` + `full` ceremony.
  *
  * @typedef {'fresh'|'inline'} CeremonyMode
+ * @typedef {'fresh-critic'|'inline-self-eval'} VerdictOwner
  * @typedef {import('./review-depth.js').ChangeLevel} ChangeLevel
  * @typedef {'minimal'|'standard'|'strict'} 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}
+ */
+export function verdictOwnerForMode(mode) {
+  return mode === 'fresh' ? 'fresh-critic' : 'inline-self-eval';
+}
+
 /** @type {readonly CeremonyProfile[]} */
 export const CEREMONY_PROFILES = Object.freeze([
   'minimal',
@@ -133,9 +159,28 @@ export function sampledFresh(clusterIndex, rate) {
  *   reason: string,
  *   sampled: boolean,
  *   profile: CeremonyProfile,
+ *   verdictOwner: VerdictOwner,
  * }}
  */
 export function resolveCeremonyForRisk(input = {}) {
+  const decision = resolveCeremonyDecision(input);
+  return { ...decision, verdictOwner: verdictOwnerForMode(decision.mode) };
+}
+
+/**
+ * Internal mode/reason resolution — the tier rules and sampling floor.
+ * `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,
+ *   sampled: boolean,
+ *   profile: CeremonyProfile,
+ * }}
+ */
+function resolveCeremonyDecision(input = {}) {
   const derivedLevel =
     input && typeof input === 'object' ? input.derivedLevel : undefined;
   const clusterIndex =

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

@@ -7,7 +7,11 @@
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
 
-import { resolveBundleSizeEnvOverrides } from '../../../baselines/env-overrides.js';
+import {
+  resolveBundleSizeEnvOverrides,
+  resolveMaintainabilityRefreshOverrides,
+} from '../../../baselines/env-overrides.js';
+import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
   checkKernelVersion,
   getKindModule,
@@ -17,6 +21,10 @@ 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:';
 
 /**
  * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
@@ -113,6 +121,88 @@ function applyBundleSizeAcknowledgment(kind, compareOutput, env) {
   };
 }
 
+/**
+ * Resolve the maintainability refresh trigger (Story #4731). Two paths, either
+ * of which acknowledges — mirroring the bundle-size acknowledge but adding the
+ * commit-tagged trigger the breach message already documents:
+ *
+ *   1. Env parity: `MAINTAINABILITY_REFRESH=1` (the manual override).
+ *   2. Commit tag: a commit in the compared range `<baseRef>..HEAD` whose
+ *      subject contains the configured `refreshTag` AND whose diff touches the
+ *      maintainability 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: …`).
+ *
+ * @returns {{ triggered: boolean, reasons: string[] }}
+ */
+function resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
+  const reasons = [];
+  const { acknowledged: envAck, overrides } =
+    resolveMaintainabilityRefreshOverrides(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.maintainability;
+    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 maintainability refresh/acknowledge (Story #4731). When triggered
+ * (env flag OR a `baseline-refresh:`-tagged range commit touching the baseline),
+ * demote every maintainability head-vs-base regression to `unchanged` for this
+ * run only — floors still apply, so a row below its `min` 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.
+ *
+ * No-op for every other kind.
+ */
+function applyMaintainabilityAcknowledgment(kind, compareOutput, ctx) {
+  if (kind !== 'maintainability') {
+    return { compareOutput, acknowledged: false };
+  }
+  const { triggered, reasons } = resolveMaintainabilityRefreshTrigger(ctx);
+  if (!triggered || compareOutput.regressions.length === 0) {
+    return { compareOutput, acknowledged: false };
+  }
+  Logger.warn(
+    `[maintainability] ⚠ ${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,
@@ -171,11 +261,14 @@ export async function evaluateKind({
     rawCompare,
     gateBlock.tolerance ?? null,
   );
-  const { compareOutput, acknowledged } = applyBundleSizeAcknowledgment(
+  const bundleAck = applyBundleSizeAcknowledgment(kind, toleratedCompare, env);
+  const miAck = applyMaintainabilityAcknowledgment(
     kind,
-    toleratedCompare,
-    env,
+    bundleAck.compareOutput,
+    { gateBlock, cmp, cwd, env },
   );
+  const compareOutput = miAck.compareOutput;
+  const acknowledged = bundleAck.acknowledged || miAck.acknowledged;
   return buildGateReport({
     kind,
     gateBlock,

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

@@ -49,6 +49,13 @@ Env vars:
                          "unchanged" for this run only (floors still
                          enforced). Never persisted — the next run without
                          this flag re-enforces the ratchet.
+  MAINTAINABILITY_REFRESH=1
+                         One-shot acknowledge for a deliberate maintainability
+                         baseline refresh: demotes maintainability head-vs-base
+                         regressions to "unchanged" for this run only (floors
+                         still enforced). Env-parity override for the
+                         'baseline-refresh:'-tagged range commit that touches
+                         baselines/maintainability.json. Never persisted.
 
 Exit codes:
   0  every enabled gate passes