mandrel 1.80.0 → 1.81.0

package/.agents/docs/configuration.md

@@ -627,6 +627,12 @@ No tier-specific knobs beyond the common shape.
 | --------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
 | `bundles` | No       | `[]`    | Array of `{ name, path, limit }` entries (e.g. `{ "name": "app", "path": "dist/app.js", "limit": "100kB" }`). |
 
+Unlike `crap` / `maintainability`, this gate has no `refreshTag` config
+field — there is no scorer to regenerate the baseline from source, so the
+one-shot refresh/acknowledge mechanism is an env var, not a config knob.
+See [`.agents/docs/quality-gates.md` § Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)
+for `BUNDLE_SIZE_REFRESH=1` usage.
+
 #### `delivery.quality.formatAutofix`
 
 | Field       | Required | Default | Purpose                                                                                                                  |
@@ -791,6 +797,7 @@ the lint ratchet, and the CRAP/MI gates.
 | `baselines/lint.json`             | `lint-baseline.js`                   | `node .agents/scripts/lint-baseline.js capture`                       |
 | `baselines/crap.json`             | `update-crap-baseline.js`            | `npm run crap:update`                                                   |
 | `baselines/maintainability.json`  | `update-maintainability-baseline.js` | `npm run maintainability:update`                                        |
+| `baselines/bundle-size.json`      | consumer's own build/measure step    | Commit the build's measured sizes; for an intentional growth, run the check with `BUNDLE_SIZE_REFRESH=1` (see [Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)) |
 
 These files are the contract. They are read by every gate (Story close, push
 hook, CI) and are regenerated only via tagged `baseline-refresh:` commits

package/.agents/docs/quality-gates.md

@@ -452,6 +452,67 @@ watch loop — an unjustified baseline ratchet is no longer caught by CI.
 
 ---
 
