mandrel 2.25.0 → 2.27.0

package/.agents/scripts/check-workflow-timeouts.js

@@ -0,0 +1,291 @@
+/**
+ * CLI: GitHub Actions job-timeout gate.
+ *
+ * Story #4936. Every job in this repository inherited GitHub's 360-minute
+ * default because not one of the four workflow files set `timeout-minutes`.
+ * That is not a theoretical cost: a deadlocked `Windows Smoke` job burned 44
+ * minutes of a `windows-latest` runner, and — because the run stayed
+ * `in_progress` — GitHub withheld the logs of the *required* check that had
+ * already failed on the same run, so the real merge blocker could not be
+ * diagnosed until the run was cancelled by hand. An unbounded job costs
+ * runner time and diagnosability at once.
+ *
+ * A ceiling only helps if it is bounded on both ends, so this gate fails on
+ * two shapes:
+ *
+ *   - a job with no `timeout-minutes` at all (unbounded, 360-minute default);
+ *   - a job whose `timeout-minutes` exceeds `MAX_TIMEOUT_MINUTES`, i.e. a
+ *     number generous enough to be useless as a deadlock detector.
+ *
+ * `MIN_TIMEOUT_MINUTES` is the floor a value must clear to be plausible
+ * headroom over a job that takes a couple of minutes today; below it, a
+ * transient slow runner reds the build for no defect.
+ *
+ * Contract:
+ *   - Scans the workflows directory (default `.github/workflows`, override
+ *     with `--dir <path>`), parsing each `*.yml` / `*.yaml` with js-yaml and
+ *     enumerating every `jobs.<id>` key.
+ *   - Prints `<file> job <id> — <reason>` per violation, then a one-line
+ *     summary even on a clean scan so the "ok" signal is visible in CI.
+ *   - With `--json`: writes a structured envelope to stdout and skips the
+ *     human summary.
+ *   - Exit codes: 0 = every job bounded in range; 1 = at least one violation.
+ *     A missing / empty workflows directory exits 0 (nothing to gate).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import yaml from 'js-yaml';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Inclusive bounds every job's `timeout-minutes` must sit within.
+ *
+ * The ceiling is the load-bearing half — it is what turns a deadlock into a
+ * bounded loss instead of a six-hour one. The floor keeps a well-meaning
+ * `timeout-minutes: 2` from reddening the build on a slow runner.
+ */
+export const MIN_TIMEOUT_MINUTES = 10;
+export const MAX_TIMEOUT_MINUTES = 30;
+
+/**
+ * Enumerate workflow files (`*.yml` / `*.yaml`) directly under `dir`.
+ * Returns absolute paths sorted for deterministic output. A missing directory
+ * yields an empty list.
+ *
+ * @param {string} dir Absolute workflows directory.
+ * @param {typeof fs} [fsLike]
+ * @returns {string[]}
+ */
+export function listWorkflowFiles(dir, fsLike = fs) {
+  let entries;
+  try {
+    entries = fsLike.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && /\.ya?ml$/i.test(e.name))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+}
+
+/**
+ * Read the `jobs` mapping out of one workflow document.
+ *
+ * The single parse point for both the violation scan and the job count, so
+ * the two can never disagree about what a workflow's job set is.
+ *
+ * @param {string} text The file contents.
+ * @param {(s: string) => unknown} parse YAML parser; injected in tests.
+ * @returns {{ jobs: Record<string, unknown> | null, error: Error | null }}
+ */
+function readJobs(text, parse) {
+  let doc;
+  try {
+    doc = parse(text);
+  } catch (err) {
+    return { jobs: null, error: err };
+  }
+  const jobs = doc && typeof doc === 'object' ? doc.jobs : null;
+  return {
+    jobs: jobs && typeof jobs === 'object' ? jobs : null,
+    error: null,
+  };
+}
+
+/**
+ * Judge one job body's `timeout-minutes`, returning the violation shape or
+ * `null` when the job is bounded in range.
+ *
+ * Reusable-workflow calls (`jobs.<id>.uses:`) are exempt: `timeout-minutes`
+ * is not a valid key on a job that delegates to another workflow — the
+ * callee's own jobs carry their timeouts, and setting one here is a schema
+ * error rather than a fix.
+ *
+ * @param {unknown} body The `jobs.<id>` value.
+ * @returns {{ timeout: number | null, reason: string } | null}
+ */
+function judgeJobTimeout(body) {
+  if (!body || typeof body !== 'object') return null;
+  if (typeof body.uses === 'string') return null;
+
+  const timeout = body['timeout-minutes'];
+  if (timeout === undefined || timeout === null) {
+    return {
+      timeout: null,
+      reason: `no timeout-minutes — the job inherits GitHub's 360-minute default`,
+    };
+  }
+  if (typeof timeout !== 'number' || !Number.isFinite(timeout)) {
+    return {
+      timeout: null,
+      reason: `timeout-minutes is not a number (${JSON.stringify(timeout)})`,
+    };
+  }
+  if (timeout > MAX_TIMEOUT_MINUTES) {
+    return {
+      timeout,
+      reason: `timeout-minutes ${timeout} exceeds the ${MAX_TIMEOUT_MINUTES}-minute ceiling`,
+    };
+  }
+  if (timeout < MIN_TIMEOUT_MINUTES) {
+    return {
+      timeout,
+      reason: `timeout-minutes ${timeout} is below the ${MIN_TIMEOUT_MINUTES}-minute floor`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Pure helper: enumerate every `jobs.<id>` key in one workflow document and
+ * return the violations.
+ *
+ * An unparseable document is itself a violation: a workflow whose jobs cannot
+ * be enumerated cannot be certified as bounded, and failing open would let
+ * the very drift this gate exists to catch through.
+ *
+ * @param {string} file Relative file label used in violation rows.
+ * @param {string} text The file contents.
+ * @param {(s: string) => unknown} [parse] YAML parser; injected in tests.
+ * @returns {Array<{ file: string, job: string, timeout: number | null, reason: string }>}
+ */
+export function scanWorkflowText(file, text, parse = yaml.load) {
+  const { jobs, error } = readJobs(text, parse);
+  if (error) {
+    return [
+      {
+        file,
+        job: '(document)',
+        timeout: null,
+        reason: `workflow could not be parsed as YAML: ${error.message}`,
+      },
+    ];
+  }
+  if (!jobs) return [];
+
+  const violations = [];
+  for (const [job, body] of Object.entries(jobs)) {
+    const verdict = judgeJobTimeout(body);
+    if (verdict) violations.push({ file, job, ...verdict });
+  }
+  return violations;
+}
+
+/**
+ * Pure helper: render the human-readable report. One line per violation
+ * followed by a one-line summary carrying a `(gate fail)` / `(ok)` marker.
+ *
+ * @param {Array<{ file: string, job: string, timeout: number | null, reason: string }>} violations
+ * @param {number} jobsScanned
+ * @returns {string}
+ */
+export function renderReport(violations, jobsScanned) {
+  const lines = violations.map((v) => `${v.file} job ${v.job} — ${v.reason}`);
+  const tag = violations.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[workflow-timeouts] jobs=${jobsScanned} violations=${violations.length} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Count every `jobs.<id>` key in a parsed workflow document, including the
+ * reusable-workflow calls the violation scan exempts — the summary reports
+ * how many jobs were enumerated, not how many were eligible.
+ *
+ * @param {string} text
+ * @param {(s: string) => unknown} [parse]
+ * @returns {number}
+ */
+export function countJobs(text, parse = yaml.load) {
+  const { jobs } = readJobs(text, parse);
+  return jobs ? Object.keys(jobs).length : 0;
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline against
+ * a fixture workflows directory without touching the repo's real workflows.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} exit code: 0 = every job bounded; 1 = violation
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const dirIdx = argv.indexOf('--dir');
+  const dir =
+    dirIdx !== -1 && argv[dirIdx + 1] && !argv[dirIdx + 1].startsWith('--')
+      ? argv[dirIdx + 1]
+      : null;
+  const json = argv.includes('--json');
+  const resolvedDir = path.resolve(
+    cwd,
+    dir ?? path.join('.github', 'workflows'),
+  );
+
+  const files = listWorkflowFiles(resolvedDir);
+  const violations = [];
+  let jobsScanned = 0;
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    const label = path.relative(cwd, file);
+    jobsScanned += countJobs(text);
+    violations.push(...scanWorkflowText(label, text));
+  }
+
+  const exitCode = violations.length > 0 ? 1 : 0;
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          kind: 'workflow-timeouts-report',
+          dir: resolvedDir,
+          filesScanned: files.length,
+          jobsScanned,
+          minTimeoutMinutes: MIN_TIMEOUT_MINUTES,
+          maxTimeoutMinutes: MAX_TIMEOUT_MINUTES,
+          violations,
+          exitCode,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    if (files.length === 0) {
+      stderr.write(
+        `[workflow-timeouts] ⚠ no workflow files found under ${resolvedDir}\n`,
+      );
+    }
+    stdout.write(`${renderReport(violations, jobsScanned)}\n`);
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'workflow-timeouts',
+  propagateExitCode: true,
+  errorPrefix: '[workflow-timeouts] ❌ Fatal error',
+});

package/.agents/scripts/diagnose-friction.js

@@ -16,7 +16,11 @@
  *
  * Usage:
  *   node diagnose-friction.js [--story <STORY_ID>] \
- *     [--epic <EPIC_ID>] --cmd <command with args...>
+ *     [--epic <EPIC_ID>] --cmd <cmd> <args...>
+ *
+ * `--cmd` consumes the remaining argv as separate words and spawns them with
+ * no shell. Quoting the whole command as one string is a usage error, not
+ * friction — it is refused loudly and writes no ledger row.
  *
  * Story/Epic resolution order:
  *   1. CLI flags (--story, --epic).
@@ -108,6 +112,16 @@ function classifyFrictionCategory(errorOutput) {
  */
 const INTERCEPTOR_TIMEOUT_SIGNAL = 'SIGTERM';
 
+/**
+ * A `maxBuffer` overflow presents identically to a timeout — `status: null`,
+ * `signal: 'SIGTERM'` — because Node kills the child the same way. The only
+ * discriminator is `result.error.code`, so a SIGTERM carrying this code is a
+ * buffer overflow and must never be reported as a timeout (Story #4915).
+ *
+ * @type {string}
+ */
+const OVERFLOW_ERROR_CODE = 'ENOBUFS';
+
 /** Shell convention for "the process died by signal N": exit `128 + N`. */
 const SIGNAL_EXIT_BASE = 128;
 
@@ -118,8 +132,10 @@ const SIGNAL_EXIT_BASE = 128;
  * interceptor would report success for a command it just watched get killed
  * (Story #4851).
  *
- * Which signal fired is the diagnostic value: SIGTERM points at the
- * interceptor's own bound, anything else at the host. Recording that plus the
+ * Which signal fired is the diagnostic value: SIGTERM points at one of the
+ * interceptor's own bounds, anything else at the host. A SIGTERM splits again
+ * on `error.code`: `ENOBUFS` means the output blew past `executionMaxBuffer`,
+ * anything else means `executionTimeoutMs` fired. Recording that plus the
  * bound itself is what makes the row actionable to a consumer who cannot edit
  * the materialized framework tree.
  *
@@ -128,13 +144,17 @@ const SIGNAL_EXIT_BASE = 128;
  * the file's per-file maintainability-delta headroom. The CLI contract is the
  * seam the unit tests drive.
  *
- * @param {{signal: (string|null), error?: {message?: string}}} result A
- *   `spawnSync` result whose `status` is `null`.
- * @param {number} executionTimeoutMs The resolved interceptor bound, in ms.
+ * @param {{signal: (string|null), error?: {message?: string, code?: string}}}
+ *   result A `spawnSync` result whose `status` is `null`.
+ * @param {{executionTimeoutMs: number, executionMaxBuffer: number}} bounds The
+ *   resolved interceptor bounds — the timeout in ms, the buffer in bytes.
  * @returns {{category: string, remediation: string, details: object,
  *   preview: string, exitCode: number}}
  */
-function describeAbnormalExit(result, executionTimeoutMs) {
+function describeAbnormalExit(
+  result,
+  { executionTimeoutMs, executionMaxBuffer },
+) {
   const signal = typeof result.signal === 'string' ? result.signal : null;
   if (signal === null) {
     return {
@@ -150,15 +170,42 @@ function describeAbnormalExit(result, executionTimeoutMs) {
     };
   }
 
-  const timedOut = signal === INTERCEPTOR_TIMEOUT_SIGNAL;
-  const killOrigin = timedOut ? 'interceptor-timeout' : 'external';
+  const sentByInterceptor = signal === INTERCEPTOR_TIMEOUT_SIGNAL;
+  const overflowed =
+    sentByInterceptor && result.error?.code === OVERFLOW_ERROR_CODE;
+  let killOrigin = 'external';
+  if (overflowed) killOrigin = 'buffer-overflow';
+  else if (sentByInterceptor) killOrigin = 'interceptor-timeout';
+
+  const shapes = {
+    'buffer-overflow': {
+      category: 'Tool Limitation',
+      remediation: ` - ${signal} was sent because the command's output overflowed the interceptor's executionMaxBuffer bound (${executionMaxBuffer} bytes / 10 MiB) — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire. Do NOT split the command into smaller steps: quieten or redirect its output, or raise the buffer bound.`,
+      extraDetails: { executionMaxBuffer },
+    },
+    'interceptor-timeout': {
+      category: 'Execution Timeout',
+      remediation: ` - ${signal} matches the interceptor's own executionTimeoutMs bound (${executionTimeoutMs}ms), so the command was almost certainly cut off rather than broken. Split it into smaller steps, or raise the bound.`,
+      extraDetails: {},
+    },
+    external: {
+      category: 'Execution Killed',
+      remediation: ` - ${signal} originated outside the interceptor — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire, so suspect an OOM kill or a hard kill from the host. Reduce the command's memory footprint or give the host more headroom.`,
+      extraDetails: {},
+    },
+  };
+
+  const shape = shapes[killOrigin];
   const signum = osConstants.signals[signal];
   return {
-    category: timedOut ? 'Execution Timeout' : 'Execution Killed',
-    remediation: timedOut
-      ? ` - ${signal} matches the interceptor's own executionTimeoutMs bound (${executionTimeoutMs}ms), so the command was almost certainly cut off rather than broken. Split it into smaller steps, or raise the bound.`
-      : ` - ${signal} originated outside the interceptor — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire, so suspect an OOM kill or a hard kill from the host. Reduce the command's memory footprint or give the host more headroom.`,
-    details: { killedBySignal: signal, killOrigin, executionTimeoutMs },
+    category: shape.category,
+    remediation: shape.remediation,
+    details: {
+      killedBySignal: signal,
+      killOrigin,
+      executionTimeoutMs,
+      ...shape.extraDetails,
+    },
     preview: `Command terminated by signal ${signal} (${killOrigin}); executionTimeoutMs=${executionTimeoutMs}.`,
     exitCode: Number.isInteger(signum) ? SIGNAL_EXIT_BASE + signum : 1,
   };
@@ -221,7 +268,23 @@ export async function main(args = process.argv.slice(2)) {
 
   if (cmdArgs.length === 0) {
     throw new Error(
-      'Usage: node diagnose-friction.js [--story <STORY_ID>] [--epic <EPIC_ID>] --cmd <command with args...>',
+      'Usage: node diagnose-friction.js [--story <STORY_ID>] [--epic <EPIC_ID>] --cmd <cmd> <args...>',
+    );
+  }
+
+  // Story #4915 — the interceptor spawns `cmdArgs[0]` directly, with no shell.
+  // A single argument containing whitespace therefore names an executable that
+  // cannot exist, and the resulting ENOENT is a usage error in the
+  // interceptor's OWN invocation, not friction in the wrapped command. It must
+  // be reported as one and MUST NOT reach the ledger — otherwise the real
+  // friction is discarded and the roll-up eventually auto-files a framework-gap
+  // ticket about the framework's own instrumentation being misused. The
+  // discriminator is this argv shape, never the ENOENT result: a correctly
+  // split command whose binary is genuinely absent yields the identical
+  // `spawnSync` result and stays real friction.
+  if (cmdArgs.length === 1 && /\s/.test(cmdArgs[0])) {
+    throw new Error(
+      `Usage: --cmd takes the command as separate argv words, not one quoted string. Received a single quoted argument: "${cmdArgs[0]}". Drop the quotes so each word is its own argv entry — \`--cmd ${cmdArgs[0]}\`. No friction signal was recorded.`,
     );
   }
 
@@ -251,7 +314,10 @@ export async function main(args = process.argv.slice(2)) {
     // `result.signal`, not in the status.
     const abnormal =
       result.status === null
-        ? describeAbnormalExit(result, executionTimeoutMs)
+        ? describeAbnormalExit(result, {
+            executionTimeoutMs,
+            executionMaxBuffer,
+          })
         : null;
     // With both streams empty an abnormal termination names its signal; the
     // `Unknown exit code` fallback is therefore reachable only with a real
@@ -343,15 +409,15 @@ runAsCli(import.meta.url, main, {
   source: 'DiagnoseFriction',
   usage: {
     invocation:
-      'node .agents/scripts/diagnose-friction.js [--story <id>] [--epic <id>] --cmd <command with args...>',
+      'node .agents/scripts/diagnose-friction.js [--story <id>] [--epic <id>] --cmd <cmd> <args...>',
     summary:
       'Run a command through the diagnostic interceptor: stream its output, then append a local friction signal describing the failure. Never posts to the ticket.',
     flags: [
       ['--story <id>', 'Story the friction belongs to.'],
       ['--epic <id>', 'Epic the friction belongs to.'],
       [
-        '--cmd <command...>',
-        'The command to execute; everything after it is the argv (required).',
+        '--cmd <cmd> <args...>',
+        'The command to execute; everything after it is the argv, as separate words — never one quoted string (required).',
       ],
     ],
   },

package/.agents/scripts/lib/audit-baselines/engine.js

@@ -0,0 +1,177 @@
+/**
+ * engine.js — assemble the `/audit-baselines` evidence envelope
+ * (Story #4902).
+ *
+ * Strictly read-only and strictly offline: it reads committed baselines, the
+ * resolved config, git history, the static import graph, and any friction
+ * ledger it finds. It never writes under `baselines/`, never refreshes a
+ * baseline, and never runs a test, coverage, or mutation suite — the whole
+ * point is that a baseline review costs a file read, not a CI run.
+ *
+ * Findings are evidence, not a verdict: assembling the envelope is success,
+ * however alarming its contents, so the CLI exits 0 whenever it got this far.
+ * Judgment belongs to the lens that reads the envelope.
+ *
+ * @module lib/audit-baselines/engine
+ */
+
+import path from 'node:path';
+import { mainCheckoutRoot, tempRootFrom } from '../config/temp-paths.js';
+import { getQuality, resolveConfig } from '../config-resolver.js';
+import { buildGateSurface } from './gate-surface.js';
+import { buildHeadroom } from './headroom.js';
+import { buildHotspots } from './hotspots.js';
+import { ALL_KINDS, baselinePathFor, GATE_KINDS } from './kinds.js';
+import { DEFAULT_TOP_N, extractOutliers } from './outliers.js';
+import { buildTrend } from './trend.js';
+import {
+  makeWeightResolver,
+  readCentrality,
+  readChurn,
+  readFriction,
+} from './weights.js';
+
+/** Envelope `kind` discriminator; matches the shipped schema's const. */
+const ENVELOPE_KIND = 'audit-baselines-envelope';
+
+/** Envelope schema version — bumped on any breaking shape change. */
+const ENVELOPE_SCHEMA_VERSION = '1';
+
+/** Cap on emitted hotspot clusters, independent of the per-gate `topN`. */
+export const DEFAULT_HOTSPOT_LIMIT = 50;
+
+/**
+ * Resolve the repository config without letting a broken `.agentrc.json`
+ * abort the run — an unreadable config still leaves the baseline files
+ * themselves readable at their default paths.
+ *
+ * @param {string} cwd
+ * @returns {{ quality: object, configError: string | null }}
+ */
+function resolveQualityBlock(cwd) {
+  try {
+    return { quality: getQuality(resolveConfig({ cwd })), configError: null };
+  } catch (err) {
+    return { quality: { gates: {} }, configError: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Absolute temp root the friction ledger is searched under, anchored to the
+ * **analysed** repository rather than the process cwd. `resolvedTempRoot()`
+ * anchors to whichever checkout the current process sits in, which is the
+ * right answer for a writer and the wrong one here: an engine pointed at
+ * another repo with `--cwd` must read that repo's ledger, not this one's.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+function tempRootFor(cwd) {
+  let relative = 'temp';
+  try {
+    relative = tempRootFrom(resolveConfig({ cwd }));
+  } catch {
+    // Unreadable config — the framework default root is still worth probing.
+  }
+  if (path.isAbsolute(relative)) return relative;
+  return path.join(mainCheckoutRoot(cwd) ?? cwd, relative);
+}
+
+/**
+ * Run the engine and return the envelope object. Pure with respect to the
+ * filesystem apart from the reads named in the module docstring — writing
+ * the result is the caller's job.
+ *
+ * @param {{
+ *   cwd: string,
+ *   topN?: number,
+ *   hotspotLimit?: number,
+ *   trendDepth?: number,
+ *   now?: Date,
+ * }} args
+ * @returns {object} the `audit-baselines-envelope`
+ */
+export function runEngine({
+  cwd,
+  topN = DEFAULT_TOP_N,
+  hotspotLimit = DEFAULT_HOTSPOT_LIMIT,
+  trendDepth = 5,
+  now = new Date(),
+}) {
+  const { quality, configError } = resolveQualityBlock(cwd);
+  const { entries, baselines } = buildGateSurface({ cwd, quality, now });
+
+  const outliers = ALL_KINDS.flatMap((kind) =>
+    extractOutliers({ kind, baseline: baselines.get(kind) ?? null, topN }),
+  );
+
+  const churn = readChurn({ cwd });
+  const centrality = readCentrality({ cwd });
+  const friction = readFriction({ tempRootAbs: tempRootFor(cwd) });
+
+  return {
+    kind: ENVELOPE_KIND,
+    schemaVersion: ENVELOPE_SCHEMA_VERSION,
+    generatedAt: now.toISOString(),
+    cwd,
+    topN,
+    configError,
+    degradations: {
+      gitHistory: churn.degraded,
+      importGraph: centrality.degraded,
+      frictionLedger: friction.degraded,
+    },
+    gateSurface: entries,
+    hotspots: buildHotspots({
+      outliers,
+      weightsFor: makeWeightResolver({ churn, centrality, friction }),
+      limit: hotspotLimit,
+    }),
+    trend: buildTrend({
+      cwd,
+      kinds: ALL_KINDS,
+      pathFor: (kind) => baselinePathFor(kind, quality),
+      depth: trendDepth,
+    }),
+    headroom: buildHeadroom({ kinds: GATE_KINDS, quality, baselines }),
+  };
+}
+
+/**
+ * Condense an envelope into the pure-JSON stdout summary. Small enough to
+ * read in a terminal, and never carrying a row set.
+ *
+ * @param {object} envelope
+ * @param {string} outPath absolute path the full envelope was written to
+ * @returns {object}
+ */
+export function summarize(envelope, outPath) {
+  return {
+    kind: 'audit-baselines-summary',
+    schemaVersion: ENVELOPE_SCHEMA_VERSION,
+    out: outPath,
+    generatedAt: envelope.generatedAt,
+    gateSurface: {
+      total: envelope.gateSurface.length,
+      configured: envelope.gateSurface.filter((g) => g.configured).length,
+      missingBaseline: envelope.gateSurface
+        .filter((g) => !g.baselineExists)
+        .map((g) => g.kind),
+      stubs: envelope.gateSurface.filter((g) => g.stub).map((g) => g.kind),
+      deadIgnoreGlobs: envelope.gateSurface.reduce(
+        (n, g) => n + g.deadIgnoreGlobs.length,
+        0,
+      ),
+    },
+    hotspots: {
+      total: envelope.hotspots.length,
+      multiGate: envelope.hotspots.filter((h) => h.gateCount > 1).length,
+      top: envelope.hotspots
+        .slice(0, 5)
+        .map((h) => ({ path: h.path, gates: h.gateKinds, rank: h.rank })),
+    },
+    trend: { kinds: envelope.trend.length },
+    headroom: { axes: envelope.headroom.length },
+    degradations: envelope.degradations,
+  };
+}