@getarbiter/cli 0.5.0

package/dist/templates/scripts/debt-lib.mjs.ejs

@@ -0,0 +1,1015 @@
+// debt-lib.mjs — generated by arbiter
+// Shared metric collection helpers used by capture-debt-baseline.mjs and debt-report.mjs.
+// Re-generate with: arbiter update
+import { spawnSync } from 'node:child_process';
+import {
+  readFileSync, existsSync, readdirSync, rmSync, mkdirSync, chmodSync, renameSync, statSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { walkRepo } from './lib/glob-walk.mjs';
+
+// The `eslint <paths> --format json` output for this repo exceeds the Node
+// spawnSync default maxBuffer (1 MiB); without a raised ceiling the child aborts
+// with ENOBUFS, stdout is silently truncated, the JSON fails to parse, and the
+// metric collapses to 0 (the dormant complexityViolations ratchet root cause,
+// #1542). 64 MiB comfortably covers the full-repo eslint/knip JSON reports.
+const RUN_MAX_BUFFER = 64 * 1024 * 1024;
+
+function run(cmd, args, opts) {
+  return spawnSync(cmd, args, {
+    encoding: 'utf-8',
+    shell: false,
+    maxBuffer: RUN_MAX_BUFFER,
+    ...opts,
+  });
+}
+
+// jscpd v5 ships its scanner as a prebuilt native `cpd` binary selected per
+// platform by `jscpd/run-jscpd.js` (#1304). On glibc Linux it installs the
+// `jscpd-linux-x64-gnu` package, but that binary is built against GLIBC ≥ 2.34;
+// on an older CI image (glibc < 2.32) the loader rejects it — exit 1, no report
+// — so the duplication scan failed closed even though jscpd "is installed". The
+// musl x64 platform package is a *static-pie* ELF with no libc dependency, so
+// it runs on any Linux regardless of glibc age. npm refuses to install a
+// `libc:["musl"]` optional dep on a glibc host, so we materialise it on demand
+// from the version-pinned registry into a local cache and run it directly.
+// jscpd renamed its platform packages once already (`cpd-linux-x64-musl` ->
+// `jscpd-linux-x64-musl` in 5.0.16, #2370), so the package name is derived from
+// jscpd's own optionalDependencies rather than hardcoded.
+
+/**
+ * The optionalDependencies key jscpd declares for the musl x64 Linux platform
+ * package. Derived instead of hardcoded because jscpd has already renamed this
+ * package once (#2370).
+ * @param {{optionalDependencies?: Record<string, string>}} jscpdPkgJson - parsed jscpd package.json
+ * @returns {string | null}
+ */
+export function deriveStaticMuslPkgName(jscpdPkgJson) {
+  const optionalDeps = jscpdPkgJson?.optionalDependencies ?? {};
+  return Object.keys(optionalDeps).find((name) => name.endsWith('-linux-x64-musl')) ?? null;
+}
+
+/**
+ * Materialise jscpd's static (musl, libc-independent) `cpd` binary into a local
+ * cache and return its path, or null if unavailable (no network / not Linux-x64
+ * / npm absent). Idempotent: a cached binary is reused. The version is pinned to
+ * the installed jscpd so the static binary always matches the gnu one (#1304).
+ * @param {string} jscpdPkgDir - dir of the resolved jscpd package (has version)
+ * @returns {string | null}
+ */
+function resolveStaticCpd(jscpdPkgDir) {
+  if (process.platform !== 'linux' || process.arch !== 'x64') return null;
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(readFileSync(join(jscpdPkgDir, 'package.json'), 'utf-8'));
+  } catch { return null; }
+  const version = pkgJson.version;
+  const staticPkgName = deriveStaticMuslPkgName(pkgJson);
+  if (!version || !staticPkgName) return null;
+  const cacheRoot = resolve(jscpdPkgDir, '..', '.cache', 'jscpd-static', version);
+  const cpdPath = join(cacheRoot, 'cpd');
+  if (existsSync(cpdPath)) return cpdPath;
+  // Fetch the version-pinned static package tarball and extract its binary.
+  let tmp;
+  try {
+    mkdirSync(cacheRoot, { recursive: true });
+    tmp = join(cacheRoot, '.pack');
+    mkdirSync(tmp, { recursive: true });
+    const pack = run('npm', ['pack', `${staticPkgName}@${version}`, '--silent'], { cwd: tmp });
+    if ((pack.status ?? 1) !== 0) return null;
+    const tgz = readdirSync(tmp).find((f) => f.endsWith('.tgz'));
+    if (!tgz) return null;
+    const untar = run('tar', ['xzf', tgz, '-C', tmp], { cwd: tmp });
+    if ((untar.status ?? 1) !== 0) return null;
+    // jscpd 5.0.16 ships the binary at package/bin/jscpd (was
+    // package/cpd-bin/cpd pre-rename, #2370). Try both so a consumer project
+    // pinned to an older jscpd (whose static package still uses the old
+    // layout) still resolves.
+    const extracted = [
+      join(tmp, 'package', 'bin', 'jscpd'),
+      join(tmp, 'package', 'cpd-bin', 'cpd'),
+    ].find((p) => existsSync(p));
+    if (!extracted) return null;
+    renameSync(extracted, cpdPath);
+    chmodSync(cpdPath, 0o755);
+    rmSync(tmp, { recursive: true, force: true });
+    return cpdPath;
+  } catch {
+    if (tmp) rmSync(tmp, { recursive: true, force: true });
+    return null;
+  }
+}
+
+/**
+ * True when a jscpd spawn result is the glibc-too-old failure: the native gnu
+ * `cpd` binary loaded but the dynamic linker could not satisfy its GLIBC version
+ * requirement (exit 1, empty report, `GLIBC_x.yy not found` on stderr) (#1304).
+ * @param {{status: number|null, stderr?: string}} r
+ * @returns {boolean}
+ */
+export function isGlibcIncompatible(r) {
+  return (r?.status ?? 0) !== 0 && /GLIBC_[\d.]+'? not found/.test(r?.stderr ?? '');
+}
+
+/**
+ * Resolve the default jscpd spawn (#1304). jscpd v5 runs a prebuilt native `cpd`
+ * binary chosen per platform by `jscpd/run-jscpd.js`. This resolves the installed
+ * jscpd launcher and runs it directly with the current node. On the docker-ci-build
+ * runner the glibc `cpd-linux-x64-gnu` binary is built against GLIBC ≥ 2.34 but the
+ * image's glibc is < 2.32, so the loader rejects it (exit 1, no report) and the scan
+ * failed closed even though jscpd is installed. On that glibc-too-old failure the
+ * spawn retries once with the static (musl, libc-independent) `cpd` — materialised
+ * on demand by resolveStaticCpd — so the scan actually runs and writes a report.
+ * If jscpd cannot be resolved at all (greenfield/baseline target without the
+ * devDependency) it falls back to the `npx --no-install jscpd` skip-spawn, whose
+ * missing-packages result drives the tool-not-installed (`{skipped:true}`) contract.
+ *
+ * The returned spawn accepts the SAME argv the caller built for the npx path
+ * (`['--no-install','jscpd',...paths,'--silent']`); the direct-binary path strips
+ * the npx-only `--no-install`/`jscpd` prefix tokens, the fallback passes them
+ * through. `resolveBin`, `resolveStatic`, and the per-call `spawnFn` are injectable
+ * so tests never shell to a real npx or native binary.
+ * @param {string} cwd
+ * @param {{resolveBin?: (cwd: string) => string, resolveStatic?: () => string | null}} [opts]
+ * @returns {(dir: string, args: string[], callOpts?: {spawnFn?: (cmd: string, args: string[], o: object) => {status: number|null, stdout: string, stderr: string}}) => ({status: number|null, stdout: string, stderr: string} | null)}
+ */
+export function resolveJscpdSpawn(cwd, opts = {}) {
+  const resolveBin =
+    opts.resolveBin ??
+    ((dir) => {
+      // Resolve from the scanned project first (its node_modules), then fall
+      // back to this module's own require context — the self repo installs jscpd
+      // as a devDependency reachable from here even when the scan dir has no
+      // local node_modules (e.g. a temp fixture or a nested workspace).
+      let pkgPath;
+      try {
+        pkgPath = createRequire(join(resolve(dir), 'package.json')).resolve('jscpd/package.json');
+      } catch {
+        pkgPath = createRequire(import.meta.url).resolve('jscpd/package.json');
+      }
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const binEntry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.jscpd;
+      if (!binEntry) throw new Error('jscpd package.json has no bin.jscpd entry');
+      return join(dirname(pkgPath), binEntry);
+    });
+
+  let binPath;
+  try {
+    binPath = resolveBin(cwd);
+  } catch {
+    // jscpd not installed/resolvable — fall back to npx --no-install jscpd, whose
+    // ENOENT/"missing packages" result drives jscpdScan's skip contract.
+    return (dir, args, callOpts = {}) => {
+      const spawnFn = callOpts.spawnFn;
+      if (spawnFn) return spawnFn('npx', args, { cwd: dir });
+      const r = spawnOrSkip('duplicationPercentage', 'jscpd', 'npx', args, { cwd: dir });
+      return r === null ? null : r;
+    };
+  }
+
+  const jscpdPkgDir = dirname(binPath);
+  const resolveStatic = opts.resolveStatic ?? (() => resolveStaticCpd(jscpdPkgDir));
+  // Direct binary: drop the npx-only prefix tokens so jscpd sees only its own
+  // positional args (paths + flags). The launcher (run-jscpd.js) selects the
+  // platform-native `cpd`; if that binary is glibc-incompatible on this runner
+  // (#1304) retry once with the static (musl, libc-independent) `cpd` so the
+  // scan ACTUALLY runs and writes a report — fail-closed stays intact when even
+  // the static binary is unavailable (the error path is unchanged).
+  return (dir, args, callOpts = {}) => {
+    const jscpdArgs = args.filter((a) => a !== '--no-install' && a !== 'jscpd');
+    const spawnFn = callOpts.spawnFn ?? ((cmd, a, o) => run(cmd, a, o));
+    const r = spawnFn(process.execPath, [binPath, ...jscpdArgs], { cwd: dir });
+    if (!isGlibcIncompatible(r)) return r;
+    const staticCpd = resolveStatic();
+    if (!staticCpd) return r;
+    return spawnFn(staticCpd, jscpdArgs, { cwd: dir });
+  };
+}
+
+/**
+ * Run a command. If the binary is not installed (ENOENT), log a warning to
+ * stderr and return null. Callers skip null-result metrics entirely.
+ * @param {string} name - metric key for the warning message
+ * @param {string} tool - human name of the missing tool
+ * @param {string} cmd  - executable
+ * @param {string[]} args
+ * @param {object} [opts]
+ * @returns {import('child_process').SpawnSyncReturns<string> | null}
+ */
+/**
+ * Whether npx declined to run because its requested package is unavailable.
+ * This is the npx equivalent of an ENOENT spawn failure: no measurement was
+ * attempted, so callers must omit the metric rather than fabricate a value or
+ * report a failed collection.
+ * @param {import('child_process').SpawnSyncReturns<string>} result
+ * @returns {boolean}
+ */
+export function isNpxMissingPackages(result) {
+  return (result.status ?? 0) !== 0 && /npx canceled due to missing packages/.test(result.stderr ?? '');
+}
+
+export function spawnOrSkip(name, tool, cmd, args, opts) {
+  const r = run(cmd, args, opts ?? {});
+  if (r.error?.code === 'ENOENT' || isNpxMissingPackages(r)) {
+    process.stderr.write(`[baseline] skip ${name} — ${tool} not installed\n`);
+    return null;
+  }
+  return r;
+}
+
+/**
+ * Count TO-DO markers across common source file extensions in cwd.
+ * Uses walkRepo (glob-walk.mjs) instead of raw `grep -r .` so nested worktree
+ * checkouts (e.g. `.claude/worktrees/**`) are never double-counted (#1734/#1752).
+ * @param {string} cwd
+ * @returns {number}
+ */
+export function countTodos(cwd) {
+  const MARKER_EXTENSIONS = new Set(['.js', '.ts', '.java', '.go', '.py', '.rs']);
+  const EXTRA_SKIP_SEGMENTS = new Set(['target', '.arbiter', '.temp']);
+  // arbiter-suppress(INV-21, until=2099-01-01, reason="self-referential marker regex inside the TODO-counting collector itself, not an unresolved TODO", owner=@luca)
+  const MARKER_RE = /\bTODO\b/;
+  let count = 0;
+  for (const rel of walkRepo(cwd)) {
+    const dot = rel.lastIndexOf('.');
+    if (dot === -1 || !MARKER_EXTENSIONS.has(rel.slice(dot))) continue;
+    if (rel.split('/').some((seg) => EXTRA_SKIP_SEGMENTS.has(seg))) continue;
+    try {
+      const lines = readFileSync(resolve(cwd, rel), 'utf-8').split('\n');
+      count += lines.filter((l) => MARKER_RE.test(l)).length;
+    } catch { /* skip unreadable files */ }
+  }
+  return count;
+}
+
+/**
+ * Return the short git commit hash for HEAD, or 'unknown'.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function getCommit(cwd) {
+  const r = run('git', ['rev-parse', '--short', 'HEAD'], { cwd });
+  return r.status === 0 ? r.stdout.trim() : 'unknown';
+}
+
+// ── Finding-hygiene metrics (#1405) ──────────────────────────────────────────
+// The incidental-findings spool (`.arbiter/findings/*.jsonl`, #1401) is the SSOT
+// for un-promoted findings. These metrics make the debt ratchet reward DRAINING
+// the spool (lower-is-better) and never let merely FILING findings inflate a
+// green signal (anti-gaming, INV-114). Spool ABSENT → both metrics are OMITTED
+// (treated as not-applicable / "missing tool"), NEVER recorded as a regression.
+
+/** Relative path of the per-shard findings spool directory (#1401). */
+const FINDINGS_DIR = '.arbiter/findings';
+
+/**
+ * Read the findings spool and return open (un-promoted) finding metrics.
+ * Returns `{}` when the spool directory is absent (metric omitted = NA, never a
+ * regression). When present:
+ *   - openFindingsCount    — distinct fingerprints across all shards (dedup-safe)
+ *   - unpromotedFindingsAge — age in whole days of the OLDEST open finding (0 when drained)
+ * Malformed JSONL lines are skipped; a missing/empty spool yields count 0, age 0.
+ * @param {string} cwd
+ * @returns {Record<string, {value: number, unit: string, direction: string}>}
+ */
+export function collectFindingsMetrics(cwd) {
+  const findingsDir = resolve(cwd, FINDINGS_DIR);
+  if (!existsSync(findingsDir)) return {};
+  let shards;
+  try {
+    shards = readdirSync(findingsDir).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    return {};
+  }
+  const fingerprints = new Set();
+  let oldestTs = null;
+  for (const shard of shards) {
+    let text;
+    try {
+      text = readFileSync(join(findingsDir, shard), 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      let entry;
+      try {
+        entry = JSON.parse(trimmed);
+      } catch {
+        continue; // malformed line — resilient skip
+      }
+      if (entry === null || typeof entry !== 'object') continue;
+      const fp = typeof entry.fingerprint === 'string' ? entry.fingerprint : trimmed;
+      fingerprints.add(fp);
+      const ts = typeof entry.ts === 'string' ? Date.parse(entry.ts) : NaN;
+      if (!Number.isNaN(ts) && (oldestTs === null || ts < oldestTs)) oldestTs = ts;
+    }
+  }
+  const ageDays = oldestTs === null ? 0 : Math.floor((Date.now() - oldestTs) / (24 * 60 * 60 * 1000));
+  return {
+    openFindingsCount: { value: fingerprints.size, unit: 'count', direction: 'lower-is-better' },
+    unpromotedFindingsAge: { value: ageDays < 0 ? 0 : ageDays, unit: 'days', direction: 'lower-is-better' },
+  };
+}
+
+/**
+ * Baseline key-drop guard (#1286): a recapture must never silently delete a
+ * metric that the prior baseline tracked (e.g. a jscpd hiccup during capture
+ * would otherwise remove duplicationPercentage and disable the ratchet).
+ * New keys are always allowed.
+ * @param {Record<string, unknown>} priorMetrics
+ * @param {Record<string, unknown>} nextMetrics
+ */
+export function assertKeyParity(priorMetrics, nextMetrics) {
+  const dropped = Object.keys(priorMetrics ?? {}).filter((k) => !(k in (nextMetrics ?? {})));
+  if (dropped.length > 0) {
+    throw new Error(
+      `baseline recapture would drop metric(s): ${dropped.join(', ')} — ` +
+      'refusing to write (fail-closed). Fix the collector or remove the key deliberately.',
+    );
+  }
+}
+
+// ─── Per-stack metric collectors ─────────────────────────────────────────────
+// Each language block exports a single `collectMetrics(cwd)` function.
+// EJS conditionals select the correct block at generation time.
+
+<% if (language === 'typescript') { %>
+/**
+ * Fail-closed jscpd v5 scan (#1286). jscpd v5 silently ignores the config
+ * `pattern`/`path` keys and exits 0 on a 0-file scan, writing a 0% report —
+ * so the fileset MUST be passed as positional CLI args. `.jscpd.json#path`
+ * is the script-private SSOT for that fileset (jscpd itself disregards the
+ * key; this helper and check-duplication.mjs read it).
+ * A scan that ran but covered 0 sources is an ERROR, never a recorded 0%.
+ * @param {string} cwd
+ * @param {{spawn?: (cwd: string, args: string[]) => {status: number|null, stdout: string, stderr: string}}} [opts]
+ *   spawn is injectable for tests; production default shells `npx --no-install jscpd`.
+ * @returns {{error?: string, skipped?: boolean, legacyNoReport?: boolean, status?: number, sources?: number, percentage?: number}}
+ */
+export function jscpdScan(cwd, opts = {}) {
+  const configPath = resolve(cwd, '.jscpd.json');
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+  } catch (err) {
+    return { error: `.jscpd.json unreadable at ${configPath}: ${err.message}` };
+  }
+  const paths = Array.isArray(cfg.path) ? cfg.path.filter((p) => typeof p === 'string' && p) : [];
+  if (paths.length === 0) {
+    return {
+      error: cfg.pattern
+        ? 'legacy v4 .jscpd.json: `pattern` is silently ignored by jscpd v5 — ' +
+          'replace it with a "path" array (the scan fileset, passed as positional args). See #1286.'
+        : '.jscpd.json has no "path" array — required as the jscpd v5 fileset SSOT (#1286).',
+    };
+  }
+  // Without the json reporter, v5 exits 0 writing no report — indistinguishable
+  // from the v4 zero-clones case, so exit-0-plus-no-report could no longer be
+  // trusted as a v4 signal. Reject the config up front (fail-closed, #1286).
+  if (!Array.isArray(cfg.reporters) || !cfg.reporters.includes('json')) {
+    return { error: '.jscpd.json "reporters" must include "json" — the scan is parsed from report/jscpd-report.json (#1286).' };
+  }
+  // Honor a custom `output` dir; default matches jscpd's `report/`.
+  const reportPath = resolve(cwd, typeof cfg.output === 'string' ? cfg.output : 'report', 'jscpd-report.json');
+  // Stale-report poisoning guard: a leftover report from a previous run must
+  // never be parsed as if it were produced by this invocation.
+  rmSync(reportPath, { force: true });
+  const spawn = opts.spawn ?? resolveJscpdSpawn(cwd);
+  const r = spawn(cwd, ['--no-install', 'jscpd', ...paths, '--silent']);
+  if (r === null) return { skipped: true };
+  // `npx --no-install` exits 1 (not ENOENT) when the package is absent — that is
+  // the tool-not-installed case (greenfield target without jscpd), same contract
+  // as spawnOrSkip: skip the collector, never a failed-scan error.
+  if (isNpxMissingPackages(r)) {
+    process.stderr.write('[baseline] skip duplicationPercentage — jscpd not installed\n');
+    return { skipped: true };
+  }
+  if (!existsSync(reportPath)) {
+    if ((r.status ?? 0) === 0) {
+      // jscpd v4 writes the json report only when clones exist; v5 always
+      // writes it. Exit 0 + no report can only be a v4 binary (brownfield
+      // project not yet bumped) with zero clones.
+      return { legacyNoReport: true, status: 0 };
+    }
+    // Surface jscpd's own stderr so the cause is visible in the gate output
+    // (e.g. a glibc-too-old runner image, #1304) instead of an opaque exit code.
+    const why = (r.stderr ?? '').trim().split('\n').slice(0, 3).join(' | ');
+    return {
+      error:
+        `jscpd failed (exit ${r.status}) and wrote no report — fail-closed (#1286)` +
+        (why ? `: ${why}` : ''),
+    };
+  }
+  let dup;
+  try {
+    dup = JSON.parse(readFileSync(reportPath, 'utf-8'));
+  } catch (err) {
+    return { error: `jscpd report unreadable: ${err.message}` };
+  }
+  const total = dup.statistics?.total ?? {};
+  const sources = total.sources ?? 0;
+  if (sources === 0) {
+    return {
+      error:
+        'jscpd scanned 0 source files — fileset/config drift; refusing to record 0% ' +
+        '(fail-closed, CANON-22 / #1286). Check .jscpd.json "path" entries exist.',
+      status: r.status ?? 0,
+    };
+  }
+  if (typeof total.percentage !== 'number') {
+    return {
+      error:
+        'jscpd report has no numeric statistics.total.percentage — schema drift; refusing to record 0% (#1286).',
+    };
+  }
+  return { status: r.status ?? 0, sources, percentage: total.percentage };
+}
+
+/**
+ * Enriched vitest-coverage failure diagnostic (#2226). The bare ENOENT named no
+ * cause: vitest exits 1 for many reasons (a failing test, a missing provider, a
+ * broken reporter) and writes no json-summary for any of them. This names the
+ * cause from the run's OWN output:
+ *   - stdout (vitest prints its version on the RUN line and the Failed Tests
+ *     summary at the end) — the stderr-only tail misled wave-1, it can be a
+ *     PASSING test's incidental stderr;
+ *   - whether .coverage-tmp/ was created at all (stale-guard vs never-ran);
+ *   - exit status/signal.
+ * @param {unknown} err - error thrown while reading/parsing the summary
+ * @param {{status: number|null, signal?: string, stdout?: string, stderr?: string}} raw
+ *   the spawned vitest result
+ * @param {string} cwd - project root (probes .coverage-tmp/)
+ * @returns {string}
+ */
+// eslint-disable-next-line no-control-regex -- strips ANSI SGR codes (\x1b[...m)
+const ANSI_SGR = /\x1b\[[0-9;]*m/g;
+
+function coverageFailureReason(err, raw, cwd) {
+  const clean = (s = '') => s.replace(ANSI_SGR, '');
+  const lines = (s) => clean(s).split('\n').filter(Boolean);
+  const stdoutTail = lines(raw.stdout).slice(-3).join(' | ');
+  const stderrTail = lines(raw.stderr).slice(-3).join(' | ');
+  const outcome = [
+    raw.status !== null ? `exit ${raw.status}` : '',
+    raw.signal ? `signal ${raw.signal}` : '',
+  ].filter(Boolean).join(', ');
+  const version =
+    lines(raw.stdout).find((l) => /^RUN\s+v\d+\.\d+\.\d+/.test(l))?.trim() ?? 'vitest version unknown';
+  const tmpDir = resolve(cwd, '.coverage-tmp');
+  const tmpState = existsSync(tmpDir)
+    ? existsSync(join(tmpDir, 'coverage-summary.json'))
+      ? '.coverage-tmp created, summary present'
+      : '.coverage-tmp created, no summary'
+    : '.coverage-tmp NOT created';
+  return [
+    `vitest coverage summary unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    outcome,
+    version,
+    tmpState,
+    stdoutTail ? `stdout: ${stdoutTail}` : '',
+    stderrTail ? `stderr: ${stderrTail}` : '',
+  ].filter(Boolean).join(' — ');
+}
+
+function readReusedCoverageSummary(cwd, opts) {
+  const rawPath = opts.coverageSummaryPath;
+  if (typeof rawPath !== 'string' || rawPath.length === 0) {
+    throw new Error('coverage summary path is missing');
+  }
+  const summaryPath = resolve(cwd, rawPath);
+  if (isAbsolute(rawPath) || relative(cwd, summaryPath).startsWith('..')) {
+    throw new Error('coverage summary path must stay inside the project root');
+  }
+  const stat = statSync(summaryPath);
+  if (!stat.isFile()) throw new Error(`coverage summary is not a file: ${summaryPath}`);
+  if (opts.coverageStartedAt !== undefined) {
+    if (!Number.isFinite(opts.coverageStartedAt)) {
+      throw new Error('coverage summary freshness timestamp is invalid');
+    }
+    if (stat.mtimeMs < opts.coverageStartedAt) {
+      throw new Error(`coverage summary is stale: ${summaryPath}`);
+    }
+  }
+  return JSON.parse(readFileSync(summaryPath, 'utf-8'));
+}
+
+function coverageMetricsFromSummary(summary) {
+  if (typeof summary.total?.lines?.pct !== 'number') {
+    throw new Error('coverage summary has no numeric total.lines.pct');
+  }
+  return {
+    coverageLine: { value: summary.total.lines.pct, unit: 'percent', direction: 'higher-is-better' },
+<% if (metricsProfile.includeBranchCoverage) { %>
+    coverageBranch: { value: summary.total.branches?.pct ?? 0, unit: 'percent', direction: 'higher-is-better' },
+<% } %>
+  };
+}
+
+/**
+ * Collect TypeScript/JavaScript debt metrics.
+ * @param {string} cwd
+ * @param {Array<{metric: string, reason: string}>} [collectionErrors]
+ *   Sink for tool-ran-but-collection-failed events (distinct from
+ *   tool-not-installed, which soft-skips). debt-report --gate hard-fails on
+ *   any entry (#1286, fail-closed).
+ * @param {{spawnCoverage?: (cwd: string, args: string[]) => {status: number|null, stdout: string, stderr: string} | null, coverageSummaryPath?: string, coverageStartedAt?: number}} [opts]
+ *   spawnCoverage is injectable for tests, mirroring jscpdScan's opts.spawn
+ *   seam: it replaces the `npx vitest run --coverage` invocation so a unit test
+ *   can deterministically simulate "vitest ran, no summary written" (the
+ *   CI-only ENOENT of #2226). Return null to soft-skip (tool-not-installed).
+ * @returns {Record<string, {value: number, unit: string, direction: string}>}
+ */
+export function collectMetrics(cwd, collectionErrors = [], opts = {}) {
+  const metrics = {};
+
+  // ── Coverage (vitest json-summary reporter) ───────────────────────────────
+  if (opts.coverageSummaryPath !== undefined) {
+    try {
+      Object.assign(metrics, coverageMetricsFromSummary(readReusedCoverageSummary(cwd, opts)));
+    } catch (err) {
+      const reason = `gate coverage summary unreadable: ${err instanceof Error ? err.message : String(err)}`;
+      collectionErrors.push({ metric: 'coverageLine', reason });
+      process.stderr.write(`[baseline] ERROR: ${reason}\n`);
+    }
+  } else {
+    // Stale-report poisoning guard, mirroring jscpdScan's reportPath guard above: a leftover .coverage-tmp from a previous run (this box's self-hosted CI workdir persists between jobs) must never be read as this run's output.
+    rmSync(resolve(cwd, '.coverage-tmp'), { recursive: true, force: true });
+    const spawnCoverage =
+      opts.spawnCoverage ??
+      ((dir, args) => spawnOrSkip('coverageLine', 'vitest', 'npx', args, { cwd: dir }));
+    const coverageRaw = spawnCoverage(cwd,
+      ['vitest', 'run', '--coverage', '--coverage.reporter=json-summary', '--coverage.reportsDirectory=.coverage-tmp']);
+    if (coverageRaw !== null) {
+      try {
+        const summary = JSON.parse(readFileSync(resolve(cwd, '.coverage-tmp/coverage-summary.json'), 'utf-8'));
+        Object.assign(metrics, coverageMetricsFromSummary(summary));
+      } catch (err) {
+        const reason = coverageFailureReason(err, coverageRaw, cwd);
+        collectionErrors.push({ metric: 'coverageLine', reason });
+        process.stderr.write(`[baseline] ERROR: ${reason}\n`);
+      }
+    }
+  }
+
+  // ── ESLint errors (severity 2) ────────────────────────────────────────────
+  const eslintRaw = spawnOrSkip('eslintErrors', 'eslint', 'npx', ['eslint', 'src', '--format', 'json'], { cwd });
+  if (eslintRaw !== null) {
+    try {
+      const report = JSON.parse(eslintRaw.stdout || '[]');
+      metrics.eslintErrors = {
+        value: report.flatMap(f => f.messages).filter(m => m.severity === 2).length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+    } catch (err) {
+      const reason = `eslint report unreadable: ${err instanceof Error ? err.message : String(err)}`;
+      collectionErrors.push({ metric: 'eslintErrors', reason });
+      process.stderr.write(`[baseline] ERROR: ${reason}\n`);
+    }
+  }
+
+  // ── TSC strict errors ─────────────────────────────────────────────────────
+  const tscRaw = spawnOrSkip('tscStrictErrors', 'tsc', 'npx', ['tsc', '--noEmit'], { cwd });
+  if (tscRaw !== null) {
+    const output = (tscRaw.stdout ?? '') + (tscRaw.stderr ?? '');
+    metrics.tscStrictErrors = {
+      value: output.split('\n').filter(l => l.includes('error TS')).length,
+      unit: 'count', direction: 'lower-is-better',
+    };
+  }
+
+  // ── Complexity violations (eslint rule) ───────────────────────────────────
+  // Scan `scripts` alongside `src`: the gate-enforcement layer is the
+  // highest-leverage code in the repo and was previously exempt from the
+  // complexity ratchet (#1523/#1542). The baseline grandfathers the current
+  // offenders; the ratchet blocks any net increase and admits gradual burn-down.
+  const eslintComplexRaw = spawnOrSkip('complexityViolations', 'eslint', 'npx',
+    ['eslint', 'src', 'scripts', '--format', 'json', '--rule', '{"complexity":["warn",10]}'], { cwd });
+  if (eslintComplexRaw !== null) {
+    try {
+      const report = JSON.parse(eslintComplexRaw.stdout || '[]');
+      metrics.complexityViolations = {
+        value: report.flatMap(f => f.messages).filter(m => m.ruleId === 'complexity').length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+    } catch (err) {
+      const reason = `eslint complexity report unreadable: ${err instanceof Error ? err.message : String(err)}`;
+      collectionErrors.push({ metric: 'complexityViolations', reason });
+      process.stderr.write(`[baseline] ERROR: ${reason}\n`);
+    }
+  }
+
+  // ── Dead code (knip) ──────────────────────────────────────────────────────
+  const knipRaw = spawnOrSkip('deadCode', 'knip', 'npx', ['knip', '--reporter', 'json'], { cwd });
+  if (knipRaw !== null) {
+    try {
+      const report = JSON.parse(knipRaw.stdout || '{}');
+      metrics.deadCode = {
+        value: (report.files ?? []).length + (report.exports ?? []).length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+    } catch (err) {
+      const reason = `knip report unreadable: ${err instanceof Error ? err.message : String(err)}`;
+      collectionErrors.push({ metric: 'deadCode', reason });
+      process.stderr.write(`[baseline] ERROR: ${reason}\n`);
+    }
+  }
+
+  // ── Duplication (jscpd) — CANON-22 DRY ratchet (Lehman entropy) ────────────
+  // jscpdScan handles the v5 fileset contract (positional paths from
+  // .jscpd.json#path, stale-report cleanup, 0-source rejection). A scan that
+  // ran but failed is surfaced via collectionErrors so debt-report --gate can
+  // hard-fail instead of soft-skipping as "missing tool" (#1286, fail-closed).
+  {
+    const scan = jscpdScan(cwd);
+    if (scan.skipped) {
+      // npx/tooling absent on this machine — genuine soft-skip (ENOENT path).
+    } else if (scan.error) {
+      collectionErrors.push({ metric: 'duplicationPercentage', reason: scan.error });
+      process.stderr.write(`[baseline] ERROR: ${scan.error}\n`);
+    } else if (scan.legacyNoReport) {
+      // v4 binary, zero clones (v5 always writes the report) — genuinely 0%.
+      metrics.duplicationPercentage = { value: 0, unit: 'percent', direction: 'lower-is-better' };
+    } else {
+      metrics.duplicationPercentage = {
+        value: scan.percentage,
+        unit: 'percent', direction: 'lower-is-better',
+      };
+    }
+  }
+
+<% if (metricsProfile.includeBundleSize) { %>
+  // ── Bundle size (frontend-spa only) ───────────────────────────────────────
+  if (existsSync(resolve(cwd, 'dist'))) {
+    const duRaw = run('du', ['-sb', 'dist/'], { cwd });
+    if (!duRaw.error && duRaw.status === 0) {
+      const match = duRaw.stdout.match(/^(\d+)/);
+      if (match) {
+        metrics.bundleSizeKb = {
+          value: Math.round(parseInt(match[1]) / 1024),
+          unit: 'kb', direction: 'lower-is-better',
+        };
+      }
+    }
+  }
+<% } %>
+<% if (metricsProfile.includePublicApiSurface) { %>
+  // ── Public API surface (library archetype — count of top-level exports) ───
+  {
+    if (existsSync(resolve(cwd, 'src'))) {
+      const grepOut = run('grep', ['-rh', '--include=*.ts', '--include=*.mts', '^export', 'src/'], {
+        cwd,
+      });
+      if (grepOut.error || (grepOut.status !== 0 && grepOut.status !== 1)) {
+        const reason = `public API grep failed${grepOut.error?.message ? `: ${grepOut.error.message}` : ` (exit ${grepOut.status})`}`;
+        collectionErrors.push({ metric: 'publicApiSurface', reason });
+        process.stderr.write(`[baseline] ERROR: ${reason}\n`);
+      } else {
+        metrics.publicApiSurface = {
+          value: grepOut.stdout ? grepOut.stdout.split('\n').filter(Boolean).length : 0,
+          unit: 'count', direction: 'lower-is-better',
+        };
+      }
+    }
+  }
+<% } %>
+
+  // ── Finding-hygiene (un-promoted findings spool, #1405) ───────────────────
+  // Language-agnostic: reads `.arbiter/findings/*.jsonl`. Spool absent → omitted
+  // (NA), so a project that never filed a finding is not penalised. Rewards
+  // DRAINING (lower-is-better); filing more findings is a regression (anti-gaming).
+  Object.assign(metrics, collectFindingsMetrics(cwd));
+
+  return metrics;
+}
+<% } else if (language === 'rust') { %>
+/**
+ * Collect Rust debt metrics.
+ * @param {string} cwd
+ * @returns {Record<string, {value: number, unit: string, direction: string}>}
+ */
+export function collectMetrics(cwd) {
+  const metrics = {};
+
+  // ── Coverage (cargo tarpaulin) ────────────────────────────────────────────
+  run('cargo', ['tarpaulin', '--out', 'Json', '--output-dir', '.coverage-tmp'], { cwd });
+  try {
+    const data = JSON.parse(readFileSync(resolve(cwd, '.coverage-tmp/tarpaulin-report.json'), 'utf-8'));
+    metrics.coverageLine = { value: data.coverage, unit: 'percent', direction: 'higher-is-better' };
+  } catch { metrics.coverageLine = { value: 0, unit: 'percent', direction: 'higher-is-better' }; }
+
+  // ── Clippy errors + complexity + dead code ────────────────────────────────
+  const clippyRaw = spawnOrSkip('clippyDenyCount', 'cargo', 'cargo',
+    ['clippy', '--message-format=json', '--', '-W', 'clippy::cognitive_complexity', '-W', 'dead_code'], { cwd });
+  if (clippyRaw !== null) {
+    try {
+      const lines = (clippyRaw.stdout ?? '').split('\n').filter(Boolean);
+      const msgs = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+      metrics.clippyDenyCount = {
+        value: msgs.filter(m => m.reason === 'compiler-message' && m.message?.level === 'error').length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+      metrics.complexityViolations = {
+        value: msgs.filter(m => m.reason === 'compiler-message' && m.message?.code?.code?.includes('cognitive_complexity')).length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+      metrics.deadCode = {
+        value: msgs.filter(m => m.reason === 'compiler-message' && m.message?.code?.code === 'dead_code').length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+    } catch {
+      metrics.clippyDenyCount = { value: 0, unit: 'count', direction: 'lower-is-better' };
+      metrics.complexityViolations = { value: 0, unit: 'count', direction: 'lower-is-better' };
+      metrics.deadCode = { value: 0, unit: 'count', direction: 'lower-is-better' };
+    }
+  }
+
+  // ── cargo audit advisories ────────────────────────────────────────────────
+  const auditRaw = spawnOrSkip('cargoAuditAdvisories', 'cargo-audit', 'cargo', ['audit', '--json'], { cwd });
+  if (auditRaw !== null) {
+    try {
+      const report = JSON.parse(auditRaw.stdout || '{}');
+      metrics.cargoAuditAdvisories = {
+        value: report.vulnerabilities?.found ?? 0,
+        unit: 'count', direction: 'lower-is-better',
+      };
+    } catch { metrics.cargoAuditAdvisories = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+  // ── Finding-hygiene (un-promoted findings spool, #1405) ───────────────────
+  Object.assign(metrics, collectFindingsMetrics(cwd));
+
+  return metrics;
+}
+<% } else if (language === 'java') { %>
+/**
+ * Collect Java debt metrics.
+ * @param {string} cwd
+ * @returns {Record<string, {value: number, unit: string, direction: string}>}
+ */
+export function collectMetrics(cwd) {
+  const metrics = {};
+  const gradleOrMvn = '<%= buildTool === "gradle" ? "./gradlew" : "mvn" %>';
+  const pmdTask = '<%= buildTool === "gradle" ? "pmdMain" : "pmd:pmd" %>';
+  const checkstyleTask = '<%= buildTool === "gradle" ? "checkstyleMain" : "checkstyle:checkstyle" %>';
+
+  // ── JaCoCo line coverage ──────────────────────────────────────────────────
+  try {
+    const report = readFileSync(resolve(cwd, 'build/reports/jacoco/test/jacocoTestReport.xml'), 'utf-8');
+    const lineMatch = report.match(/type="LINE"[^/]*missed="(\d+)"[^/]*covered="(\d+)"/);
+    if (lineMatch) {
+      const missed = parseInt(lineMatch[1]), covered = parseInt(lineMatch[2]);
+      const pct = covered + missed > 0 ? (covered / (covered + missed)) * 100 : 0;
+      metrics.coverageLine = { value: Math.round(pct * 10) / 10, unit: 'percent', direction: 'higher-is-better' };
+    } else { metrics.coverageLine = { value: 0, unit: 'percent', direction: 'higher-is-better' }; }
+<% if (metricsProfile.includeBranchCoverage) { %>
+    const branchMatch = report.match(/type="BRANCH"[^/]*missed="(\d+)"[^/]*covered="(\d+)"/);
+    if (branchMatch) {
+      const missed = parseInt(branchMatch[1]), covered = parseInt(branchMatch[2]);
+      const pct = covered + missed > 0 ? (covered / (covered + missed)) * 100 : 0;
+      metrics.coverageBranch = { value: Math.round(pct * 10) / 10, unit: 'percent', direction: 'higher-is-better' };
+    }
+<% } %>
+  } catch { metrics.coverageLine = { value: 0, unit: 'percent', direction: 'higher-is-better' }; }
+
+  // ── PMD violations ────────────────────────────────────────────────────────
+  const pmdBuildRaw = spawnOrSkip('pmdViolations', gradleOrMvn, gradleOrMvn, [pmdTask, '-q'], { cwd });
+  if (pmdBuildRaw !== null) {
+    try {
+      const pmdXmlPaths = [
+        resolve(cwd, 'build/reports/pmd/main.xml'),
+        resolve(cwd, 'target/pmd.xml'),
+      ];
+      let found = false;
+      for (const p of pmdXmlPaths) {
+        if (existsSync(p)) {
+          const xml = readFileSync(p, 'utf-8');
+          const matches = xml.match(/<violation\b/g);
+          metrics.pmdViolations = { value: matches ? matches.length : 0, unit: 'count', direction: 'lower-is-better' };
+          found = true; break;
+        }
+      }
+      if (!found) metrics.pmdViolations = { value: 0, unit: 'count', direction: 'lower-is-better' };
+    } catch { metrics.pmdViolations = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+  // ── Checkstyle violations ─────────────────────────────────────────────────
+  const csBuildRaw = spawnOrSkip('checkstyleViolations', gradleOrMvn, gradleOrMvn, [checkstyleTask, '-q'], { cwd });
+  if (csBuildRaw !== null) {
+    try {
+      const csXmlPaths = [
+        resolve(cwd, 'build/reports/checkstyle/main.xml'),
+        resolve(cwd, 'target/checkstyle-result.xml'),
+      ];
+      let found = false;
+      for (const p of csXmlPaths) {
+        if (existsSync(p)) {
+          const xml = readFileSync(p, 'utf-8');
+          const matches = xml.match(/<error\b/g);
+          metrics.checkstyleViolations = { value: matches ? matches.length : 0, unit: 'count', direction: 'lower-is-better' };
+          found = true; break;
+        }
+      }
+      if (!found) metrics.checkstyleViolations = { value: 0, unit: 'count', direction: 'lower-is-better' };
+    } catch { metrics.checkstyleViolations = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+<% if (metricsProfile.spotbugsEnabled) { %>
+  // ── SpotBugs violations ───────────────────────────────────────────────────
+  const sbBuildRaw = spawnOrSkip('spotbugsViolations', gradleOrMvn, gradleOrMvn, ['spotbugsMain', '-q'], { cwd });
+  if (sbBuildRaw !== null) {
+    try {
+      const sbXmlPaths = [
+        resolve(cwd, 'build/reports/spotbugs/main.xml'),
+        resolve(cwd, 'build/reports/spotbugs/spotbugsMain.xml'),
+      ];
+      let found = false;
+      for (const p of sbXmlPaths) {
+        if (existsSync(p)) {
+          const xml = readFileSync(p, 'utf-8');
+          const matches = xml.match(/<BugInstance\b/g);
+          metrics.spotbugsViolations = { value: matches ? matches.length : 0, unit: 'count', direction: 'lower-is-better' };
+          found = true; break;
+        }
+      }
+      if (!found) metrics.spotbugsViolations = { value: 0, unit: 'count', direction: 'lower-is-better' };
+    } catch { metrics.spotbugsViolations = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+<% } %>
+
+<% if (metricsProfile.archunitEnabled) { %>
+  // ── ArchUnit failing rule count ───────────────────────────────────────────
+  const archBuildRaw = spawnOrSkip('archunitFailingRules', gradleOrMvn, gradleOrMvn,
+    ['test', '-q', '--tests', '*ArchitectureTest*'], { cwd });
+  if (archBuildRaw !== null) {
+    try {
+      const testResultsDir = resolve(cwd, 'build/test-results/test');
+      if (existsSync(testResultsDir)) {
+        const files = readdirSync(testResultsDir).filter(f => f.includes('ArchitectureTest') && f.endsWith('.xml'));
+        const failingRules = [];
+        for (const f of files) {
+          const xml = readFileSync(resolve(testResultsDir, f), 'utf-8');
+          const methodMatches = [...xml.matchAll(/<testcase[^>]*name="([^"]+)"[^>]*>[^<]*<failure/g)];
+          for (const m of methodMatches) failingRules.push(m[1]);
+        }
+        metrics.archunitFailingRules = {
+          value: failingRules.length,
+          unit: 'count', direction: 'lower-is-better',
+          ...(failingRules.length > 0 ? { items: failingRules } : {}),
+        };
+      } else {
+        metrics.archunitFailingRules = { value: 0, unit: 'count', direction: 'lower-is-better' };
+      }
+    } catch { metrics.archunitFailingRules = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+<% } %>
+
+  // ── Finding-hygiene (un-promoted findings spool, #1405) ───────────────────
+  Object.assign(metrics, collectFindingsMetrics(cwd));
+
+  return metrics;
+}
+<% } else if (language === 'go') { %>
+/**
+ * Collect Go debt metrics.
+ * @param {string} cwd
+ * @returns {Record<string, {value: number, unit: string, direction: string}>}
+ */
+export function collectMetrics(cwd) {
+  const metrics = {};
+
+  // ── Coverage (go test -cover) ─────────────────────────────────────────────
+  // Enumerate project packages with `go list ./...` and exclude import paths
+  // containing /node_modules/ — npm packages that ship Go source without a
+  // nested go.mod (e.g. `flatted`) are otherwise measured as project code,
+  // making the debt ratchet dependency-layout-sensitive (#1950). Package paths
+  // are passed as separate spawn arguments (shell:false), never concatenated.
+  // Fail closed if enumeration fails or yields no usable packages.
+  const goList = run('go', ['list', './...'], { cwd });
+  if ((goList.status ?? 1) !== 0) {
+    throw new Error(
+      `go list ./... failed (exit ${goList.status}): ${goList.stderr ?? ''} — refusing to write (fail-closed)`,
+    );
+  }
+  const goPkgs = (goList.stdout ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !l.includes('/node_modules/'));
+  if (goPkgs.length === 0) {
+    throw new Error(
+      'go list ./... returned no project packages after excluding /node_modules/ — refusing to write (fail-closed)',
+    );
+  }
+  run('go', ['test', '-coverprofile=.coverage-tmp.out', ...goPkgs], { cwd });
+  const goCoverRaw = run('go', ['tool', 'cover', '-func=.coverage-tmp.out'], { cwd });
+  try {
+    const match = goCoverRaw.stdout.match(/total:\s+\(statements\)\s+([\d.]+)%/);
+    metrics.coverageLine = { value: match ? parseFloat(match[1]) : 0, unit: 'percent', direction: 'higher-is-better' };
+  } catch { metrics.coverageLine = { value: 0, unit: 'percent', direction: 'higher-is-better' }; }
+
+  // ── golangci-lint violations ──────────────────────────────────────────────
+  const golintRaw = spawnOrSkip('golangciViolations', 'golangci-lint', 'golangci-lint',
+    ['run', '--out-format=json'], { cwd });
+  if (golintRaw !== null) {
+    try {
+      const report = JSON.parse(golintRaw.stdout || '{"Issues":[]}');
+      metrics.golangciViolations = {
+        value: (report.Issues ?? []).length,
+        unit: 'count', direction: 'lower-is-better',
+      };
+    } catch { metrics.golangciViolations = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+  // ── govulncheck advisories ────────────────────────────────────────────────
+  const govulnRaw = spawnOrSkip('govulncheckAdvisories', 'govulncheck', 'govulncheck',
+    ['-json', './...'], { cwd });
+  if (govulnRaw !== null) {
+    try {
+      const lines = (govulnRaw.stdout ?? '').split('\n').filter(Boolean);
+      const osvIds = new Set();
+      for (const l of lines) {
+        try {
+          const obj = JSON.parse(l);
+          if (obj.osv?.id) osvIds.add(obj.osv.id);
+        } catch { /* skip malformed line */ }
+      }
+      metrics.govulncheckAdvisories = { value: osvIds.size, unit: 'count', direction: 'lower-is-better' };
+    } catch { metrics.govulncheckAdvisories = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+  // ── Finding-hygiene (un-promoted findings spool, #1405) ───────────────────
+  Object.assign(metrics, collectFindingsMetrics(cwd));
+
+  return metrics;
+}
+<% } else if (language === 'python') { %>
+/**
+ * Collect Python debt metrics.
+ * @param {string} cwd
+ * @returns {Record<string, {value: number, unit: string, direction: string}>}
+ */
+export function collectMetrics(cwd) {
+  const metrics = {};
+
+  // ── Coverage (pytest --cov) ───────────────────────────────────────────────
+  run('pytest', ['--cov', '--cov-report=json', '--cov-report=term'], { cwd });
+  try {
+    const data = JSON.parse(readFileSync(resolve(cwd, 'coverage.json'), 'utf-8'));
+    metrics.coverageLine = { value: data.totals?.percent_covered ?? 0, unit: 'percent', direction: 'higher-is-better' };
+  } catch { metrics.coverageLine = { value: 0, unit: 'percent', direction: 'higher-is-better' }; }
+
+  // ── ruff errors (all rules) ───────────────────────────────────────────────
+  const ruffRaw = spawnOrSkip('ruffErrors', 'ruff', 'ruff',
+    ['check', '.', '--output-format', 'json'], { cwd });
+  if (ruffRaw !== null) {
+    try {
+      const violations = JSON.parse(ruffRaw.stdout || '[]');
+      metrics.ruffErrors = { value: violations.length, unit: 'count', direction: 'lower-is-better' };
+    } catch { metrics.ruffErrors = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+  // ── mypy strict errors (skip if no mypy config) ───────────────────────────
+  const mypyConfigExists = existsSync(resolve(cwd, 'mypy.ini'))
+    || existsSync(resolve(cwd, '.mypy.ini'))
+    || existsSync(resolve(cwd, 'setup.cfg'));
+  if (mypyConfigExists) {
+    const mypyRaw = spawnOrSkip('mypyStrictErrors', 'mypy', 'mypy',
+      ['--strict', '.', '--no-color-output'], { cwd });
+    if (mypyRaw !== null) {
+      const errorLines = (mypyRaw.stdout ?? '').split('\n').filter(l => l.includes(': error:'));
+      metrics.mypyStrictErrors = { value: errorLines.length, unit: 'count', direction: 'lower-is-better' };
+    }
+  } else {
+    metrics.mypyStrictErrors = { value: 0, unit: 'count', direction: 'lower-is-better' };
+  }
+
+  // ── pip-audit advisories ──────────────────────────────────────────────────
+  const pipAuditRaw = spawnOrSkip('pipAuditAdvisories', 'pip-audit', 'pip-audit',
+    ['--format', 'json'], { cwd });
+  if (pipAuditRaw !== null) {
+    try {
+      const report = JSON.parse(pipAuditRaw.stdout || '{"dependencies":[]}');
+      const vulnCount = (report.dependencies ?? []).reduce(
+        (acc, dep) => acc + (dep.vulns?.length ?? 0), 0,
+      );
+      metrics.pipAuditAdvisories = { value: vulnCount, unit: 'count', direction: 'lower-is-better' };
+    } catch { metrics.pipAuditAdvisories = { value: 0, unit: 'count', direction: 'lower-is-better' }; }
+  }
+
+  // ── Finding-hygiene (un-promoted findings spool, #1405) ───────────────────
+  Object.assign(metrics, collectFindingsMetrics(cwd));
+
+  return metrics;
+}
+<% } else { %>
+/**
+ * Unknown language — no stack-specific metrics collected.
+ * @param {string} _cwd
+ * @returns {Record<string, never>}
+ */
+export function collectMetrics(_cwd) {
+  return {};
+}
+<% } %>