mandrel 2.16.0 → 2.17.0

package/.agents/scripts/generate-lens-checklists.js

@@ -83,16 +83,21 @@ export function planChecklists(lenses, workflowExists, readWorkflow) {
  *   content; `missing` lists lenses with no `audit-<lens>.md`; `strays` lists
  *   on-disk checklist basenames that map to no current lens.
  */
-export function buildExpected() {
-  const workflowPath = (lens) => path.join(WORKFLOWS_DIR, `audit-${lens}.md`);
+export function buildExpected({
+  fsImpl = fs,
+  lenses = AUDIT_LENSES,
+  workflowsDir = WORKFLOWS_DIR,
+  checklistsDir = CHECKLISTS_DIR,
+} = {}) {
+  const workflowPath = (lens) => path.join(workflowsDir, `audit-${lens}.md`);
   const { expected, missing } = planChecklists(
-    AUDIT_LENSES,
-    (lens) => fs.existsSync(workflowPath(lens)),
-    (lens) => fs.readFileSync(workflowPath(lens), 'utf8'),
+    lenses,
+    (lens) => fsImpl.existsSync(workflowPath(lens)),
+    (lens) => fsImpl.readFileSync(workflowPath(lens), 'utf8'),
   );
 
-  const onDisk = fs.existsSync(CHECKLISTS_DIR)
-    ? fs.readdirSync(CHECKLISTS_DIR).filter((name) => name.endsWith('.md'))
+  const onDisk = fsImpl.existsSync(checklistsDir)
+    ? fsImpl.readdirSync(checklistsDir).filter((name) => name.endsWith('.md'))
     : [];
   const strays = onDisk.filter((name) => !expected.has(name));
 
@@ -101,29 +106,69 @@ export function buildExpected() {
 
 /**
  * @param {string} basename — e.g. `security.md`
+ * @param {string} [checklistsDir]
+ * @param {string} [projectRoot]
  * @returns {string} repo-relative POSIX path for messages.
  */
-function relChecklist(basename) {
+function relChecklist(
+  basename,
+  checklistsDir = CHECKLISTS_DIR,
+  projectRoot = PROJECT_ROOT,
+) {
   return path
-    .relative(PROJECT_ROOT, path.join(CHECKLISTS_DIR, basename))
+    .relative(projectRoot, path.join(checklistsDir, basename))
     .split(path.sep)
     .join('/');
 }
 
 /**
- * @param {string[]} argv
+ * The generator core, extracted from the CLI shell so both modes — the
+ * `--check` drift gate and the write/prune pass — are reachable without
+ * touching the real `.agents/audit-checklists` tree.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * `npm run docs:check` are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   fsImpl?: typeof fs,
+ *   lenses?: ReadonlyArray<string>,
+ *   workflowsDir?: string,
+ *   checklistsDir?: string,
+ *   projectRoot?: string,
+ *   logger?: { info: Function },
+ * }} [deps]
+ * @returns {Promise<{ wrote: number, pruned: number, checked?: boolean }>}
  */
-async function main(argv = process.argv.slice(2)) {
+export async function runGenerateLensChecklists(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    fsImpl = fs,
+    lenses = AUDIT_LENSES,
+    workflowsDir = WORKFLOWS_DIR,
+    checklistsDir = CHECKLISTS_DIR,
+    projectRoot = PROJECT_ROOT,
+    logger = Logger,
+  } = deps;
   const { values } = parseArgs({
     args: argv,
     options: { check: { type: 'boolean', default: false } },
     allowPositionals: false,
   });
 
-  const { expected, missing, strays } = buildExpected();
+  const { expected, missing, strays } = buildExpected({
+    fsImpl,
+    lenses,
+    workflowsDir,
+    checklistsDir,
+  });
+  const rel = (basename) => relChecklist(basename, checklistsDir, projectRoot);
 
   if (missing.length > 0) {
-    Logger.info(
+    logger.info(
       `generate-lens-checklists: no audit-<lens>.md for: ${missing.join(', ')} — no checklist emitted.`,
     );
   }
@@ -131,21 +176,21 @@ async function main(argv = process.argv.slice(2)) {
   if (values.check) {
     const drifted = [];
     for (const [basename, content] of expected) {
-      const target = path.join(CHECKLISTS_DIR, basename);
-      const original = fs.existsSync(target)
-        ? fs.readFileSync(target, 'utf8')
+      const target = path.join(checklistsDir, basename);
+      const original = fsImpl.existsSync(target)
+        ? fsImpl.readFileSync(target, 'utf8')
         : null;
-      if (original !== content) drifted.push(relChecklist(basename));
+      if (original !== content) drifted.push(rel(basename));
     }
     if (drifted.length === 0 && strays.length === 0) {
-      Logger.info(
+      logger.info(
         `generate-lens-checklists: ${expected.size} checklist(s) up to date.`,
       );
-      return;
+      return { wrote: 0, pruned: 0, checked: true };
     }
     const problems = [
       ...drifted.map((p) => `out of date: ${p}`),
-      ...strays.map((s) => `stray (no lens): ${relChecklist(s)}`),
+      ...strays.map((s) => `stray (no lens): ${rel(s)}`),
     ];
     throw new Error(
       `Lens checklists are out of sync:\n  ${problems.join('\n  ')}\n` +
@@ -153,26 +198,32 @@ async function main(argv = process.argv.slice(2)) {
     );
   }
 
-  fs.mkdirSync(CHECKLISTS_DIR, { recursive: true });
+  fsImpl.mkdirSync(checklistsDir, { recursive: true });
   let wrote = 0;
   for (const [basename, content] of expected) {
-    const target = path.join(CHECKLISTS_DIR, basename);
-    const original = fs.existsSync(target)
-      ? fs.readFileSync(target, 'utf8')
+    const target = path.join(checklistsDir, basename);
+    const original = fsImpl.existsSync(target)
+      ? fsImpl.readFileSync(target, 'utf8')
       : null;
     if (original === content) continue;
-    fs.writeFileSync(target, content, 'utf8');
+    fsImpl.writeFileSync(target, content, 'utf8');
     wrote += 1;
   }
   for (const stray of strays) {
-    fs.rmSync(path.join(CHECKLISTS_DIR, stray));
-    Logger.info(
-      `generate-lens-checklists: pruned stray ${relChecklist(stray)}`,
-    );
+    fsImpl.rmSync(path.join(checklistsDir, stray));
+    logger.info(`generate-lens-checklists: pruned stray ${rel(stray)}`);
   }
-  Logger.info(
+  logger.info(
     `generate-lens-checklists: wrote ${wrote} of ${expected.size} checklist(s) (${strays.length} pruned).`,
   );
+  return { wrote, pruned: strays.length };
+}
+
+/**
+ * @param {string[]} [argv]
+ */
+async function main(argv = process.argv.slice(2)) {
+  await runGenerateLensChecklists(argv);
 }
 
 export { CHECKLISTS_DIR, WORKFLOWS_DIR };

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -31,6 +31,9 @@ const HEADING_FINDING = /^###\s+(.+?)\s*$/;
 const HEADING_SECTION = /^##\s+(.+?)\s*$/;
 const PATH_HINT =
   /(?<![\w/])([A-Za-z0-9_./\\@-]+\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env))(?![\w])/g;
+const FILE_EXT =
+  /\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env)$/;
+const TITLE_ANCHOR = /^\s*`([^`]+)`/;
 
 function unwrapInlineCode(value) {
   if (typeof value !== 'string') return '';
@@ -81,17 +84,81 @@ function deriveDimension(fields, fallbackDimension) {
  * @param {Record<string, string>} fields
  * @returns {string[]}
  */
-function deriveLocationFiles(fields) {
+/**
+ * Normalise a raw path token to a repo-relative path, or `null` when the
+ * token is not a usable file reference.
+ *
+ * Three shapes historically leaked through and poisoned grouping downstream:
+ * an **absolute** path (which can never match a repo-relative group key), a
+ * **degenerate** token such as a bare `/`, and — most damagingly — a
+ * **root-level** file such as `AGENTS.md`, which the old slash-only guard
+ * discarded outright even when it was the finding's explicit `Location:`.
+ *
+ * `requireSeparator` is what keeps that third fix from over-reaching. In the
+ * **structured** fields — the title anchor and `Location:` — a bare
+ * `AGENTS.md` is unambiguously a file, so the separator is not required. In
+ * free **prose**, a bare `description.md` is far more likely to be a word than
+ * a path, so the separator stays mandatory there.
+ *
+ * @param {string} raw — the token as it appeared in the report.
+ * @param {string} [repoRoot] — absolute repo root; absolute tokens beneath it
+ *   are relativised. Omitted (the pure default) leaves absolutes to be dropped.
+ * @param {{ requireSeparator?: boolean }} [options]
+ * @returns {string|null}
+ */
+function normalisePathToken(raw, repoRoot, { requireSeparator = false } = {}) {
+  if (typeof raw !== 'string') return null;
+  const stripped = raw
+    .replace(/^[`'"([]+/, '')
+    .replace(/[`'")\].,;]+$/, '')
+    .trim();
+  // `Location:` anchors appear as `:line`, `:line:col`, and `:start-end`.
+  const cleaned = stripped.replace(/:\d+(?:-\d+)?(?::\d+)?$/, '');
+  if (!cleaned || cleaned === '.' || cleaned === '..') return null;
+
+  let out = cleaned;
+  if (typeof repoRoot === 'string' && repoRoot.length > 0) {
+    for (const sep of ['/', '\\']) {
+      const root = repoRoot.endsWith(sep) ? repoRoot : `${repoRoot}${sep}`;
+      if (out.startsWith(root)) {
+        out = out.slice(root.length);
+        break;
+      }
+    }
+  }
+  // A path that is still absolute lives outside the repo — it can never be a
+  // valid group key, so drop it rather than let it become one.
+  if (out.startsWith('/') || out.startsWith('\\') || /^[A-Za-z]:/.test(out)) {
+    return null;
+  }
+  const hasSeparator = out.includes('/') || out.includes('\\');
+  if (requireSeparator && !hasSeparator) return null;
+  if (!hasSeparator && !FILE_EXT.test(out)) return null;
+  return out;
+}
+
+/**
+ * The finding-block skeleton mandates that a title lead with the primary file
+ * the finding lives in (``### `path/to/file.ext` — title``). That anchor is
+ * the most reliable primary-file signal a block carries, so it seeds `files[]`
+ * ahead of `Location:` and prose scraping — `pickPrimaryFile` takes `files[0]`.
+ */
+function deriveTitleFile(title, repoRoot) {
+  const match = TITLE_ANCHOR.exec(typeof title === 'string' ? title : '');
+  if (!match) return [];
+  const normalised = normalisePathToken(match[1], repoRoot);
+  return normalised ? [normalised] : [];
+}
+
+function deriveLocationFiles(fields, repoRoot) {
   const raw = fields.location;
   if (typeof raw !== 'string' || raw.trim().length === 0) return [];
   const cleaned = raw.replace(/[`[\]]/g, ' ');
   const out = [];
   for (const token of cleaned.split(/[\s,]+/)) {
     if (!token) continue;
-    const withoutLine = token.replace(/:\d+(?::\d+)?$/, '');
-    if (withoutLine.includes('/') || withoutLine.includes('\\')) {
-      out.push(withoutLine);
-    }
+    const normalised = normalisePathToken(token, repoRoot);
+    if (normalised) out.push(normalised);
   }
   return out;
 }
@@ -113,14 +180,15 @@ function normaliseTitle(title) {
     .trim();
 }
 
-function extractFilePaths(text) {
+function extractFilePaths(text, repoRoot) {
   if (typeof text !== 'string') return [];
   const seen = new Set();
   for (const match of text.matchAll(PATH_HINT)) {
-    const candidate = match[1].replace(/^[`'"]+|[`'"]+$/g, '');
-    if (candidate.includes('/') || candidate.includes('\\')) {
-      seen.add(candidate);
-    }
+    // Prose: a bare `description.md` is more likely a word than a path.
+    const normalised = normalisePathToken(match[1], repoRoot, {
+      requireSeparator: true,
+    });
+    if (normalised) seen.add(normalised);
   }
   return [...seen];
 }
@@ -211,7 +279,7 @@ function parseBlockFields(bodyLines) {
  *   sourceReport: string,
  * }>}
  */
-export function parseAuditReport({ markdown, sourceReport }) {
+export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
   if (typeof markdown !== 'string') {
     throw new Error('parseAuditReport: markdown must be a string');
   }
@@ -231,10 +299,11 @@ export function parseAuditReport({ markdown, sourceReport }) {
       fields['recommendation & rationale'] ?? fields.recommendation ?? '';
     const agentPrompt = fields['agent prompt'] ?? '';
     const fileSet = new Set([
-      ...deriveLocationFiles(fields),
-      ...extractFilePaths(currentState),
-      ...extractFilePaths(recommendation),
-      ...extractFilePaths(agentPrompt),
+      ...deriveTitleFile(block.title, repoRoot),
+      ...deriveLocationFiles(fields, repoRoot),
+      ...extractFilePaths(currentState, repoRoot),
+      ...extractFilePaths(recommendation, repoRoot),
+      ...extractFilePaths(agentPrompt, repoRoot),
     ]);
 
     return {
@@ -258,15 +327,17 @@ export function parseAuditReport({ markdown, sourceReport }) {
  * an audit can legitimately come back empty.
  *
  * @param {Array<{ markdown: string, sourceReport: string }>} reports
+ * @param {{ repoRoot?: string }} [options] — `repoRoot` relativises absolute
+ *   paths quoted in a report so they can match repo-relative group keys.
  * @returns {Array<ReturnType<typeof parseAuditReport>[number]>}
  */
-export function parseAuditReports(reports) {
+export function parseAuditReports(reports, { repoRoot } = {}) {
   if (!Array.isArray(reports)) {
     throw new Error('parseAuditReports: reports must be an array');
   }
   const out = [];
   for (const report of reports) {
-    out.push(...parseAuditReport(report));
+    out.push(...parseAuditReport({ ...report, repoRoot }));
   }
   return out;
 }

package/.agents/scripts/lib/baselines/drift-detector.js

@@ -0,0 +1,351 @@
+// .agents/scripts/lib/baselines/drift-detector.js
+/**
+ * drift-detector.js — full-scope baseline drift detection (Story #4776).
+ *
+ * Every enforcement site for the maintainability and CRAP baselines is
+ * **diff-scoped**: close-validation, the pre-push hook and CI all compare
+ * the files a branch touched against their committed rows. That is the
+ * right per-PR trade — full-scope scoring on every push would be far too
+ * expensive — but it has a structural blind spot. A file that is never
+ * modified after its baseline row is written is never re-scored, so a
+ * regression introduced *indirectly* (a dependency getting more complex, a
+ * test deletion moving coverage underneath it) is invisible for as long as
+ * nobody happens to touch that file.
+ *
+ * This module closes that hole with the check that is too expensive to run
+ * per-PR and cheap enough to run on a schedule: re-score every target
+ * directory in full, and report every row whose current score has moved
+ * away from its baseline by more than the gate's tolerance — **in either
+ * direction**. Drift, not regression: a row that silently improved is
+ * equally strong evidence that the committed baseline no longer describes
+ * the tree, and leaving it stale means the ratchet is anchored to a number
+ * that no longer exists.
+ *
+ * Re-scoring routes through `refresh-service.resolveDefaultScorer` — the
+ * same scorer that writes the baseline — so the detector cannot report two
+ * implementations disagreeing with each other as drift in the tree.
+ *
+ * Pure-ish: the scorer and the baseline loader are both injectable, and the
+ * module never writes anything, exits, or emits friction.
+ *
+ * The public surface is deliberately the three symbols the CLI actually
+ * uses — `DRIFT_KINDS`, `detectBaselineDrift`, `formatDriftReport`. Every
+ * internal helper below stays module-local and is exercised through them
+ * (`detectBaselineDrift` forwards its `loadBaselineRows` / `scoreFullScope`
+ * seams straight down). Exporting the helpers so tests could reach them
+ * directly would ship five entry points nothing in production reaches —
+ * exactly the orphaning this Story exists to stop.
+ */
+
+import { getQuality } from '../config/quality.js';
+import { resolveConfig } from '../config-resolver.js';
+import { getKindModule } from './kernel.js';
+import { load as loadBaseline } from './reader.js';
+import { resolveDefaultScorer } from './refresh-service.js';
+
+/** The kinds whose rows carry a per-file/per-method score worth re-scoring. */
+export const DRIFT_KINDS = Object.freeze(['maintainability', 'crap']);
+
+/**
+ * Per-kind identity, metric axis, and refresh remedy. `identity` must match
+ * the granularity the kind's baseline rows are keyed at, or unchanged rows
+ * masquerade as added/removed pairs.
+ */
+const KIND_SPECS = Object.freeze({
+  maintainability: Object.freeze({
+    metric: 'mi',
+    identity: (row) => row.path,
+    label: (row) => row.path,
+    refreshCommand: 'npm run maintainability:update -- --full-scope',
+    defaultTolerance: 0.5,
+  }),
+  crap: Object.freeze({
+    metric: 'crap',
+    identity: (row) => `${row.path}::${row.method}@${row.startLine}`,
+    label: (row) => `${row.path}::${row.method} (line ${row.startLine})`,
+    refreshCommand: 'npm run crap:update -- --full-scope',
+    defaultTolerance: 0.001,
+  }),
+});
+
+/**
+ * Resolve the absolute drift tolerance for a kind: an explicit override
+ * wins, then the gate's configured `tolerance.value`, then the per-kind
+ * default.
+ *
+ * @param {string} kind
+ * @param {object|undefined} gate resolved `delivery.quality.gates.<kind>`
+ * @param {number|null|undefined} override
+ * @returns {number}
+ */
+function resolveTolerance(kind, gate, override) {
+  if (typeof override === 'number' && Number.isFinite(override)) {
+    return Math.abs(override);
+  }
+  const configured = gate?.tolerance;
+  if (configured?.kind === 'absolute') {
+    const value = Number(configured.value);
+    if (Number.isFinite(value)) return Math.abs(value);
+  }
+  return KIND_SPECS[kind].defaultTolerance;
+}
+
+/**
+ * Normalise a scorer's raw rows into the kind's canonical on-disk row
+ * shape, so scored rows and baseline rows are directly comparable. The
+ * per-kind `projectRow` is the same projection the writer applies, which is
+ * what makes the two sides comparable at all (it also reconciles the CRAP
+ * scorer's `file` key with the envelope's `path`).
+ *
+ * @param {string} kind
+ * @param {Array<object>} rows
+ * @returns {Array<object>}
+ */
+function projectScoredRows(kind, rows) {
+  const mod = getKindModule(kind);
+  const out = [];
+  for (const row of rows ?? []) {
+    try {
+      out.push(mod.projectRow(row));
+    } catch {
+      // A row the writer itself would refuse is not evidence of drift.
+    }
+  }
+  return out;
+}
+
+/**
+ * Diff two row sets by the kind's identity, classifying each key as
+ * drifted / added / removed. Pure.
+ *
+ * @param {{ kind: string, baselineRows: Array<object>, currentRows: Array<object>, tolerance: number }} opts
+ * @returns {{ drifted: Array<object>, added: Array<object>, removed: Array<object> }}
+ */
+function diffRows({ kind, baselineRows, currentRows, tolerance }) {
+  const spec = KIND_SPECS[kind];
+  const baseByKey = new Map();
+  for (const row of baselineRows ?? []) baseByKey.set(spec.identity(row), row);
+
+  const drifted = [];
+  const added = [];
+  const seen = new Set();
+
+  for (const row of currentRows ?? []) {
+    const key = spec.identity(row);
+    seen.add(key);
+    const base = baseByKey.get(key);
+    if (!base) {
+      added.push({ key, label: spec.label(row), current: row[spec.metric] });
+      continue;
+    }
+    const before = Number(base[spec.metric] ?? 0);
+    const after = Number(row[spec.metric] ?? 0);
+    const delta = after - before;
+    if (Math.abs(delta) <= tolerance) continue;
+    drifted.push({
+      key,
+      label: spec.label(row),
+      baseline: before,
+      current: after,
+      delta,
+    });
+  }
+
+  const removed = [];
+  for (const [key, row] of baseByKey) {
+    if (seen.has(key)) continue;
+    removed.push({ key, label: spec.label(row), baseline: row[spec.metric] });
+  }
+
+  return { drifted, added, removed };
+}
+
+/**
+ * Re-score one kind full-scope and diff the result against its committed
+ * baseline.
+ *
+ * Returns `{ ok: true, skipped: '<reason>' }` when the kind cannot be
+ * checked (gate disabled, no baseline on disk, no scorer registered, the
+ * scorer produced nothing) — an unscorable kind is not drift, and a
+ * scheduled job must not go red because coverage happened to be absent.
+ *
+ * @param {{
+ *   kind: string,
+ *   cwd?: string,
+ *   quality?: object,
+ *   tolerance?: number|null,
+ *   loadBaselineRows?: (kind: string, cwd: string) => Array<object>|null,
+ *   scoreFullScope?: (kind: string, cwd: string) => Promise<Array<object>|null>|Array<object>|null,
+ * }} opts
+ * @returns {Promise<object>}
+ */
+async function detectKindDrift({
+  kind,
+  cwd = process.cwd(),
+  quality,
+  tolerance = null,
+  loadBaselineRows = defaultLoadBaselineRows,
+  scoreFullScope = defaultScoreFullScope,
+}) {
+  if (!Object.hasOwn(KIND_SPECS, kind)) {
+    throw new Error(
+      `[drift] unknown kind "${kind}"; expected one of ${DRIFT_KINDS.join(', ')}`,
+    );
+  }
+  const gate = quality?.[kind];
+  const spec = KIND_SPECS[kind];
+  const base = { kind, refreshCommand: spec.refreshCommand };
+  if (gate?.enabled === false) {
+    return { ...base, ok: true, skipped: 'gate-disabled' };
+  }
+
+  const baselineRows = loadBaselineRows(kind, cwd);
+  if (!Array.isArray(baselineRows) || baselineRows.length === 0) {
+    return { ...base, ok: true, skipped: 'no-baseline' };
+  }
+
+  const raw = await scoreFullScope(kind, cwd);
+  if (raw === null || raw === undefined) {
+    return { ...base, ok: true, skipped: 'no-scorer' };
+  }
+  const currentRows = projectScoredRows(kind, raw);
+  if (currentRows.length === 0) {
+    return { ...base, ok: true, skipped: 'no-scored-rows' };
+  }
+
+  const resolvedTolerance = resolveTolerance(kind, gate, tolerance);
+  const { drifted, added, removed } = diffRows({
+    kind,
+    baselineRows,
+    currentRows,
+    tolerance: resolvedTolerance,
+  });
+
+  return {
+    ...base,
+    ok: drifted.length === 0,
+    tolerance: resolvedTolerance,
+    scanned: currentRows.length,
+    baselineRows: baselineRows.length,
+    drifted,
+    added,
+    removed,
+  };
+}
+
+/**
+ * Run the drift check across several kinds.
+ *
+ * @param {{ kinds?: string[], cwd?: string, tolerance?: number|null, quality?: object }} opts
+ * @returns {Promise<{ ok: boolean, results: Array<object> }>}
+ */
+export async function detectBaselineDrift({
+  kinds = DRIFT_KINDS,
+  cwd = process.cwd(),
+  tolerance = null,
+  quality,
+  ...seams
+} = {}) {
+  let resolvedQuality = quality;
+  if (!resolvedQuality) {
+    try {
+      resolvedQuality = getQuality(resolveConfig({ cwd })) ?? {};
+    } catch {
+      resolvedQuality = {};
+    }
+  }
+  const results = [];
+  for (const kind of kinds) {
+    results.push(
+      await detectKindDrift({
+        kind,
+        cwd,
+        tolerance,
+        quality: resolvedQuality,
+        ...seams,
+      }),
+    );
+  }
+  return { ok: results.every((r) => r.ok), results };
+}
+
+/**
+ * Default baseline loader — reads and schema-validates the committed
+ * envelope. Returns `null` when it cannot be read, which the caller maps to
+ * the `no-baseline` skip.
+ */
+function defaultLoadBaselineRows(kind, cwd) {
+  try {
+    return loadBaseline(kind, { cwd }).rows;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Default full-scope scorer — the same scorer `refreshBaseline` uses, run
+ * with `fullScope: true` so it walks every configured target directory
+ * rather than a diff-derived file list.
+ */
+async function defaultScoreFullScope(kind, cwd) {
+  const scorer = resolveDefaultScorer(kind, { cwd });
+  if (typeof scorer !== 'function') return null;
+  return await scorer(null, { fullScope: true, cwd });
+}
+
+/**
+ * Render one kind's result as an operator-facing block: a per-row
+ * before/after table plus the refresh remedy. Returns a string always —
+ * a clean kind reports one line so a scheduled job's log shows it ran.
+ *
+ * @param {object} result
+ * @returns {string}
+ */
+function formatKindDrift(result) {
+  if (result.skipped) {
+    return `[drift] ⏭ ${result.kind}: skipped (${result.skipped})`;
+  }
+  if (result.ok) {
+    return `[drift] ✓ ${result.kind}: ${result.scanned} row(s) re-scored full-scope, no drift beyond ±${result.tolerance}`;
+  }
+  const width = Math.max(
+    12,
+    ...result.drifted.map((d) => String(d.label).length),
+  );
+  const lines = [
+    `[drift] ✖ ${result.kind}: ${result.drifted.length} row(s) drifted beyond ±${result.tolerance} (${result.scanned} re-scored, ${result.baselineRows} in baseline)`,
+    `  ${'ROW'.padEnd(width)}  ${'BASELINE'.padStart(10)}  ${'CURRENT'.padStart(10)}  ${'DELTA'.padStart(10)}`,
+  ];
+  for (const d of result.drifted) {
+    lines.push(
+      `  ${String(d.label).padEnd(width)}  ${d.baseline.toFixed(2).padStart(10)}  ${d.current
+        .toFixed(2)
+        .padStart(
+          10,
+        )}  ${(d.delta > 0 ? `+${d.delta.toFixed(2)}` : d.delta.toFixed(2)).padStart(10)}`,
+    );
+  }
+  if (result.added.length > 0 || result.removed.length > 0) {
+    lines.push(
+      `  (${result.added.length} row(s) absent from baseline, ${result.removed.length} baseline row(s) absent from the tree)`,
+    );
+  }
+  lines.push(
+    `  Remedy: run \`${result.refreshCommand}\` and commit the refreshed baseline with a \`baseline-refresh:\` tagged subject (non-empty body).`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Render the whole run.
+ *
+ * @param {{ ok: boolean, results: Array<object> }} run
+ * @returns {string}
+ */
+export function formatDriftReport(run) {
+  const body = run.results.map(formatKindDrift).join('\n');
+  const tail = run.ok
+    ? '[drift] ✅ No baseline drift detected.'
+    : '[drift] ❌ Baseline drift detected — the committed baselines no longer describe the tree.';
+  return `${body}\n${tail}`;
+}