agentboss 0.1.0 → 0.1.2

package/server/analysis/thresholds-v2.js

@@ -1,358 +1,364 @@
-/**
- * v2 capability thresholds — single source of truth.
- *
- * Each sub-indicator declares:
- *   • how its raw value should be interpreted (higher / lower / band-better)
- *   • the L1-L4 boundaries, possibly per difficulty bucket
- *
- * The shape is deliberately flat data so it can be tweaked without code
- * changes and (eventually) edited from the Settings UI.
- *
- * Source of truth: docs/superpowers/specs/2026-06-13-capability-model-v2.md §4
- *
- * @author Felix
- */
-
-'use strict';
-
-// ---------------------------------------------------------------------------
-//  Helpers
-// ---------------------------------------------------------------------------
-
-/** Map L1..L4 to a centred numeric score the rollup can average. */
-const LEVEL_SCORE = { 1: 25, 2: 55, 3: 80, 4: 95 };
-
-/** Map a numeric score back to a level (matches §5 rules). */
-function scoreToLevel(score) {
-  if (score == null || Number.isNaN(score)) return null;
-  if (score >= 85) return 4;
-  if (score >= 65) return 3;
-  if (score >= 40) return 2;
-  return 1;
-}
-
-// ---------------------------------------------------------------------------
-//  Threshold tables
-//  Each row reads "if value satisfies the cell for level L at difficulty D,
-//  return L".  Difficulty buckets: 1 trivial · 2 routine · 3 complex · 4 heavy.
-//
-//  direction: 'lower' = lower is better
-//             'higher' = higher is better
-//             'band'   = ideal range, anything else penalised
-// ---------------------------------------------------------------------------
-
-/* ----- H1 — Problem Definition ------------------------------------- */
-
-const H1 = {
-  /** AI proactive-question count (HEAD 30% of the session). */
-  clarity: {
-    direction: 'lower',
-    // bucket = difficulty.  cell = inclusive upper bound for that level.
-    table: {
-      1: { L4: 0, L3: 1, L2: 3 },
-      2: { L4: 1, L3: 2, L2: 5 },
-      3: { L4: 2, L3: 4, L2: 8 },
-      4: { L4: 3, L3: 6, L2: 12 },
-    },
-  },
-  /** User-message rounds needed to converge. */
-  converge: {
-    direction: 'lower',
-    table: {
-      1: { L4: 3,  L3: 5,  L2: 8 },
-      2: { L4: 5,  L3: 8,  L2: 15 },
-      3: { L4: 8,  L3: 15, L2: 25 },
-      4: { L4: 15, L3: 30, L2: 50 },
-    },
-  },
-  /** Direction-change events. */
-  drift: {
-    direction: 'lower',
-    table: {
-      1: { L4: 0, L3: 1, L2: 2 },
-      2: { L4: 0, L3: 1, L2: 2 },
-      3: { L4: 1, L3: 2, L2: 4 },
-      4: { L4: 1, L3: 3, L2: 6 },
-    },
-  },
-};
-
-/* ----- H2 — Judgement ---------------------------------------------- */
-
-const H2 = {
-  challenge: {
-    direction: 'higher',
-    table: {
-      1: { L4: 0.20, L3: 0.10, L2: 0.03 },
-      2: { L4: 0.30, L3: 0.18, L2: 0.08 },
-      3: { L4: 0.35, L3: 0.25, L2: 0.15 },
-      4: { L4: 0.40, L3: 0.30, L2: 0.20 },
-    },
-  },
-  /**
-   * Override rate — band metric: too low = rubber-stamping, too high =
-   * thrashing.  Encoded as { ideal: [lo, hi], tolerance: [[L3 lo, L3 hi], …] }
-   */
-  override: {
-    direction: 'band',
-    bands: {
-      1: { L4: [0, 0.10],   L3: [0, 0.20],   L2: [0, 0.35] },
-      2: { L4: [0.05, 0.15],L3: [0, 0.25],   L2: [0, 0.40] },
-      3: { L4: [0.10, 0.20],L3: [0, 0.30],   L2: [0, 0.45] },
-      4: { L4: [0.10, 0.25],L3: [0, 0.35],   L2: [0, 0.50] },
-    },
-  },
-  /** Compliant-without-comment rate — ideal band 60-85% (difficulty-agnostic). */
-  accept_rate: {
-    direction: 'band',
-    bands: {
-      1: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
-      2: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
-      3: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
-      4: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
-    },
-  },
-};
-
-/* ----- H3 — System Thinking (rolling) ------------------------------ */
-
-const H3 = {
-  consistency: {
-    direction: 'higher',
-    table: { all: { L4: 0.80, L3: 0.60, L2: 0.40 } },
-  },
-  dedup: {
-    direction: 'lower',
-    table: { all: { L4: 0.05, L3: 0.15, L2: 0.30 } },
-  },
-  refactor: {  // per 100 sessions
-    direction: 'higher',
-    table: { all: { L4: 6, L3: 3, L2: 1 } },
-  },
-  abstraction: {
-    direction: 'higher',
-    table: { all: { L4: 0.20, L3: 0.10, L2: 0.05 } },
-  },
-};
-
-/* ----- E1 — Knowledge Coverage ------------------------------------- */
-
-const E1 = {
-  domain_errors: {
-    direction: 'lower',
-    table: { all: { L4: 0.03, L3: 0.08, L2: 0.15 } },
-  },
-  staleness: {
-    direction: 'lower',
-    table: { all: { L4: 0, L3: 1, L2: 3 } },
-  },
-  best_practice: {
-    direction: 'higher',
-    table: { all: { L4: 0.85, L3: 0.65, L2: 0.45 } },
-  },
-};
-
-/* ----- E2 — Tool Coverage ------------------------------------------ */
-
-const E2 = {
-  tool_pick: {
-    direction: 'higher',
-    table: {
-      1: { L4: 0.95, L3: 0.85, L2: 0.70 },
-      2: { L4: 0.90, L3: 0.80, L2: 0.65 },
-      3: { L4: 0.85, L3: 0.75, L2: 0.60 },
-      4: { L4: 0.80, L3: 0.70, L2: 0.55 },
-    },
-  },
-  /** calls-per-intent ratio vs baseline 1.0 (LOWER better) */
-  chain_eff: {
-    direction: 'lower',
-    table: { all: { L4: 1.1, L3: 1.4, L2: 1.8 } },
-  },
-  self_heal: {
-    direction: 'higher',
-    table: { all: { L4: 0.85, L3: 0.65, L2: 0.40 } },
-  },
-};
-
-/* ----- O1 — Output Quality ----------------------------------------- */
-
-const O1 = {
-  first_take: {
-    direction: 'higher',
-    table: {
-      1: { L4: 0.80, L3: 0.60, L2: 0.40 },
-      2: { L4: 0.70, L3: 0.55, L2: 0.40 },
-      3: { L4: 0.60, L3: 0.45, L2: 0.30 },
-      4: { L4: 0.50, L3: 0.35, L2: 0.25 },
-    },
-  },
-  code_style: {
-    direction: 'higher',
-    table: { all: { L4: 0.85, L3: 0.65, L2: 0.45 } },
-  },
-  completeness: {
-    direction: 'higher',
-    table: { all: { L4: 0.80, L3: 0.60, L2: 0.40 } },
-  },
-};
-
-const ALL = { H1, H2, H3, E1, E2, O1 };
-
-// ---------------------------------------------------------------------------
-//  Roll-up weights — see spec §5
-// ---------------------------------------------------------------------------
-
-const WEIGHTS = {
-  H1: { clarity: 0.45, converge: 0.35, drift: 0.20 },
-  H2: { challenge: 0.40, override: 0.35, accept_rate: 0.25 },
-  H3: { consistency: 0.30, dedup: 0.25, refactor: 0.20, abstraction: 0.25 },
-  E1: { domain_errors: 0.40, staleness: 0.25, best_practice: 0.35 },
-  E2: { tool_pick: 0.40, chain_eff: 0.30, self_heal: 0.30 },
-  O1: { first_take: 0.45, code_style: 0.25, completeness: 0.30 },
-};
-
-// ---------------------------------------------------------------------------
-//  Level evaluation
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a numeric value to L1..L4 against an indicator spec.
- *
- * @param {Object} indicator   one of H1.clarity, H2.override, etc.
- * @param {number|null} value  the raw measurement
- * @param {number} difficulty  1-4 (ignored if the spec table is keyed by 'all')
- * @returns {1|2|3|4|null}
- */
-function evalLevel(indicator, value, difficulty = 2) {
-  if (!indicator || value == null || Number.isNaN(value)) return null;
-
-  const key = pickTableKey(indicator, difficulty);
-
-  if (indicator.direction === 'band') {
-    const bands = indicator.bands[key];
-    if (!bands) return null;
-    if (inBand(value, bands.L4)) return 4;
-    if (inBand(value, bands.L3)) return 3;
-    if (inBand(value, bands.L2)) return 2;
-    return 1;
-  }
-
-  const cells = indicator.table[key];
-  if (!cells) return null;
-
-  if (indicator.direction === 'lower') {
-    if (value <= cells.L4) return 4;
-    if (value <= cells.L3) return 3;
-    if (value <= cells.L2) return 2;
-    return 1;
-  }
-  // 'higher'
-  if (value >= cells.L4) return 4;
-  if (value >= cells.L3) return 3;
-  if (value >= cells.L2) return 2;
-  return 1;
-}
-
-function pickTableKey(indicator, difficulty) {
-  const t = indicator.table || indicator.bands || {};
-  if (t.all) return 'all';
-  if (t[difficulty] != null) return difficulty;
-  // fall back to the closest available bucket
-  const keys = Object.keys(t).map(Number).filter(Number.isFinite).sort((a, b) => a - b);
-  if (!keys.length) return null;
-  return keys.reduce((acc, k) => (Math.abs(k - difficulty) < Math.abs(acc - difficulty) ? k : acc), keys[0]);
-}
-
-function inBand(value, range) {
-  return Array.isArray(range) && value >= range[0] && value <= range[1];
-}
-
-/**
- * Convenience: given a raw measurement, return both the level and a
- * centred numeric score useful for averaging into the dimension score.
- *
- * @param {Object} indicator
- * @param {number} value
- * @param {number} difficulty
- * @returns {{ level: number|null, score: number|null }}
- */
-function evalIndicator(indicator, value, difficulty = 2) {
-  const lvl = evalLevel(indicator, value, difficulty);
-  return { level: lvl, score: lvl == null ? null : LEVEL_SCORE[lvl] };
-}
-
-/**
- * Like evalIndicator but also returns a structured "why" payload the UI
- * can render in a tooltip without re-implementing the threshold tables.
- *
- *   { level, score, bounds, direction, table }
- *     - bounds.l4, l3, l2  : the inclusive boundaries used for this
- *                            difficulty bucket (numbers or [lo, hi] for bands)
- *     - direction          : 'lower' | 'higher' | 'band'
- *     - bucketKey          : 'all' or 1-4 (which row of the table was used)
- *
- * @param {Object} indicator
- * @param {number|null} value
- * @param {number} difficulty
- */
-function explainIndicator(indicator, value, difficulty = 2) {
-  const base = evalIndicator(indicator, value, difficulty);
-  if (!indicator) return { ...base, value, direction: null, bounds: null, bucketKey: null };
-
-  const bucketKey = pickTableKey(indicator, difficulty);
-  let bounds = null;
-  if (indicator.direction === 'band' && indicator.bands?.[bucketKey]) {
-    const b = indicator.bands[bucketKey];
-    bounds = { L4: b.L4 || null, L3: b.L3 || null, L2: b.L2 || null };
-  } else if (indicator.table?.[bucketKey]) {
-    const t = indicator.table[bucketKey];
-    bounds = { L4: t.L4 ?? null, L3: t.L3 ?? null, L2: t.L2 ?? null };
-  }
-
-  return {
-    ...base,
-    value,
-    direction: indicator.direction,
-    bounds,
-    bucketKey,
-  };
-}
-
-/**
- * Roll up a set of sub-scores into one dimension score using the
- * declared weights.  Missing sub-scores are skipped and the remaining
- * weights are re-normalised so a partial measurement still produces a
- * sensible number.
- *
- * @param {string} dimensionKey  'H1' | 'H2' | … | 'O1'
- * @param {Object} subScores     { clarity: 80, converge: 55, … }
- * @returns {number|null}
- */
-function rollupDimension(dimensionKey, subScores) {
-  const w = WEIGHTS[dimensionKey];
-  if (!w) return null;
-
-  let total = 0;
-  let weightSum = 0;
-  for (const key of Object.keys(w)) {
-    const v = subScores ? subScores[key] : null;
-    if (v == null || Number.isNaN(v)) continue;
-    total += v * w[key];
-    weightSum += w[key];
-  }
-
-  if (weightSum === 0) return null;
-  return Math.round(total / weightSum);
-}
-
-module.exports = {
-  H1, H2, H3, E1, E2, O1, ALL,
-  WEIGHTS,
-  LEVEL_SCORE,
-  scoreToLevel,
-  evalLevel,
-  evalIndicator,
-  explainIndicator,
-  rollupDimension,
-};
+/**
+ * v2 capability thresholds — single source of truth.
+ *
+ * Each sub-indicator declares:
+ *   • how its raw value should be interpreted (higher / lower / band-better)
+ *   • the L1-L4 boundaries, possibly per difficulty bucket
+ *
+ * The shape is deliberately flat data so it can be tweaked without code
+ * changes and (eventually) edited from the Settings UI.
+ *
+ * Source of truth: docs/superpowers/specs/2026-06-13-capability-model-v2.md §4
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+// ---------------------------------------------------------------------------
+//  Helpers
+// ---------------------------------------------------------------------------
+
+/** Map L1..L4 to a centred numeric score the rollup can average. */
+const LEVEL_SCORE = { 1: 25, 2: 55, 3: 80, 4: 95 };
+
+/** Map a numeric score back to a level (matches §5 rules). */
+function scoreToLevel(score) {
+  if (score == null || Number.isNaN(score)) return null;
+  if (score >= 85) return 4;
+  if (score >= 65) return 3;
+  if (score >= 40) return 2;
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+//  Threshold tables
+//  Each row reads "if value satisfies the cell for level L at difficulty D,
+//  return L".  Difficulty buckets: 1 trivial · 2 routine · 3 complex · 4 heavy.
+//
+//  direction: 'lower' = lower is better
+//             'higher' = higher is better
+//             'band'   = ideal range, anything else penalised
+// ---------------------------------------------------------------------------
+
+/* ----- H1 — Problem Definition ------------------------------------- */
+
+const H1 = {
+  /** AI proactive-question count (HEAD 30% of the session). */
+  clarity: {
+    direction: 'lower',
+    // bucket = difficulty.  cell = inclusive upper bound for that level.
+    table: {
+      1: { L4: 0, L3: 1, L2: 3 },
+      2: { L4: 1, L3: 2, L2: 5 },
+      3: { L4: 2, L3: 4, L2: 8 },
+      4: { L4: 3, L3: 6, L2: 12 },
+    },
+  },
+  /** User-message rounds needed to converge. */
+  converge: {
+    direction: 'lower',
+    table: {
+      1: { L4: 3,  L3: 5,  L2: 8 },
+      2: { L4: 5,  L3: 8,  L2: 15 },
+      3: { L4: 8,  L3: 15, L2: 25 },
+      4: { L4: 15, L3: 30, L2: 50 },
+    },
+  },
+  /** Direction-change events. */
+  drift: {
+    direction: 'lower',
+    table: {
+      1: { L4: 0, L3: 1, L2: 2 },
+      2: { L4: 0, L3: 1, L2: 2 },
+      3: { L4: 1, L3: 2, L2: 4 },
+      4: { L4: 1, L3: 3, L2: 6 },
+    },
+  },
+};
+
+/* ----- H2 — Judgement ---------------------------------------------- */
+
+const H2 = {
+  challenge: {
+    direction: 'higher',
+    table: {
+      1: { L4: 0.20, L3: 0.10, L2: 0.03 },
+      2: { L4: 0.30, L3: 0.18, L2: 0.08 },
+      3: { L4: 0.35, L3: 0.25, L2: 0.15 },
+      4: { L4: 0.40, L3: 0.30, L2: 0.20 },
+    },
+  },
+  /**
+   * Override rate — band metric: too low = rubber-stamping, too high =
+   * thrashing.  Encoded as { ideal: [lo, hi], tolerance: [[L3 lo, L3 hi], …] }
+   */
+  override: {
+    direction: 'band',
+    bands: {
+      1: { L4: [0, 0.10],   L3: [0, 0.20],   L2: [0, 0.35] },
+      2: { L4: [0.05, 0.15],L3: [0, 0.25],   L2: [0, 0.40] },
+      3: { L4: [0.10, 0.20],L3: [0, 0.30],   L2: [0, 0.45] },
+      4: { L4: [0.10, 0.25],L3: [0, 0.35],   L2: [0, 0.50] },
+    },
+  },
+  /** Compliant-without-comment rate — ideal band 60-85% (difficulty-agnostic). */
+  accept_rate: {
+    direction: 'band',
+    bands: {
+      1: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+      2: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+      3: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+      4: { L4: [0.60, 0.85], L3: [0.50, 0.90], L2: [0.40, 0.95] },
+    },
+  },
+};
+
+/* ----- H3 — System Thinking (rolling) ------------------------------ */
+
+const H3 = {
+  consistency: {
+    direction: 'higher',
+    table: { all: { L4: 0.80, L3: 0.60, L2: 0.40 } },
+  },
+  dedup: {
+    direction: 'lower',
+    table: { all: { L4: 0.05, L3: 0.15, L2: 0.30 } },
+  },
+  refactor: {  // per 100 sessions
+    direction: 'higher',
+    table: { all: { L4: 6, L3: 3, L2: 1 } },
+  },
+  abstraction: {
+    direction: 'higher',
+    table: { all: { L4: 0.20, L3: 0.10, L2: 0.05 } },
+  },
+};
+
+/* ----- E1 — Knowledge Coverage ------------------------------------- */
+
+const E1 = {
+  domain_errors: {
+    direction: 'lower',
+    table: { all: { L4: 0.03, L3: 0.08, L2: 0.15 } },
+  },
+  staleness: {
+    direction: 'lower',
+    table: { all: { L4: 0, L3: 1, L2: 3 } },
+  },
+  best_practice: {
+    direction: 'higher',
+    table: { all: { L4: 0.85, L3: 0.65, L2: 0.45 } },
+  },
+};
+
+/* ----- E2 — Tool Coverage ------------------------------------------ */
+
+const E2 = {
+  tool_pick: {
+    direction: 'higher',
+    table: {
+      1: { L4: 0.95, L3: 0.85, L2: 0.70 },
+      2: { L4: 0.90, L3: 0.80, L2: 0.65 },
+      3: { L4: 0.85, L3: 0.75, L2: 0.60 },
+      4: { L4: 0.80, L3: 0.70, L2: 0.55 },
+    },
+  },
+  /** calls-per-intent ratio vs baseline 1.0 (LOWER better) */
+  chain_eff: {
+    direction: 'lower',
+    table: { all: { L4: 1.1, L3: 1.4, L2: 1.8 } },
+  },
+  self_heal: {
+    direction: 'higher',
+    table: { all: { L4: 0.85, L3: 0.65, L2: 0.40 } },
+  },
+};
+
+/* ----- O1 — Output Quality ----------------------------------------- */
+
+const O1 = {
+  first_take: {
+    direction: 'higher',
+    table: {
+      1: { L4: 0.80, L3: 0.60, L2: 0.40 },
+      2: { L4: 0.70, L3: 0.55, L2: 0.40 },
+      3: { L4: 0.60, L3: 0.45, L2: 0.30 },
+      4: { L4: 0.50, L3: 0.35, L2: 0.25 },
+    },
+  },
+  code_style: {
+    direction: 'higher',
+    table: { all: { L4: 0.85, L3: 0.65, L2: 0.45 } },
+  },
+  completeness: {
+    direction: 'higher',
+    table: { all: { L4: 0.80, L3: 0.60, L2: 0.40 } },
+  },
+};
+
+const ALL = { H1, H2, H3, E1, E2, O1 };
+
+// ---------------------------------------------------------------------------
+//  Roll-up weights — see spec §5
+// ---------------------------------------------------------------------------
+
+const WEIGHTS = {
+  H1: { clarity: 0.45, converge: 0.35, drift: 0.20 },
+  H2: { challenge: 0.40, override: 0.35, accept_rate: 0.25 },
+  // Per-session H3 (v2.1) uses abstraction/reuse/standard; the older
+  // rolling keys (consistency/dedup/refactor) are kept for back-compat with
+  // the now-unused rolling aggregator.  rollupDimension only sums weights
+  // for the sub-scores actually present, so both shapes work.
+  H3: { abstraction: 0.40, reuse: 0.35, standard: 0.25, consistency: 0.30, dedup: 0.25, refactor: 0.20 },
+  E1: { domain_errors: 0.40, staleness: 0.25, best_practice: 0.35 },
+  E2: { tool_pick: 0.40, chain_eff: 0.30, self_heal: 0.30 },
+  // v2.1: E1+E2 merged into one LLM-judged ENV dimension.
+  ENV: { knowledge: 0.40, tooling: 0.35, currency: 0.25 },
+  O1: { first_take: 0.45, code_style: 0.25, completeness: 0.30 },
+};
+
+// ---------------------------------------------------------------------------
+//  Level evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a numeric value to L1..L4 against an indicator spec.
+ *
+ * @param {Object} indicator   one of H1.clarity, H2.override, etc.
+ * @param {number|null} value  the raw measurement
+ * @param {number} difficulty  1-4 (ignored if the spec table is keyed by 'all')
+ * @returns {1|2|3|4|null}
+ */
+function evalLevel(indicator, value, difficulty = 2) {
+  if (!indicator || value == null || Number.isNaN(value)) return null;
+
+  const key = pickTableKey(indicator, difficulty);
+
+  if (indicator.direction === 'band') {
+    const bands = indicator.bands[key];
+    if (!bands) return null;
+    if (inBand(value, bands.L4)) return 4;
+    if (inBand(value, bands.L3)) return 3;
+    if (inBand(value, bands.L2)) return 2;
+    return 1;
+  }
+
+  const cells = indicator.table[key];
+  if (!cells) return null;
+
+  if (indicator.direction === 'lower') {
+    if (value <= cells.L4) return 4;
+    if (value <= cells.L3) return 3;
+    if (value <= cells.L2) return 2;
+    return 1;
+  }
+  // 'higher'
+  if (value >= cells.L4) return 4;
+  if (value >= cells.L3) return 3;
+  if (value >= cells.L2) return 2;
+  return 1;
+}
+
+function pickTableKey(indicator, difficulty) {
+  const t = indicator.table || indicator.bands || {};
+  if (t.all) return 'all';
+  if (t[difficulty] != null) return difficulty;
+  // fall back to the closest available bucket
+  const keys = Object.keys(t).map(Number).filter(Number.isFinite).sort((a, b) => a - b);
+  if (!keys.length) return null;
+  return keys.reduce((acc, k) => (Math.abs(k - difficulty) < Math.abs(acc - difficulty) ? k : acc), keys[0]);
+}
+
+function inBand(value, range) {
+  return Array.isArray(range) && value >= range[0] && value <= range[1];
+}
+
+/**
+ * Convenience: given a raw measurement, return both the level and a
+ * centred numeric score useful for averaging into the dimension score.
+ *
+ * @param {Object} indicator
+ * @param {number} value
+ * @param {number} difficulty
+ * @returns {{ level: number|null, score: number|null }}
+ */
+function evalIndicator(indicator, value, difficulty = 2) {
+  const lvl = evalLevel(indicator, value, difficulty);
+  return { level: lvl, score: lvl == null ? null : LEVEL_SCORE[lvl] };
+}
+
+/**
+ * Like evalIndicator but also returns a structured "why" payload the UI
+ * can render in a tooltip without re-implementing the threshold tables.
+ *
+ *   { level, score, bounds, direction, table }
+ *     - bounds.l4, l3, l2  : the inclusive boundaries used for this
+ *                            difficulty bucket (numbers or [lo, hi] for bands)
+ *     - direction          : 'lower' | 'higher' | 'band'
+ *     - bucketKey          : 'all' or 1-4 (which row of the table was used)
+ *
+ * @param {Object} indicator
+ * @param {number|null} value
+ * @param {number} difficulty
+ */
+function explainIndicator(indicator, value, difficulty = 2) {
+  const base = evalIndicator(indicator, value, difficulty);
+  if (!indicator) return { ...base, value, direction: null, bounds: null, bucketKey: null };
+
+  const bucketKey = pickTableKey(indicator, difficulty);
+  let bounds = null;
+  if (indicator.direction === 'band' && indicator.bands?.[bucketKey]) {
+    const b = indicator.bands[bucketKey];
+    bounds = { L4: b.L4 || null, L3: b.L3 || null, L2: b.L2 || null };
+  } else if (indicator.table?.[bucketKey]) {
+    const t = indicator.table[bucketKey];
+    bounds = { L4: t.L4 ?? null, L3: t.L3 ?? null, L2: t.L2 ?? null };
+  }
+
+  return {
+    ...base,
+    value,
+    direction: indicator.direction,
+    bounds,
+    bucketKey,
+  };
+}
+
+/**
+ * Roll up a set of sub-scores into one dimension score using the
+ * declared weights.  Missing sub-scores are skipped and the remaining
+ * weights are re-normalised so a partial measurement still produces a
+ * sensible number.
+ *
+ * @param {string} dimensionKey  'H1' | 'H2' | … | 'O1'
+ * @param {Object} subScores     { clarity: 80, converge: 55, … }
+ * @returns {number|null}
+ */
+function rollupDimension(dimensionKey, subScores) {
+  const w = WEIGHTS[dimensionKey];
+  if (!w) return null;
+
+  let total = 0;
+  let weightSum = 0;
+  for (const key of Object.keys(w)) {
+    const v = subScores ? subScores[key] : null;
+    if (v == null || Number.isNaN(v)) continue;
+    total += v * w[key];
+    weightSum += w[key];
+  }
+
+  if (weightSum === 0) return null;
+  return Math.round(total / weightSum);
+}
+
+module.exports = {
+  H1, H2, H3, E1, E2, O1, ALL,
+  WEIGHTS,
+  LEVEL_SCORE,
+  scoreToLevel,
+  evalLevel,
+  evalIndicator,
+  explainIndicator,
+  rollupDimension,
+};