mandrel 2.17.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/docs/agentrc-reference.json

@@ -128,6 +128,16 @@
     "docsFreshness": {
       "paths": ["README.md"]
     },
+    "tempRetention": {
+      "enabled": true,
+      "staleDays": 7,
+      "classes": {
+        "orchestrationLogs": true,
+        "validationEvidence": true,
+        "auditResults": true,
+        "planDirs": true
+      }
+    },
     "deliverRunner": {
       "concurrencyCap": 3
     },

package/.agents/docs/configuration.md

@@ -125,6 +125,14 @@ top-level keys are validation errors.
 | `lease.ttlMs` | No | `integer` | — | — |
 | `docsFreshness` | No | `object` | — | Nested configuration block. |
 | `docsFreshness.paths` | No | `array` | — | — |
+| `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path. |
+| `tempRetention.enabled` | No | `boolean` | — | Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op. |
+| `tempRetention.staleDays` | No | `integer` | — | Age floor (days, default 7) for the families no Story id can be recovered from — roster-level audit reports and abandoned plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are purged as soon as their merge is confirmed. |
+| `tempRetention.classes` | No | `object` | — | Per-class opt-out. Each defaults to true; set one false to keep that family while the rest are purged. |
+| `tempRetention.classes.orchestrationLogs` | No | `boolean` | — | <tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps. |
+| `tempRetention.classes.validationEvidence` | No | `boolean` | — | Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees. |
+| `tempRetention.classes.auditResults` | No | `boolean` | — | <tempRoot>/audits/ — audit lens reports. |
+| `tempRetention.classes.planDirs` | No | `boolean` | — | <tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded. |
 | `deliverRunner` | No | `object` | — | Nested configuration block. |
 | `deliverRunner.concurrencyCap` | No | `integer` | — | Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
 | `worktreeIsolation` | No | `object` | — | Nested configuration block. |

package/.agents/schemas/agentrc.schema.json

@@ -441,6 +441,45 @@
       },
       "additionalProperties": false
     },
+    "tempRetention": {
+      "type": "object",
+      "description": "Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op."
+        },
+        "staleDays": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Age floor (days, default 7) for the families no Story id can be recovered from — roster-level audit reports and abandoned plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are purged as soon as their merge is confirmed."
+        },
+        "classes": {
+          "type": "object",
+          "description": "Per-class opt-out. Each defaults to true; set one false to keep that family while the rest are purged.",
+          "properties": {
+            "orchestrationLogs": {
+              "type": "boolean",
+              "description": "<tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps."
+            },
+            "validationEvidence": {
+              "type": "boolean",
+              "description": "Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees."
+            },
+            "auditResults": {
+              "type": "boolean",
+              "description": "<tempRoot>/audits/ — audit lens reports."
+            },
+            "planDirs": {
+              "type": "boolean",
+              "description": "<tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "docsFreshness": {
       "type": "object",
       "properties": {
@@ -1324,6 +1363,9 @@
         "docsFreshness": {
           "$ref": "#/$defs/docsFreshness"
         },
+        "tempRetention": {
+          "$ref": "#/$defs/tempRetention"
+        },
         "deliverRunner": {
           "$ref": "#/$defs/deliverRunner"
         },

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -86,13 +86,18 @@
         "followUps",
         "statusResync",
         "refCleanup",
-        "baseFastForward"
+        "baseFastForward",
+        "tempPurge"
       ],
       "properties": {
         "followUps": { "type": "boolean" },
         "statusResync": { "type": "boolean" },
         "refCleanup": { "type": "boolean" },
         "baseFastForward": { "type": "boolean" },
+        "tempPurge": {
+          "type": "boolean",
+          "description": "Story #4794 — the merged Story's spent temp artifacts (gate transcripts, validation evidence) were purged under delivery.tempRetention. A disabled policy reports true: the operator turned the purge off, so doing nothing IS the correct outcome. Only a real failure — an unreadable temp root, an undeletable artifact — reports false, and like every tail step that degrades the report, never the land."
+        },
         "details": {
           "type": "object",
           "description": "Per-step diagnostic detail — the reason a false step reported false.",

package/.agents/scripts/boot-sweep.js

@@ -46,6 +46,25 @@ import { Logger } from './lib/Logger.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
+import { sweepTempRetention } from './lib/temp-retention.js';
+
+/**
+ * Recover the Story ids from the branch names a sweep reaped. Only the
+ * canonical `story-<id>` shape yields an id — an operator's ad-hoc branch that
+ * happened to match the include glob contributes nothing, so a purge can never
+ * be triggered by a name this framework did not create.
+ *
+ * @param {string[]|undefined} branches
+ * @returns {number[]}
+ */
+export function storyIdsFromBranches(branches) {
+  const ids = [];
+  for (const branch of Array.isArray(branches) ? branches : []) {
+    const match = /^story-(\d+)$/.exec(String(branch));
+    if (match) ids.push(Number(match[1]));
+  }
+  return ids;
+}
 
 const HELP = `Usage: node .agents/scripts/boot-sweep.js [options]
 
@@ -85,9 +104,11 @@ Options:
  *   injectedConfig?: object,
  *   injectedProvider?: object,
  *   injectedSweep?: Function,
+ *   purgeFn?: Function,
  *   logger?: { info?: Function, warn?: Function },
  * }} [args]
- * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope, plus a
+ *   `tempPurge` result from the Story #4794 temp-retention catch-up.
  */
 export async function runBootSweep({
   cwd,
@@ -99,6 +120,7 @@ export async function runBootSweep({
   injectedConfig,
   injectedProvider,
   injectedSweep,
+  purgeFn = sweepTempRetention,
   logger = Logger,
 } = {}) {
   const root = path.resolve(cwd ?? PROJECT_ROOT);
@@ -125,7 +147,7 @@ export async function runBootSweep({
       config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
 
     const sweepFn = injectedSweep ?? sweepMergedBranches;
-    return await sweepFn({
+    const result = await sweepFn({
       cwd: root,
       baseBranch,
       include: includeGlobs,
@@ -140,6 +162,21 @@ export async function runBootSweep({
       lockPath,
       lockTimeoutMs,
     });
+
+    // Story #4794 — the temp-retention catch-up. Two eligibility signals, both
+    // already paid for: every branch this sweep reaped is a merge it CONFIRMED
+    // (merged PR + matching headRefOid), so those Stories' artifacts are spent;
+    // and the age floor collects everything else — the backlog from Stories
+    // merged before this existed, merged through the GitHub UI, or whose branch
+    // was already gone. Best-effort like the sweep itself: `runBootSweep`'s
+    // catch swallows any throw into the `ok: false` envelope, and exit stays 0.
+    const purge = await purgeFn({
+      config,
+      mergedStoryIds: storyIdsFromBranches(result?.reaped),
+      label: 'boot-sweep',
+      logger,
+    });
+    return { ...result, tempPurge: purge };
   } catch (err) {
     const msg = err?.message ?? String(err);
     logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);

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/config/temp-paths.js

@@ -274,6 +274,33 @@ export function tempRootFrom(config) {
     : 'temp';
 }
 
+/**
+ * Directory segment (under `tempRoot`) holding every orchestration run log —
+ * the close gate transcripts (`close-gates-<sid>.log`) and the terse-result
+ * detail dumps (`story-init-result-<sid>.log`, `sync-result-<branch>.log`, …).
+ *
+ * Story #4794: the four writers that land here each hand-rolled the temp path
+ * from a literal `temp` segment joined onto their own cwd, which ignores
+ * `project.paths.tempRoot` entirely. On a consumer that relocates its temp
+ * root, the writers wrote to `<cwd>/temp/` while every reader — including the
+ * retention purge — resolved the configured root, so the artifacts were
+ * invisible to the tooling meant to manage them. Routing all four through this
+ * helper also picks up main-checkout anchoring for free, so a close running
+ * from a Story worktree lands its logs in the same tree the host reads.
+ */
+export const ORCHESTRATION_DIRNAME = 'orchestration';
+
+/**
+ * `<tempRoot>/orchestration/` — resolved against the configured temp root and
+ * anchored to the main checkout, like every other helper in this module.
+ *
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function orchestrationLogDir(config) {
+  return path.join(anchorTempRoot(tempRootFrom(config)), ORCHESTRATION_DIRNAME);
+}
+
 const runId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -352,12 +352,81 @@ const AUDIT_TO_STORIES_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * `delivery.tempRetention` — auto-purge of spent temp artifacts (Story #4794).
+ *
+ * `enabled` defaults to `true`: reclaiming a landed Story's gate transcripts
+ * and evidence is the behaviour, and the knob exists to turn it off. `classes`
+ * lets an operator keep one family while purging the rest; `staleDays` is the
+ * age floor for the families no Story id can be recovered from (audit reports,
+ * abandoned `plan-<slug>/` dirs).
+ */
+const TEMP_RETENTION_SCHEMA = {
+  type: 'object',
+  description:
+    'Story #4794. Auto-purge of spent temp artifacts once their Story lands. ' +
+    'Classification is an allowlist: only the declared classes below are ever ' +
+    'deleted, so operator scratch files under tempRoot are reported with their ' +
+    'size and left alone. signals.ndjson is never purged by any path.',
+  properties: {
+    enabled: {
+      type: 'boolean',
+      description:
+        "Master switch. Default true — reclaiming a landed Story's gate " +
+        'transcripts and validation evidence is the behaviour, and this knob ' +
+        'turns it off. When false every purge path is a reported no-op.',
+    },
+    staleDays: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Age floor (days, default 7) for the families no Story id can be ' +
+        'recovered from — roster-level audit reports and abandoned ' +
+        'plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are ' +
+        'purged as soon as their merge is confirmed.',
+    },
+    classes: {
+      type: 'object',
+      description:
+        'Per-class opt-out. Each defaults to true; set one false to keep that ' +
+        'family while the rest are purged.',
+      properties: {
+        orchestrationLogs: {
+          type: 'boolean',
+          description:
+            '<tempRoot>/orchestration/*.log — close gate transcripts and ' +
+            'terse-result detail dumps.',
+        },
+        validationEvidence: {
+          type: 'boolean',
+          description:
+            'Per-Story validation-evidence.json, lifecycle.ndjson, and ' +
+            'manifest.md under the standalone and per-run story trees.',
+        },
+        auditResults: {
+          type: 'boolean',
+          description: '<tempRoot>/audits/ — audit lens reports.',
+        },
+        planDirs: {
+          type: 'boolean',
+          description:
+            '<tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. ' +
+            'Age-floored only; the current run is always excluded.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  additionalProperties: false,
+};
+
 export const DELIVERY_SCHEMA = {
   type: 'object',
   properties: {
     execution: EXECUTION_SCHEMA,
     lease: LEASE_SCHEMA,
     docsFreshness: DOCS_FRESHNESS_SCHEMA,
+    tempRetention: TEMP_RETENTION_SCHEMA,
     deliverRunner: DELIVER_RUNNER_SCHEMA,
     worktreeIsolation: WORKTREE_ISOLATION_SCHEMA,
     signals: SIGNALS_SCHEMA,