mandrel 2.18.0 → 2.20.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

@@ -67,27 +67,6 @@
     }
   },
   "planning": {
-    "codebaseSnapshot": {
-      "tier": "skinny",
-      "include": [
-        ".agents/scripts/**",
-        "src/**",
-        "lib/**",
-        "app/**",
-        "packages/**"
-      ],
-      "exclude": [
-        "**/node_modules/**",
-        "**/dist/**",
-        "**/build/**",
-        "**/.next/**",
-        "**/.turbo/**",
-        "**/coverage/**",
-        "**/*.test.*",
-        "**/*.spec.*"
-      ],
-      "recentCommitWindow": 30
-    },
     "riskHeuristics": [
       "Destructive or irreversible data mutations (dropping tables, deleting rows without soft-delete or backup, truncating production state).",
       "Modifications to shared security or auth infrastructure (IAM policies, auth middleware, session or token handling, secret rotation).",

package/.agents/docs/configuration.md

@@ -26,7 +26,7 @@ with the runtime validators.
   "$schema": "./.agents/schemas/agentrc.schema.json",
   "project":  { /* paths, commands, baseBranch, docsContextFiles */ },
   "github":   { /* owner, repo, branchProtection, mergeMethods, notifications */ },
-  "planning": { /* riskHeuristics, conflict gates, codebaseSnapshot, context */ },
+  "planning": { /* riskHeuristics, conflict gates, complexityGate, navigation */ },
   "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ }
 }
 ```
@@ -38,7 +38,7 @@ top-level keys are validation errors.
 | ------------- | -------- | ---------------------------------------------------------------------------------- |
 | `project`     | **Yes**  | Project-local paths, base branch, validation commands, and context-hydration files. |
 | `github`      | No       | Ticketing provider config: owner/repo, branch protection, merge methods, notifications. |
-| `planning`    | No       | `/plan` tuning: conflict advisories, codebase snapshot, context cap. (Story sizing ceilings are code-absolute — not agentrc.) |
+| `planning`    | No       | `/plan` tuning: conflict advisories, complexity routing, navigability gate. (Story sizing ceilings and the planner-context cap are code-absolute — not agentrc.) |
 | `delivery`    | No       | `/deliver` tuning: quality gates, worktree isolation, runners, CI watch, code-review providers. |
 | `$schema`     | No       | JSON Schema pointer for editor tooling.                                            |
 
@@ -97,11 +97,6 @@ top-level keys are validation errors.
 | Key | Required | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `riskHeuristics` | No | `string[]` or `{ append?, prepend? }` | — | — |
-| `codebaseSnapshot` | No | `object` | — | Nested configuration block. |
-| `codebaseSnapshot.tier` | No | `"skinny"` \| `"medium"` | — | — |
-| `codebaseSnapshot.include` | No | `array<string>` | — | — |
-| `codebaseSnapshot.exclude` | No | `array<string>` | — | — |
-| `codebaseSnapshot.recentCommitWindow` | No | `integer` | — | — |
 | `complexityGate` | No | `object` | — | Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables. |
 | `complexityGate.enabled` | No | `boolean` | — | Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true. |
 | `complexityGate.maxArtifacts` | No | `integer` | — | Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1. |
@@ -352,13 +347,15 @@ Defaults are **advisory, not Story-width ceilings**. Session-mass ceilings live
 as absolute authored-token constants on `DEFAULT_MODEL_CAPACITY` in
 `ticket-validator-sizing.js` (soft 30k / hard 75k); there is no `maxTokenBudget`
 envelope, and cohesion / split policy / conflict advisories are the primary
-sizing signal. The `codebaseSnapshot` `skinny` tier caps at 250 paths using
-**per-top-level-directory proportional budgeting** (round-robin across matched
-trees) so a large dot-prefixed tree like `.agents/scripts/**` cannot monopolise
-the budget and truncate away the consumer's own source; the shipped `include`
-scans `.agents/scripts/**`, `src/**`, `lib/**`, `app/**`, `packages/**` and
-`exclude` drops `node_modules`, build dirs, and test files. Override `include`
-only when the project's source layout differs.
+sizing signal.
+
+There is no snapshot knob to tune: Story #4811 retired the structural-snapshot
+block outright. Spec authoring is grounded by the author's own targeted repo
+retrieval plus the Phase 8 `validateStoryFileAssumptions` gate, which probes
+every authored `{path, assumption}` against the real tree as a hard error — a
+pre-computed inventory added a second, staler answer to the same question.
+A config still carrying the retired key is a hard validation failure; the
+2.20.0 retirement migration strips it on upgrade.
 
 - **`complexityGate`.** Shape-derived ceremony-lite routing (Story #4722,
   superseding the word-count gate of Stories #4683/#4707). The full ceremony

package/.agents/docs/execution-reference.md

@@ -96,12 +96,15 @@ over-ceiling envelope or an over-budget Story count.
 - **`PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`** (`lib/orchestration/plan-context.js`):
   256 KB (≈64K tokens at the ≈4-chars/token estimate) on the serialized
   envelope `buildPlanContext` assembles, checked at the single choke point
-  every mode returns through. Measured envelopes on this repo land at ~42 KB,
-  so the ceiling is >2× headroom over a worst-case seed plus a medium-tier
-  codebase snapshot.
+  every mode returns through. A measured seed-mode envelope on this repo is
+  ~120 KB — `docsContext` (~63 KB) and `systemPrompts` (~54 KB) are the whole
+  of it, every other field under 1 KB — so the ceiling carries roughly 2×
+  headroom. Story #4811 retired the codebase snapshot that used to sit
+  alongside them, leaving the operator-supplied seed the only unbounded
+  contributor.
 - **On refusal**, the error names the envelope's largest fields. Trim the seed,
-  plan fewer `--tickets` source issues in one run, or narrow
-  `planning.codebaseSnapshot`. The seed is carried **verbatim** by design — it
+  or plan fewer `--tickets` source issues in one run. The seed is carried
+  **verbatim** by design — it
   is the operator's request, and summarizing it silently would degrade planning
   quality precisely when the input is richest — so there is no elision path to
   fall back on. Raising the ceiling needs a measured justification.

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

@@ -324,9 +324,6 @@
         "riskHeuristics": {
           "$ref": "#/$defs/listOrExtenderOfStrings"
         },
-        "codebaseSnapshot": {
-          "$ref": "#/$defs/codebaseSnapshot"
-        },
         "complexityGate": {
           "type": "object",
           "description": "Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.",
@@ -392,34 +389,6 @@
       },
       "additionalProperties": false
     },
-    "codebaseSnapshot": {
-      "type": "object",
-      "properties": {
-        "tier": {
-          "type": "string",
-          "enum": ["skinny", "medium"]
-        },
-        "include": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "exclude": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "recentCommitWindow": {
-          "type": "integer",
-          "minimum": 1
-        }
-      },
-      "additionalProperties": false
-    },
     "execution": {
       "type": "object",
       "properties": {

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/check-test-temp-hygiene.js

@@ -15,16 +15,41 @@
  * per-process scratch dir. This script is the regression guard that keeps
  * the fix honest, plus a local cleanup mode for the accumulated noise:
  *
+ * The guard covers two distinct temp roots, and conflating them is how the
+ * second one went unmeasured for so long:
+ *
+ *   1. The repo's own `temp/` telemetry tree — the original dimension above.
+ *   2. The **OS temp root** (Story #4808). The redirect in (1) sends stray
+ *      writes into `os.tmpdir()` scratch dirs, and nothing ever reaped them:
+ *      the remedy for (1) became the largest single leaker into (2). Since
+ *      the damaging axis there is entry *count*, the suite now nests every
+ *      managed dir inside one per-process `mandrel-suite-*` root
+ *      (`lib/test-temp.js`) and reaps it, and this guard asserts that no
+ *      such root survives a run.
+ *
  *   --snapshot         Record a fingerprint (size + sha256) of every stream
- *                      file under `temp/` to the snapshot baseline. Run this
- *                      before the suite.
+ *                      file under `temp/`, plus the `mandrel-suite-*` roots
+ *                      already present in the OS temp root, to the snapshot
+ *                      baseline. Run this before the suite.
  *   --assert           Re-scan and fail if any stream file was added or grew
- *                      relative to the snapshot. Run this after the suite. A
- *                      missing snapshot is a hard failure ("snapshot missing
+ *                      relative to the snapshot, or if a suite root appeared
+ *                      and survived. Run this after the suite. A missing
+ *                      snapshot is a hard failure ("snapshot missing
  *                      — guard cannot attest"), never a silent re-baseline:
  *                      the baseline lives *outside* the protected `temp/`
  *                      tree (Story #4711), so a test wiping `temp/` can no
  *                      longer destroy the baseline and fail the guard open.
+ *                      Recording pre-existing suite roots (rather than
+ *                      asserting an empty set) is what keeps a concurrent
+ *                      suite in another checkout from failing this one.
+ *   --lint-globs <g>   Comma-separated repo-relative globs to scan for test
+ *                      files that call `mkdtemp` against `os.tmpdir()`
+ *                      directly instead of going through `makeTempDir`.
+ *                      **Off unless passed**: this script ships in the
+ *                      materialized `.agents/` payload and a consumer's
+ *                      tests are none of this rule's business. A line (or
+ *                      the line above it) carrying `test-temp-allow` opts
+ *                      out.
  *   --baseline <path>  Explicit snapshot-baseline path (CI sets this to a
  *                      runner-temp path). Defaults to an OS scratch location
  *                      keyed by the resolved repo root. Refused when it
@@ -53,6 +78,12 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  findRawTmpdirMkdtemp,
+  listSuiteTempRoots,
+  SUITE_ROOTS_KEY,
+  survivingSuiteTempRoots,
+} from './lib/test-temp.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -193,17 +224,27 @@ export function buildManifest(tempDir) {
  * `defaultBaselinePath` — never inside `temp/`).
  * @param {string} repoRoot
  * @param {string} [baselinePath]
- * @returns {{ snapshotPath: string, count: number }}
+ * @param {{ tmpDir?: string }} [deps] Injectable OS temp root for tests.
+ * @returns {{ snapshotPath: string, count: number, suiteRoots: number }}
  */
-export function writeSnapshot(repoRoot, baselinePath) {
+export function writeSnapshot(repoRoot, baselinePath, { tmpDir } = {}) {
   const snapshotPath = checkedBaselinePath(
     repoRoot,
     baselinePath ?? defaultBaselinePath(repoRoot),
   );
   const manifest = buildManifest(tempDirFor(repoRoot));
+  const count = Object.keys(manifest).length;
+  // Reserved key: stream entries are always `*.ndjson` relative paths, so
+  // this cannot shadow one, and `diffAgainstSnapshot` only ever looks up
+  // keys derived from the tree it just walked.
+  manifest[SUITE_ROOTS_KEY] = listSuiteTempRoots(tmpDir ?? os.tmpdir());
   mkdirSync(path.dirname(snapshotPath), { recursive: true });
   writeFileSync(snapshotPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-  return { snapshotPath, count: Object.keys(manifest).length };
+  return {
+    snapshotPath,
+    count,
+    suiteRoots: manifest[SUITE_ROOTS_KEY].length,
+  };
 }
 
 /**
@@ -331,7 +372,7 @@ export function cleanFixtureDirs({
 /**
  * Parse the CLI argv into a normalised options object.
  * @param {string[]} argv
- * @returns {{ mode: 'snapshot'|'assert'|'clean', apply: boolean, ids: number[]|null, repoRoot: string, baseline: string|null }}
+ * @returns {{ mode: 'snapshot'|'assert'|'clean', apply: boolean, ids: number[]|null, repoRoot: string, baseline: string|null, lintGlobs: string[] }}
  */
 export function parseArgv(argv) {
   let mode = 'assert';
@@ -339,13 +380,20 @@ export function parseArgv(argv) {
   let ids = null;
   let repoRoot = REPO_ROOT;
   let baseline = null;
+  let lintGlobs = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--snapshot') mode = 'snapshot';
     else if (arg === '--assert') mode = 'assert';
     else if (arg === '--clean') mode = 'clean';
     else if (arg === '--yes') apply = true;
-    else if (arg === '--ids') {
+    else if (arg === '--lint-globs') {
+      i += 1;
+      lintGlobs = String(argv[i] ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (arg === '--ids') {
       i += 1;
       ids = String(argv[i] ?? '')
         .split(',')
@@ -359,7 +407,7 @@ export function parseArgv(argv) {
       baseline = path.resolve(String(argv[i] ?? '.'));
     }
   }
-  return { mode, apply, ids, repoRoot, baseline };
+  return { mode, apply, ids, repoRoot, baseline, lintGlobs };
 }
 
 /**
@@ -369,14 +417,23 @@ export function parseArgv(argv) {
  *
  * @param {ReturnType<typeof parseArgv>} opts
  * @param {(line: string) => void} [log]
+ * @param {{ tmpDir?: string }} [deps] Injectable OS temp root for tests.
  * @returns {number}
  */
-export function runHygiene(opts, log = (l) => process.stdout.write(`${l}\n`)) {
-  const { mode, apply, ids, repoRoot, baseline = null } = opts;
+export function runHygiene(
+  opts,
+  log = (l) => process.stdout.write(`${l}\n`),
+  { tmpDir = os.tmpdir() } = {},
+) {
+  const { mode, apply, ids, repoRoot, baseline = null, lintGlobs = [] } = opts;
   if (mode === 'snapshot') {
-    const { snapshotPath, count } = writeSnapshot(repoRoot, baseline);
+    const { snapshotPath, count, suiteRoots } = writeSnapshot(
+      repoRoot,
+      baseline,
+      { tmpDir },
+    );
     log(
-      `[test-temp-hygiene] snapshot recorded (${count} stream file(s)) → ${snapshotPath}`,
+      `[test-temp-hygiene] snapshot recorded (${count} stream file(s), ${suiteRoots} pre-existing suite root(s)) → ${snapshotPath}`,
     );
     return 0;
   }
@@ -409,6 +466,26 @@ export function runHygiene(opts, log = (l) => process.stdout.write(`${l}\n`)) {
     );
     return 1;
   }
+  // Every dimension runs and reports; a failure in one must not hide a
+  // failure in another, so the exit code is the max rather than an
+  // early return.
+  const codes = [
+    assertStreamTree(repoRoot, snapshot, log),
+    assertNoSurvivingSuiteRoots(snapshot, log, tmpDir),
+    assertNoRawTmpdirMkdtemp(repoRoot, lintGlobs, log),
+  ];
+  return Math.max(...codes);
+}
+
+/**
+ * Dimension 1 — the repo's own `temp/` telemetry tree (Story #4696).
+ *
+ * @param {string} repoRoot
+ * @param {Record<string, unknown>} snapshot
+ * @param {(line: string) => void} log
+ * @returns {number} exit code
+ */
+function assertStreamTree(repoRoot, snapshot, log) {
   const { added, changed } = diffAgainstSnapshot(
     tempDirFor(repoRoot),
     snapshot,
@@ -428,6 +505,68 @@ export function runHygiene(opts, log = (l) => process.stdout.write(`${l}\n`)) {
   return 1;
 }
 
+/**
+ * Dimension 2 — the OS temp root (Story #4808). Fails when a suite root
+ * appeared since the snapshot and is still on disk, which means the run
+ * created it and never reaped it.
+ *
+ * @param {Record<string, unknown>} snapshot
+ * @param {(line: string) => void} log
+ * @param {string} tmpDir
+ * @returns {number} exit code
+ */
+function assertNoSurvivingSuiteRoots(snapshot, log, tmpDir) {
+  const before = Array.isArray(snapshot[SUITE_ROOTS_KEY])
+    ? snapshot[SUITE_ROOTS_KEY]
+    : [];
+  const surviving = survivingSuiteTempRoots(tmpDir, before);
+  if (surviving.length === 0) {
+    log('[test-temp-hygiene] OK — no suite temp roots survived the run.');
+    return 0;
+  }
+  log(
+    `[test-temp-hygiene] FAIL — ${surviving.length} suite temp root(s) survived in ${tmpDir}:`,
+  );
+  for (const name of surviving) log(`  + leaked ${name}`);
+  log(
+    '[test-temp-hygiene] a process minted a suite root and exited without reaping it. Do not delete these by hand — find the writer that bypassed makeTempDir().',
+  );
+  return 1;
+}
+
+/**
+ * Dimension 3 — the static backstop (Story #4808). Skipped, and reported
+ * as skipped, unless the caller passed `--lint-globs`.
+ *
+ * @param {string} repoRoot
+ * @param {string[]} globs
+ * @param {(line: string) => void} log
+ * @returns {number} exit code
+ */
+function assertNoRawTmpdirMkdtemp(repoRoot, globs, log) {
+  if (!globs || globs.length === 0) {
+    log(
+      '[test-temp-hygiene] SKIP — raw-tmpdir lint not requested (pass --lint-globs to enable).',
+    );
+    return 0;
+  }
+  const findings = findRawTmpdirMkdtemp(repoRoot, globs);
+  if (findings.length === 0) {
+    log(
+      '[test-temp-hygiene] OK — no test file mints OS temp dirs outside makeTempDir().',
+    );
+    return 0;
+  }
+  log(
+    `[test-temp-hygiene] FAIL — ${findings.length} raw os.tmpdir() mkdtemp call(s) in test files:`,
+  );
+  for (const f of findings) log(`  ${f.file}:${f.line}  ${f.text}`);
+  log(
+    "[test-temp-hygiene] use makeTempDir() from .agents/scripts/lib/test-temp.js so teardown is registered, or mark the line 'test-temp-allow: <reason>' when the real root is genuinely required.",
+  );
+  return 1;
+}
+
 runAsCli(
   import.meta.url,
   async () => {