@ngockhoale/ukit 3.4.47 → 3.4.48

package/scripts/perf/audit-perf.mjs

@@ -1,1195 +0,0 @@
-#!/usr/bin/env node
-/**
- * audit-perf.mjs — TASK-233 (SPEC §2 FR-001) performance audit generator.
- *
- * Measures every SPEC §2 area from four independent sources and writes
- * `scripts/perf/perf-findings.json` (machine-readable, consumed by TASK-234,
- * TASK-235 and TASK-236) plus `perf-measure.md` next to it (raw appendix).
- * Running this again with the same arguments IS the "measure it the same way
- * both times" requirement from SPEC §5 — TASK-236 re-runs it for before/after.
- *
- * Sources, in the order they are consulted:
- *   1. telemetry — `.ukit/storage/cache/hook-latency/*.jsonl`: per-hook rows,
- *      per-tool-call aggregates reconstructed on `toolUseId`, non-tool events
- *      clustered by time gap, and the nested per-script rows that
- *      `hook-chain-runner.mjs` already emits.
- *   2. structure — `settings.json` hook groups, which decide the process-spawn
- *      count per (event, matcher) pair.
- *   3. micro-benchmark — live spawn measurements: the `bash` and `node` boot
- *      floor, the advisory telemetry child, each settings row's script, and the
- *      index/router helpers invoked per prompt — plus an in-process measurement
- *      of `appendTelemetryRow` itself, so the observability layer's own I/O is
- *      measured rather than assumed (O5).
- *   4. git-log — hot-path files added in the regression window (SPEC §2.3).
- *
- * Honesty contract: a number is emitted only when it was measured. An area with
- * no telemetry rows keeps `null` numbers, `evidence: 'unavailable'` and
- * `status: 'deferred'` — never a plausible-looking guess.
- *
- * Usage:
- *   node scripts/perf/audit-perf.mjs [--root <dir>] [--telemetry-dir <dir>]
- *     [--settings <file>] [--out <file>] [--since <days>] [--bench-iterations <n>]
- *
- * Advisory: exits 0 with a diagnostic when a source is missing, so the audit is
- * runnable against a tree that has never installed UKit.
- */
-
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { execFileSync, spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_ROOT = path.resolve(SCRIPT_DIR, '..', '..');
-
-// Event clusters (non-tool events carry no toolUseId) are reconstructed by
-// grouping consecutive rows of the same event within this window. A host fires
-// a group's hooks back-to-back; the gap before an unrelated event of the same
-// kind is normally model turn latency, orders of magnitude wider.
-const CLUSTER_GAP_MS = 1500;
-
-// SPEC §2.6: anything measured above this p50 on a per-call / per-prompt path
-// is a finding in its own right, not merely a term inside a chain total.
-const HOTSPOT_P50_MS = 50;
-
-// TASK-010: every spawned child carries an explicit timeout + killSignal — a
-// wedged hook script or git child must fail the benchmark sample, not hang the
-// audit forever (same class as BUG-C22-20/21). UKIT_PERF_SPAWN_TIMEOUT_MS
-// overrides the budget for tests.
-const SPAWN_TIMEOUT_MS = Number(process.env.UKIT_PERF_SPAWN_TIMEOUT_MS) || 60 * 1000; // 1 min
-
-// A hook row costs the wrapper `bash`, its `node` runtime, and the advisory
-// telemetry `node --finish` child armed by hook-telemetry.sh.
-const PROCESSES_PER_HOOK_ROW = 3;
-
-const HOOKS_SUBPATH = ['template_project', '.claude', 'hooks'];
-const CHAIN_RUNNER_LABEL = 'hook-chain-runner';
-// The ONE append API every hook writes through — the subject of the O5 benchmark.
-const TELEMETRY_MODULE_SUBPATH = ['template_project', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'];
-
-// Index/router helpers a prompt or an edit pays a cold start for (SPEC §2.5).
-const ROUTER_HELPERS = [
-  ['skill-router.sh', ['.claude', 'hooks', 'skill-router.sh'], true],
-  ['query-index.mjs', ['scripts', 'index', 'query-index.mjs'], false],
-  ['route-task.mjs', ['.claude', 'ukit', 'index', 'route-task.mjs'], false],
-  ['resolve-context.mjs', ['.claude', 'ukit', 'index', 'resolve-context.mjs'], false],
-];
-
-function parseArgs(argv) {
-  const options = {
-    root: DEFAULT_ROOT,
-    telemetryDir: null,
-    settings: null,
-    out: null,
-    sinceDays: 14,
-    benchIterations: 10,
-  };
-  // A value-taking flag as the last argv entry (or followed by another flag)
-  // would reach path.resolve(undefined) → TypeError; fail with usage instead
-  // (same convention as scripts/audit/decision-coverage.mjs).
-  const valueFor = (flag, i) => {
-    const next = argv[i + 1];
-    if (next === undefined || next.startsWith('--')) {
-      console.error(`[audit-perf] missing value for ${flag} — expected: node scripts/perf/audit-perf.mjs ${flag} <value>`);
-      process.exit(1);
-    }
-    return next;
-  };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    switch (arg) {
-      case '--root': options.root = path.resolve(valueFor(arg, i)); i += 1; break;
-      case '--telemetry-dir': options.telemetryDir = path.resolve(valueFor(arg, i)); i += 1; break;
-      case '--settings': options.settings = path.resolve(valueFor(arg, i)); i += 1; break;
-      case '--out': options.out = path.resolve(valueFor(arg, i)); i += 1; break;
-      case '--since': options.sinceDays = Number.parseInt(valueFor(arg, i), 10); i += 1; break;
-      case '--bench-iterations': options.benchIterations = Number.parseInt(valueFor(arg, i), 10); i += 1; break;
-      default: break;
-    }
-  }
-  if (!Number.isFinite(options.sinceDays) || options.sinceDays <= 0) options.sinceDays = 14;
-  if (!Number.isFinite(options.benchIterations) || options.benchIterations <= 0) options.benchIterations = 10;
-  return options;
-}
-
-// --- statistics ------------------------------------------------------------
-
-function percentile(values, p) {
-  if (!values.length) return null;
-  const sorted = [...values].sort((a, b) => a - b);
-  const index = Math.min(sorted.length - 1, Math.max(0, Math.floor(sorted.length * p)));
-  return sorted[index];
-}
-
-function summarise(values) {
-  const clean = values.filter((value) => typeof value === 'number' && Number.isFinite(value));
-  if (!clean.length) return { n: 0, p50: null, p95: null, max: null, total: null };
-  return {
-    n: clean.length,
-    p50: percentile(clean, 0.5),
-    p95: percentile(clean, 0.95),
-    max: Math.max(...clean),
-    total: clean.reduce((sum, value) => sum + value, 0),
-  };
-}
-
-// --- source 1: telemetry ---------------------------------------------------
-
-function loadTelemetry(dir) {
-  if (!dir || !fs.existsSync(dir)) {
-    return { available: false, dir: dir || null, files: 0, rows: [], malformed: 0 };
-  }
-  const files = fs.readdirSync(dir).filter((name) => name.endsWith('.jsonl'));
-  const rows = [];
-  let malformed = 0;
-  for (const name of files) {
-    const body = fs.readFileSync(path.join(dir, name), 'utf8');
-    for (const line of body.split('\n')) {
-      if (!line.trim()) continue;
-      try {
-        rows.push(JSON.parse(line));
-      } catch {
-        malformed += 1;
-      }
-    }
-  }
-  const timestamps = rows.map((row) => row.ts).filter((ts) => typeof ts === 'number');
-  const span = timestamps.length
-    ? `${new Date(Math.min(...timestamps)).toISOString()} → ${new Date(Math.max(...timestamps)).toISOString()}`
-    : 'n/a';
-  return { available: true, dir, files: files.length, rows, malformed, span };
-}
-
-/** Per-hook stats, keyed by hook basename (includes the `(unattributed)` bucket). */
-function perHookStats(rows) {
-  const byHook = new Map();
-  for (const row of rows) {
-    const key = row.hook || '(unattributed)';
-    const bucket = byHook.get(key) || [];
-    bucket.push(row.elapsedMs);
-    byHook.set(key, bucket);
-  }
-  const out = new Map();
-  for (const [hook, values] of byHook) out.set(hook, summarise(values));
-  return out;
-}
-
-/**
- * One record per tool call (rows sharing an event and `toolUseId`) and per
- * non-tool event cluster. Each record exposes `costMs` — the wall time the host
- * actually waited — the execution path it came from, and a per-hook fire count
- * that proves or refutes repeats.
- *
- * The two paths must never be summed: when a `hook-chain-runner` row is present
- * its child rows and the direct per-hook rows describe the SAME executions (the
- * runner emits both), so the chain total is authoritative there and the direct
- * rows are kept only for multiplicity.
- */
-function callRecords(rows) {
-  const toolCalls = new Map();
-  const eventRows = new Map();
-  for (const row of rows) {
-    if (row.toolUseId) {
-      // Keyed by event too: PreToolUse and PostToolUse for one tool call share a
-      // toolUseId and are separate hook chains this audit must not merge.
-      const key = `${row.hookEvent}|${row.toolUseId}`;
-      const bucket = toolCalls.get(key) || [];
-      bucket.push(row);
-      toolCalls.set(key, bucket);
-    } else {
-      const event = row.hookEvent || '(unattributed)';
-      const bucket = eventRows.get(event) || [];
-      bucket.push(row);
-      eventRows.set(event, bucket);
-    }
-  }
-
-  const records = [];
-  for (const [, bucket] of toolCalls) {
-    const first = bucket[0];
-    records.push(buildCallRecord({ event: first.hookEvent, tool: first.toolName || null }, bucket));
-  }
-
-  // A cluster's rows are only complete once the group closes, so clusters are
-  // collected first and turned into records with the identical cost model after.
-  const clusters = new Map();
-  for (const [event, list] of eventRows) {
-    list.sort((a, b) => (a.ts || 0) - (b.ts || 0));
-    let current = null;
-    for (const row of list) {
-      if (!current || (row.ts || 0) - current.last > CLUSTER_GAP_MS) {
-        current = { rows: [] };
-        clusters.set(event, (clusters.get(event) || []).concat([current]));
-      }
-      current.rows.push(row);
-      current.last = row.ts || 0;
-    }
-  }
-  let index = 0;
-  for (const [event, list] of clusters) {
-    for (const cluster of list) {
-      index += 1;
-      records.push(buildCallRecord({ event, tool: null, cluster: index }, cluster.rows));
-    }
-  }
-  return records;
-}
-
-function countHooks(rows) {
-  const counts = {};
-  for (const row of rows) {
-    const key = row.hook || '(unattributed)';
-    counts[key] = (counts[key] || 0) + 1;
-  }
-  return counts;
-}
-
-function sumElapsed(rows) {
-  return rows.reduce((sum, row) => sum + (row.elapsedMs || 0), 0);
-}
-
-/**
- * Cost model shared by tool calls and event clusters. `hook-chain-runner` is
- * the consolidated path; direct rows around it are the same child executions,
- * so the chain total is authoritative and `path` records which model applies.
- */
-function buildCallRecord(identity, rows) {
-  const direct = rows.filter((row) => row.hook !== CHAIN_RUNNER_LABEL);
-  const chained = rows.filter((row) => row.hook === CHAIN_RUNNER_LABEL);
-  return {
-    ...identity,
-    path: chained.length ? 'chain-runner' : 'direct',
-    costMs: chained.length ? sumElapsed(chained) : sumElapsed(direct),
-    direct: sumElapsed(direct),
-    chained: chained.length ? sumElapsed(chained) : null,
-    hookCounts: countHooks(direct),
-    directHooks: direct.length,
-    chainedHooks: chained.length,
-  };
-}
-
-/** Aggregate records by event, optionally restricted to a set of tools. */
-function aggregateCalls(records, event, tools) {
-  const selected = records.filter((record) => record.event === event
-    && (tools === null || (record.tool !== null && tools.includes(record.tool))));
-  return {
-    calls: selected.length,
-    cost: summarise(selected.map((record) => record.costMs)),
-    hookRows: summarise(selected.map((record) => record.directHooks + record.chainedHooks)),
-    directOnly: summarise(selected.filter((record) => record.path === 'direct')
-      .map((record) => record.costMs)),
-    chainOnly: summarise(selected.filter((record) => record.path === 'chain-runner')
-      .map((record) => record.costMs)),
-    byPath: {
-      direct: selected.filter((record) => record.path === 'direct').length,
-      chainRunner: selected.filter((record) => record.path === 'chain-runner').length,
-    },
-  };
-}
-
-/** Non-tool event aggregates, in the same shape as a tool-call aggregate. */
-function eventAggregates(records) {
-  const names = new Set(records.filter((record) => record.tool === null
-    && record.cluster !== undefined).map((record) => record.event));
-  const out = new Map();
-  for (const event of names) out.set(event, aggregateCalls(records, event, null));
-  return out;
-}
-
-/** Fire count of each hook inside a single tool call — proves or refutes repeats. */
-function hookMultiplicity(records) {
-  const perHook = new Map();
-  for (const record of records) {
-    if (!record.hookCounts) continue;
-    for (const [hook, count] of Object.entries(record.hookCounts)) {
-      const tally = perHook.get(hook) || new Map();
-      tally.set(count, (tally.get(count) || 0) + 1);
-      perHook.set(hook, tally);
-    }
-  }
-  const out = new Map();
-  for (const [hook, tally] of perHook) {
-    const distribution = {};
-    for (const count of [...tally.keys()].sort((a, b) => a - b)) distribution[count] = tally.get(count);
-    out.set(hook, {
-      maxPerCall: Math.max(...tally.keys()),
-      calls: [...tally.values()].reduce((sum, value) => sum + value, 0),
-      distribution,
-    });
-  }
-  return out;
-}
-
-/** Nested per-script stats from `hook-chain-runner` rows (the omp path). */
-function nestedScriptStats(rows) {
-  const byScript = new Map();
-  for (const row of rows) {
-    if (row.hook !== CHAIN_RUNNER_LABEL || !Array.isArray(row.scripts)) continue;
-    for (const child of row.scripts) {
-      const bucket = byScript.get(child.scriptName) || [];
-      bucket.push(child.elapsedMs);
-      byScript.set(child.scriptName, bucket);
-    }
-  }
-  const out = new Map();
-  for (const [name, values] of byScript) out.set(name, summarise(values));
-  return out;
-}
-
-/**
- * O3 (SPEC §FR-009): the exec-vs-stage split. A hook's wall time is two
- * different things added together — time it spent waiting for the producer to
- * finish writing stdin, and time it spent working — and only the second is the
- * hook's cost. Rows carry the stage half as `stdinStageMs` (chain rows) or
- * `stageMs` (direct rows); the exec half is derived from the row's own
- * `elapsedMs`, and both halves come from ONE row so they always sum to it.
- *
- * Null-safe by construction: a row carrying neither field is skipped entirely
- * rather than counted as a zero stage, and a bucket with no usable numbers
- * summarises to nulls (`summarise` filters non-finite values), so a tree whose
- * dataset predates the fields renders as "not measured", never as 0ms.
- */
-function stageSplit(rows) {
-  const buckets = new Map();
-  const allStage = [];
-  const allExec = [];
-  for (const row of rows) {
-    const chainStage = row.stdinStageMs;
-    const directStage = row.stageMs;
-    const hasChain = typeof chainStage === 'number' && Number.isFinite(chainStage);
-    const hasDirect = typeof directStage === 'number' && Number.isFinite(directStage);
-    if (!hasChain && !hasDirect) continue;
-    const stage = hasChain ? chainStage : directStage;
-    const key = row.hook || '(unattributed)';
-    if (!buckets.has(key)) {
-      buckets.set(key, { field: hasChain ? 'stdinStageMs' : 'stageMs', stage: [], exec: [] });
-    }
-    const bucket = buckets.get(key);
-    bucket.stage.push(stage);
-    allStage.push(stage);
-    if (typeof row.elapsedMs === 'number' && Number.isFinite(row.elapsedMs)) {
-      const exec = Math.max(0, row.elapsedMs - stage);
-      bucket.exec.push(exec);
-      allExec.push(exec);
-    }
-  }
-  const hooks = new Map();
-  for (const [hook, bucket] of buckets) {
-    hooks.set(hook, {
-      field: bucket.field,
-      stage: summarise(bucket.stage),
-      exec: summarise(bucket.exec),
-      // The rows belong to `hooks`, but `measured` counts the whole dataset so a
-      // reader can tell a fully-split snapshot from a partially-migrated one.
-      measured: bucket.stage.length,
-    });
-  }
-  return {
-    hooks,
-    measured: allStage.length,
-    stage: summarise(allStage),
-    exec: summarise(allExec),
-  };
-}
-
-// --- source 2: settings.json structure -------------------------------------
-
-function loadSettings(root, override) {
-  const candidates = override
-    ? [override]
-    : [
-      path.join(root, 'template_project', '.claude', 'settings.json'),
-      path.join(root, '.claude', 'settings.json'),
-    ];
-  for (const candidate of candidates) {
-    if (!fs.existsSync(candidate)) continue;
-    try {
-      return { file: candidate, settings: JSON.parse(fs.readFileSync(candidate, 'utf8')), error: null };
-    } catch (error) {
-      // Corrupt settings.json (e.g. unresolved merge markers) must not crash
-      // the audit — report the failure and continue with no hook groups.
-      return { file: candidate, settings: null, error: `settings.json parse failed: ${error.message}` };
-    }
-  }
-  return { file: null, settings: null, error: null };
-}
-
-function describeGroups(settings) {
-  if (!settings || !settings.hooks) return [];
-  const groups = [];
-  for (const [event, list] of Object.entries(settings.hooks)) {
-    for (const group of list) {
-      groups.push({
-        event,
-        matcher: group.matcher || null,
-        tools: group.matcher ? group.matcher.split('|') : null,
-        scripts: (group.hooks || []).map((hook) => ({
-          command: hook.command,
-          script: String(hook.command || '').replace(/.*\//, '').replace(/"/g, ''),
-          timeout: hook.timeout,
-        })),
-      });
-    }
-  }
-  return groups;
-}
-
-// --- source 3: micro-benchmarks -------------------------------------------
-
-function benchSpawn(file, args, iterations, env) {
-  const samples = [];
-  for (let i = 0; i < iterations; i += 1) {
-    const start = process.hrtime.bigint();
-    spawnSync(file, args, { env, input: '{}', stdio: ['pipe', 'ignore', 'ignore'], timeout: SPAWN_TIMEOUT_MS, killSignal: 'SIGKILL' });
-    samples.push(Number(process.hrtime.bigint() - start) / 1e6);
-  }
-  return summarise(samples);
-}
-
-/**
- * Every benchmark that exercises the telemetry writer is pointed at a throwaway
- * project root: the audit must never add rows to the dataset it is measuring,
- * or two snapshots of the same tree would differ by the act of auditing them
- * (O2/O5).
- */
-function scratchRoot(label) {
-  return fs.mkdtempSync(path.join(os.tmpdir(), `ukit-perf-${label}-`));
-}
-
-function benchmarkFloor(root, iterations) {
-  const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
-  const telemetryTwin = path.join(root, 'template_project', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs');
-  const scratch = scratchRoot('floor');
-  try {
-    return {
-      floor: {
-        bash: benchSpawn('bash', ['-c', 'true'], iterations, env),
-        node: benchSpawn('node', ['-e', '0'], iterations, env),
-      },
-      telemetryFinish: fs.existsSync(telemetryTwin)
-        ? benchSpawn('node', [telemetryTwin, '--finish'], iterations, {
-          ...env,
-          UKIT_TEL_HOOK: 'audit-bench.sh',
-          UKIT_TEL_RC: '0',
-          PROJECT_ROOT: scratch,
-          CLAUDE_PROJECT_DIR: scratch,
-        })
-        : null,
-    };
-  } finally {
-    fs.rmSync(scratch, { recursive: true, force: true });
-  }
-}
-
-/** The telemetry writer a tree ships, preferring the template (like hooksDir). */
-function telemetryModulePath(root) {
-  const candidates = [
-    path.join(root, 'template_project', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
-    path.join(root, '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
-  ];
-  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
-}
-
-/**
- * O5: cost of one telemetry row as the writer actually pays it — the same
- * `appendTelemetryRow` the hooks call, invoked in-process against a temp project
- * root. The function is async only because the ESM writer must be imported
- * dynamically; the measured region is synchronous I/O, not module loading.
- */
-async function benchmarkAppend(root, iterations) {
-  const module = telemetryModulePath(root);
-  if (!module) return { stats: null, iterations, module: null, reason: 'telemetry writer not resolvable from this root' };
-  let dir = null;
-  try {
-    dir = scratchRoot('append');
-    const { appendTelemetryRow } = await import(pathToFileURL(module).href);
-    const row = {
-      v: 1,
-      ts: Date.now(),
-      hookEvent: 'PreToolUse',
-      hook: 'audit-append-bench.sh',
-      elapsedMs: 1,
-      outcome: 'ok',
-    };
-    const samples = [];
-    for (let i = 0; i < iterations; i += 1) {
-      const start = process.hrtime.bigint();
-      appendTelemetryRow(dir, 'audit-append-bench', row);
-      samples.push(Number(process.hrtime.bigint() - start) / 1e6);
-    }
-    return { stats: summarise(samples), iterations, module, reason: null };
-  } catch (error) {
-    return { stats: null, iterations, module, reason: `append measurement failed: ${error.message}` };
-  } finally {
-    if (dir) fs.rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-/** Resolves the directory holding the shipped hooks, preferring the template. */
-function hooksDir(root) {
-  const candidates = [
-    path.join(root, ...HOOKS_SUBPATH),
-    path.join(root, '.claude', 'hooks'),
-  ];
-  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
-}
-
-function benchmarkHooks(root, groups, iterations) {
-  const dir = hooksDir(root);
-  const results = new Map();
-  if (!dir) return { results, dir: null };
-  const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
-  const names = new Set(groups.flatMap((group) => group.scripts.map((script) => script.script)));
-  for (const name of names) {
-    const file = path.join(dir, name);
-    if (!fs.existsSync(file)) continue;
-    results.set(name, benchSpawn('/bin/bash', [file], iterations, env));
-  }
-  return { results, dir };
-}
-
-function benchmarkRouterHelpers(root, iterations) {
-  const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
-  const results = new Map();
-  for (const [label, relative, isHook] of ROUTER_HELPERS) {
-    const file = path.join(root, ...relative);
-    if (!fs.existsSync(file)) continue;
-    const args = isHook ? [file] : [file];
-    results.set(label, benchSpawn(isHook ? '/bin/bash' : 'node', args, iterations, env));
-  }
-  return results;
-}
-
-// --- source 4: git log ----------------------------------------------------
-
-function recentHotPathAdditions(root, sinceDays) {
-  try {
-    const stdout = execFileSync(
-      'git',
-      [
-        '-C', root, 'log',
-        `--since=${sinceDays} days ago`,
-        '--format=__C__%h|%ad|%s',
-        '--date=short',
-        '--name-only',
-        '--diff-filter=A',
-        '--',
-        'template_project/.claude/hooks',
-        'template_project/.claude/ukit/runtime',
-        'template_project/.claude/ukit/index',
-        '.claude/hooks',
-        '.claude/ukit/runtime',
-      ],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: SPAWN_TIMEOUT_MS, killSignal: 'SIGKILL' },
-    );
-    const commits = [];
-    let current = null;
-    for (const line of stdout.split('\n')) {
-      if (line.startsWith('__C__')) {
-        const [hash, date, subject] = line.slice(5).split('|');
-        current = { hash, date, subject, files: [] };
-        commits.push(current);
-      } else if (line.trim() && current) {
-        current.files.push(line.trim());
-      }
-    }
-    return commits.filter((commit) => commit.files.length);
-  } catch {
-    return [];
-  }
-}
-
-// --- findings --------------------------------------------------------------
-
-function finding(entry) {
-  return {
-    id: entry.id,
-    area: entry.area,
-    evidence: entry.evidence,
-    evidenceDetail: entry.evidenceDetail,
-    p50ms: entry.p50ms ?? null,
-    p95ms: entry.p95ms ?? null,
-    totalMs: entry.totalMs ?? null,
-    invocations: entry.invocations ?? 0,
-    rootCause: entry.rootCause,
-    fixTask: entry.fixTask ?? null,
-    status: entry.status,
-  };
-}
-
-function slug(value) {
-  return String(value).replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toLowerCase();
-}
-function buildFindings(context) {
-  const {
-    telemetry, telemetryDetail, groups, floor, telemetryFinish, hookBench,
-    routerBench, perHook, records, events, multiplicity, nested, additions, spawns,
-    appendBench, root, split, telemetryRows,
-  } = context;
-
-  const findings = [];
-  const measuredEvidence = telemetry.available ? 'telemetry' : 'unavailable';
-
-  // Every settings.json group is a spawn-count finding: whatever its measured
-  // p50, the fix is the same consolidation. `deferred` is reserved for the case
-  // where this tree has no rows to measure the group at all.
-  const classify = (stats) => (stats && stats.p50 !== null
-    ? { status: 'confirmed', fixTask: 'TASK-234' }
-    : { status: 'deferred', fixTask: null });
-
-  // 1. One finding per settings.json group — the spawn-count unit.
-  for (const group of groups) {
-    const measured = group.matcher
-      ? aggregateCalls(records, group.event, group.tools)
-      : (events.get(group.event) || null);
-    const stats = measured ? measured.cost : null;
-    const hasMeasurement = Boolean(stats && stats.n > 0);
-    const spawnsPerCall = group.scripts.length * PROCESSES_PER_HOOK_ROW;
-    const hookList = group.scripts
-      .map((script) => {
-        const bench = hookBench.get(script.script);
-        return `${script.script} (${script.timeout}s${bench ? `, ${bench.p50.toFixed(0)}ms` : ''})`;
-      })
-      .join(', ');
-    const verdict = classify(hasMeasurement ? stats : null);
-
-    findings.push(finding({
-      id: `chain-${slug(group.event)}-${slug(group.matcher || 'all')}`,
-      area: `hook chain — ${group.event}${group.matcher ? ` ${group.matcher}` : ' (all tools)'} — ${group.scripts.length} hook${group.scripts.length === 1 ? '' : 's'}`,
-      evidence: hasMeasurement ? measuredEvidence : 'settings.json',
-      evidenceDetail: hasMeasurement
-        ? `${telemetryDetail}; measured per-call hook cost for the group's matching tools (n=${stats.n}, p50 ${stats.p50}ms, ${measured.hookRows ? measured.hookRows.p50 : 'n/a'} hook rows/call; paths: ${measured.byPath.direct} direct / ${measured.byPath.chainRunner} chain-runner). Hooks: ${hookList}`
-        : `settings.json group only — no telemetry rows are attributable to this group, so no per-call cost is reported. Hooks: ${hookList}`,
-      p50ms: hasMeasurement ? stats.p50 : null,
-      p95ms: hasMeasurement ? stats.p95 : null,
-      totalMs: hasMeasurement ? stats.total : null,
-      invocations: hasMeasurement ? stats.n : 0,
-      rootCause: `${spawnsPerCall} process spawns per call (${group.scripts.length} settings rows × ${PROCESSES_PER_HOOK_ROW}: wrapper bash + node runtime + advisory telemetry node child), against a measured floor of bash ${floor.bash.p50.toFixed(1)}ms + node ${floor.node.p50.toFixed(1)}ms + telemetry finish ${telemetryFinish ? telemetryFinish.p50.toFixed(1) : 'n/a'}ms. ${
-        hasMeasurement && stats.p50 > HOTSPOT_P50_MS
-          ? 'Measured p50 exceeds the 50ms hotspot bar, so the spawn multiplier is the dominant term.'
-          : hasMeasurement
-            ? 'Measured p50 is under the 50ms hotspot bar; consolidation is still the mechanism that removes the spawns.'
-            : 'Not measured on this tree.'
-      }`,
-      fixTask: verdict.fixTask,
-      status: verdict.status,
-    }));
-  }
-
-  // 2. Per-hook hotspots above the SPEC §2.6 bar.
-  for (const [hook, stats] of perHook) {
-    if (stats.p50 === null || stats.p50 <= HOTSPOT_P50_MS) continue;
-    const bench = hookBench.get(hook);
-    findings.push(finding({
-      id: `hook-${slug(hook)}`,
-      area: `single hook — ${hook}`,
-      evidence: measuredEvidence,
-      evidenceDetail: `${telemetryDetail}; standalone re-run p50 ${bench ? `${bench.p50.toFixed(1)}ms` : 'not benchmarked (script not resolvable from this root)'}`,
-      p50ms: stats.p50,
-      p95ms: stats.p95,
-      totalMs: stats.total,
-      invocations: stats.n,
-      rootCause: `per-invocation cost is dominated by the ${PROCESSES_PER_HOOK_ROW}-spawn hook row (wrapper bash ${floor.bash.p50.toFixed(1)}ms + node ${floor.node.p50.toFixed(1)}ms + telemetry finish ${telemetryFinish ? telemetryFinish.p50.toFixed(1) : 'n/a'}ms), plus this script's own work`,
-      fixTask: 'TASK-234',
-      status: 'confirmed',
-    }));
-  }
-
-  // 3. project-important.sh tail (SPEC §2.2).
-  const pi = perHook.get('project-important.sh');
-  if (pi && pi.p95 !== null) {
-    const piClusters = records.filter((record) => record.hookCounts
-      && record.hookCounts['project-important.sh']);
-    const piEvents = [...new Set(piClusters.map((record) => record.event || '(no event)'))].join(', ');
-    findings.push(finding({
-      id: 'hook-project-important-tail',
-      area: 'project-important.sh — PROJECT_IMPORTANT.md injection tail',
-      evidence: measuredEvidence,
-      evidenceDetail: `${telemetryDetail}; bimodal across ${pi.n} invocations: p50 ${pi.p50}ms vs p95 ${pi.p95}ms vs max ${pi.max}ms (paths seen: ${piEvents}) — a cheap path and an expensive path with no cache between them`,
-      p95ms: pi.p95,
-      totalMs: pi.total,
-      invocations: pi.n,
-      rootCause: 'the renderer re-reads PROJECT_IMPORTANT.md and re-runs its full work (strict UTF-8 decode, control-character validation, sensitive-value scan, envelope render) on every invocation; there is no mtime/content-keyed cache, so repeat runs pay the whole cost instead of replaying the previous result',
-      fixTask: 'TASK-235',
-      status: pi.p95 > HOTSPOT_P50_MS ? 'confirmed' : 'not-a-bug',
-    }));
-  } else {
-    findings.push(finding({
-      id: 'hook-project-important-tail',
-      area: 'project-important.sh — PROJECT_IMPORTANT.md injection tail',
-      evidence: 'unavailable',
-      evidenceDetail: `${telemetryDetail}; the 1.5s p95 tail reported by SPEC §2.2 cannot be sized on this tree`,
-      p50ms: null,
-      p95ms: null,
-      totalMs: null,
-      invocations: 0,
-      rootCause: 'no telemetry rows for project-important.sh exist here; the tail must be measured before TASK-235 can claim a fix',
-      fixTask: null,
-      status: 'deferred',
-    }));
-  }
-
-  // 4. record-execution.sh multiplicity (SPEC §2.4) — hypothesis check.
-  const recordExec = multiplicity.get('record-execution.sh');
-  const recordStats = perHook.get('record-execution.sh');
-  const recordGroups = groups.filter((group) => group.scripts.some((script) => script.script === 'record-execution.sh')).length;
-  findings.push(finding({
-    id: 'record-execution-multiplicity',
-    area: `record-execution.sh — PostToolUse receipt writer registered in ${recordGroups} matcher groups`,
-    evidence: recordExec ? measuredEvidence : 'settings.json',
-    evidenceDetail: recordExec
-      ? `${telemetryDetail}; measured fire count per tool call = ${recordExec.maxPerCall} (distribution ${JSON.stringify(recordExec.distribution)} over ${recordExec.calls} calls). The "once per matching matcher group" repeat hypothesis is REFUTED: settings.json names the hook in ${recordGroups} groups, but those matchers are mutually exclusive per tool, so it runs exactly once per call. Its real cost is breadth — highest-invocation hook measured (n=${recordStats ? recordStats.n : 0}, p50 ${recordStats ? recordStats.p50 : 'n/a'}ms, total ${recordStats ? recordStats.total : 'n/a'}ms).`
-      : `settings.json lists record-execution.sh in ${recordGroups} matcher groups; without telemetry the per-call fire count cannot be proven`,
-    p50ms: recordStats ? recordStats.p50 : null,
-    p95ms: recordStats ? recordStats.p95 : null,
-    totalMs: recordStats ? recordStats.total : null,
-    invocations: recordStats ? recordStats.n : (recordExec ? recordExec.calls : 0),
-    rootCause: recordExec
-      ? 'not a duplication bug: the matchers (Read|Grep|Glob, Edit|Write, Bash) are mutually exclusive, so at most one group fires per tool. The cost is that one full 3-spawn hook row is paid on every tool call of every kind — breadth, not repeats.'
-      : 'unverified: a repeat can only be distinguished from breadth with per-tool-call telemetry',
-    fixTask: recordStats && recordStats.p50 > HOTSPOT_P50_MS ? 'TASK-234' : null,
-    status: recordExec && recordStats && recordStats.p50 > HOTSPOT_P50_MS ? 'confirmed' : 'not-a-bug',
-  }));
-
-  // 5. index/router cold start (SPEC §2.5).
-  const promptEvents = events.get('UserPromptSubmit') || null;
-  const routerStats = routerBench.get('skill-router.sh') || hookBench.get('skill-router.sh') || null;
-  if (promptEvents || routerStats) {
-    const helperText = ROUTER_HELPERS
-      .map(([label]) => {
-        const stats = routerBench.get(label) || hookBench.get(label);
-        return `${label} ${stats ? `${stats.p50.toFixed(1)}ms` : 'not benchmarked'}`;
-      })
-      .join(', ');
-    findings.push(finding({
-      id: 'index-router-cold-start',
-      area: 'index/router helpers invoked per prompt (skill-router → resolve-context / route-task / query-index)',
-      evidence: promptEvents && promptEvents.cost.n ? measuredEvidence : 'micro-benchmark',
-      evidenceDetail: `${telemetryDetail}; UserPromptSubmit groups: ${promptEvents ? `n=${promptEvents.cost.n}, p50 ${promptEvents.cost.p50}ms, p95 ${promptEvents.cost.p95}ms, ${promptEvents.hookRows.p50} hook rows/group` : 'none'}. Standalone cold starts: ${helperText}`,
-      p50ms: promptEvents ? promptEvents.cost.p50 : (routerStats ? routerStats.p50 : null),
-      p95ms: promptEvents ? promptEvents.cost.p95 : (routerStats ? routerStats.p95 : null),
-      totalMs: promptEvents ? promptEvents.cost.total : null,
-      invocations: promptEvents ? promptEvents.cost.n : 0,
-      rootCause: 'every router helper pays a fresh node cold start (no warm process is reused), and skill-router.sh additionally imports the index core in-process per invocation; the cost is process boot plus module load, not the routing decision itself',
-      fixTask: 'TASK-234',
-      status: 'confirmed',
-    }));
-  }
-
-  // 6. Recent hot-path additions (SPEC §2.3).
-  const addedFiles = additions.flatMap((commit) => commit.files);
-  if (addedFiles.length) {
-    findings.push(finding({
-      id: 'c29-c32-hot-path-additions',
-      area: `recent hot-path additions — ${addedFiles.length} files across ${additions.length} commits`,
-      evidence: 'git-log',
-      evidenceDetail: `git log --since=${context.sinceDays} days ago --diff-filter=A -- template_project/.claude/hooks template_project/.claude/ukit/runtime template_project/.claude/ukit/index: ${addedFiles.slice(0, 12).join(', ')}${addedFiles.length > 12 ? `, +${addedFiles.length - 12} more` : ''}`,
-      p50ms: null,
-      p95ms: null,
-      totalMs: null,
-      invocations: addedFiles.length,
-      rootCause: 'each added hook file becomes another settings.json row on the event it joins, i.e. another 3-spawn hook row per call (SPEC §1.3 consolidation is what removes them); each added runtime module is an extra cold-start import paid per invocation. The regression is additive spawn count, not one slow file.',
-      fixTask: 'TASK-234',
-      status: 'confirmed',
-    }));
-  }
-
-  // 7. The already-consolidated path — the TASK-234 reuse evidence.
-  const chainStats = perHook.get(CHAIN_RUNNER_LABEL);
-  if (chainStats && chainStats.n) {
-    const nestedText = [...nested.entries()]
-      .sort((a, b) => b[1].n - a[1].n)
-      .slice(0, 6)
-      .map(([name, stats]) => `${name} p50 ${stats.p50}ms`)
-      .join(', ');
-    findings.push(finding({
-      id: 'existing-chain-runner-baseline',
-      area: 'hook-chain-runner.mjs — already-consolidated omp path (TASK-234 reuse target)',
-      evidence: measuredEvidence,
-      evidenceDetail: `${telemetryDetail}; a whole chain of ${spawns.chainScripts ? `${spawns.chainScripts} ` : ''}scripts runs in ONE node process at p50 ${chainStats.p50}ms / p95 ${chainStats.p95}ms (n=${chainStats.n}), while a Claude settings group of comparable size pays ${PROCESSES_PER_HOOK_ROW} spawns per script. Nested per-script rows: ${nestedText}`,
-      p50ms: chainStats.p50,
-      p95ms: chainStats.p95,
-      totalMs: chainStats.total,
-      invocations: chainStats.n,
-      rootCause: 'no defect — this is the measured proof that one-process-per-group execution is achievable with per-script telemetry intact, so TASK-234 should re-point settings.json at this runner rather than build a new one',
-      fixTask: 'TASK-234',
-      status: 'confirmed',
-    }));
-  }
-
-  // 8. The measured floor itself.
-  findings.push(finding({
-    id: 'process-floor',
-    area: 'process spawn floor (bash + node + advisory telemetry child)',
-    evidence: 'micro-benchmark',
-    evidenceDetail: `live spawnSync over ${context.iterations} iterations: bash -c true p50 ${floor.bash.p50.toFixed(2)}ms, node -e 0 p50 ${floor.node.p50.toFixed(2)}ms, node hook-telemetry.mjs --finish p50 ${telemetryFinish ? telemetryFinish.p50.toFixed(2) : 'n/a'}ms`,
-    p50ms: floor.bash.p50 + floor.node.p50 + (telemetryFinish ? telemetryFinish.p50 : 0),
-    p95ms: floor.bash.p95 + floor.node.p95 + (telemetryFinish ? telemetryFinish.p95 : 0),
-    totalMs: null,
-    invocations: 0,
-    rootCause: 'each settings.json hook row is a bash wrapper that boots node, then arms a second node child for advisory telemetry; this floor is paid per row, so it multiplies by the row count of the event',
-    fixTask: 'TASK-234',
-    status: 'not-a-bug',
-  }));
-
-  // 9. The observability layer's own cost (O5) — measured in-process, against a
-  // throwaway project root, so auditing a tree never writes into the dataset
-  // whose rows the audit is counting. Below the hotspot bar this is a documented
-  // non-issue; above it the append joins the same per-call cost reducible by
-  // TASK-234's consolidation.
-  const appendStats = appendBench.stats;
-  if (appendStats && appendStats.p50 !== null) {
-    const hotspot = appendStats.p50 > HOTSPOT_P50_MS;
-    findings.push(finding({
-      id: 'telemetry-append-overhead',
-      area: 'telemetry append overhead — appendTelemetryRow, in-process against a throwaway project root',
-      evidence: 'micro-benchmark',
-      evidenceDetail: `appendTelemetryRow over ${appendBench.iterations} iterations against a temp project root (the audited telemetry dir is never written): p50 ${appendStats.p50.toFixed(3)}ms, p95 ${appendStats.p95.toFixed(3)}ms, max ${appendStats.max.toFixed(3)}ms, total ${appendStats.total.toFixed(3)}ms; writer ${appendBench.module ? path.relative(root, appendBench.module) : 'n/a'}`,
-      p50ms: appendStats.p50,
-      p95ms: appendStats.p95,
-      totalMs: appendStats.total,
-      invocations: appendBench.iterations,
-      rootCause: hotspot
-        ? `one synchronous append costs p50 ${appendStats.p50.toFixed(3)}ms — above the ${HOTSPOT_P50_MS}ms hotspot bar — so the observability layer is paying a measurable per-hook term on the hot path`
-        : `one synchronous append costs p50 ${appendStats.p50.toFixed(3)}ms (under the ${HOTSPOT_P50_MS}ms hotspot bar): the observability layer's own I/O is bounded by a single append plus an amortized 1-in-16 sampled sweep, so it is not the hook chain's dominant term`,
-      fixTask: hotspot ? 'TASK-234' : null,
-      status: hotspot ? 'confirmed' : 'not-a-bug',
-    }));
-  } else {
-    findings.push(finding({
-      id: 'telemetry-append-overhead',
-      area: 'telemetry append overhead — appendTelemetryRow, in-process against a throwaway project root',
-      evidence: 'unavailable',
-      evidenceDetail: `${telemetryDetail}; the append benchmark needs the telemetry writer (${TELEMETRY_MODULE_SUBPATH.join('/')}) resolvable from this root — ${appendBench.reason || 'not resolvable'}, so the observability layer's own cost stays unset rather than estimated`,
-      p50ms: null,
-      p95ms: null,
-      totalMs: null,
-      invocations: 0,
-      rootCause: 'the observability layer cannot be measured on a tree that ships no telemetry writer; the absence is reported instead of a plausible-looking number',
-      fixTask: null,
-      status: 'deferred',
-    }));
-  }
-
-  // 10. O3: the exec-vs-stage split. The reported number here is the EXEC half
-  // — the hook's own cost — because the stage half is the producer's, and
-  // treating wait-on-stdin as a hook defect is exactly the misreading O3 names.
-  // Both halves are stated so the tail can be attributed rather than debated.
-  if (split.measured > 0) {
-    const stageText = split.stage.p50 === null
-      ? 'n/a'
-      : `${split.stage.p50}ms p50 / ${split.stage.p95}ms p95`;
-    const execText = split.exec.p50 === null
-      ? 'n/a'
-      : `${split.exec.p50}ms p50 / ${split.exec.p95}ms p95`;
-    const top = [...split.hooks.entries()]
-      .sort((a, b) => (b[1].stage.total || 0) - (a[1].stage.total || 0))
-      .slice(0, 5)
-      .map(([hook, entry]) => `${hook} (${entry.field}: stage ${entry.stage.p50}ms p50, exec ${entry.exec.p50}ms p50, n=${entry.measured})`)
-      .join(', ');
-    const execHotspot = split.exec.p50 !== null && split.exec.p50 > HOTSPOT_P50_MS;
-    findings.push(finding({
-      id: 'stdin-stage-vs-exec-split',
-      area: 'stdin stage vs execution split (O3 — the wall-time tail attributed)',
-      evidence: measuredEvidence,
-      evidenceDetail: `${telemetryDetail}; ${split.measured} of ${telemetryRows} rows carry the split (a row the producer's stdin held open carries the stage half; a row measured before this field existed carries neither and is excluded, not counted as 0ms). Across those rows, stage ${stageText} vs exec ${execText}; the exec half is the hook's own cost. Per hook: ${top}`,
-      p50ms: split.exec.p50,
-      p95ms: split.exec.p95,
-      totalMs: split.exec.total,
-      invocations: split.measured,
-      rootCause: execHotspot
-        ? `once the stdin stage is attributed to the producer, the remaining execution p50 of ${split.exec.p50}ms is still above the ${HOTSPOT_P50_MS}ms hotspot bar, so the tail is NOT fully explained by stdin staging and the hook's own work needs TASK-234's consolidation`
-        : `the tail artifact is a measurement artifact, not hook work: the wall time a hook reports is the stdin stage plus its execution, and only the execution half is the hook's cost. Attributing the stage half to the producer is what makes project-important.sh's reported p95 tail interpretable instead of looking like a slow script`,
-      fixTask: execHotspot ? 'TASK-234' : null,
-      status: execHotspot ? 'confirmed' : 'not-a-bug',
-    }));
-  } else {
-    // Rows predating the fields are the expected state on an unmigrated tree —
-    // reported as an evidenced absence, never as a 0ms stage.
-    findings.push(finding({
-      id: 'stdin-stage-vs-exec-split',
-      area: 'stdin stage vs execution split (O3 — the wall-time tail attributed)',
-      evidence: 'unavailable',
-      evidenceDetail: `${telemetryDetail}; no row carries \`stdinStageMs\` or \`stageMs\`, so the exec-vs-stage split is unmeasured on this tree. Old rows keep aggregating exactly as before — the fields are additive and optional, so their absence is reported rather than guessed at as 0ms.`,
-      p50ms: null,
-      p95ms: null,
-      totalMs: null,
-      invocations: 0,
-      rootCause: 'the split needs rows written after the fields shipped; a dataset predating them yields no numbers at all (null, not zero), which is the null-safe posture the audit reports here',
-      fixTask: null,
-      status: 'deferred',
-    }));
-  }
-
-  // 11. Registered hooks with no rows at all — evidenced absence, not a guess.
-  const settingsScripts = [...new Set(groups.flatMap((group) => group.scripts.map((script) => script.script)))];
-  for (const script of settingsScripts) {
-    if (perHook.has(script)) continue;
-    findings.push(finding({
-      id: `hook-${slug(script)}-unmeasured`,
-      area: `single hook — ${script} (registered in settings.json, no telemetry rows)`,
-      evidence: 'unavailable',
-      evidenceDetail: `${telemetryDetail}; no row exists for this script, so no per-invocation number is reported. It still costs ${PROCESSES_PER_HOOK_ROW} spawns on its event and is therefore already counted inside that chain's total.`,
-      p50ms: null,
-      p95ms: null,
-      totalMs: null,
-      invocations: 0,
-      rootCause: `no measurement exists for ${script} on this tree — its cost stays unset (evidenced by absence) rather than estimated; the chain it belongs to carries the spawn floor`,
-      fixTask: null,
-      status: 'deferred',
-    }));
-  }
-
-  return findings;
-}
-
-// --- markdown appendix -----------------------------------------------------
-
-function renderMeasureDoc(context) {
-  const {
-    generatedAt, root, telemetry, telemetryDetail, perHook, records, events,
-    multiplicity, nested, groups, floor, telemetryFinish, hookBench, routerBench,
-    additions, findings, settingsFile, settingsError, iterations, hooksResolvedFrom,
-    telemetryRows, telemetryFiles, appendBench, split,
-  } = context;
-  const lines = [];
-  lines.push('# perf-measure.md — raw measurement notes (TASK-233)');
-  lines.push('');
-  lines.push(`Generated: ${generatedAt}`);
-  lines.push('');
-  lines.push('Appendix source for `docs/AI_REPORT/AI_REVIEW_BUGS_REPORT.md`. Every number in');
-  lines.push('`perf-findings.json` comes from one of the four sources below. TASK-236 re-runs');
-  lines.push('the identical command for the before/after table (SPEC §5). Two numbers from two');
-  lines.push('different snapshots are only comparable once their provenance line agrees.');
-  lines.push('');
-  lines.push('## 1. Reproduce');
-  lines.push('');
-  lines.push('```bash');
-  lines.push('node scripts/perf/audit-perf.mjs \\');
-  lines.push(`  --telemetry-dir "${telemetry.dir || path.join(root, '.ukit', 'storage', 'cache', 'hook-latency')}" \\`);
-  lines.push(`  --out "${root}/scripts/perf/perf-findings.json"`);
-  lines.push('node scripts/perf/diff-perf-findings.mjs <earlier-snapshot>.json scripts/perf/perf-findings.json');
-  lines.push('node --test tests/handoff/c33/perfFindings.test.js');
-  lines.push('');
-  lines.push(`- root: \`${root}\``);
-  lines.push(`- settings.json: \`${settingsFile || 'NOT FOUND'}\`${settingsError ? ` — **PARSE FAILED** (${settingsError}); hook-group findings degrade to 'settings.json not readable'` : ''}`);
-  lines.push(`- hooks resolved from: \`${hooksResolvedFrom || 'NOT FOUND'}\``);
-  lines.push(`- telemetry: ${telemetry.available ? `\`${telemetry.dir}\` — ${telemetry.rows.length} rows in ${telemetry.files} files${telemetry.malformed ? ` (${telemetry.malformed} malformed lines skipped)` : ''}` : 'NOT PRESENT — every telemetry-sourced finding is `evidence: "unavailable"`'}`);
-  lines.push(`- snapshot provenance: generatedAt \`${generatedAt}\`, telemetryRows: ${telemetryRows}, telemetryFiles: ${telemetryFiles} — hooks append continuously, so a report is a point-in-time view, not a stable dataset`);
-  lines.push(`- benchmark iterations per subject: ${iterations}`);
-  lines.push('');
-  lines.push('## 2. Process floor (live spawnSync, ms)');
-  lines.push('');
-  lines.push('| subject | p50 | p95 | max |');
-  lines.push('|---|---|---|---|');
-  lines.push(`| \`bash -c true\` | ${floor.bash.p50.toFixed(2)} | ${floor.bash.p95.toFixed(2)} | ${floor.bash.max.toFixed(2)} |`);
-  lines.push(`| \`node -e 0\` | ${floor.node.p50.toFixed(2)} | ${floor.node.p95.toFixed(2)} | ${floor.node.max.toFixed(2)} |`);
-  if (telemetryFinish) {
-    lines.push(`| \`node hook-telemetry.mjs --finish\` | ${telemetryFinish.p50.toFixed(2)} | ${telemetryFinish.p95.toFixed(2)} | ${telemetryFinish.max.toFixed(2)} |`);
-  }
-  lines.push('');
-  lines.push(`A hook row = wrapper bash + node runtime + advisory telemetry child = **${PROCESSES_PER_HOOK_ROW} processes**.`);
-  lines.push('');
-  lines.push('## 3. Telemetry append overhead (O5 — in-process `appendTelemetryRow`, ms)');
-  lines.push('');
-  if (appendBench.stats) {
-    lines.push('| subject | iterations | p50 | p95 | max |');
-    lines.push('|---|---|---|---|---|');
-    lines.push(`| \`appendTelemetryRow\` → throwaway temp root | ${appendBench.iterations} | ${appendBench.stats.p50.toFixed(3)} | ${appendBench.stats.p95.toFixed(3)} | ${appendBench.stats.max.toFixed(3)} |`);
-    lines.push('');
-    lines.push(`Writer: \`${appendBench.module ? path.relative(root, appendBench.module) : 'n/a'}\`. Measured against a temp project root, so auditing a tree never adds rows to the dataset it is counting.`);
-  } else {
-    lines.push(`NOT MEASURED — ${appendBench.reason || 'the telemetry writer is not resolvable from this root'}. The observability layer's own cost stays unset rather than estimated.`);
-  }
-  lines.push('');
-  lines.push('## 4. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)');
-  lines.push('| hook | p50 | p95 | max |');
-  lines.push('|---|---|---|---|');
-  for (const [name, stats] of [...hookBench.entries()].sort((a, b) => b[1].p50 - a[1].p50)) {
-    lines.push(`| \`${name}\` | ${stats.p50.toFixed(1)} | ${stats.p95.toFixed(1)} | ${stats.max.toFixed(1)} |`);
-  }
-  if (!hookBench.size) lines.push('| _(no settings hook resolvable from this root)_ | | | |');
-  lines.push('');
-  lines.push('## 5. Router/index helper cold start (ms)');
-  lines.push('');
-  lines.push('| helper | p50 | p95 | max |');
-  lines.push('|---|---|---|---|');
-  for (const [name, stats] of [...routerBench.entries()].sort((a, b) => b[1].p50 - a[1].p50)) {
-    lines.push(`| \`${name}\` | ${stats.p50.toFixed(1)} | ${stats.p95.toFixed(1)} | ${stats.max.toFixed(1)} |`);
-  }
-  if (!routerBench.size) lines.push('| _(no helper resolvable from this root)_ | | | |');
-  lines.push('');
-  lines.push('## 6. Per-hook telemetry (every hook with rows)');
-  lines.push('');
-  lines.push('| hook | n | p50 | p95 | max | total |');
-  lines.push('|---|---|---|---|---|---|');
-  for (const [hook, stats] of [...perHook.entries()].sort((a, b) => (b[1].total || 0) - (a[1].total || 0))) {
-    lines.push(`| \`${hook}\` | ${stats.n} | ${stats.p50 ?? 'n/a'} | ${stats.p95 ?? 'n/a'} | ${stats.max ?? 'n/a'} | ${stats.total ?? 'n/a'} |`);
-  }
-  lines.push('');
-  lines.push('## 7. Stdin stage vs execution split (O3 — the wall-time tail attributed)');
-  lines.push('');
-  lines.push('A row\'s `elapsedMs` is the stdin stage plus the hook\'s own execution. `stageMs`');
-  lines.push('(direct rows) and `stdinStageMs` (chain rows) are the first half — the producer\'s');
-  lines.push('time, not the hook\'s — and `exec` below is the remainder, derived from the SAME');
-  lines.push('row so the two halves always sum to it. A row carrying neither field predates the');
-  lines.push('split or never staged stdin: it is excluded, never counted as a 0ms stage.');
-  lines.push('');
-  lines.push(`- rows with the split: ${split.measured} of ${telemetryRows}`);
-  lines.push(`- overall: stage ${split.stage.p50 ?? 'n/a'}ms p50 / ${split.stage.p95 ?? 'n/a'}ms p95, exec ${split.exec.p50 ?? 'n/a'}ms p50 / ${split.exec.p95 ?? 'n/a'}ms p95`);
-  lines.push('');
-  lines.push('| hook | field | n | stage p50 | stage p95 | exec p50 | exec p95 |');
-  lines.push('|---|---|---|---|---|---|---|');
-  for (const [hook, entry] of [...split.hooks.entries()].sort((a, b) => (b[1].stage.total || 0) - (a[1].stage.total || 0))) {
-    lines.push(`| \`${hook}\` | \`${entry.field}\` | ${entry.measured} | ${entry.stage.p50 ?? 'n/a'} | ${entry.stage.p95 ?? 'n/a'} | ${entry.exec.p50 ?? 'n/a'} | ${entry.exec.p95 ?? 'n/a'} |`);
-  }
-  if (!split.hooks.size) lines.push('| _(no row carries the split on this tree)_ | | | | | | |');
-  lines.push('');
-  lines.push('## 8. Per tool / per event cost (chain-runner total where present, else direct sum)');
-  lines.push('');
-  lines.push('| scope | calls | cost p50 | cost p95 | hook rows/call p50 | direct / chain-runner calls |');
-  lines.push('|---|---|---|---|---|---|');
-  const toolScopes = [...new Set(records.filter((record) => record.cluster === undefined)
-    .map((record) => `${record.event} ${record.tool || '-'}`))].sort();
-  for (const scope of toolScopes) {
-    const [event, ...rest] = scope.split(' ');
-    const aggregate = aggregateCalls(records, event, [rest.join(' ')]);
-    lines.push(`| ${scope} | ${aggregate.calls} | ${aggregate.cost.p50 ?? 'n/a'} | ${aggregate.cost.p95 ?? 'n/a'} | ${aggregate.hookRows.p50 ?? 'n/a'} | ${aggregate.byPath.direct} / ${aggregate.byPath.chainRunner} |`);
-  }
-  for (const [event, entry] of [...events.entries()].sort()) {
-    lines.push(`| event ${event} (clustered, gap ≤ ${CLUSTER_GAP_MS}ms) | ${entry.calls} | ${entry.cost.p50 ?? 'n/a'} | ${entry.cost.p95 ?? 'n/a'} | ${entry.hookRows.p50 ?? 'n/a'} | ${entry.byPath.direct} / ${entry.byPath.chainRunner} |`);
-  }
-  lines.push('');
-  lines.push('## 9. Hook multiplicity proof (repeat-fire check)');
-  lines.push('');
-  lines.push('| hook | max fires in one tool call | calls observed | fire-count distribution |');
-  lines.push('|---|---|---|---|');
-  for (const [hook, entry] of [...multiplicity.entries()].sort()) {
-    lines.push(`| \`${hook}\` | ${entry.maxPerCall} | ${entry.calls} | ${JSON.stringify(entry.distribution)} |`);
-  }
-  lines.push('');
-  lines.push('## 10. hook-chain-runner nested per-script (already-consolidated omp path)');
-  lines.push('');
-  lines.push('| script | n | p50 | p95 | max |');
-  lines.push('|---|---|---|---|---|');
-  for (const [name, stats] of [...nested.entries()].sort((a, b) => b[1].n - a[1].n)) {
-    lines.push(`| \`${name}\` | ${stats.n} | ${stats.p50} | ${stats.p95} | ${stats.max} |`);
-  }
-  lines.push('');
-  lines.push('## 11. settings.json groups (spawn budget per call)');
-  lines.push('');
-  lines.push('| event | matcher | hooks | registered timeouts | spawns/call |');
-  lines.push('|---|---|---|---|---|');
-  for (const group of groups) {
-    lines.push(`| ${group.event} | ${group.matcher || '(all)'} | ${group.scripts.map((script) => script.script).join(', ')} | ${group.scripts.map((script) => `${script.timeout}s`).join(', ')} | ${group.scripts.length * PROCESSES_PER_HOOK_ROW} |`);
-  }
-  lines.push('');
-  lines.push('## 12. Recent hot-path additions (`git log --diff-filter=A`)');
-  lines.push('');
-  lines.push('| commit | date | subject | files added |');
-  lines.push('|---|---|---|---|');
-  for (const commit of additions) {
-    lines.push(`| \`${commit.hash}\` | ${commit.date} | ${commit.subject} | ${commit.files.map((file) => `\`${file}\``).join(', ')} |`);
-  }
-  if (!additions.length) lines.push('| _(none in window)_ | | | |');
-  lines.push('');
-  lines.push('## 13. Findings emitted');
-  lines.push('');
-  lines.push('| id | evidence | p50 | p95 | status | fixTask |');
-  lines.push('|---|---|---|---|---|---|');
-  for (const item of findings) {
-    lines.push(`| \`${item.id}\` | ${item.evidence} | ${item.p50ms ?? 'n/a'} | ${item.p95ms ?? 'n/a'} | ${item.status} | ${item.fixTask || '-'} |`);
-  }
-  lines.push('');
-  return `${lines.join('\n')}\n`;
-}
-
-// --- main ------------------------------------------------------------------
-
-async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const root = options.root;
-  const telemetryDir = options.telemetryDir || path.join(root, '.ukit', 'storage', 'cache', 'hook-latency');
-  const outFile = options.out || path.join(root, 'scripts', 'perf', 'perf-findings.json');
-  const measureFile = path.join(path.dirname(outFile), 'perf-measure.md');
-
-  const telemetry = loadTelemetry(telemetryDir);
-  const { file: settingsFile, settings, error: settingsError } = loadSettings(root, options.settings);
-  const groups = describeGroups(settings);
-
-  const perHook = perHookStats(telemetry.rows);
-  const records = callRecords(telemetry.rows);
-  const events = eventAggregates(records);
-  const multiplicity = hookMultiplicity(records);
-  const nested = nestedScriptStats(telemetry.rows);
-  const split = stageSplit(telemetry.rows);
-
-  const { floor, telemetryFinish } = benchmarkFloor(root, options.benchIterations);
-  const { results: hookBench, dir: hooksResolvedFrom } = benchmarkHooks(root, groups, options.benchIterations);
-  const routerBench = benchmarkRouterHelpers(root, options.benchIterations);
-  const appendBench = await benchmarkAppend(root, options.benchIterations);
-  const additions = recentHotPathAdditions(root, options.sinceDays);
-  const chainScripts = (() => {
-    const lengths = new Map();
-    for (const row of telemetry.rows) {
-      if (row.hook !== CHAIN_RUNNER_LABEL || !Array.isArray(row.scripts)) continue;
-      lengths.set(row.scripts.length, (lengths.get(row.scripts.length) || 0) + 1);
-    }
-    return [...lengths.entries()].sort((a, b) => b[1] - a[1]).map(([length]) => length)[0] || 0;
-  })();
-
-  // Snapshot provenance (O2): the dataset grows while it is being audited
-  // (30k → 34k rows in two hours in the finding), so a report that does not
-  // state how many rows and files it looked at cannot be compared with another.
-  const telemetryRows = telemetry.available ? telemetry.rows.length : 0;
-  const telemetryFiles = telemetry.available ? telemetry.files : 0;
-  const telemetryDetail = telemetry.available
-    ? `.ukit/storage/cache/hook-latency — ${telemetryRows} rows across ${telemetryFiles} session files, span ${telemetry.span || 'n/a'}`
-    : `telemetry directory not present (${telemetry.dir || 'n/a'})`;
-
-  const generatedAt = new Date().toISOString();
-  const context = {
-    telemetry, telemetryDetail, groups, floor, telemetryFinish, hookBench, routerBench,
-    root,
-    perHook, records, events, multiplicity, nested, additions, settingsFile, settingsError, split,
-    iterations: options.benchIterations,
-    sinceDays: options.sinceDays,
-    telemetryRows, telemetryFiles, appendBench,
-    spawns: { chainScripts },
-  };
-  const findings = buildFindings({ ...context, generatedAt });
-
-  const report = {
-    generatedAt,
-    schema: 'ukit-perf-findings/1',
-    telemetryRows,
-    telemetryFiles,
-    sources: {
-      telemetry: telemetry.available
-        ? { dir: telemetryDir, rows: telemetryRows, files: telemetryFiles }
-        : { dir: telemetryDir, available: false },
-      settings: settingsFile ? { file: settingsFile, error: settingsError } : null,
-      hooksDir: hooksResolvedFrom,
-      benchmarkIterations: options.benchIterations,
-      gitLogWindowDays: options.sinceDays,
-    },
-    findings,
-  };
-
-  fs.mkdirSync(path.dirname(outFile), { recursive: true });
-  fs.writeFileSync(outFile, `${JSON.stringify(report, null, 2)}\n`);
-  fs.writeFileSync(measureFile, renderMeasureDoc({ ...context, findings, generatedAt }));
-
-  process.stdout.write(
-    `${findings.length} findings → ${path.relative(root, outFile)}`
-    + ` (generatedAt ${generatedAt}, telemetry ${telemetry.available ? `${telemetryRows} rows / ${telemetryFiles} files` : 'absent'},`
-    + ` settings ${settingsError ? 'unparseable' : settingsFile ? 'found' : 'missing'},`
-    + ` ${groups.length} groups, ${hookBench.size} hooks benchmarked)\n`,
-  );
-}
-
-main().catch((error) => {
-  console.error(`[audit-perf] ${error && error.message ? error.message : error}`);
-  process.exit(1);
-});