mandrel 2.18.0 → 2.19.0

package/.agents/docs/SDLC.md

@@ -528,7 +528,7 @@ new CI gate**, route the check through a `package.json` script (add it to
 transitivity. **When a workflow file genuinely must change** (a new job, a
 trigger change, a runner bump), the edit must be made by an operator with
 `Workflows: Read and write` PAT permissions — see
-[`docs/release-operations.md` § One-time PAT setup](../../docs/release-operations.md#one-time-pat-setup).
+[`docs/release-operations.md` § One-time PAT setup](https://github.com/dsj1984/mandrel/blob/main/docs/release-operations.md#one-time-pat-setup).
 
 ### Worktree config shadow
 

package/.agents/scripts/check-doc-links.js

@@ -25,6 +25,10 @@
 //      a retired token is always a non-zero exit even if a stale workflow
 //      file happens to exist.
 //
+//   4. Story #4801 — every relative link originating under `.agents/**`
+//      resolves to a target that still exists once the tree is materialized
+//      into a *consumer* project. See `escapesPayload` for the boundary rule.
+//
 // Exit codes:
 //   0  every link and slash-command token resolves cleanly.
 //   1  at least one violation; details are written to stderr (file:line).
@@ -35,6 +39,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { minimatch } from 'minimatch';
+import { parseStandardCliArgs } from './lib/cli/standard-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
 
@@ -124,6 +130,63 @@ export const SLASH_ALLOWLIST = new Set([
   'main',
 ]);
 
+// --- Payload boundary (Story #4801) ----------------------------------------
+
+// `mandrel sync` materializes ONLY the package's `.agents/` payload into a
+// consumer's project, at `<projectRoot>/.agents` (see `lib/cli/sync.js`:
+// `destRoot = path.join(projectRoot, '.agents')`). `bin/` and `lib/` ship
+// inside the npm tarball but stay under `node_modules/mandrel/`, and the
+// framework's own `tests/`, `docs/` (bar the CHANGELOG) and `.claude/` trees
+// ship nowhere at all. So a relative link that escapes `.agents/` resolves
+// cleanly in THIS repo and dangles in every consumer — which is exactly why
+// the checker cannot catch this class by `fs.existsSync` alone.
+//
+// This is why the boundary is `.agents/` and NOT `package.json#files`: the
+// latter lists `lib/` and `bin/`, which are packaged but never materialized
+// at a consumer's repo root.
+export const MATERIALIZED_ROOT = '.agents';
+
+// Repo-root-relative paths OUTSIDE `.agents/` that a Mandrel *consumer*
+// legitimately owns, so a doc under `.agents/**` may still link to them.
+// Deliberately explicit rather than pattern-derived: whether a given repo-root
+// path is consumer-owned or framework-only is a judgment per path, not a rule.
+// A new escaping link fails closed until it is justified and added here.
+export const CONSUMER_OWNED_PATHS = new Set([
+  'package.json',
+  '.agentrc.json',
+  '.c8rc.cjs',
+  'docs/architecture.md',
+  'docs/decisions.md',
+]);
+
+// Directory prefixes (repo-root-relative, trailing slash) whose whole subtree
+// is consumer-owned.
+export const CONSUMER_OWNED_PREFIXES = Object.freeze(['baselines/']);
+
+/**
+ * True when `relTarget` is unreachable from a materialized consumer tree.
+ *
+ * Only links whose SOURCE lives under `.agents/**` are subject to the rule —
+ * `docs/**` is framework-repo-only, ships nowhere, and keeps today's
+ * existence-only semantics.
+ *
+ * @param {string} relFile   repo-relative POSIX path of the linking document
+ * @param {string} relTarget repo-relative POSIX path the link resolves to
+ */
+export function escapesPayload(relFile, relTarget) {
+  if (!relFile.startsWith(`${MATERIALIZED_ROOT}/`)) return false;
+  if (
+    relTarget === MATERIALIZED_ROOT ||
+    relTarget.startsWith(`${MATERIALIZED_ROOT}/`)
+  ) {
+    return false;
+  }
+  if (CONSUMER_OWNED_PATHS.has(relTarget)) return false;
+  if (CONSUMER_OWNED_PREFIXES.some((p) => relTarget.startsWith(p)))
+    return false;
+  return true;
+}
+
 // --- File discovery --------------------------------------------------------
 
 function isExcludedRelPath(relPath) {
@@ -150,14 +213,28 @@ function walkMarkdown(dirAbs, repoRoot, out) {
   }
 }
 
-export function discoverMarkdown(rootAbs, scanRoots) {
+/**
+ * Collect every non-excluded `*.md` under each `scanRoots` entry.
+ *
+ * @param {string}   rootAbs     absolute repo root
+ * @param {string[]} scanRoots   repo-relative subtrees to walk
+ * @param {string[]} [exclude]   minimatch globs; a repo-relative POSIX path
+ *                               matching any of them is dropped from the scan
+ */
+export function discoverMarkdown(rootAbs, scanRoots, exclude = []) {
   const out = [];
   for (const sub of scanRoots) {
     const subAbs = path.join(rootAbs, sub);
     if (fs.existsSync(subAbs)) walkMarkdown(subAbs, rootAbs, out);
   }
-  out.sort();
-  return out;
+  const filtered = exclude.length
+    ? out.filter((abs) => {
+        const rel = path.relative(rootAbs, abs).split(path.sep).join('/');
+        return !exclude.some((g) => minimatch(rel, g, { dot: true }));
+      })
+    : out;
+  filtered.sort();
+  return filtered;
 }
 
 // --- Region masking --------------------------------------------------------
@@ -326,6 +403,26 @@ export function checkFile(absPath, repoRoot) {
     } else {
       resolved = path.resolve(fileDir, pathOnly);
     }
+    // Payload boundary (Story #4801) takes precedence over existence: a link
+    // that escapes the materialized tree is a defect even when the target
+    // exists here, and reporting both kinds for one link would double-count.
+    const relTarget = path
+      .relative(repoRoot, resolved)
+      .split(path.sep)
+      .join('/');
+    if (escapesPayload(relFile, relTarget)) {
+      violations.push({
+        file: relFile,
+        line,
+        kind: 'payload-boundary',
+        message:
+          `link escapes the materialized payload: ${target} → ${relTarget}. ` +
+          `Only '${MATERIALIZED_ROOT}/' is materialized into a consumer project, ` +
+          'so this resolves here but dangles for every consumer. Use an absolute ' +
+          'GitHub URL or a non-link code span.',
+      });
+      continue;
+    }
     if (!fs.existsSync(resolved)) {
       violations.push({
         file: relFile,
@@ -377,6 +474,8 @@ export function checkFile(absPath, repoRoot) {
 
 // --- Public entry point ----------------------------------------------------
 
+export const DEFAULT_SCAN_ROOTS = Object.freeze(['docs', '.agents']);
+
 /**
  * Run the checker programmatically. Returns `{ exitCode, violations }`.
  * `exitCode` is 0 when every doc is clean, 1 otherwise.
@@ -384,11 +483,13 @@ export function checkFile(absPath, repoRoot) {
  * @param {object} [options]
  * @param {string} [options.repoRoot] Defaults to the framework repo root.
  * @param {string[]} [options.scanRoots] Defaults to `['docs', '.agents']`.
+ * @param {string[]} [options.exclude] minimatch globs dropped from the scan.
  */
 export function runCheck(options = {}) {
   const repoRoot = options.repoRoot ?? REPO_ROOT;
-  const scanRoots = options.scanRoots ?? ['docs', '.agents'];
-  const files = discoverMarkdown(repoRoot, scanRoots);
+  const scanRoots = options.scanRoots ?? [...DEFAULT_SCAN_ROOTS];
+  const exclude = options.exclude ?? [];
+  const files = discoverMarkdown(repoRoot, scanRoots, exclude);
   const violations = [];
   for (const abs of files) {
     const fileViolations = checkFile(abs, repoRoot);
@@ -405,8 +506,28 @@ function formatViolation(v) {
   return `${v.file}:${v.line}: [${v.kind}] ${v.message}`;
 }
 
+/**
+ * Translate argv into `runCheck` options. Repeatable `--scan-root` replaces
+ * the default scan set entirely; repeatable `--exclude` filters whatever was
+ * scanned. Absent flags reproduce the pre-#4801 defaults exactly.
+ */
+export function parseArgs(argv) {
+  const { values } = parseStandardCliArgs({
+    argv,
+    extras: {
+      'scan-root': { type: 'string-multi', alias: 'scanRoot' },
+      exclude: { type: 'string-multi', alias: 'exclude' },
+    },
+  });
+  const scanRoots = values.scanRoot?.length
+    ? values.scanRoot
+    : [...DEFAULT_SCAN_ROOTS];
+  return { scanRoots, exclude: values.exclude ?? [] };
+}
+
 async function main() {
-  const result = runCheck();
+  const { scanRoots, exclude } = parseArgs(process.argv.slice(2));
+  const result = runCheck({ scanRoots, exclude });
   if (result.violations.length === 0) {
     Logger.info(
       `[check-doc-links] OK — scanned ${result.scanned} active markdown file(s); no violations.`,
@@ -426,11 +547,22 @@ async function main() {
 runAsCli(import.meta.url, main, {
   source: 'check-doc-links',
   usage: {
-    invocation: 'node .agents/scripts/check-doc-links.js',
+    invocation:
+      'node .agents/scripts/check-doc-links.js [--scan-root <path>] [--exclude <glob>]',
     summary:
-      'Validate every relative Markdown link and /slash-command token across docs/ and .agents/, and reject mentions of retired commands.',
-    flags: [],
+      'Validate every relative Markdown link and /slash-command token across docs/ and .agents/, reject mentions of retired commands, and reject links that escape the materialized .agents/ payload.',
+    flags: [
+      [
+        '--scan-root <path>',
+        'Repeatable. Repo-relative subtree to scan. Replaces the default set (docs, .agents).',
+      ],
+      [
+        '--exclude <glob>',
+        'Repeatable. minimatch glob; matching files are dropped from the scan.',
+      ],
+    ],
     notes: [
+      'Consumers materialize only .agents/, so a relative link from .agents/**\nto a framework-repo-only path (tests/, lib/, .claude/, framework docs)\nis reported as a payload-boundary violation even though it resolves here.',
       'Exit codes:\n  0  every link and command token resolves\n  1  at least one violation (file:line on stderr)',
     ],
   },

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

@@ -83,69 +83,61 @@ export function resolveCrapEnvOverrides(crapConfig, env) {
 }
 
 /**
- * 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 env var that acknowledges a deliberate baseline refresh for `kind`.
+ * Upper-snakes the kind name, so `bundle-size` → `BUNDLE_SIZE_REFRESH` and
+ * `coverage` → `COVERAGE_REFRESH`. The two names that predate the generic
+ * mechanism (`BUNDLE_SIZE_REFRESH`, Story #151; `MAINTAINABILITY_REFRESH`,
+ * Story #4731) are exactly what this rule produces, so generalizing kept
+ * both working unchanged.
  *
- * 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).
+ * Module-local: `resolveKindRefreshOverrides` is the public surface, and the
+ * naming rule is pinned through it rather than exported for its own sake.
  *
- * 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[] }}
+ * @param {string} kind
+ * @returns {string|null} null when `kind` is not a usable kind name
  */
-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 };
+function kindRefreshEnvVar(kind) {
+  if (typeof kind !== 'string' || kind.length === 0) return null;
+  return `${kind.toUpperCase().replace(/-/g, '_')}_REFRESH`;
 }
 
 /**
- * Pure helper: resolve the one-shot maintainability refresh/acknowledge flag
- * (Story #4731). This is the env-parity sibling of
- * `resolveBundleSizeEnvOverrides`: `MAINTAINABILITY_REFRESH=1` (or `true`,
- * case-insensitive) tells `check-baselines --gate maintainability` to demote
- * this run's head-vs-base maintainability regressions to `unchanged` for this
- * invocation only. Floors still apply — an acknowledged run can still fail on
- * an absolute floor breach (e.g. a row below `min` 70); only the
- * ratchet-vs-base regression comparison is suspended.
+ * Pure helper: resolve the one-shot baseline refresh/acknowledge flag for any
+ * ratcheted kind (Story #4802, generalizing Story #151 / Story #4731).
+ *
+ * `<KIND>_REFRESH=1` tells `check-baselines --gate <kind>` to demote this
+ * run's head-vs-base regressions to `unchanged` for this invocation only.
+ * Floors still apply — an acknowledged run can still fail on an absolute
+ * floor breach; only the ratchet-vs-base comparison is suspended.
+ *
+ * Why every kind needs this: a diff-scope baseline is an accretion of many
+ * partial runs, not one measurement. Replacing it with a single full-scope
+ * measurement necessarily produces row deltas in both directions that are
+ * arithmetic, not behavioural — so without an acknowledgment path the gate
+ * blocks precisely the correction it should encourage.
  *
- * Unlike bundle-size, maintainability also has a **commit-tagged** trigger
- * (a `baseline-refresh:`-tagged commit in the compared range that touches the
- * maintainability baseline file) resolved in the evaluate phase — this env
- * flag is the manual override the two share by shape. Neither is persisted:
- * the next run without the flag / tag re-enforces the ratchet at full
- * strength automatically.
+ * The flag is **not persisted** anywhere (no config write, no committed tag):
+ * the very next invocation without the env var reverts to full strict
+ * enforcement automatically, so there is no lingering loosened tolerance to
+ * remember to reset. The evaluate phase pairs this with a commit-tagged
+ * trigger that is likewise one-shot by construction.
  *
- * Accepted truthy values: `1`, `true` (case-insensitive). Anything else
- * (including unset/empty) resolves to `acknowledged: false`.
+ * Accepted truthy values: `1`, `true` (case-insensitive), with surrounding
+ * whitespace trimmed. Anything else — including unset, empty, `0`, `false`,
+ * and non-string values — resolves to `acknowledged: false`.
  *
+ * @param {string} kind
  * @param {NodeJS.ProcessEnv} env
  * @returns {{ acknowledged: boolean, overrides: string[] }}
  */
-export function resolveMaintainabilityRefreshOverrides(env) {
-  const raw = env?.MAINTAINABILITY_REFRESH;
+export function resolveKindRefreshOverrides(kind, env) {
+  const varName = kindRefreshEnvVar(kind);
+  if (!varName) return { acknowledged: false, overrides: [] };
+  const raw = env?.[varName];
   const acknowledged =
     typeof raw === 'string' && /^(1|true)$/i.test(raw.trim());
   const overrides = acknowledged
-    ? [`acknowledged=true (MAINTAINABILITY_REFRESH=${raw})`]
+    ? [`acknowledged=true (${varName}=${raw})`]
     : [];
   return { acknowledged, overrides };
 }

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

@@ -7,10 +7,7 @@
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
 
-import {
-  resolveBundleSizeEnvOverrides,
-  resolveMaintainabilityRefreshOverrides,
-} from '../../../baselines/env-overrides.js';
+import { resolveKindRefreshOverrides } from '../../../baselines/env-overrides.js';
 import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
   checkBaselineSemantics,
@@ -91,57 +88,34 @@ 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],
-    },
-  };
-}
-
-/**
- * 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:
+ * 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: `MAINTAINABILITY_REFRESH=1` (the manual override).
+ *   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 the
- *      maintainability baseline file. One-shot by construction — once merged,
- *      the refreshed baseline becomes the base and the tag leaves the range.
+ *      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 resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
+function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
   const reasons = [];
-  const { acknowledged: envAck, overrides } =
-    resolveMaintainabilityRefreshOverrides(env);
+  const { acknowledged: envAck, overrides } = resolveKindRefreshOverrides(
+    kind,
+    env,
+  );
   if (envAck) reasons.push(...overrides);
 
   const baseRef = cmp?.baseRef ?? null;
@@ -154,15 +128,17 @@ function resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
       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})`,
-      );
+        : 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})`,
+        );
+      }
     }
   }
 
@@ -170,26 +146,24 @@ function resolveMaintainabilityRefreshTrigger({ gateBlock, cmp, cwd, env }) {
 }
 
 /**
- * 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.
+ * 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.
  *
- * No-op for every other kind.
+ * A no-op absent a trigger, so an unacknowledged run of any kind reports its
+ * regressions exactly as before.
  */
-function applyMaintainabilityAcknowledgment(kind, compareOutput, ctx) {
-  if (kind !== 'maintainability') {
-    return { compareOutput, acknowledged: false };
-  }
-  const { triggered, reasons } = resolveMaintainabilityRefreshTrigger(ctx);
+function applyRefreshAcknowledgment(kind, compareOutput, ctx) {
+  const { triggered, reasons } = resolveRefreshTrigger({ ...ctx, kind });
   if (!triggered || compareOutput.regressions.length === 0) {
     return { compareOutput, acknowledged: false };
   }
   Logger.warn(
-    `[maintainability] ⚠ ${reasons.join('; ')} — ` +
+    `[${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.',
@@ -274,14 +248,14 @@ export async function evaluateKind({
     rawCompare,
     gateBlock.tolerance ?? null,
   );
-  const bundleAck = applyBundleSizeAcknowledgment(kind, toleratedCompare, env);
-  const miAck = applyMaintainabilityAcknowledgment(
-    kind,
-    bundleAck.compareOutput,
-    { gateBlock, cmp, cwd, env },
-  );
-  const compareOutput = miAck.compareOutput;
-  const acknowledged = bundleAck.acknowledged || miAck.acknowledged;
+  const ack = applyRefreshAcknowledgment(kind, toleratedCompare, {
+    gateBlock,
+    cmp,
+    cwd,
+    env,
+  });
+  const compareOutput = ack.compareOutput;
+  const acknowledged = ack.acknowledged;
   return buildGateReport({
     kind,
     gateBlock,

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

@@ -44,18 +44,26 @@ 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.
-  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.
+  <KIND>_REFRESH=1       One-shot acknowledge for a deliberate baseline
+                         refresh of that kind: demotes its head-vs-base
+                         regressions to "unchanged" for this run only. Floors
+                         are STILL enforced, so a genuine breach is still
+                         caught. The kind name is upper-snaked, e.g.
+                         COVERAGE_REFRESH, CRAP_REFRESH, DUPLICATION_REFRESH,
+                         MAINTAINABILITY_REFRESH, BUNDLE_SIZE_REFRESH.
+                         Never persisted — the next run without the flag
+                         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
+                         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.
+
+                         Use these when replacing a diff-scope baseline with a
+                         full-scope measurement: the resulting row deltas are
+                         arithmetic, not behavioural.
 
 Exit codes:
   0  every enabled gate passes

package/.agents/scripts/lib/orchestration/lifecycle/listeners/README.md

@@ -2,7 +2,8 @@
 
 Each listener in this directory subscribes to one or more lifecycle bus
 events and performs a single side effect. The full close-tail roster and
-event taxonomy live in [`docs/LIFECYCLE.md`](../../../../../../docs/LIFECYCLE.md)
+event taxonomy live in
+[`docs/LIFECYCLE.md`](https://github.com/dsj1984/mandrel/blob/main/docs/LIFECYCLE.md)
 — that document is the SSOT. This README only indexes the **files that still
 live in this folder**.
 

package/.agents/workflows/audit-performance.md

@@ -39,8 +39,8 @@ Sequential inline execution is the fallback (see the core's Execution strategy).
 > orchestrated path grants its measurement agents a `Bash` tool restricted to a
 > **non-mutating command allowlist** (profilers, timers, bundle-stat and
 > file-size probes — never a command that writes source, installs, or mutates
-> git/labels). See the allowlist in
-> [`../../.claude/workflows/audit-performance.workflow.js`](../../.claude/workflows/audit-performance.workflow.js).
+> git/labels). See the allowlist in the harness-generated
+> `.claude/workflows/audit-performance.workflow.js`.
 
 ## Step 0: Measure before you judge (mandatory)
 

package/.agents/workflows/helpers/diagnose.md

@@ -113,5 +113,5 @@ pipelines and CI-step parsing.
   — the canonical contract every check module must satisfy.
 - [`.agents/scripts/diagnose.js`](../../scripts/diagnose.js) — the CLI
   implementation backing this helper.
-- [`tests/diagnose-output.test.js`](../../../tests/diagnose-output.test.js)
+- [`tests/diagnose-output.test.js`](https://github.com/dsj1984/mandrel/blob/main/tests/diagnose-output.test.js)
   — pinned output and exit-code contracts.

package/.agents/workflows/helpers/signals.md

@@ -106,7 +106,7 @@ node .agents/scripts/signals-view.js 9999
   CLI implementation backing this helper.
 - [`.agents/scripts/lib/signals/`](../../scripts/lib/signals/) — the
   shared reader + schema + span-tree barrel.
-- [`tests/signals-view.test.js`](../../../tests/signals-view.test.js) —
+- [`tests/signals-view.test.js`](https://github.com/dsj1984/mandrel/blob/main/tests/signals-view.test.js) —
   pinned output and tempRoot-honour contracts.
-- [`tests/lib/signals/span-tree.test.js`](../../../tests/lib/signals/span-tree.test.js) —
+- [`tests/lib/signals/span-tree.test.js`](https://github.com/dsj1984/mandrel/blob/main/tests/lib/signals/span-tree.test.js) —
   pure-function contract for the span-tree builder.

package/.agents/workflows/mandrel-update.md

@@ -13,7 +13,7 @@ description: >-
 # /mandrel-update
 
 > **Upgrade owner.** The mechanical upgrade is owned end to end by the
-> [`mandrel update`](../../lib/cli/update.js) CLI under the npm distribution
+> [`mandrel update`](https://github.com/dsj1984/mandrel/blob/main/lib/cli/update.js) CLI under the npm distribution
 > model. This workflow wraps that CLI: it runs
 > `npx mandrel update`, then walks the operator through the
 > **distribution-agnostic judgment steps** the CLI deliberately does **not**
@@ -66,7 +66,7 @@ envelope (`{ ok, blocked, findings[] }`) plus a human-readable report:
   the version probe.
 
 The preflight is a workflow-layer guard; it deliberately lives outside
-[`lib/cli/update.js`](../../lib/cli/update.js), which stays git-free.
+[`lib/cli/update.js`](https://github.com/dsj1984/mandrel/blob/main/lib/cli/update.js), which stays git-free.
 
 ## Step 1 — Run the updater
 
@@ -102,9 +102,9 @@ recovered and a clean re-run reports success.**
 
 Identify the failed phase (the CLI's stderr names it) and run the matching
 remedy. These commands match the hint strings
-[`lib/cli/update.js`](../../lib/cli/update.js) emits verbatim — it is the
+[`lib/cli/update.js`](https://github.com/dsj1984/mandrel/blob/main/lib/cli/update.js) emits verbatim — it is the
 single source of truth, kept in lockstep with this table by
-[`tests/bootstrap/mandrel-update-recovery-drift.test.js`](../../tests/bootstrap/mandrel-update-recovery-drift.test.js):
+[`tests/bootstrap/mandrel-update-recovery-drift.test.js`](https://github.com/dsj1984/mandrel/blob/main/tests/bootstrap/mandrel-update-recovery-drift.test.js):
 
 | Failed phase      | Manual remedy                                            |
 | ----------------- | ------------------------------------------------------- |

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.19.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.18.0...mandrel-v2.19.0) (2026-07-27)
+
+
+### Added
+
+* check-baselines: generalize the one-shot baseline-refresh acknowledgment across every ratcheted kind ([#4802](https://github.com/dsj1984/mandrel/issues/4802)) ([#4805](https://github.com/dsj1984/mandrel/issues/4805)) ([ec9b066](https://github.com/dsj1984/mandrel/commit/ec9b066a5d4f74eb53f88ab347138b3434ffa47b))
+* **doc-links:** reject links escaping the materialized .agents payload (refs [#4801](https://github.com/dsj1984/mandrel/issues/4801)) ([#4803](https://github.com/dsj1984/mandrel/issues/4803)) ([97a383a](https://github.com/dsj1984/mandrel/commit/97a383a4765a9a617648f6c1b422c17d837b6ad8))
+
 ## [2.18.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.17.0...mandrel-v2.18.0) (2026-07-26)
 
 

package/package.json

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