mandrel 2.24.0 → 2.26.0

package/.agents/scripts/check-schema-references.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+
+/**
+ * CLI: report every JSON Schema under `.agents/schemas/` that no code path
+ * compiles.
+ *
+ * A well-formed schema sitting in a schema directory reads as an enforced
+ * contract to every human reader and every audit lens — existence plus valid
+ * syntax is taken for authority. When nothing actually compiles it, that
+ * reading is wrong in the most expensive direction: the reader believes a
+ * shape the runtime rejects. `friction-event.schema.json` sat unreferenced
+ * from the Epic #4406 envelope cutover until Story #4938; in between, an
+ * `/audit-documentation` lens graded a High finding against it as the live
+ * contract, the finding became an acceptance criterion, and the delivering
+ * worker had to overrule that criterion to avoid writing a payload the
+ * enforced validator drops. Two verification layers accepted the file
+ * because it existed and parsed. Only reading the code caught it.
+ *
+ * This gate is that code read, run every time instead of once by accident.
+ *
+ * ## What counts as a compiling reference
+ *
+ * Resolution is evidence-ranked; the first kind that hits wins, and the
+ * report names both the kind and the file that supplied the evidence, so a
+ * pass is auditable rather than merely green.
+ *
+ *   1. `literal`     — the schema's basename appears in a JS source. This is
+ *                      the ordinary idiom (`signal-validator.js` resolves
+ *                      `signal-event.schema.json` by literal path).
+ *   2. `schema-ref`  — another schema `$ref`s this file by name, and that
+ *                      schema is itself referenced. A `$ref` is a compile
+ *                      edge: AJV pulls the target in when the parent
+ *                      compiles.
+ *   3. `dynamic`     — the schema lives in a SUBDIRECTORY of the schema root
+ *                      that some JS source loads by computed path (a
+ *                      `` `${key}.schema.json` `` template), AND the
+ *                      schema's stem appears literally in a JS source as the
+ *                      key that would produce it. `lifecycle/` is loaded this
+ *                      way by `lib/orchestration/lifecycle/bus.js`, and
+ *                      `baselines/` by `lib/baselines/envelope.js`.
+ *
+ *                      BOTH halves are required. The directory evidence alone
+ *                      would bless every future file dropped into a
+ *                      dynamically-enumerated directory — the same blindness
+ *                      this gate exists to remove. Dynamic resolution is not
+ *                      offered for schemas sitting at the schema root: every
+ *                      root schema today is compiled by an explicit literal
+ *                      path, so a root-level stem match would be coincidence,
+ *                      not evidence.
+ *
+ * Anything left over is a finding — unless the schema says otherwise in its
+ * own body (see below). A finding is not an accusation of deadness; it is a
+ * demand that the file state which one it is.
+ *
+ * ## Recording a deliberate exemption
+ *
+ * A schema deliberately kept without a compiler declares it IN THE FILE, at
+ * the document root:
+ *
+ * ```json
+ * "x-mandrel-uncompiled": {
+ *   "reason": "Documented SSOT; AJV is deliberately not in this path.",
+ *   "runtimeGate": "lib/orchestration/foo.js#validateFooPayload"
+ * }
+ * ```
+ *
+ * In-file, never a side-car allowlist. The failure this gate answers was a
+ * reader trusting the schema document; the correction has to be legible to
+ * that same reader, in that same document. An allowlist elsewhere in the repo
+ * would leave the file itself still lying.
+ *
+ * Story #4938 left the tree with exactly one: `friction-event.schema.json` was
+ * deleted outright (its shape preserved field-for-field in
+ * `docs/archive/data-dictionary-2026-08.md`), and
+ * `model-attribution.schema.json` — a documented SSOT with a hand-rolled
+ * validator behind it — declared the marker.
+ *
+ * The gate answers "is anything compiling this?", not "is what compiles it
+ * faithful to it?". A schema whose hand-rolled mirror has silently drifted
+ * still passes here.
+ *
+ * Flags:
+ *   --root <path>  scan a different repository root (default: cwd)
+ *   --json         emit the structured envelope as single-line JSON
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+
+/** Schema root, relative to the repository root. */
+const SCHEMA_ROOT = path.join('.agents', 'schemas');
+
+/** Directories never worth walking for JS sources. */
+const SKIP_DIRS = new Set([
+  '.git',
+  '.worktrees',
+  'node_modules',
+  'coverage',
+  'temp',
+]);
+
+/** Source extensions that can compile a schema. */
+const JS_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
+
+/** Root keyword a schema uses to declare a deliberate exemption. */
+const EXEMPTION_KEY = 'x-mandrel-uncompiled';
+
+/**
+ * A computed schema path — `` `${something}.schema.json` `` — anywhere in a
+ * source file. Evidence that the file loads schemas by runtime key rather
+ * than by literal name.
+ */
+const COMPUTED_PATH_RE = /\$\{[^}]*\}\.schema\.json/;
+
+/** Block comments, including the JSDoc prose every module here opens with. */
+const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+
+/**
+ * Line comments. Anchored to start-of-line or whitespace so a `//` inside a
+ * URL (`http://…`) is left alone — truncating that line could delete a real
+ * reference sitting after it.
+ */
+const LINE_COMMENT_RE = /(^|\s)\/\/[^\n]*/g;
+
+/**
+ * Strip comments from a source before matching.
+ *
+ * Prose is not a compile. This module's own header names
+ * `friction-event.schema.json` a dozen times while compiling nothing, and
+ * every schema-loading module documents the path it loads directly above the
+ * line that loads it — matching raw text would let a gate certify itself and
+ * would count a docblock as enforcement, which is precisely the confusion
+ * Story #4938 exists to end.
+ *
+ * @param {string} text raw source
+ * @returns {string} source with comment bodies removed
+ */
+function stripComments(text) {
+  return text.replace(BLOCK_COMMENT_RE, ' ').replace(LINE_COMMENT_RE, '$1');
+}
+
+/**
+ * Parse argv. Exported so a unit test can pin the parser without spawning.
+ *
+ * @param {string[]} argv
+ * @returns {{ root: string, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  const out = { root: process.cwd(), json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--json') out.json = true;
+    else if (argv[i] === '--root' && argv[i + 1]) {
+      out.root = path.resolve(argv[i + 1]);
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Recursively collect files under `dir` whose extension is in `extensions`.
+ *
+ * @param {string} dir absolute directory to walk
+ * @param {Set<string>} extensions lowercase extensions including the dot
+ * @param {string[]} [acc]
+ * @returns {string[]} absolute file paths
+ */
+function walk(dir, extensions, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) walk(full, extensions, acc);
+    } else if (extensions.has(path.extname(entry.name).toLowerCase())) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+/**
+ * Read every JS source in the repository once.
+ *
+ * @param {string} root absolute repository root
+ * @returns {Array<{ rel: string, text: string }>}
+ */
+function readSources(root) {
+  return walk(root, JS_EXTENSIONS).map((file) => ({
+    rel: path.relative(root, file),
+    text: stripComments(fs.readFileSync(file, 'utf8')),
+  }));
+}
+
+/**
+ * Describe every `*.schema.json` under the schema root.
+ *
+ * @param {string} root absolute repository root
+ * @returns {Array<{ rel: string, basename: string, stem: string, dir: string, doc: object|null }>}
+ */
+function readSchemas(root) {
+  const schemaRoot = path.join(root, SCHEMA_ROOT);
+  return walk(schemaRoot, new Set(['.json']))
+    .filter((file) => file.endsWith('.schema.json'))
+    .map((file) => {
+      const basename = path.basename(file);
+      let doc = null;
+      try {
+        doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch {
+        doc = null;
+      }
+      return {
+        rel: path.relative(root, file),
+        basename,
+        stem: basename.slice(0, -'.schema.json'.length),
+        dir: path.relative(schemaRoot, path.dirname(file)),
+        doc,
+      };
+    })
+    .sort((a, b) => a.rel.localeCompare(b.rel));
+}
+
+/**
+ * Find the first source whose text contains `needle`.
+ *
+ * @param {Array<{ rel: string, text: string }>} sources
+ * @param {string} needle
+ * @returns {string | null} the relative path of the witness, or null
+ */
+function witness(sources, needle) {
+  const hit = sources.find((source) => source.text.includes(needle));
+  return hit ? hit.rel : null;
+}
+
+/**
+ * Find a source that loads schemas from `dir` by computed path.
+ *
+ * The file must both build a runtime-keyed schema path and name the
+ * directory — as a quoted `path.join` segment or as a `schemas/<dir>` path
+ * fragment.
+ *
+ * @param {Array<{ rel: string, text: string }>} sources
+ * @param {string} dir directory name relative to the schema root
+ * @returns {string | null}
+ */
+function dynamicLoaderFor(sources, dir) {
+  if (!dir) return null;
+  const hit = sources.find(
+    (source) =>
+      COMPUTED_PATH_RE.test(source.text) &&
+      (source.text.includes(`'${dir}'`) ||
+        source.text.includes(`"${dir}"`) ||
+        source.text.includes(`schemas/${dir}`)),
+  );
+  return hit ? hit.rel : null;
+}
+
+/**
+ * Read a schema's in-file exemption declaration.
+ *
+ * A bare string is accepted as the reason; the object form additionally
+ * carries `runtimeGate`, the `file.js#functionName` actually enforcing the
+ * shape at runtime. That field is what makes an exemption reviewable: a
+ * schema kept as a documented SSOT with a hand-rolled validator behind it is
+ * a different animal from one kept purely for provenance, and the report
+ * should not flatten the two.
+ *
+ * @param {object|null} doc parsed schema document
+ * @returns {{ reason: string, runtimeGate: string | null } | null}
+ */
+function exemption(doc) {
+  const block = doc?.[EXEMPTION_KEY];
+  const reason = typeof block === 'string' ? block : block?.reason;
+  if (typeof reason !== 'string' || !reason.trim()) return null;
+  const gate =
+    typeof block?.runtimeGate === 'string' ? block.runtimeGate : null;
+  return { reason: reason.trim(), runtimeGate: gate };
+}
+
+/**
+ * Resolve one schema to a reference kind plus the evidence for it.
+ *
+ * @param {object} schema a `readSchemas` record
+ * @param {Array<{ rel: string, text: string }>} sources
+ * @param {Array<{ rel: string, text: string }>} schemaTexts raw schema bodies
+ * @returns {{ kind: string, evidence: string | object | null }}
+ */
+function resolveSchema(schema, sources, schemaTexts) {
+  const literal = witness(sources, schema.basename);
+  if (literal) return { kind: 'literal', evidence: literal };
+
+  const ref = schemaTexts.find(
+    (other) =>
+      other.rel !== schema.rel &&
+      other.text.includes(`"$ref"`) &&
+      other.text.includes(schema.basename),
+  );
+  if (ref) return { kind: 'schema-ref', evidence: ref.rel };
+
+  const loader = dynamicLoaderFor(sources, schema.dir);
+  if (loader) {
+    const key = witness(sources, schema.stem);
+    if (key) return { kind: 'dynamic', evidence: `${loader} (key: ${key})` };
+  }
+
+  const declared = exemption(schema.doc);
+  if (declared) return { kind: 'exempt', evidence: declared };
+
+  return { kind: 'unreferenced', evidence: null };
+}
+
+/**
+ * Run the audit and return a structured envelope.
+ *
+ * @param {{ root?: string }} [opts]
+ * @returns {{ schemaCount: number, referenced: number, exempt: Array<object>, findings: Array<object> }}
+ */
+export function auditSchemaReferences(opts = {}) {
+  const root = opts.root ?? process.cwd();
+  const sources = readSources(root);
+  const schemas = readSchemas(root);
+  const schemaTexts = schemas.map((schema) => ({
+    rel: schema.rel,
+    text: fs.readFileSync(path.join(root, schema.rel), 'utf8'),
+  }));
+
+  const exempt = [];
+  const findings = [];
+  let referenced = 0;
+
+  for (const schema of schemas) {
+    const { kind, evidence } = resolveSchema(schema, sources, schemaTexts);
+    if (kind === 'unreferenced') findings.push({ schema: schema.rel });
+    else if (kind === 'exempt')
+      exempt.push({ schema: schema.rel, ...evidence });
+    else referenced += 1;
+  }
+
+  return { schemaCount: schemas.length, referenced, exempt, findings };
+}
+
+/**
+ * Render the human-readable report.
+ *
+ * @param {ReturnType<typeof auditSchemaReferences>} report
+ * @returns {string}
+ */
+function formatReport(report) {
+  const digest =
+    `[check-schema-references] ${report.schemaCount} schema(s): ` +
+    `${report.referenced} compiled, ${report.exempt.length} exempt, ` +
+    `${report.findings.length} unreferenced.`;
+  if (report.findings.length === 0) return digest;
+  const lines = report.findings.map(
+    (finding) => `  ✗ ${finding.schema} — no code path compiles it.`,
+  );
+  return [
+    digest,
+    ...lines,
+    '',
+    'Every schema under .agents/schemas/ must be compiled by code, or say in',
+    `its own body why not. Either delete it, wire it, or add a root-level`,
+    `"${EXEMPTION_KEY}": { "reason": "…" } declaring the retention.`,
+  ].join('\n');
+}
+
+/**
+ * CLI entry point.
+ *
+ * @param {string[]} [argv]
+ * @returns {Promise<number>} process exit code
+ */
+export async function main(argv = process.argv.slice(2)) {
+  const { root, json } = parseArgv(argv);
+  const report = auditSchemaReferences({ root });
+  process.stdout.write(
+    json ? `${JSON.stringify(report)}\n` : `${formatReport(report)}\n`,
+  );
+  return report.findings.length > 0 ? 1 : 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'check-schema-references',
+  propagateExitCode: true,
+});