+## Bundle-size ratchet — one-shot refresh/acknowledge (Story #151)
+
+> Baseline envelope, axes, and component model: see the
+> [Baseline reference](#baseline-reference) section below.
+
+`check-baselines --gate bundle-size` is a **strict** ratchet: it diffs the
+branch's committed `baselines/bundle-size.json` (head) against the base
+ref's copy (`origin/main` by default) using the gate's configured
+`tolerance`, and separately checks the head aggregate against `floors`.
+Unlike `coverage` / `crap` / `maintainability`, bundle-size has **no
+scorer of its own** — the measured `rawKb` / `gzippedKb` numbers come from
+whatever build step the consumer already runs, not a source-tree rescan —
+so there is no `refreshBaseline({ kind: 'bundle-size', ... })` path to
+regenerate a "corrected" baseline the way `npm run crap:update` does.
+
+This makes an **intentional** bundle-size growth (a framework major bump,
+a new dependency, an SSR runtime swap) impossible to land cleanly with the
+usual levers: permanently raising `tolerance` in `.agentrc.json` disables
+the ratchet for every *future* PR too, not just the one that legitimately
+grew.
+
+### `BUNDLE_SIZE_REFRESH=1`
+
+Set the environment variable for the one CI/local run that needs to land
+the growth:
+
+```bash
+BUNDLE_SIZE_REFRESH=1 npm run bundle-size:check
+# or, calling the dispatcher directly:
+BUNDLE_SIZE_REFRESH=1 node .agents/scripts/check-baselines.js --gate bundle-size
+```
+
+When set (`1` or `true`, case-insensitive), every `bundle-size`
+head-vs-base regression is demoted to `unchanged` **for that invocation
+only** — the gate compares head-vs-head in effect, so it passes even
+though the committed baseline grew. **Floors still apply**: an
+acknowledged PR can still fail if the head aggregate breaches the
+configured `floors` budget, so a genuinely runaway regression isn't
+silently waved through under the guise of "intentional".
+
+Commit the regenerated `baselines/bundle-size.json` (reflecting the real,
+larger sizes) in the same PR so the new numbers become the base for the
+*next* PR's diff.
+
+### The ratchet returns to full strength automatically
+
+`BUNDLE_SIZE_REFRESH` is read fresh on every invocation and is **never
+persisted** — no config write, no committed tag, no lingering state. The
+very next `check-baselines --gate bundle-size` run (i.e. the next PR),
+without the env var set, re-enforces the ratchet at full strength against
+the now-larger committed baseline. There is nothing to remember to reset.
+
+This mirrors the `CRAP_TOLERANCE` env-override precedent (see
+[CRAP gate — Consumer onboarding](#crap-gate--consumer-onboarding) above),
+but as a true one-shot acknowledgment rather than a run-scoped tolerance
+override: `CRAP_TOLERANCE` changes the *threshold*, `BUNDLE_SIZE_REFRESH`
+demotes the *outcome* of an already-flagged regression, which is the
+correct shape for a gate with no rescoring path of its own.
+
+---
+
 ## HITL blocker escalation
 
 `risk::high` is informational/planning metadata only. Runtime execution

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -82,6 +82,41 @@ export function resolveCrapEnvOverrides(crapConfig, env) {
   return { newMethodCeiling, tolerance, refreshTag, overrides };
 }
 
+/**
+ * Pure helper: resolve the one-shot bundle-size refresh/acknowledge flag
+ * (Story #151). Unlike `coverage` / `crap` / `maintainability`, the
+ * bundle-size gate has no scorer of its own — the measured sizes come from
+ * a build step the operator already runs, not a source-tree rescan — so
+ * there is no `refreshBaseline({ kind: 'bundle-size', ... })` path to
+ * regenerate a "corrected" baseline. Instead, `BUNDLE_SIZE_REFRESH=1`
+ * (mirroring `CRAP_TOLERANCE`'s env-override precedent) tells
+ * `check-baselines --gate bundle-size` to treat this run's head
+ * measurements as the newly acknowledged baseline: head-vs-base
+ * regressions are demoted to `unchanged` for this invocation only. Floors
+ * still apply — an acknowledged PR can still fail on an absolute budget
+ * breach, only the ratchet-vs-`origin/main` comparison is suspended.
+ *
+ * The flag is **not persisted** anywhere (no config write, no committed
+ * tag): the very next `check-baselines` invocation without the env var —
+ * i.e. the next PR — reverts to full strict enforcement automatically, so
+ * there is no lingering loosened tolerance to remember to reset (AC-3).
+ *
+ * Accepted truthy values: `1`, `true` (case-insensitive). Anything else
+ * (including unset/empty) resolves to `acknowledged: false`.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ acknowledged: boolean, overrides: string[] }}
+ */
+export function resolveBundleSizeEnvOverrides(env) {
+  const raw = env?.BUNDLE_SIZE_REFRESH;
+  const acknowledged =
+    typeof raw === 'string' && /^(1|true)$/i.test(raw.trim());
+  const overrides = acknowledged
+    ? [`acknowledged=true (BUNDLE_SIZE_REFRESH=${raw})`]
+    : [];
+  return { acknowledged, overrides };
+}
+
 /**
  * Pure helper: resolve the effective MI tolerance by layering precedence:
  *   1. `CRAP_TOLERANCE` env-var (CI override — the baseline-refresh-

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

@@ -7,8 +7,10 @@
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
 
+import { resolveBundleSizeEnvOverrides } from '../../../baselines/env-overrides.js';
 import { checkKernelVersion } from '../../../baselines/kernel.js';
 import * as reader from '../../../baselines/reader.js';
+import { Logger } from '../../../Logger.js';
 import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
 import { applyFloors, flattenBreaches } from './floors.js';
 
@@ -22,6 +24,38 @@ function loadHeadBaseline(kind, cwd, configPath) {
   }
 }
 
+/**
+ * One-shot bundle-size refresh/acknowledge (Story #151). When
+ * `BUNDLE_SIZE_REFRESH=1` is set, demote every `bundle-size` regression to
+ * `unchanged` for this run only — floors still apply, so a genuine budget
+ * breach is still caught. The flag is read fresh on every invocation and
+ * never persisted, so the ratchet returns to full strength automatically on
+ * the very next run (no lingering loosened tolerance to remember to reset).
+ *
+ * No-op for every other kind.
+ */
+function applyBundleSizeAcknowledgment(kind, compareOutput, env) {
+  if (kind !== 'bundle-size') return { compareOutput, acknowledged: false };
+  const { acknowledged, overrides } = resolveBundleSizeEnvOverrides(env);
+  if (!acknowledged || compareOutput.regressions.length === 0) {
+    return { compareOutput, acknowledged: false };
+  }
+  Logger.warn(
+    `[bundle-size] ⚠ ${overrides.join(', ')} — ` +
+      `${compareOutput.regressions.length} regression(s) acknowledged for this run only; ` +
+      'floors still enforced. This does not persist: the next run without ' +
+      'BUNDLE_SIZE_REFRESH re-enforces the ratchet at full strength.',
+  );
+  return {
+    acknowledged: true,
+    compareOutput: {
+      ...compareOutput,
+      regressions: [],
+      unchanged: [...compareOutput.unchanged, ...compareOutput.regressions],
+    },
+  };
+}
+
 function buildGateReport({
   kind,
   gateBlock,
@@ -30,6 +64,7 @@ function buildGateReport({
   breaches,
   compareOutput,
   cmp,
+  acknowledged,
 }) {
   const kernel = checkKernelVersion(kind, baseline.kernelVersion);
   return {
@@ -50,6 +85,7 @@ function buildGateReport({
     regressionCount: compareOutput.regressions.length,
     baseRef: cmp.baseRef ?? null,
     generatedAt: baseline.generatedAt,
+    acknowledged,
   };
 }
 
@@ -59,6 +95,7 @@ export async function evaluateKind({
   scope,
   cwd,
   configPath,
+  env = process.env,
 }) {
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
@@ -67,7 +104,15 @@ export async function evaluateKind({
   const breaches = flattenBreaches(findings);
   const cmp = await evaluateCompare({ kind, gateBlock, scope, cwd });
   const rawCompare = runCompareStage(baseline, cmp);
-  const compareOutput = applyTolerance(rawCompare, gateBlock.tolerance ?? null);
+  const toleratedCompare = applyTolerance(
+    rawCompare,
+    gateBlock.tolerance ?? null,
+  );
+  const { compareOutput, acknowledged } = applyBundleSizeAcknowledgment(
+    kind,
+    toleratedCompare,
+    env,
+  );
   return buildGateReport({
     kind,
     gateBlock,
@@ -76,5 +121,6 @@ export async function evaluateKind({
     breaches,
     compareOutput,
     cmp,
+    acknowledged,
   });
 }

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

@@ -43,6 +43,13 @@ Unified baseline dispatcher. Per-kind pipeline (schema → floor → tolerance
 compare) over every configured gate, with centralised friction emission and
 aggregated exit codes.
 
+Env vars:
+  BUNDLE_SIZE_REFRESH=1  One-shot acknowledge for an intentional bundle-size
+                         growth: demotes bundle-size regressions to
+                         "unchanged" for this run only (floors still
+                         enforced). Never persisted — the next run without
+                         this flag re-enforces the ratchet.
+
 Exit codes:
   0  every enabled gate passes
   1  any floor breach

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

@@ -59,7 +59,7 @@ function dispatchPerKind({ wanted, quality, env, cwd, configPath }) {
     wanted.map((kind) => {
       const gateBlock = quality.gates[kind];
       const scope = resolveDispatchScope({ kind, quality, env });
-      return evaluateKind({ kind, gateBlock, scope, cwd, configPath });
+      return evaluateKind({ kind, gateBlock, scope, cwd, configPath, env });
     }),
   );
 }

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

@@ -27,7 +27,8 @@ function formatGateLine(g) {
     ? ''
     : ` [kernel drift ${g.kernelBaseline} → ${g.kernelCurrent}]`;
   const baseRef = g.baseRef ? ` [baseRef=${g.baseRef}]` : '';
-  return `  - ${g.kind}: ${status}${drift}${baseRef}`;
+  const ack = g.acknowledged ? ' [ACKNOWLEDGED — this run only]' : '';
+  return `  - ${g.kind}: ${status}${drift}${baseRef}${ack}`;
 }
 
 function formatViolationLine(component, v) {

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.81.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.80.0...mandrel-v1.81.0) (2026-07-01)
+
+
+### Fixed
+
+* **baselines:** add one-shot BUNDLE_SIZE_REFRESH acknowledge for the bundle-size ratchet ([#4309](https://github.com/dsj1984/mandrel/issues/4309)) ([bc466b9](https://github.com/dsj1984/mandrel/commit/bc466b98f6c7521c3a24bbb4d93ee5169c163839))
+
 ## [1.80.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.79.0...mandrel-v1.80.0) (2026-07-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.80.0",
+  "version": "1.81.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",