mandrel 1.79.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/rules/git-conventions.md

@@ -107,6 +107,18 @@ rejected by `pre-push` hooks):
 4.  **Never bypass hooks**: Do not use `--no-verify`, `--no-gpg-sign`, or
     other hook-skipping flags unless the operator explicitly authorizes it.
     If a hook fails, investigate the underlying cause.
+    - **Known false-negative signature**: a `pre-push`/`pre-commit` failure
+      whose message is a _zero-match_ error (e.g. Biome's
+      `No files were processed in the specified paths`) rather than a
+      reported violation, combined with an agent CWD under a harness-managed
+      worktree path a consumer's lint config ignores (e.g.
+      `.claude/worktrees/<name>/` against a `files.includes` glob like
+      `"!**/.claude"`), is a **consumer-tooling gap**, not a real lint
+      failure. It does not authorize `--no-verify`. See
+      [`worktree-lifecycle.md` § Harness-worktree ⇄ consumer-lint-ignore interaction](../workflows/helpers/worktree-lifecycle.md#harness-worktree-consumer-lint-ignore-interaction-story-152)
+      for the recognition signature and the sanctioned consumer-side fix
+      (`--no-errors-on-unmatched` or equivalent) before escalating via
+      `agent::blocked`.
 
 ## Meta Labels (Retrospective Signal Routing)
 

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/.agents/workflows/helpers/worktree-lifecycle.md

@@ -260,6 +260,74 @@ Symlink strategy:
   specific failure up to 3 times with 250/500/1000 ms backoff. Unrelated fetch
   failures surface immediately — no retry.
 
+## Harness-worktree ⇄ consumer-lint-ignore interaction (Story #152)
+
+Mandrel's own worktree isolation (above) always roots story worktrees at
+`delivery.worktreeIsolation.root` (default `.worktrees/` at the repo root).
+That path is separate from **the host IDE/CLI harness's own worktree
+mechanism** — for example Claude Code, when it manages an agent session as a
+git worktree, nests it at `.claude/worktrees/<name>/`. A mandrel delivery
+agent can be invoked from *either* location depending on how the operator's
+harness composes with `/deliver`: mandrel's own `.worktrees/story-<id>/` when
+`worktreeIsolation.enabled` drives the checkout, or a harness-level
+`.claude/worktrees/<name>/` when the harness itself provides the isolated
+working directory mandrel runs inside.
+
+This matters because a consumer's `pre-push` (or `pre-commit`) lint step is
+commonly configured with an ignore glob that excludes noisy agent-tooling
+directories, e.g. a Biome `files.includes` entry like `"!**/.claude"`. When
+the *agent's CWD itself* resolves under `.claude/worktrees/<name>/`, a
+lint invocation scoped to `.` (`biome check .`, or equivalent) resolves
+every candidate path as living under the ignored `.claude` prefix — the glob
+matches zero files, and tools that treat zero-match as failure (Biome's
+default `check` behavior without `--no-errors-on-unmatched`) exit non-zero
+with something like `No files were processed in the specified paths`. This
+is a **false negative**: the changed files were never actually linted
+against, and the hook is not reporting a real defect. It is functionally
+distinct from a `pre-push` rejection caused by a genuine lint violation, and
+must not be treated the same way.
+
+**Do not resolve this by bypassing the push hook.**
+[`rules/git-conventions.md`](../../rules/git-conventions.md) § "Push
+Validation & Reliability" prohibits skipping hooks without explicit operator
+authorization, and that prohibition is not weakened by this interaction —
+the zero-match failure is a **consumer-tooling gap**, not a framework
+authorization the agent gets to grant itself.
+
+**Sanctioned resolution path:**
+
+1. **Recognize the signature.** A `pre-push`/`pre-commit` failure whose
+   message is a zero-match error (`No files were processed`, `0 files
+   matched`, or equivalent for the consumer's linter) — not a reported
+   violation in a specific file — combined with an agent CWD under
+   `.claude/worktrees/` (or any other harness-managed path a consumer's lint
+   config ignores) is this known interaction, not a real lint failure.
+2. **Fix it in the consumer, not the agent invocation.** The remedy lives in
+   the consumer's own lint command, mirroring what its `lint-staged` config
+   (if present) likely already does for the same reason: make the zero-match
+   case a no-op instead of a failure. For Biome:
+   `biome check --no-errors-on-unmatched .`. Other linters have an
+   equivalent flag (e.g. ESLint's `--no-error-on-unmatched-pattern`). This is
+   a one-line consumer-side change, typically to `.husky/pre-push` or the
+   `package.json` script it invokes.
+3. **Escalate through the normal HITL path**, per
+   [`.agents/instructions.md` § 1.J](../../instructions.md), if the agent
+   cannot edit the consumer's hook/lint config directly (e.g. it sits outside
+   the Story's scope). Transition to `agent::blocked`, name the zero-match
+   signature and the one-line remedy in the blocker summary, and let the
+   operator apply the consumer-side fix or explicitly authorize a one-time
+   hook-skip per [`rules/git-conventions.md`](../../rules/git-conventions.md)
+   § "Push Validation & Reliability". Explicit operator authorization is the
+   *only* circumstance under which a hook may be skipped — never as an
+   agent's unilateral default when this signature is recognized.
+4. **Do not relocate mandrel's own worktrees to work around a harness-level
+   path.** `delivery.worktreeIsolation.root` controls where *mandrel*
+   materializes `story-<id>` worktrees (default `.worktrees/`, already
+   outside `.claude/`) and is unrelated to where the host harness places its
+   own session worktree. Changing `worktreeIsolation.root` does not fix this
+   interaction when the false negative originates from the harness's path,
+   not mandrel's.
+
 ## Fallback: single-tree mode
 
 Set `delivery.worktreeIsolation.enabled: false` (or omit the block) to

package/docs/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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)
+
+
+### Chores
+
+* **release:** force a release to ship the [#4306](https://github.com/dsj1984/mandrel/issues/4306) worktree-lifecycle doc fix ([#4307](https://github.com/dsj1984/mandrel/issues/4307)) ([fa54ebb](https://github.com/dsj1984/mandrel/commit/fa54ebb52fc8fe264bab2f4c6dea180973023c28))
+
 ## [1.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.78.0...mandrel-v1.79.0) (2026-06-30)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.79.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/",