@hegemonart/get-design-done 1.23.0 → 1.23.5

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.23.0"
+    "version": "1.23.5"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.23.0",
+      "version": "1.23.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.23.0",
+  "version": "1.23.5",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.23.5] — 2026-04-25
+
+Phase 23.5 No-Regret Adaptive Layer milestone — turns the passive Phase 22–23 observability + validation infrastructure into a closed self-tuning loop. Three tightly-scoped no-regret algorithms sharing one feature-flag ladder. Single-user viable via informed Beta-prior bootstrap (no shared telemetry required). Ships as a decimal patch on the v1.23 minor — does NOT shift Phase 24 → v1.24.0.
+
+### Added
+
+- **Bandit router** — `scripts/lib/bandit-router.cjs` implements contextual Thompson sampling over `(agent_type, touches_size_bin) → {haiku, sonnet, opus}`. Per-arm `Beta(α, β)` posterior at `.design/telemetry/posterior.json` (atomic .tmp + rename). Discounted Thompson via per-arm time-decay factor `ρ^days_since_last_use` applied at sample time (default ρ=0.988 → 60-day half-life). Informed bootstrap: each arm starts at `Beta(α, β)` with α weighted toward the historical tier success rate (haiku=0.6, sonnet=0.8, opus=0.85) and `α + β ≈ 10` so 5–10 local samples shift the posterior. Two-stage lexicographic reward: `if !solidify_pass: 0; elif user_undo_in_session: 0; else: 1 − λ · normalize(cost + ε · wall_time)`. API: `pull / update / reset / loadPosterior / savePosterior / computeReward`. Touches-size bins: `tiny <5`, `small 5–15`, `medium 16–50`, `large >50` globs. (Plan 23.5-01)
+
+- **Hedge ensemble** — `scripts/lib/hedge-ensemble.cjs` implements parameter-free AdaNormalHedge weighted-majority over verifier + checker agents. Weights persist at `.design/telemetry/hedge-weights.json`. Update rule: `η_i = sqrt(ln(N) / max(1, cumLoss2_i))` per-agent learning rate; `w_i *= exp(-η_i * loss_i)`; renormalise. Vote semantics: weighted sum normalised by the SUM of voting agents' weights — agents in the pool that didn't vote this round don't dilute the verdict. API: `loss / vote / weights / loadWeights / saveWeights`. Default vote threshold 0.5. (Plan 23.5-02)
+
+- **MMR re-rank** — `scripts/lib/mmr-rerank.cjs` implements Maximal Marginal Relevance over scored items. Solves the "all 5 surfaced learnings are about the same thing" failure mode in the Phase 14.5 decision-injector. Greedy criterion: `next = argmax_{i ∉ selected} λ * relevance(i) − (1 − λ) * max_sim(i, selected)`. Similarity = Jaccard on word n-grams (default n=2). λ default 0.7. No external deps, no embedding API. API: `rerank / similarity / tokenize / ngrams / jaccard`. (Plan 23.5-03)
+
+- **Adaptive-mode feature flag ladder** — `scripts/lib/adaptive-mode.cjs` is the single source of truth for which Phase 23.5 components are active. Three modes:
+  - `static` (DEFAULT) — Phase 10.1 behaviour. Static `tier_overrides` applies. No posterior writes / no hedge updates / no MMR.
+  - `hedge` — Adds AdaNormalHedge consensus + MMR re-rank. Routing still static (bandit OFF). Safest intro level.
+  - `full` — Adds bandit Thompson-sampling routing + reflector confidence-interval proposals. Both posterior + hedge persist.
+  Read from `.design/budget.json.adaptive_mode` with safe fallback to `static` on missing/malformed/unknown values. API: `getMode / setMode / caps / isBanditEnabled / isHedgeEnabled / isMmrEnabled / isReflectorProposalsEnabled`. (Plan 23.5-04)
+
+### Changed
+
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.23.5`.
+- `test-fixture/baselines/phase-20/resilience-primitives.txt` regenerated alphabetically with all four new `.cjs` modules added.
+
+### Tests
+
+- `tests/bandit-router.test.cjs` — bin partitioning, prior elevation per tier, beta sampling, pull persistence, missing-input throws, update/reward/clamp, reset, decay-toward-prior, all reward branches, load+save, 60-round convergence smoke test (18 tests)
+- `tests/hedge-ensemble.test.cjs` — init uniform, high-loss penalty, normalisation, simple vs weighted vote, boolean=numeric equivalence, custom threshold, empty votes, loss clamp, NaN throw, round-trip (14)
+- `tests/mmr-rerank.test.cjs` — tokenize edges, ngram size+fallback, similarity properties, λ=1 pure relevance, λ=0 pure diversity, textOf/relevanceOf overrides, empty input, non-array throw, k>length truncation, defaults, jaccard guards, canonical "5 D-13 hits" scenario (18)
+- `tests/adaptive-mode.test.cjs` — missing-file fallback, malformed-JSON fallback, unknown-mode quiet fallback, all 3 capability matrices, all 4 predicates, setMode preserves other fields, parent-dir creation, mode rejection, exports, absolute-path support (13)
+- `tests/phase-23.5-baseline.test.cjs` — Phase 23.5 regression baseline (8)
+
+Total: 71 new tests. All Phase 20/21/22/23 tests still green.
+
+### Reflector integration
+
+The Phase 22 code-level reflector reads `posterior.json` + hedge weights at run time (under `adaptive_mode: "full"`). When `stddev(Beta(α, β)) < 0.05` for a single-arm dominant tier, it proposes `tier_overrides` updates via `/gdd:apply-reflections`. Pure-read; never auto-writes. Same proposal pattern as Plan 23-06 touches pattern miner.
+
+### Deferred (evidence-gated, per ROADMAP)
+
+- Hierarchical shared prior (revisit after 20+ cycles of single-user convergence data)
+- Dense-embedding retrieval (revisit if MMR-only miss-rate exceeds 15%)
+- Offline policy evaluation harness (bootstraps from bandit's stochastic logs once accumulated)
+- Auto changepoint detection (manual `/gdd:bandit-reset --reason "<msg>"` covers v1)
+
+### Explicitly out of scope
+
+- HDBSCAN auto-crystallization, BOCPD changepoint detection, Personalized PageRank, MinHash/LSH dedup, Borda/Kemeny rank aggregation, submodular greedy — each rejected with rationale in ROADMAP.md.
+
+---
+
 ## [1.23.0] — 2026-04-25
 
 Phase 23 GDD SDK Domain Primitives milestone — lands the highest-leverage code primitives from the ROADMAP "GDD SDK Domain Primitives" entry as typed Node modules with tests. 10 atomic plans (23-01 through 23-10), additive — every Phase 20/21/22 consumer keeps working unchanged. Distribution as separate `@hegemonart/gdd-sdk` npm package and screenshot-capture orchestration are explicitly deferred to follow-up phases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.23.0",
+  "version": "1.23.5",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/scripts/lib/adaptive-mode.cjs

@@ -0,0 +1,170 @@
+/**
+ * adaptive-mode.cjs — feature-flag ladder facade for the Phase 23.5
+ * no-regret stack (Plan 23.5-04).
+ *
+ * Three modes, ladder-shaped:
+ *
+ *   "static"  — Phase 10.1 behaviour. Static tier_overrides map applies;
+ *               no posterior writes; no hedge weight updates; no MMR.
+ *               Default for all installs.
+ *
+ *   "hedge"   — Adds AdaNormalHedge consensus thresholding to verifier
+ *               + checker pools. Routing still static. Safest intro
+ *               level — bandit routing is NOT enabled, so the model
+ *               choice for any agent is unchanged.
+ *
+ *   "full"    — Adds bandit Thompson-sampling routing on top of hedge.
+ *               Both posterior + hedge weights persist. Reflector
+ *               proposals based on confidence intervals enabled.
+ *
+ * The ladder is read from `.design/budget.json.adaptive_mode`. Fallback
+ * default = "static". Unknown values clamp to "static" with a stderr
+ * warning (silent if `quiet: true`).
+ *
+ * This module owns the SINGLE source of truth for "is bandit on / is
+ * hedge on" — every consumer (router, hedge, MMR, reflector, the
+ * Phase 22 budget-enforcer hook) reads from `getMode(opts)`.
+ *
+ * No external deps. CommonJS.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_BUDGET_PATH = '.design/budget.json';
+const VALID_MODES = Object.freeze(['static', 'hedge', 'full']);
+const DEFAULT_MODE = 'static';
+
+/** Capability matrix per mode — consumed by callers as a boolean check. */
+const MODE_CAPS = Object.freeze({
+  static: Object.freeze({ bandit: false, hedge: false, mmr: false, reflector_proposals: false }),
+  hedge: Object.freeze({ bandit: false, hedge: true, mmr: true, reflector_proposals: false }),
+  full: Object.freeze({ bandit: true, hedge: true, mmr: true, reflector_proposals: true }),
+});
+
+function resolveBudgetPath(opts = {}) {
+  if (opts.budgetPath) {
+    return path.isAbsolute(opts.budgetPath)
+      ? opts.budgetPath
+      : path.resolve(opts.baseDir ?? process.cwd(), opts.budgetPath);
+  }
+  return path.resolve(opts.baseDir ?? process.cwd(), DEFAULT_BUDGET_PATH);
+}
+
+/**
+ * Read the current adaptive_mode from .design/budget.json. Falls back
+ * to "static" when the file is absent, malformed, or holds an
+ * unrecognised value.
+ *
+ * @param {{baseDir?: string, budgetPath?: string, quiet?: boolean}} [opts]
+ * @returns {'static'|'hedge'|'full'}
+ */
+function getMode(opts = {}) {
+  const p = resolveBudgetPath(opts);
+  if (!fs.existsSync(p)) return DEFAULT_MODE;
+  /** @type {{adaptive_mode?: string}} */
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return DEFAULT_MODE;
+  }
+  const m = cfg && typeof cfg.adaptive_mode === 'string' ? cfg.adaptive_mode : null;
+  if (!m) return DEFAULT_MODE;
+  if (!VALID_MODES.includes(m)) {
+    if (!opts.quiet) {
+      try {
+        process.stderr.write(
+          `[adaptive-mode] unknown adaptive_mode "${m}" in ${p}; falling back to "static"\n`,
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+    return DEFAULT_MODE;
+  }
+  return /** @type {'static'|'hedge'|'full'} */ (m);
+}
+
+/**
+ * Convenience: capability matrix for the current mode.
+ *
+ * @param {{baseDir?: string, budgetPath?: string, quiet?: boolean}} [opts]
+ * @returns {{bandit: boolean, hedge: boolean, mmr: boolean, reflector_proposals: boolean}}
+ */
+function caps(opts = {}) {
+  return MODE_CAPS[getMode(opts)];
+}
+
+/**
+ * Set the adaptive_mode on disk. Atomic write (.tmp + rename). Creates
+ * the budget.json file if missing — the rest of the budget config
+ * defaults to {} so other readers see "no caps configured".
+ *
+ * @param {'static'|'hedge'|'full'} mode
+ * @param {{baseDir?: string, budgetPath?: string}} [opts]
+ * @returns {string} absolute path written
+ */
+function setMode(mode, opts = {}) {
+  if (!VALID_MODES.includes(mode)) {
+    throw new RangeError(
+      `adaptive-mode.setMode: mode must be one of [${VALID_MODES.join('|')}], got ${JSON.stringify(mode)}`,
+    );
+  }
+  const p = resolveBudgetPath(opts);
+  /** @type {Record<string, unknown>} */
+  let cfg = {};
+  if (fs.existsSync(p)) {
+    try {
+      cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      cfg = {};
+    }
+  }
+  cfg.adaptive_mode = mode;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+/**
+ * High-level "should bandit route this agent?" predicate. Replaces ad-
+ * hoc `if (mode === 'full' || …)` checks across the codebase.
+ *
+ * @param {{baseDir?: string, budgetPath?: string}} [opts]
+ * @returns {boolean}
+ */
+function isBanditEnabled(opts = {}) {
+  return caps(opts).bandit;
+}
+
+function isHedgeEnabled(opts = {}) {
+  return caps(opts).hedge;
+}
+
+function isMmrEnabled(opts = {}) {
+  return caps(opts).mmr;
+}
+
+function isReflectorProposalsEnabled(opts = {}) {
+  return caps(opts).reflector_proposals;
+}
+
+module.exports = {
+  getMode,
+  setMode,
+  caps,
+  isBanditEnabled,
+  isHedgeEnabled,
+  isMmrEnabled,
+  isReflectorProposalsEnabled,
+  resolveBudgetPath,
+  DEFAULT_BUDGET_PATH,
+  DEFAULT_MODE,
+  VALID_MODES,
+  MODE_CAPS,
+};

package/scripts/lib/bandit-router.cjs

@@ -0,0 +1,368 @@
+/**
+ * bandit-router.cjs — contextual Thompson-sampling bandit over
+ * (agent_type, touches_size_bin) → {haiku, sonnet, opus} (Plan 23.5-01).
+ *
+ * Replaces Phase 10.1's static tier_overrides map when the user opts
+ * into adaptive_mode = "full". The static map continues to apply when
+ * adaptive_mode = "static" (default).
+ *
+ * Posterior persistence:
+ *   .design/telemetry/posterior.json
+ *     { schema_version: '1.0.0',
+ *       generated_at: ISO,
+ *       arms: [{agent, bin, tier, alpha, beta, last_used, count}] }
+ *
+ * Atomic .tmp + rename. Discounted Thompson via per-arm time-decay
+ * factor `rho^days_since_last_use` applied at sample time, not stored.
+ *
+ * Reward computation (D-06): two-stage lexicographic
+ *   if !solidify_pass:           reward = 0
+ *   elif user_undo_in_session:   reward = 0
+ *   else:                        reward = 1 - lambda * normalize(cost + epsilon * wall_time)
+ *
+ * No external deps. CommonJS to match scripts/lib/ siblings.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_POSTERIOR_PATH = '.design/telemetry/posterior.json';
+const SCHEMA_VERSION = '1.0.0';
+
+// Decay factor — 60-day half-life.
+const DEFAULT_DECAY = 0.988;
+
+// Informed prior strengths per tier (D-03). alpha + beta ≈ 10 → 5–10
+// local samples will visibly shift the posterior.
+const TIER_PRIOR = Object.freeze({
+  haiku: 0.6,
+  sonnet: 0.8,
+  opus: 0.85,
+});
+
+const PRIOR_STRENGTH = 10;
+const DEFAULT_TIERS = Object.freeze(['haiku', 'sonnet', 'opus']);
+
+const DEFAULT_PRIORS = Object.freeze({
+  decay: DEFAULT_DECAY,
+  strength: PRIOR_STRENGTH,
+  tiers: DEFAULT_TIERS,
+  perTier: TIER_PRIOR,
+});
+
+const TOUCHES_BINS = Object.freeze([
+  { name: 'tiny', max: 4 },
+  { name: 'small', max: 15 },
+  { name: 'medium', max: 50 },
+  { name: 'large', max: Infinity },
+]);
+
+/**
+ * Resolve a touches-size bin from a glob count.
+ * @param {number} globCount
+ * @returns {string}
+ */
+function binForGlobCount(globCount) {
+  for (const b of TOUCHES_BINS) {
+    if (globCount <= b.max) return b.name;
+  }
+  return 'large';
+}
+
+/**
+ * Load the posterior file or return a fresh envelope.
+ * @param {{baseDir?: string, posteriorPath?: string}} [opts]
+ * @returns {{schema_version: string, generated_at: string, arms: object[]}}
+ */
+function loadPosterior(opts = {}) {
+  const p = resolvePath(opts);
+  if (!fs.existsSync(p)) {
+    return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), arms: [] };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!Array.isArray(data.arms)) {
+      data.arms = [];
+    }
+    return data;
+  } catch {
+    return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), arms: [] };
+  }
+}
+
+function resolvePath(opts = {}) {
+  if (opts.posteriorPath) {
+    return path.isAbsolute(opts.posteriorPath)
+      ? opts.posteriorPath
+      : path.resolve(opts.baseDir ?? process.cwd(), opts.posteriorPath);
+  }
+  return path.resolve(opts.baseDir ?? process.cwd(), DEFAULT_POSTERIOR_PATH);
+}
+
+/**
+ * Persist the posterior atomically.
+ * @param {object} posterior
+ * @param {{baseDir?: string, posteriorPath?: string}} [opts]
+ * @returns {string} absolute path written
+ */
+function savePosterior(posterior, opts = {}) {
+  const p = resolvePath(opts);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  posterior.generated_at = new Date().toISOString();
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(posterior, null, 2));
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+/**
+ * Reset the posterior — deletes the file. Next call rebootstraps.
+ *
+ * @param {{baseDir?: string, posteriorPath?: string, reason?: string}} [opts]
+ * @returns {{deleted: boolean, path: string, reason?: string}}
+ */
+function reset(opts = {}) {
+  const p = resolvePath(opts);
+  const existed = fs.existsSync(p);
+  if (existed) fs.unlinkSync(p);
+  return { deleted: existed, path: p, reason: opts.reason };
+}
+
+function priorFor(tier, strength) {
+  const prior = TIER_PRIOR[tier];
+  if (prior === undefined) {
+    return { alpha: strength / 2, beta: strength / 2 };
+  }
+  return {
+    alpha: 2 + prior * (strength - 4),
+    beta: 2 + (1 - prior) * (strength - 4),
+  };
+}
+
+function findArm(arms, agent, bin, tier) {
+  return arms.find((a) => a.agent === agent && a.bin === bin && a.tier === tier);
+}
+
+function ensureArm(posterior, agent, bin, tier, strength) {
+  let arm = findArm(posterior.arms, agent, bin, tier);
+  if (arm) return arm;
+  const { alpha, beta } = priorFor(tier, strength);
+  arm = {
+    agent,
+    bin,
+    tier,
+    alpha,
+    beta,
+    last_used: null,
+    count: 0,
+  };
+  posterior.arms.push(arm);
+  return arm;
+}
+
+/**
+ * Sample from a Beta(alpha, beta) distribution via the gamma-ratio
+ * trick: X = G(alpha, 1) / (G(alpha, 1) + G(beta, 1)).
+ *
+ * Gamma(k, 1) sampled via Marsaglia-Tsang (k>=1) or
+ * Ahrens-Dieter (k<1). For our priors alpha/beta ∈ [2, ~10] so the
+ * k>=1 branch dominates.
+ *
+ * @param {number} alpha
+ * @param {number} beta
+ * @returns {number}
+ */
+function sampleBeta(alpha, beta) {
+  if (alpha <= 0 || beta <= 0) return 0.5;
+  const x = sampleGamma(alpha);
+  const y = sampleGamma(beta);
+  if (x + y === 0) return 0.5;
+  return x / (x + y);
+}
+
+// Math.random() is intentional here. Bandit sampling needs uniform
+// noise, not cryptographic randomness — using crypto + arithmetic is
+// what CodeQL js/biased-cryptographic-random flags. Math.random is
+// uniform-enough for Thompson sampling; security is not a concern.
+function randn() {
+  const u1 = Math.random() || 1e-12; // avoid log(0)
+  const u2 = Math.random();
+  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+
+function rand01() {
+  return Math.random();
+}
+
+function sampleGamma(k) {
+  if (k < 1) {
+    const u = rand01();
+    return sampleGamma(k + 1) * Math.pow(u, 1 / k);
+  }
+  const d = k - 1 / 3;
+  const c = 1 / Math.sqrt(9 * d);
+  // Marsaglia-Tsang.
+  // Loop until accepted; bounded iterations for safety.
+  for (let i = 0; i < 1000; i++) {
+    const x = randn();
+    const v = Math.pow(1 + c * x, 3);
+    if (v <= 0) continue;
+    const u = rand01();
+    if (u < 1 - 0.0331 * Math.pow(x, 4)) return d * v;
+    if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v;
+  }
+  return d; // fallback to mean
+}
+
+/**
+ * Apply discounted decay to an arm in place. Returns the (alpha, beta)
+ * after decay — does NOT persist.
+ *
+ * @param {object} arm
+ * @param {{decay?: number, now?: Date}} [opts]
+ * @returns {{alpha: number, beta: number}}
+ */
+function decayArm(arm, opts = {}) {
+  const decay = opts.decay ?? DEFAULT_DECAY;
+  const now = opts.now ?? new Date();
+  if (!arm.last_used) return { alpha: arm.alpha, beta: arm.beta };
+  const lastDate = new Date(arm.last_used);
+  const days = Math.max(0, (now.getTime() - lastDate.getTime()) / 86_400_000);
+  const factor = Math.pow(decay, days);
+  // Decay shrinks both α and β toward the prior. We never go below the
+  // initial prior strength — caller can rebuild a fresh prior via reset().
+  const { alpha: pa, beta: pb } = priorFor(arm.tier, opts.strength ?? PRIOR_STRENGTH);
+  return {
+    alpha: pa + factor * Math.max(0, arm.alpha - pa),
+    beta: pb + factor * Math.max(0, arm.beta - pb),
+  };
+}
+
+/**
+ * Pull an arm — sample each tier's Beta posterior (with decay) and
+ * pick the argmax. Persists the chosen arm's `last_used` + `count`
+ * counters. Bandit pull does NOT update the success/fail counters —
+ * that happens in `update()` once the outcome is known.
+ *
+ * @param {{agent: string, bin: string, tiers?: string[], baseDir?: string, posteriorPath?: string, decay?: number, strength?: number, now?: Date}} input
+ * @returns {{tier: string, samples: Record<string, number>, posteriorPath: string}}
+ */
+function pull(input) {
+  if (!input || typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('bandit-router.pull: agent (string) required');
+  }
+  if (typeof input.bin !== 'string' || input.bin.length === 0) {
+    throw new TypeError('bandit-router.pull: bin (string) required');
+  }
+  const tiers = input.tiers ?? DEFAULT_TIERS;
+  const strength = input.strength ?? PRIOR_STRENGTH;
+  const now = input.now ?? new Date();
+
+  const posterior = loadPosterior(input);
+  /** @type {Record<string, number>} */
+  const samples = {};
+  let bestTier = tiers[0];
+  let bestSample = -1;
+  for (const tier of tiers) {
+    const arm = ensureArm(posterior, input.agent, input.bin, tier, strength);
+    const decayed = decayArm(arm, { decay: input.decay, now, strength });
+    const s = sampleBeta(decayed.alpha, decayed.beta);
+    samples[tier] = s;
+    if (s > bestSample) {
+      bestSample = s;
+      bestTier = tier;
+    }
+  }
+  // Bump counters on the chosen arm.
+  const chosen = ensureArm(posterior, input.agent, input.bin, bestTier, strength);
+  chosen.last_used = now.toISOString();
+  chosen.count += 1;
+  const written = savePosterior(posterior, input);
+  return { tier: bestTier, samples, posteriorPath: written };
+}
+
+/**
+ * Update the posterior with a reward signal. Reward is applied as a
+ * Bernoulli observation: success → α += reward, β += (1 - reward).
+ *
+ * @param {{agent: string, bin: string, tier: string, reward: number, baseDir?: string, posteriorPath?: string, strength?: number}} input
+ * @returns {{alpha: number, beta: number, posteriorPath: string}}
+ */
+function update(input) {
+  if (!input) throw new TypeError('bandit-router.update: input required');
+  for (const k of ['agent', 'bin', 'tier']) {
+    if (typeof input[k] !== 'string' || input[k].length === 0) {
+      throw new TypeError(`bandit-router.update: ${k} (string) required`);
+    }
+  }
+  if (typeof input.reward !== 'number' || Number.isNaN(input.reward)) {
+    throw new TypeError('bandit-router.update: reward (number) required');
+  }
+  // Reward must be in [0, 1].
+  const r = Math.min(1, Math.max(0, input.reward));
+  const posterior = loadPosterior(input);
+  const arm = ensureArm(posterior, input.agent, input.bin, input.tier, input.strength ?? PRIOR_STRENGTH);
+  arm.alpha += r;
+  arm.beta += 1 - r;
+  const p = savePosterior(posterior, input);
+  return { alpha: arm.alpha, beta: arm.beta, posteriorPath: p };
+}
+
+/**
+ * Two-stage lexicographic reward (D-06).
+ *
+ *   if !solidify_pass: 0
+ *   elif user_undo_in_session: 0
+ *   else: 1 - lambda * normalize(cost_usd + epsilon * wall_time_ms / 1000)
+ *
+ * Cost is normalised via the supplied `costNormalizer` (defaults to
+ * mapping [0, 5 USD] → [0, 1], capped at 1).
+ *
+ * @param {{
+ *   solidify_pass: boolean,
+ *   user_undo_in_session?: boolean,
+ *   cost_usd?: number,
+ *   wall_time_ms?: number,
+ *   lambda?: number,
+ *   epsilon?: number,
+ *   costNormalizer?: (n: number) => number,
+ * }} input
+ * @returns {number} reward in [0, 1]
+ */
+function computeReward(input) {
+  if (!input || typeof input !== 'object') return 0;
+  if (!input.solidify_pass) return 0;
+  if (input.user_undo_in_session === true) return 0;
+  const lambda = typeof input.lambda === 'number' ? input.lambda : 0.3;
+  const epsilon = typeof input.epsilon === 'number' ? input.epsilon : 0.05;
+  const norm =
+    typeof input.costNormalizer === 'function'
+      ? input.costNormalizer
+      : (n) => Math.min(1, Math.max(0, n / 5));
+  const wall = (typeof input.wall_time_ms === 'number' ? input.wall_time_ms : 0) / 1000;
+  const raw = (typeof input.cost_usd === 'number' ? input.cost_usd : 0) + epsilon * wall;
+  const reward = 1 - lambda * norm(raw);
+  return Math.min(1, Math.max(0, reward));
+}
+
+module.exports = {
+  pull,
+  update,
+  reset,
+  loadPosterior,
+  savePosterior,
+  computeReward,
+  binForGlobCount,
+  decayArm,
+  sampleBeta,
+  priorFor,
+  DEFAULT_PRIORS,
+  DEFAULT_TIERS,
+  TIER_PRIOR,
+  PRIOR_STRENGTH,
+  TOUCHES_BINS,
+  DEFAULT_POSTERIOR_PATH,
+  SCHEMA_VERSION,
+};

package/scripts/lib/hedge-ensemble.cjs

@@ -0,0 +1,217 @@
+/**
+ * hedge-ensemble.cjs — AdaNormalHedge weighted-majority over verifier
+ * + checker agents (Plan 23.5-02).
+ *
+ * Parameter-free: no manual learning rate. Weights self-adapt via
+ * the AdaNormalHedge regret-bound trick — η is recomputed each round
+ * from cumulative loss variance, eliminating the typical "tune η or
+ * suffer" tax.
+ *
+ * Weights persist at `.design/telemetry/hedge-weights.json` (atomic
+ * .tmp + rename). Schema:
+ *   { schema_version: '1.0.0',
+ *     generated_at: ISO,
+ *     pools: { <poolId>: { agents: { <agentId>: {weight, cumLoss, cumLoss2, rounds} } } } }
+ *
+ * Reused by adaptive_mode = "hedge" or "full" — see Plan 23.5-04.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_WEIGHTS_PATH = '.design/telemetry/hedge-weights.json';
+const SCHEMA_VERSION = '1.0.0';
+const DEFAULT_VOTE_THRESHOLD = 0.5;
+
+function resolvePath(opts = {}) {
+  if (opts.weightsPath) {
+    return path.isAbsolute(opts.weightsPath)
+      ? opts.weightsPath
+      : path.resolve(opts.baseDir ?? process.cwd(), opts.weightsPath);
+  }
+  return path.resolve(opts.baseDir ?? process.cwd(), DEFAULT_WEIGHTS_PATH);
+}
+
+/**
+ * @returns {{schema_version: string, generated_at: string, pools: object}}
+ */
+function loadWeights(opts = {}) {
+  const p = resolvePath(opts);
+  if (!fs.existsSync(p)) {
+    return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), pools: {} };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!data.pools || typeof data.pools !== 'object') data.pools = {};
+    return data;
+  } catch {
+    return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), pools: {} };
+  }
+}
+
+function saveWeights(state, opts = {}) {
+  const p = resolvePath(opts);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  state.generated_at = new Date().toISOString();
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+function ensurePool(state, poolId) {
+  if (!state.pools[poolId]) state.pools[poolId] = { agents: {} };
+  return state.pools[poolId];
+}
+
+function ensureAgent(pool, agentId) {
+  if (!pool.agents[agentId]) {
+    pool.agents[agentId] = {
+      weight: 1, // uniform start; normalised on read
+      cumLoss: 0,
+      cumLoss2: 0,
+      rounds: 0,
+    };
+  }
+  return pool.agents[agentId];
+}
+
+/**
+ * Apply one round of losses to a pool. losses: Record<agentId, lossInZeroOne>.
+ *
+ * AdaNormalHedge update (parameter-free):
+ *   For each agent i:
+ *     R_i        = sum of (mean_loss - loss_i) over rounds  (instantaneous regret)
+ *     C_i        = sum of (loss_i - mean_loss)^2            (cumulative loss variance)
+ *   Set η_i = sqrt(ln(N) / max(1, C_i))  per-agent learning rate.
+ *   weight_i ∝ Phi(R_i, C_i) where Phi is a positive-only potential.
+ *
+ * Simplification used here: w_i *= exp(-η * loss_i) with η derived
+ * from cumulative variance — gives the same regret bound as full
+ * AdaNormalHedge for the binary-loss case we care about (verifier
+ * pass/fail). Trade off: slightly less tight bound vs the full
+ * potential, but no need to plumb regret tracking everywhere.
+ *
+ * @param {{poolId: string, losses: Record<string, number>, baseDir?: string, weightsPath?: string, eta?: number}} input
+ * @returns {{weights: Record<string, number>, weightsPath: string}}
+ */
+function loss(input) {
+  if (!input || typeof input.poolId !== 'string' || input.poolId.length === 0) {
+    throw new TypeError('hedge-ensemble.loss: poolId (string) required');
+  }
+  if (!input.losses || typeof input.losses !== 'object') {
+    throw new TypeError('hedge-ensemble.loss: losses (Record<string, number>) required');
+  }
+  const state = loadWeights(input);
+  const pool = ensurePool(state, input.poolId);
+  // First, ensure every losing agent exists.
+  for (const [agentId, lossVal] of Object.entries(input.losses)) {
+    if (typeof lossVal !== 'number' || Number.isNaN(lossVal)) {
+      throw new TypeError(`hedge-ensemble.loss: losses.${agentId} must be a number`);
+    }
+  }
+  for (const agentId of Object.keys(input.losses)) {
+    ensureAgent(pool, agentId);
+  }
+  const N = Object.keys(pool.agents).length;
+  // Compute mean loss this round (over agents that received a value).
+  const lossList = Object.values(input.losses);
+  const meanLoss = lossList.length > 0 ? lossList.reduce((a, b) => a + b, 0) / lossList.length : 0;
+  // Update each agent's cumulative variance + regret-like signal, then
+  // recompute its weight via exp(-η_i * loss_i).
+  for (const [agentId, rawLoss] of Object.entries(input.losses)) {
+    const lossVal = Math.min(1, Math.max(0, rawLoss));
+    const a = pool.agents[agentId];
+    const dev = lossVal - meanLoss;
+    a.cumLoss += lossVal;
+    a.cumLoss2 += dev * dev;
+    a.rounds += 1;
+    const eta =
+      typeof input.eta === 'number'
+        ? input.eta
+        : Math.sqrt(Math.log(Math.max(2, N)) / Math.max(1, a.cumLoss2));
+    a.weight *= Math.exp(-eta * lossVal);
+    if (!Number.isFinite(a.weight) || a.weight <= 0) a.weight = 1e-9;
+  }
+  // Renormalize.
+  const total = Object.values(pool.agents).reduce((s, x) => s + x.weight, 0) || 1;
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const agentId of Object.keys(pool.agents)) {
+    pool.agents[agentId].weight /= total;
+    out[agentId] = pool.agents[agentId].weight;
+  }
+  const writtenPath = saveWeights(state, input);
+  return { weights: out, weightsPath: writtenPath };
+}
+
+/**
+ * Compute the weighted-majority verdict for a pool given each agent's
+ * binary vote (pass=1, fail=0). Vote passes when the weighted sum
+ * exceeds threshold (default 0.5).
+ *
+ * @param {{poolId: string, votes: Record<string, 0|1|boolean>, threshold?: number, baseDir?: string, weightsPath?: string}} input
+ * @returns {{passes: boolean, weighted: number, threshold: number, perAgent: Record<string, {weight: number, vote: number}>}}
+ */
+function vote(input) {
+  if (!input || typeof input.poolId !== 'string') {
+    throw new TypeError('hedge-ensemble.vote: poolId required');
+  }
+  if (!input.votes || typeof input.votes !== 'object') {
+    throw new TypeError('hedge-ensemble.vote: votes required');
+  }
+  const state = loadWeights(input);
+  const pool = ensurePool(state, input.poolId);
+  const threshold = typeof input.threshold === 'number' ? input.threshold : DEFAULT_VOTE_THRESHOLD;
+  let total = 0;
+  /** @type {Record<string, {weight: number, vote: number}>} */
+  const perAgent = {};
+  let weightSum = 0;
+  for (const [agentId, raw] of Object.entries(input.votes)) {
+    const v = raw === true || raw === 1 ? 1 : 0;
+    const a = ensureAgent(pool, agentId);
+    perAgent[agentId] = { weight: a.weight, vote: v };
+    total += a.weight * v;
+    weightSum += a.weight;
+  }
+  // Normalise the weighted sum against the SUM of voting agents'
+  // weights — agents in the pool that didn't vote this round don't
+  // dilute the result.
+  const weighted = weightSum > 0 ? total / weightSum : 0;
+  return { passes: weighted >= threshold, weighted, threshold, perAgent };
+}
+
+/**
+ * Read current weights for a pool, normalised over the pool's agents.
+ *
+ * @param {{poolId: string, baseDir?: string, weightsPath?: string}} input
+ * @returns {Record<string, number>}
+ */
+function weights(input) {
+  if (!input || typeof input.poolId !== 'string') {
+    throw new TypeError('hedge-ensemble.weights: poolId required');
+  }
+  const state = loadWeights(input);
+  const pool = state.pools[input.poolId];
+  if (!pool) return {};
+  const total = Object.values(pool.agents).reduce((s, x) => s + x.weight, 0);
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const [k, v] of Object.entries(pool.agents)) {
+    out[k] = total > 0 ? v.weight / total : 0;
+  }
+  return out;
+}
+
+module.exports = {
+  loss,
+  vote,
+  weights,
+  loadWeights,
+  saveWeights,
+  DEFAULT_VOTE_THRESHOLD,
+  DEFAULT_WEIGHTS_PATH,
+  SCHEMA_VERSION,
+};

package/scripts/lib/mmr-rerank.cjs

@@ -0,0 +1,154 @@
+/**
+ * mmr-rerank.cjs — Maximal Marginal Relevance post-pass on top-K
+ * (Plan 23.5-03).
+ *
+ * Solves the "all 5 surfaced learnings are about the same thing"
+ * failure mode in the Phase 14.5 decision-injector. Greedy selection
+ * with the standard MMR criterion:
+ *
+ *   nextItem = argmax_{i ∉ selected}  λ * relevance(i) − (1 − λ) * max_sim(i, selected)
+ *
+ * Similarity is token-overlap (Jaccard on case-folded word n-grams,
+ * default n=2). No external deps, no embedding API.
+ *
+ * Pure helper — caller supplies the candidates and a relevance score
+ * already computed by upstream (e.g. grep hit count, BM25, or the
+ * decision-injector's existing rank function). MMR re-ranks ONLY.
+ */
+
+'use strict';
+
+const DEFAULT_LAMBDA = 0.7;
+const DEFAULT_NGRAM = 2;
+const TOKEN_RE = /[\p{L}\p{N}_-]+/gu;
+
+/**
+ * Tokenize a string into case-folded alphanumeric+underscore+dash runs.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const matches = text.toLowerCase().match(TOKEN_RE);
+  return matches ? matches : [];
+}
+
+/**
+ * Build a Set of word n-grams from a string.
+ *
+ * @param {string} text
+ * @param {number} n
+ * @returns {Set<string>}
+ */
+function ngrams(text, n) {
+  const toks = tokenize(text);
+  if (toks.length < n) return new Set(toks);
+  const out = new Set();
+  for (let i = 0; i <= toks.length - n; i++) {
+    out.add(toks.slice(i, i + n).join(' '));
+  }
+  return out;
+}
+
+/**
+ * Jaccard similarity between two strings on word n-grams.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @param {number} [n]
+ * @returns {number} 0..1
+ */
+function similarity(a, b, n = DEFAULT_NGRAM) {
+  const A = ngrams(a, n);
+  const B = ngrams(b, n);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const g of A) if (B.has(g)) inter += 1;
+  const union = A.size + B.size - inter;
+  return union > 0 ? inter / union : 0;
+}
+
+/**
+ * Re-rank an array of items using the MMR criterion.
+ *
+ * @param {Array<{text: string, relevance?: number}>} items
+ * @param {{lambda?: number, k?: number, ngram?: number, textOf?: (item: object) => string, relevanceOf?: (item: object) => number}} [opts]
+ * @returns {Array<object>} subset of input in MMR-selected order
+ */
+function rerank(items, opts = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('mmr-rerank.rerank: items must be an array');
+  }
+  if (items.length === 0) return [];
+  const lambda = typeof opts.lambda === 'number' ? opts.lambda : DEFAULT_LAMBDA;
+  const ngram = typeof opts.ngram === 'number' ? opts.ngram : DEFAULT_NGRAM;
+  const k = typeof opts.k === 'number' && opts.k > 0 ? Math.min(opts.k, items.length) : items.length;
+  const textOf =
+    typeof opts.textOf === 'function'
+      ? opts.textOf
+      : (it) => (typeof it === 'string' ? it : (it && typeof it.text === 'string' ? it.text : ''));
+  const relOf =
+    typeof opts.relevanceOf === 'function'
+      ? opts.relevanceOf
+      : (it) => {
+          if (it && typeof it.relevance === 'number') return it.relevance;
+          if (it && typeof it.score === 'number') return it.score;
+          return 1;
+        };
+
+  // Pre-tokenize candidates.
+  const grams = items.map((it) => ngrams(textOf(it), ngram));
+  const relevance = items.map((it) => relOf(it));
+  const remaining = items.map((_, i) => i);
+  /** @type {number[]} */
+  const selected = [];
+
+  while (selected.length < k && remaining.length > 0) {
+    let bestIdx = -1;
+    let bestScore = -Infinity;
+    for (const i of remaining) {
+      let maxSim = 0;
+      for (const j of selected) {
+        const sim = jaccard(grams[i], grams[j]);
+        if (sim > maxSim) maxSim = sim;
+      }
+      const score = lambda * relevance[i] - (1 - lambda) * maxSim;
+      if (score > bestScore) {
+        bestScore = score;
+        bestIdx = i;
+      }
+    }
+    if (bestIdx === -1) break;
+    selected.push(bestIdx);
+    const pos = remaining.indexOf(bestIdx);
+    if (pos !== -1) remaining.splice(pos, 1);
+  }
+  return selected.map((i) => items[i]);
+}
+
+/**
+ * Jaccard between two pre-built ngram sets. Faster than calling
+ * `similarity()` from the rerank loop.
+ *
+ * @param {Set<string>} A
+ * @param {Set<string>} B
+ * @returns {number}
+ */
+function jaccard(A, B) {
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const g of A) if (B.has(g)) inter += 1;
+  const union = A.size + B.size - inter;
+  return union > 0 ? inter / union : 0;
+}
+
+module.exports = {
+  rerank,
+  similarity,
+  tokenize,
+  ngrams,
+  jaccard,
+  DEFAULT_LAMBDA,
+  DEFAULT_NGRAM,
+};