@ngockhoale/ukit 2.6.11 → 2.7.1

package/scripts/perf/audit-perf.mjs

@@ -0,0 +1,920 @@
+#!/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
+ * `docs/AI_REPORT/perf-findings.json` (machine-readable, consumed by TASK-234,
+ * TASK-235 and TASK-236) plus `docs/AI_REPORT/perf-measure.md` (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.
+ *   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 path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } 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;
+
+// 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 = ['templates', '.claude', 'hooks'];
+const CHAIN_RUNNER_LABEL = 'hook-chain-runner';
+
+// 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,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    switch (arg) {
+      case '--root': options.root = path.resolve(next); i += 1; break;
+      case '--telemetry-dir': options.telemetryDir = path.resolve(next); i += 1; break;
+      case '--settings': options.settings = path.resolve(next); i += 1; break;
+      case '--out': options.out = path.resolve(next); i += 1; break;
+      case '--since': options.sinceDays = Number.parseInt(next, 10); i += 1; break;
+      case '--bench-iterations': options.benchIterations = Number.parseInt(next, 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;
+}
+
+// --- source 2: settings.json structure -------------------------------------
+
+function loadSettings(root, override) {
+  const candidates = override
+    ? [override]
+    : [
+      path.join(root, 'templates', '.claude', 'settings.json'),
+      path.join(root, '.claude', 'settings.json'),
+    ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return { file: candidate, settings: JSON.parse(fs.readFileSync(candidate, 'utf8')) };
+    }
+  }
+  return { file: null, settings: 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'] });
+    samples.push(Number(process.hrtime.bigint() - start) / 1e6);
+  }
+  return summarise(samples);
+}
+
+function benchmarkFloor(root, iterations) {
+  const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
+  const telemetryTwin = path.join(root, 'templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs');
+  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: root,
+      })
+      : null,
+  };
+}
+
+/** 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',
+        '--',
+        'templates/.claude/hooks',
+        'templates/.claude/ukit/runtime',
+        'templates/.claude/ukit/index',
+        '.claude/hooks',
+        '.claude/ukit/runtime',
+      ],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    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,
+  } = 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 -- templates/.claude/hooks templates/.claude/ukit/runtime templates/.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. 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, iterations, hooksResolvedFrom,
+  } = 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).');
+  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}/docs/AI_REPORT/perf-findings.json"`);
+  lines.push('node --test tests/handoff/c33/perfFindings.test.js');
+  lines.push('```');
+  lines.push('');
+  lines.push(`- root: \`${root}\``);
+  lines.push(`- settings.json: \`${settingsFile || 'NOT FOUND'}\``);
+  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(`- 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. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)');
+  lines.push('');
+  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('## 4. 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('## 5. 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('## 6. 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('## 7. 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('## 8. 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('## 9. 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('## 10. 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('## 11. 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 ------------------------------------------------------------------
+
+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, 'docs', 'AI_REPORT', 'perf-findings.json');
+  const measureFile = path.join(path.dirname(outFile), 'perf-measure.md');
+
+  const telemetry = loadTelemetry(telemetryDir);
+  const { file: settingsFile, settings } = 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 { floor, telemetryFinish } = benchmarkFloor(root, options.benchIterations);
+  const { results: hookBench, dir: hooksResolvedFrom } = benchmarkHooks(root, groups, options.benchIterations);
+  const routerBench = benchmarkRouterHelpers(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;
+  })();
+
+  const telemetryDetail = telemetry.available
+    ? `.ukit/storage/cache/hook-latency — ${telemetry.rows.length} rows across ${telemetry.files} 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,
+    iterations: options.benchIterations,
+    sinceDays: options.sinceDays,
+    spawns: { chainScripts },
+    hooksResolvedFrom,
+  };
+  const findings = buildFindings({ ...context, generatedAt });
+
+  const report = {
+    generatedAt,
+    schema: 'ukit-perf-findings/1',
+    sources: {
+      telemetry: telemetry.available
+        ? { dir: telemetryDir, rows: telemetry.rows.length, files: telemetry.files }
+        : { dir: telemetryDir, available: false },
+      settings: settingsFile,
+      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)}`
+    + ` (telemetry ${telemetry.available ? `${telemetry.rows.length} rows` : 'absent'},`
+    + ` settings ${settingsFile ? 'found' : 'missing'},`
+    + ` ${groups.length} groups, ${hookBench.size} hooks benchmarked)\n`,
+  );
+}
+
+main();