mandrel 2.17.0 → 2.19.0

package/.agents/scripts/lib/observability/terse-result.js

@@ -1,6 +1,7 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
+import { orchestrationLogDir } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 
 /**
@@ -69,8 +70,10 @@ function detailBlock(label, result) {
  *   on; serialized compactly onto the single summary line.
  * @param {string|number} [args.scope] Disambiguating suffix for the log name
  *   (typically the Story id) so concurrent deliveries don't clobber one file.
- * @param {string} [args.logDir] Directory for the detail log. Defaults to
- *   `<cwd>/temp/orchestration`.
+ * @param {string} [args.logDir] Directory for the detail log. Defaults to the
+ *   configured `<tempRoot>/orchestration` (Story #4794 — was a hardcoded
+ *   `<cwd>/temp/orchestration`, which ignored `project.paths.tempRoot`).
+ * @param {object} [args.config] Resolved config bag, for the default `logDir`.
  * @param {typeof nodeFs} [args.fs] Filesystem seam (tests).
  * @param {{ info: (m: string) => void }} [args.log] Logger seam (tests).
  * @param {NodeJS.ProcessEnv} [args.env] Environment seam (tests).
@@ -82,6 +85,7 @@ export function emitTerseResult({
   summary = {},
   scope,
   logDir,
+  config,
   fs = nodeFs,
   log = Logger,
   env = process.env,
@@ -94,7 +98,7 @@ export function emitTerseResult({
     return { logPath: null, inline: true };
   }
 
-  const dir = logDir ?? path.join(process.cwd(), 'temp', 'orchestration');
+  const dir = logDir ?? orchestrationLogDir(config);
   const name = `${slugify(label)}${scope ? `-${scope}` : ''}.log`;
 
   try {

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/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -37,13 +37,12 @@
  * @module lib/orchestration/plan-persist/run-plan-persist
  */
 
-import { readdir, rm, stat } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
 import path from 'node:path';
-
-import { anchorTempRoot, tempRootFrom } from '../../config/temp-paths.js';
 import { getLimits, PROJECT_ROOT } from '../../config-resolver.js';
 import { gitSpawn } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