package/.agents/scripts/check-test-temp-hygiene.js

@@ -78,6 +78,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAsCli } from './lib/cli-utils.js';
+import { mainCheckoutRoot } from './lib/config/temp-paths.js';
+import {
+  isReservedTestId,
+  RESERVED_TEST_ID_BAND,
+} from './lib/reserved-test-ids.js';
 import {
   findRawTmpdirMkdtemp,
   listSuiteTempRoots,
@@ -369,6 +374,84 @@ export function cleanFixtureDirs({
   return { candidates, removed };
 }
 
+/**
+ * Every Epic / Story id a stream file's own path attributes it to.
+ *
+ * Both canonical layouts are read, and a nested Epic-attached stream yields
+ * both ids (`run-<eid>/stories/story-<sid>/…`): either half being a fixture id
+ * makes the stream fixture-owned, and taking only the outer one is how a
+ * fixture Story under a real run would slip past.
+ *
+ * @param {string} rel POSIX-normalised path relative to `temp/`.
+ * @returns {number[]}
+ */
+function streamOwnerIds(rel) {
+  const ids = [];
+  const run = /^run-(\d+)$/.exec(rel.split('/')[0]);
+  if (run) ids.push(Number(run[1]));
+  const story = /(?:^|\/)story-(\d+)\//.exec(rel);
+  if (story) ids.push(Number(story[1]));
+  return ids;
+}
+
+/**
+ * Stream files under `tempDir` owned by a **reserved test-fixture id**
+ * (Story #4892).
+ *
+ * This is the residual-pollution dimension the snapshot/assert bracket cannot
+ * cover: the bracket only runs in CI, where `temp/` starts empty, so a local
+ * run that appends fixture telemetry to the operator's live ledger was only
+ * ever discovered from the ticket the retro graduator filed off it (issue
+ * #4870 cited `#999999`, a `--story 999999` CLI spawn from the suite).
+ *
+ * Unlike the snapshot diff this needs no baseline and is immune to a
+ * concurrent delivery in another checkout: a reserved id is reserved *from*
+ * real work, so nothing but a test can own one of these files.
+ *
+ * @param {string} tempDir
+ * @returns {string[]} POSIX-normalised paths relative to `tempDir`, sorted.
+ */
+export function findReservedIdStreamFiles(tempDir) {
+  return listStreamFiles(tempDir).filter((rel) =>
+    streamOwnerIds(rel).some(isReservedTestId),
+  );
+}
+
+/**
+ * Post-run guard: fail when a test run left a fixture-id telemetry stream in
+ * the **repository-root** temp tree (Story #4892).
+ *
+ * Resolution matters more than it looks: every writer anchors a relative
+ * `tempRoot` to the *main checkout* (so a Story worktree and its `/deliver`
+ * host converge on one ledger), so a guard that scanned `cwd` would scan an
+ * empty worktree tree and pass vacuously on the very tree it is meant to
+ * protect. `resolveRoot` is the injection seam for tests.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {(line: string) => void} [opts.log]
+ * @param {(cwd: string) => string|null} [opts.resolveRoot]
+ * @returns {number} exit code (0 clean, 1 polluted).
+ */
+export function assertNoReservedIdStreams({
+  cwd = process.cwd(),
+  log = (l) => process.stderr.write(`${l}\n`),
+  resolveRoot = mainCheckoutRoot,
+} = {}) {
+  const root = resolveRoot(cwd) ?? cwd;
+  const tempDir = tempDirFor(root);
+  const found = findReservedIdStreamFiles(tempDir);
+  if (found.length === 0) return 0;
+  log(
+    `[test-temp-hygiene] FAIL — ${found.length} fixture-id telemetry stream(s) in the real temp tree (${tempDir}):`,
+  );
+  for (const rel of found) log(`  + fixture ${rel}`);
+  log(
+    `[test-temp-hygiene] ids ${RESERVED_TEST_ID_BAND} are reserved for fixtures, so a test wrote to the live ledger — the retro graduator reads these streams and files tickets off them. Inject an absolute per-test tempRoot on the offending spawn, then remove the stream(s) with --clean --ids <id> --yes.`,
+  );
+  return 1;
+}
+
 /**
  * Parse the CLI argv into a normalised options object.
  * @param {string[]} argv
@@ -573,5 +656,42 @@ runAsCli(
     const code = runHygiene(parseArgv(process.argv.slice(2)));
     return code;
   },
-  { source: 'check-test-temp-hygiene', propagateExitCode: true },
+  {
+    source: 'check-test-temp-hygiene',
+    propagateExitCode: true,
+    usage: {
+      invocation:
+        'node .agents/scripts/check-test-temp-hygiene.js [--snapshot | --assert | --clean] [--baseline <path>] [--lint-globs <globs>] [--ids <ids>] [--root <dir>]',
+      summary:
+        'Regression guard for test-fixture pollution of the temp trees: the repo temp/ telemetry streams every retro reads, and the OS temp root the suite scratch dirs nest under.',
+      flags: [
+        [
+          '--snapshot',
+          'Fingerprint every temp/ stream file and the pre-existing OS suite roots. Run BEFORE the suite.',
+        ],
+        [
+          '--assert',
+          'Re-scan and fail on any stream added or grown, or a surviving suite root. Run AFTER the suite. This is the default when no mode flag is passed.',
+        ],
+        [
+          '--clean',
+          'List stream directories whose Epic/Story id matches a known fixture id. Report-only — deletes nothing.',
+        ],
+        [
+          '--baseline <path>',
+          'Explicit snapshot path (CI sets a runner-temp path). Defaults to an OS scratch location keyed by the repo root; refused inside the protected temp/ tree.',
+        ],
+        [
+          '--lint-globs <globs>',
+          'Comma-separated repo-relative globs scanned for tests calling mkdtemp against os.tmpdir() instead of makeTempDir(). Off unless passed.',
+        ],
+        ['--ids <ids>', 'Comma-separated fixture ids for --clean.'],
+        ['--root <dir>', 'Repository root to scan (default: repo root).'],
+      ],
+      notes: [
+        '--assert requires a snapshot recorded by an earlier --snapshot run: a missing one is a hard failure, never a silent re-baseline.',
+        'Exit codes:\n  0  clean\n  1  a breach, or --assert with no snapshot to attest against',
+      ],
+    },
+  },
 );