syndes 0.1.0

package/analytics/metrics/tools.mjs

@@ -0,0 +1,118 @@
+/** Tool mix, read-before-edit, search discipline, delegation, top targets. */
+
+import { KIND } from '../../ledger/schema.mjs';
+
+export const name = 'tools';
+const TOP = 40;
+
+export function create() {
+  return {
+    byFamily: new Map(), byTool: new Map(), commands: new Map(), targets: new Map(),
+    readFirst: 0, blindEdit: 0,
+    searchViaBash: 0, searchViaTool: 0,
+    verifications: 0, delegations: 0, skills: 0,
+    durations: [], failures: 0, calls: 0,
+  };
+}
+
+export function add(state, record) {
+  const data = record.data;
+
+  if (record.kind === KIND.TOOL_PRE) {
+    if (data.searchViaBash) state.searchViaBash += 1;
+    if (data.family === 'search') state.searchViaTool += 1;
+    if (data.verification) state.verifications += 1;
+    if (data.family === 'delegate') state.delegations += 1;
+    if (data.tool === 'Skill') state.skills += 1;
+    if (data.tool === 'Bash' && data.target) bump(state.commands, data.target);
+    return;
+  }
+
+  if (record.kind === KIND.TOOL_POST) {
+    state.calls += 1;
+    bump(state.byFamily, data.family ?? 'other');
+    bump(state.byTool, data.tool ?? 'Unknown');
+    if (data.target) bump(state.targets, data.target);
+    if (data.failed) state.failures += 1;
+    if (typeof data.durationMs === 'number') state.durations.push(data.durationMs);
+    return;
+  }
+
+  if (record.kind === KIND.FILE_TOUCH) {
+    if (data.readFirst) state.readFirst += 1;
+    else state.blindEdit += 1;
+  }
+}
+
+export function done(state) {
+  return {
+    byFamily: Object.fromEntries(state.byFamily),
+    byTool: Object.fromEntries(state.byTool),
+    commands: top(state.commands, TOP),
+    targets: top(state.targets, TOP),
+    readFirst: state.readFirst,
+    blindEdit: state.blindEdit,
+    searchViaBash: state.searchViaBash,
+    searchViaTool: state.searchViaTool,
+    verifications: state.verifications,
+    delegations: state.delegations,
+    skills: state.skills,
+    failures: state.failures,
+    calls: state.calls,
+    // A duration histogram, not the raw list: the list grows without bound and
+    // nothing downstream asks a question the buckets cannot answer.
+    durationBuckets: bucketize(state.durations),
+  };
+}
+
+export function merge(parts) {
+  const out = {
+    byFamily: {}, byTool: {}, commands: {}, targets: {},
+    readFirst: 0, blindEdit: 0, searchViaBash: 0, searchViaTool: 0,
+    verifications: 0, delegations: 0, skills: 0, failures: 0, calls: 0,
+    durationBuckets: {},
+  };
+
+  for (const part of parts) {
+    for (const key of ['byFamily', 'byTool', 'commands', 'targets', 'durationBuckets']) {
+      for (const [name_, count] of Object.entries(part[key] ?? {})) {
+        out[key][name_] = (out[key][name_] ?? 0) + count;
+      }
+    }
+    for (const key of ['readFirst', 'blindEdit', 'searchViaBash', 'searchViaTool',
+      'verifications', 'delegations', 'skills', 'failures', 'calls']) {
+      out[key] += part[key] ?? 0;
+    }
+  }
+
+  const edits = out.readFirst + out.blindEdit;
+  const searches = out.searchViaBash + out.searchViaTool;
+  return {
+    ...out,
+    commands: top(new Map(Object.entries(out.commands)), TOP),
+    targets: top(new Map(Object.entries(out.targets)), TOP),
+    readBeforeEditRate: edits ? out.readFirst / edits : null,
+    searchDiscipline: searches ? out.searchViaTool / searches : null,
+    failureRate: out.calls ? out.failures / out.calls : 0,
+  };
+}
+
+function bump(map, key) {
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+
+function top(map, limit) {
+  return Object.fromEntries([...map.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit));
+}
+
+const BUCKETS = [100, 500, 1000, 5000, 15000, 60000];
+
+function bucketize(values) {
+  const out = {};
+  for (const value of values) {
+    const edge = BUCKETS.find((limit) => value < limit) ?? 'slow';
+    const key = edge === 'slow' ? '60000+' : `<${edge}`;
+    out[key] = (out[key] ?? 0) + 1;
+  }
+  return out;
+}

package/analytics/metrics/volume.mjs

@@ -0,0 +1,98 @@
+/** Sessions, prompts, tool calls, files, commits — the counting floor everything else divides by. */
+
+import { KIND } from '../../ledger/schema.mjs';
+
+export const name = 'volume';
+
+export function create() {
+  return {
+    sessions: new Set(), projects: new Set(), files: new Set(),
+    prompts: 0, toolCalls: 0, writes: 0, commits: 0,
+    insertions: 0, deletions: 0, filesChanged: 0,
+    // Which agent each record came from. This is what makes cross-agent
+    // comparison possible at all — everything else divides by these.
+    bySource: new Map(),
+  };
+}
+
+export function add(state, record) {
+  if (record.session) state.sessions.add(record.session);
+  if (record.project) state.projects.add(record.project);
+
+  const source = record.source ?? 'claude-code';
+  if (!state.bySource.has(source)) state.bySource.set(source, { records: 0, prompts: 0, toolCalls: 0, sessions: new Set() });
+  const bucket = state.bySource.get(source);
+  bucket.records += 1;
+  if (record.session) bucket.sessions.add(record.session);
+  if (record.kind === KIND.PROMPT) bucket.prompts += 1;
+  if (record.kind === KIND.TOOL_POST) bucket.toolCalls += 1;
+
+  switch (record.kind) {
+    case KIND.PROMPT: state.prompts += 1; break;
+    case KIND.TOOL_POST: state.toolCalls += 1; break;
+    case KIND.FILE_TOUCH:
+      state.writes += 1;
+      if (record.data.path) state.files.add(record.data.path);
+      break;
+    case KIND.GIT_COMMIT:
+      state.commits += 1;
+      state.insertions += record.data.insertions ?? 0;
+      state.deletions += record.data.deletions ?? 0;
+      state.filesChanged += record.data.files ?? 0;
+      break;
+    default: break;
+  }
+}
+
+export function done(state) {
+  return {
+    sessions: [...state.sessions],
+    projects: [...state.projects],
+    files: [...state.files].slice(0, 500),
+    prompts: state.prompts,
+    toolCalls: state.toolCalls,
+    writes: state.writes,
+    commits: state.commits,
+    insertions: state.insertions,
+    deletions: state.deletions,
+    filesChanged: state.filesChanged,
+    bySource: Object.fromEntries([...state.bySource].map(([id, b]) => [id, {
+      records: b.records, prompts: b.prompts, toolCalls: b.toolCalls, sessions: [...b.sessions],
+    }])),
+  };
+}
+
+export function merge(parts) {
+  const sessions = new Set();
+  const projects = new Set();
+  const files = new Set();
+  const totals = { prompts: 0, toolCalls: 0, writes: 0, commits: 0, insertions: 0, deletions: 0, filesChanged: 0 };
+
+  const bySource = {};
+  for (const part of parts) {
+    for (const id of part.sessions ?? []) sessions.add(id);
+    for (const id of part.projects ?? []) projects.add(id);
+    for (const file of part.files ?? []) files.add(file);
+    for (const key of Object.keys(totals)) totals[key] += part[key] ?? 0;
+
+    for (const [id, bucket] of Object.entries(part.bySource ?? {})) {
+      bySource[id] ??= { records: 0, prompts: 0, toolCalls: 0, sessions: new Set() };
+      bySource[id].records += bucket.records ?? 0;
+      bySource[id].prompts += bucket.prompts ?? 0;
+      bySource[id].toolCalls += bucket.toolCalls ?? 0;
+      for (const s of bucket.sessions ?? []) bySource[id].sessions.add(s);
+    }
+  }
+
+  return {
+    ...totals,
+    sessionCount: sessions.size,
+    projectCount: projects.size,
+    fileCount: files.size,
+    sessions: [...sessions],
+    projects: [...projects],
+    bySource: Object.fromEntries(Object.entries(bySource).map(([id, b]) => [id, {
+      records: b.records, prompts: b.prompts, toolCalls: b.toolCalls, sessions: b.sessions.size,
+    }])),
+  };
+}

package/analytics/ranges.mjs

@@ -0,0 +1,98 @@
+/**
+ * Time bucketing, in the user's LOCAL timezone.
+ *
+ * Segments are stored in UTC (ledger/segments.mjs) precisely so this module can
+ * be the only place that knows about local time. "Today", "this week" and the
+ * hour-of-day heatmap all mean local time to a human and would be quietly wrong
+ * in UTC — quietly is the problem, since nobody double-checks a heatmap.
+ *
+ * DST is handled by letting Date do the arithmetic on calendar fields rather
+ * than by adding 86,400,000 milliseconds, which is wrong twice a year.
+ */
+
+export const DAY_MS = 86_400_000;
+
+export function localDay(ts) {
+  const date = new Date(ts);
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/** Half-open [start, end). Calendar arithmetic, so a 23- or 25-hour day works. */
+export function dayBounds(day) {
+  const [year, month, date] = day.split('-').map(Number);
+  return {
+    start: new Date(year, month - 1, date, 0, 0, 0, 0).getTime(),
+    end: new Date(year, month - 1, date + 1, 0, 0, 0, 0).getTime(),
+  };
+}
+
+export function shiftDay(day, delta) {
+  const [year, month, date] = day.split('-').map(Number);
+  return localDay(new Date(year, month - 1, date + delta, 12).getTime());
+}
+
+export function daysBetween(from, to) {
+  const out = [];
+  let day = from;
+  while (day <= to) {
+    out.push(day);
+    day = shiftDay(day, 1);
+    if (out.length > 4000) break; // a decade of days is a bug, not a query
+  }
+  return out;
+}
+
+/**
+ * @param {string} spec  today | yesterday | 7d | 30d | 90d | week | month | all
+ *                       | a literal YYYY-MM-DD | 'YYYY-MM-DD..YYYY-MM-DD'
+ * @returns {{from: number, to: number, days: string[], label: string, spec: string}}
+ */
+export function rangeFor(spec = '7d', now = Date.now()) {
+  const today = localDay(now);
+
+  if (spec === 'all') {
+    return build(shiftDay(today, -3650), today, 'all time', spec);
+  }
+  if (spec === 'today') return build(today, today, 'today', spec);
+  if (spec === 'yesterday') {
+    const yesterday = shiftDay(today, -1);
+    return build(yesterday, yesterday, 'yesterday', spec);
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(spec)) return build(spec, spec, spec, spec);
+
+  const explicit = /^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/.exec(spec);
+  if (explicit) return build(explicit[1], explicit[2], `${explicit[1]} to ${explicit[2]}`, spec);
+
+  const relative = /^(\d+)d$/.exec(spec);
+  const count = relative ? Number(relative[1]) : { week: 7, month: 30, quarter: 90 }[spec] ?? 7;
+  return build(shiftDay(today, -(count - 1)), today, `last ${count} days`, spec);
+}
+
+/** The equally sized period immediately before a range, for deltas. */
+export function previousRange(range) {
+  const length = range.days.length;
+  const to = shiftDay(range.days[0], -1);
+  const from = shiftDay(to, -(length - 1));
+  return build(from, to, `previous ${length} days`, `${from}..${to}`);
+}
+
+function build(from, to, label, spec) {
+  const days = daysBetween(from, to);
+  return {
+    from: dayBounds(from).start,
+    to: dayBounds(to).end,
+    days,
+    label,
+    spec,
+  };
+}
+
+export function formatDuration(ms) {
+  if (!ms || ms < 0) return '0m';
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`;
+}

package/analytics/rollup.mjs

@@ -0,0 +1,151 @@
+/**
+ * Incremental daily rollups in rollup/YYYY-MM-DD.json.
+ *
+ * The dashboard must open instantly on a year of data. Re-reading the chain per
+ * request would not, so each finished local day is folded once and cached; only
+ * today (and yesterday, until it settles) is recomputed.
+ *
+ * A rollup is a cache and is always safe to delete — `syndes rebuild`
+ * regenerates every one of them from the chain, which is the only source of truth.
+ */
+
+import { writeFileSync, mkdirSync, existsSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { rollupDir, rollupFile } from '../runtime/paths.mjs';
+import { loadConfig } from '../runtime/config.mjs';
+import { readRange } from '../ledger/read.mjs';
+import { listDays } from '../ledger/segments.mjs';
+import { localDay, dayBounds, daysBetween, shiftDay } from './ranges.mjs';
+import { debug } from '../runtime/log.mjs';
+
+import * as volume from './metrics/volume.mjs';
+import * as time from './metrics/time.mjs';
+import * as tokens from './metrics/tokens.mjs';
+import * as tools from './metrics/tools.mjs';
+import * as context from './metrics/context.mjs';
+import * as friction from './metrics/friction.mjs';
+import * as rework from './metrics/rework.mjs';
+import * as prompts from './metrics/prompts.mjs';
+
+export const METRICS = [volume, time, tokens, tools, context, friction, rework, prompts];
+
+/** Bumped whenever a fold changes shape, so stale caches rebuild themselves. */
+export const ROLLUP_VERSION = 1;
+
+export async function buildDay(day) {
+  const config = loadConfig();
+  const { start, end } = dayBounds(day);
+  const ctx = { day, start, end, idleGapMs: config.idleGapMinutes * 60_000 };
+
+  const states = METRICS.map((metric) => metric.create());
+  let records = 0;
+  let lastSeq = -1;
+
+  for await (const record of readRange(start, end)) {
+    records += 1;
+    lastSeq = record.seq;
+    for (let index = 0; index < METRICS.length; index += 1) {
+      METRICS[index].add(states[index], record, ctx);
+    }
+  }
+
+  const metrics = {};
+  for (let index = 0; index < METRICS.length; index += 1) {
+    metrics[METRICS[index].name] = METRICS[index].done(states[index]);
+  }
+
+  return {
+    day,
+    version: ROLLUP_VERSION,
+    records,
+    lastSeq,
+    builtAt: Date.now(),
+    // A day is final once it is over. Final rollups are never rebuilt.
+    final: Date.now() >= end,
+    metrics,
+  };
+}
+
+export function loadRollup(day) {
+  const file = rollupFile(day);
+  if (!existsSync(file)) return null;
+  try {
+    const rollup = JSON.parse(readFileSync(file, 'utf8'));
+    return rollup.version === ROLLUP_VERSION ? rollup : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeRollup(rollup) {
+  try {
+    mkdirSync(rollupDir, { recursive: true });
+    writeFileSync(rollupFile(rollup.day), `${JSON.stringify(rollup)}\n`);
+  } catch (error) {
+    debug('rollup write failed', rollup.day, error.message);
+  }
+}
+
+/** Every local day the ledger might have records for. */
+export function coveredDays() {
+  const utcDays = listDays();
+  if (!utcDays.length) return [];
+  // A UTC day spills into the local day on either side of it, depending which
+  // way the offset runs. Widening by one on each end is cheaper than being wrong.
+  return daysBetween(shiftDay(utcDays[0], -1), shiftDay(utcDays[utcDays.length - 1], 1))
+    .filter((day) => day <= localDay(Date.now()));
+}
+
+/**
+ * Bring the cache up to date. Called by the worker after every append.
+ *
+ * Rebuilds any day with no valid rollup, plus every non-final one. `all` forces
+ * a full rebuild, which is what `syndes rebuild` runs.
+ */
+export async function updateRollups({ all = false } = {}) {
+  const days = coveredDays();
+  const built = [];
+
+  for (const day of days) {
+    const cached = all ? null : loadRollup(day);
+    if (cached?.final) continue;
+
+    const rollup = await buildDay(day);
+    writeRollup(rollup);
+    built.push(day);
+  }
+  return { built, days: days.length };
+}
+
+/** Rollups for a range, building anything missing on demand. */
+export async function rollupsFor(range) {
+  const out = [];
+  for (const day of range.days) {
+    let rollup = loadRollup(day);
+    if (!rollup || !rollup.final) {
+      rollup = await buildDay(day);
+      if (rollup.records || rollup.final) writeRollup(rollup);
+    }
+    out.push(rollup);
+  }
+  return out;
+}
+
+/** Combine day rollups into one summary per metric. */
+export function mergeRollups(rollups) {
+  const merged = {};
+  for (const metric of METRICS) {
+    merged[metric.name] = metric.merge(rollups.map((rollup) => rollup.metrics?.[metric.name] ?? {}));
+  }
+  merged.records = rollups.reduce((sum, rollup) => sum + (rollup.records ?? 0), 0);
+  merged.days = rollups.length;
+  merged.activeDays = rollups.filter((rollup) => (rollup.records ?? 0) > 0).length;
+  return merged;
+}
+
+export function clearRollups() {
+  try {
+    for (const name of readdirSync(rollupDir)) {
+      if (name.endsWith('.json')) unlinkSync(rollupFile(name.replace('.json', '')));
+    }
+  } catch { /* nothing cached */ }
+}

package/analytics/score.mjs

@@ -0,0 +1,194 @@
+/**
+ * The Efficiency Score: 0–100, five weighted pillars.
+ *
+ * Two rules this file exists to enforce:
+ *
+ *   1. A pillar with no data scores `null`, never zero. Punishing someone for a
+ *      metric we could not measure is the fastest way to make a score ignorable.
+ *      The total re-normalises over the pillars that actually have evidence.
+ *   2. Every part carries its evidence — the number, and the thing that produced
+ *      it — so the UI can open any figure and land on the records behind it.
+ *      A score with no drill-down is a horoscope.
+ */
+
+export const PILLARS = [
+  { key: 'context', label: 'Context hygiene', weight: 25 },
+  { key: 'tools', label: 'Tool discipline', weight: 20 },
+  { key: 'feedback', label: 'Feedback loop', weight: 20 },
+  { key: 'prompts', label: 'Prompt quality', weight: 20 },
+  { key: 'flow', label: 'Flow & friction', weight: 15 },
+];
+
+const clamp = (value) => Math.max(0, Math.min(100, Math.round(value)));
+
+/**
+ * A part with no computable score is absent, not zero.
+ *
+ * The non-finite guard is load-bearing: a metric that is present but empty
+ * yields NaN through the arithmetic, and NaN propagating into the total would
+ * present "we could not measure this" as "you scored nothing".
+ */
+function part(label, weight, score, value, evidence) {
+  if (score === null || score === undefined || !Number.isFinite(score)) return null;
+  return { label, weight, score: clamp(score), value, evidence };
+}
+
+function combine(parts) {
+  const present = parts.filter(Boolean);
+  if (!present.length) return { score: null, parts: [] };
+  const weight = present.reduce((sum, item) => sum + item.weight, 0);
+  const score = present.reduce((sum, item) => sum + item.score * item.weight, 0) / weight;
+  return { score: clamp(score), parts: present };
+}
+
+/**
+ * @param {object} merged  from rollup.mergeRollups()
+ * @returns {{total, confidence, pillars, missing}}
+ */
+export function score(merged) {
+  const { context, tools, rework, prompts, friction, time, volume, tokens } = merged;
+
+  const sessions = volume?.sessionCount ?? 0;
+  const activeHours = (time?.activeMs ?? 0) / 3_600_000;
+
+  const pillars = {
+    context: combine([
+      sessions
+        ? part('Ran out of context', 60,
+            100 - (context.autoCompacts / sessions) * 55,
+            context.autoCompacts / sessions,
+            `${context.autoCompacts} automatic compaction${context.autoCompacts === 1 ? '' : 's'} across ${sessions} session${sessions === 1 ? '' : 's'}`)
+        : null,
+      context?.starts
+        ? part('Continued vs restarted', 20,
+            40 + context.resumeRate * 60,
+            context.resumeRate,
+            `${context.resumed} of ${context.starts} sessions resumed rather than started cold`)
+        : null,
+      context?.avgTokensBeforeCompact
+        ? part('Window used before compacting', 20,
+            Math.min(100, (context.avgTokensBeforeCompact / 150_000) * 100),
+            context.avgTokensBeforeCompact,
+            `${Math.round(context.avgTokensBeforeCompact / 1000)}k tokens in context at the average compact`)
+        : null,
+    ]),
+
+    tools: combine([
+      tools?.readBeforeEditRate === null || tools?.readBeforeEditRate === undefined
+        ? null
+        : part('Read before editing', 40,
+            tools.readBeforeEditRate * 100,
+            tools.readBeforeEditRate,
+            `${tools.readFirst} of ${tools.readFirst + tools.blindEdit} edits touched a file the session had read`),
+      tokens?.turnsWithTools
+        ? part('Calls batched per turn', 30,
+            // One call per turn is a full round-trip each; three is efficient.
+            ((tokens.callsPerTurn - 1) / 2) * 100,
+            tokens.callsPerTurn,
+            `${tokens.callsPerTurn.toFixed(2)} tool calls per turn that used tools`)
+        : null,
+      tools?.searchDiscipline === null || tools?.searchDiscipline === undefined
+        ? null
+        : part('Search tools vs bash grep', 30,
+            tools.searchDiscipline * 100,
+            tools.searchDiscipline,
+            `${tools.searchViaBash} of ${tools.searchViaBash + tools.searchViaTool} searches went through Bash`),
+    ]),
+
+    feedback: combine([
+      rework?.verifyRate === null || rework?.verifyRate === undefined
+        ? null
+        : part('Verified after changing', 45,
+            rework.verifyRate * 100,
+            rework.verifyRate,
+            `${rework.verifiedRuns} of ${rework.verifiedRuns + rework.unverifiedRuns} edit runs ended in a test or build`),
+      rework?.calls
+        ? part('Tool failure rate', 35,
+            100 - rework.errorRate * 400,
+            rework.errorRate,
+            `${rework.errors} failures in ${rework.calls} tool calls`)
+        : null,
+      rework?.calls
+        ? part('Retry storms', 20,
+            100 - rework.stormCount * 25,
+            rework.stormCount,
+            rework.stormCount
+              ? `${rework.stormCount} command${rework.stormCount === 1 ? '' : 's'} retried 3+ times without a change`
+              : 'no command retried 3+ times unchanged')
+        : null,
+    ]),
+
+    prompts: combine([
+      prompts?.count
+        ? part('Corrections', 40,
+            100 - prompts.correctionRate * 350,
+            prompts.correctionRate,
+            `${prompts.corrections} of ${prompts.count} prompts read as a correction`)
+        : null,
+      prompts?.reprompRate === null || prompts?.reprompRate === undefined
+        ? null
+        : part('Re-prompts without progress', 35,
+            100 - prompts.reprompRate * 200,
+            prompts.reprompRate,
+            `${prompts.followUp} prompts followed one that produced no tool call`),
+      prompts?.count
+        ? part('Prompt detail', 25,
+            // Too short under-specifies; past a point more words stop helping.
+            Math.min(100, (prompts.medianWords ?? 0) / 35 * 100),
+            prompts.medianWords,
+            `${prompts.medianWords} words in the median prompt`)
+        : null,
+    ]),
+
+    flow: combine([
+      activeHours >= 0.1
+        ? part('Permission interruptions', 45,
+            100 - (friction.blocks / activeHours) * 12,
+            friction.blocks / activeHours,
+            `${(friction.blocks / activeHours).toFixed(1)} permission stops per active hour`)
+        : null,
+      friction?.blocks
+        ? part('Time spent blocked', 25,
+            100 - (friction.blockedMs / 1000 / 60) * 2,
+            friction.blockedMs,
+            `${Math.round(friction.blockedMs / 60_000)} minutes waiting on permission prompts`)
+        : null,
+      time?.wallMs
+        ? part('Focus', 30,
+            time.activeShare * 130,
+            time.activeShare,
+            `${Math.round(time.activeShare * 100)}% of session wall-clock was active work`)
+        : null,
+    ]),
+  };
+
+  let total = 0;
+  let weight = 0;
+  const missing = [];
+  for (const pillar of PILLARS) {
+    const result = pillars[pillar.key];
+    if (result.score === null) { missing.push(pillar.key); continue; }
+    total += result.score * pillar.weight;
+    weight += pillar.weight;
+  }
+
+  return {
+    total: weight ? clamp(total / weight) : null,
+    weightCovered: weight,
+    confidence: confidenceOf(merged),
+    pillars: PILLARS.map((pillar) => ({ ...pillar, ...pillars[pillar.key] })),
+    missing,
+  };
+}
+
+/**
+ * A score computed from three tool calls is noise. Saying so is more useful than
+ * a confident number, so the UI can show the caveat instead of the illusion.
+ */
+function confidenceOf(merged) {
+  const calls = merged.tools?.calls ?? 0;
+  const sessions = merged.volume?.sessionCount ?? 0;
+  if (calls >= 300 && sessions >= 5) return 'high';
+  if (calls >= 60 && sessions >= 2) return 'medium';
+  return 'low';
+}