+import { sweepTempRetention } from '../../temp-retention.js';
 import {
   deriveStoryShape,
   LITE_ROUTE_LABEL,
@@ -374,13 +373,6 @@ function resolveEffectiveRoute({
   };
 }
 
-/**
- * Age after which an abandoned `temp/plan-*` directory is reaped. A plan run
- * that is still being authored is minutes-to-hours old; a week is far past
- * any live run and comfortably past an operator returning to a paused one.
- */
-const STALE_PLAN_DIR_MS = 7 * 24 * 60 * 60 * 1000;
-
 /**
  * Reap abandoned `plan-*` directories under the temp root (Story #4541).
  *
@@ -389,9 +381,16 @@ const STALE_PLAN_DIR_MS = 7 * 24 * 60 * 60 * 1000;
  * `--dry-run` left its directory behind forever. This sweeps the stragglers
  * on each persist.
  *
+ * Story #4794 folded the age-floored reap into the shared temp-retention
+ * engine — `planDirs` is one of its declared classes, so the plan path and
+ * the delivery path now converge on one classifier and one staleness floor
+ * (`delivery.tempRetention.staleDays`, still 7 days by default) instead of
+ * this module owning a private constant. Behaviour is unchanged: only
+ * `plan-*` directories are considered, the age test is the directory's own
+ * mtime, and the current run's `planDir` is excluded.
+ *
  * Best-effort throughout: this is hygiene, never a reason to fail a run that
- * has already created Stories. The current run's own `planDir` is always
- * excluded — its cleanup is the caller's decision.
+ * has already created Stories.
  *
  * @param {{ config?: object, keepDir?: string|null, now?: number }} args
  * @returns {Promise<{ reaped: string[] }>}
@@ -401,35 +400,14 @@ export async function reapStalePlanDirs({
   keepDir = null,
   now = Date.now(),
 } = {}) {
-  const reaped = [];
-  const tempRoot = anchorTempRoot(tempRootFrom(config));
-  let entries;
-  try {
-    entries = await readdir(tempRoot, { withFileTypes: true });
-  } catch {
-    return { reaped }; // No temp root yet — nothing to reap.
-  }
-  const keep = keepDir ? path.resolve(keepDir) : null;
-  for (const entry of entries) {
-    if (!entry.isDirectory() || !entry.name.startsWith('plan-')) continue;
-    const dir = path.resolve(tempRoot, entry.name);
-    if (keep !== null && dir === keep) continue;
-    try {
-      const { mtimeMs } = await stat(dir);
-      if (now - mtimeMs < STALE_PLAN_DIR_MS) continue;
-      await rm(dir, { recursive: true, force: true });
-      reaped.push(dir);
-    } catch {
-      // A racing writer or a permission error: leave it for the next run.
-    }
-  }
-  if (reaped.length > 0) {
-    Logger.info(
-      `[plan-persist] reaped ${reaped.length} abandoned plan director(ies) ` +
-        `older than 7d under ${tempRoot}.`,
-    );
-  }
-  return { reaped };
+  const result = await sweepTempRetention({
+    config,
+    only: ['planDirs'],
+    excludePaths: keepDir ? [keepDir] : [],
+    now,
+    label: 'plan-persist',
+  });
+  return { reaped: result.purged.map((entry) => entry.path) };
 }
 
 /**

package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js

@@ -59,6 +59,7 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
+import { orchestrationLogDir } from '../../config/temp-paths.js';
 import { Logger, resolveLevel } from '../../Logger.js';
 
 /**
@@ -210,26 +211,29 @@ function createArtifactWriter(fs, logPath, handle) {
  *
  * @param {{
  *   storyId: number|null,
- *   cwd?: string,
  *   logDir?: string,
  *   fs?: typeof nodeFs,
  *   logger?: { info: (m: string) => void },
  *   level?: string,
- * }} [args] `logDir` defaults to `<cwd>/temp/orchestration`; `level` defaults
- *   to the live Logger level so `AGENT_LOG_LEVEL=verbose` restores streaming.
+ *   config?: object,
+ * }} [args] `logDir` defaults to the configured `<tempRoot>/orchestration`
+ *   (Story #4794 — was a hardcoded `<cwd>/temp/orchestration`, which ignored
+ *   `project.paths.tempRoot` and hid the artifact from the retention purge);
+ *   `level` defaults to the live Logger level so `AGENT_LOG_LEVEL=verbose`
+ *   restores streaming.
  * @returns {GateLogSink}
  */
 export function createGateLogSink({
   storyId = null,
-  cwd = process.cwd(),
   logDir,
   fs = nodeFs,
   logger = Logger,
   level,
+  config,
 } = {}) {
   const emit = (line) => logger.info?.(line);
   const verbose = (level ?? resolveLevel()) === 'verbose';
-  const dir = logDir ?? path.join(cwd, 'temp', 'orchestration');
+  const dir = logDir ?? orchestrationLogDir(config);
 
   let writer = null;
   let logPath = null;

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -143,7 +143,7 @@ export async function runCloseValidationPhase({
   );
   // Story #4736 — one sink for both `log` seams (gate construction and gate
   // execution), so nothing in the chain can route around the artifact.
-  const gateLog = createGateLogSink({ storyId, cwd });
+  const gateLog = createGateLogSink({ storyId, config });
   let validation;
   try {
     validation = await runCloseValidation({

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -39,6 +39,7 @@ import {
   RUNTIME_FRICTION_CATEGORIES,
 } from '../../../observability/runtime-friction.js';
 import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
+import { purgeStoryTempArtifacts as defaultPurgeStoryTempArtifacts } from '../../../temp-retention.js';
 import {
   executeFastForward as defaultExecuteFastForward,
   planFastForward as defaultPlanFastForward,
@@ -224,6 +225,22 @@ async function stepBaseFastForward({
   };
 }
 
+/**
+ * Purge this Story's spent temp artifacts now that its merge is confirmed
+ * (Story #4794).
+ *
+ * The engine already emits its own one-line summary and returns a disabled
+ * policy as `skipped` with no errors, so this step needs no branching of its
+ * own: errors degrade it, everything else — including a deliberate
+ * config-disabled no-op — is a success. Reporting a disabled purge as a failed
+ * step would train readers to ignore the field.
+ */
+async function stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }) {
+  const result = await purgeStoryTempArtifactsFn({ storyId, config });
+  const errors = result?.errors ?? [];
+  return { ok: errors.length === 0, detail: errors.join('; ') || null };
+}
+
 /**
  * Run the whole post-land tail. Never throws.
  *
@@ -262,7 +279,8 @@ async function stepBaseFastForward({
  * @param {Function} [args.planFastForwardFn]       Test seam.
  * @param {Function} [args.executeFastForwardFn]    Test seam.
  * @param {Function} [args.acquireLockWithWaitFn]   Test seam.
- * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, details: Record<string, string|null> }>}
+ * @param {Function} [args.purgeStoryTempArtifactsFn] Test seam.
+ * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
   storyId,
@@ -280,6 +298,7 @@ export async function runPostLandTail({
   planFastForwardFn = defaultPlanFastForward,
   executeFastForwardFn = defaultExecuteFastForward,
   acquireLockWithWaitFn = defaultAcquireLockWithWait,
+  purgeStoryTempArtifactsFn = defaultPurgeStoryTempArtifacts,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -373,16 +392,27 @@ export async function runPostLandTail({
     if (lock.acquired) lock.release();
   }
 
+  // Story #4794 — the merge is confirmed, so this Story's gate transcripts and
+  // validation evidence are spent. Runs LAST so a purge can never race a step
+  // that still reads them, and outside the checkout lock because it touches
+  // only the temp tree. Its `signals.ndjson` survives by construction.
+  const tempPurge = await step(
+    () => stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }),
+    { name: 'temp purge', progress },
+  );
+
   const tail = {
     followUps: followUps.ok,
     statusResync: statusResync.ok,
     refCleanup: refCleanup.ok,
     baseFastForward: baseFastForward.ok,
+    tempPurge: tempPurge.ok,
     details: {
       followUps: followUps.detail,
       statusResync: statusResync.detail,
       refCleanup: refCleanup.detail,
       baseFastForward: baseFastForward.detail,
+      tempPurge: tempPurge.detail,
     },
   };
   const degraded = Object.entries(tail)

package/.agents/scripts/lib/single-story-sweep.js

@@ -90,6 +90,7 @@ const STORY_BRANCH_INCLUDE = 'story-*';
  *   candidates: number,
  *   localDeleted: number,
  *   remoteDeleted: number,
+ *   reaped: string[],
  *   protected: Array<{ branch: string, reason: string, worktreePath?: string|null }>,
  *   contentMerged: Array<{ branch: string, worktreePath: string|null }>,
  *   failures: Array<{ branch: string|null, scope: string, stderr?: string }>,
@@ -147,6 +148,7 @@ export async function sweepMergedBranches({
         candidates: 0,
         localDeleted: 0,
         remoteDeleted: 0,
+        reaped: [],
         protected: [],
         contentMerged: [],
         failures: [],
@@ -296,6 +298,7 @@ async function runSweepUnderLock({
       candidates: 0,
       localDeleted: 0,
       remoteDeleted: 0,
+      reaped: [],
       protected: [],
       contentMerged,
       failures: [],
@@ -320,6 +323,7 @@ async function runSweepUnderLock({
       candidates: reapCandidates.length,
       localDeleted: 0,
       remoteDeleted: 0,
+      reaped: [],
       protected: protectedList,
       contentMerged,
       failures: [],
@@ -365,6 +369,7 @@ function executeReap({
       candidates: candidateCount,
       localDeleted: 0,
       remoteDeleted: 0,
+      reaped: [],
       protected: protectedList,
       contentMerged,
       failures: [{ branch: null, scope: 'execute', stderr: msg }],
@@ -398,6 +403,11 @@ function executeReap({
     candidates: candidateCount,
     localDeleted,
     remoteDeleted,
+    // Story #4794 — the branch names, not just the count. Each one is a merge
+    // this sweep CONFIRMED (merged PR + matching headRefOid), which is exactly
+    // the evidence the temp-retention catch-up needs to purge that Story's
+    // spent artifacts. Previously these existed only inside a log string.
+    reaped: reapable.map((c) => c.branch),
     protected: protectedList,
     contentMerged,
     failures: result.failures,
@@ -503,6 +513,7 @@ function zeroResult({ error }) {
     candidates: 0,
     localDeleted: 0,
     remoteDeleted: 0,
+    reaped: [],
     protected: [],
     contentMerged: [],
     failures: [],