@hegemonart/get-design-done 1.22.0 → 1.23.5

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,
+};

package/scripts/lib/parse-contract.cjs

@@ -204,11 +204,176 @@ function loadMotionMapSchema(projectRoot) {
   return JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
 }
 
+// ---------------------------------------------------------------------------
+// Phase 23 Plan 23-01 — planner + verifier decision contracts.
+//
+// These parsers ride the same extract→parse→validate pipeline as
+// parseMotionMap. Validation is structural (required fields, enums,
+// types) — full JSON Schema validation is delegated to ajv when callers
+// want strict enforcement; the in-line validators keep the no-deps
+// guarantee for the hot path.
+// ---------------------------------------------------------------------------
+
+const VALID_VERIFIER_VERDICTS = ['pass', 'fail', 'gap'];
+const VALID_GAP_SEVERITIES = ['P0', 'P1', 'P2', 'P3'];
+const VALID_VERIFIER_CONFIDENCE = ['high', 'med', 'low'];
+
+function validatePlannerDecision(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    return { ok: false, errors: ['Top-level value is not an object'] };
+  }
+  if (data.schema_version !== '1.0.0') {
+    errors.push(`schema_version must be "1.0.0" (got ${JSON.stringify(data.schema_version)})`);
+  }
+  if (typeof data.plan_id !== 'string' || data.plan_id.length === 0) {
+    errors.push('plan_id is required (non-empty string)');
+  }
+  if (!Array.isArray(data.tasks) || data.tasks.length === 0) {
+    errors.push('tasks must be a non-empty array');
+  } else {
+    data.tasks.forEach((task, i) => {
+      const tag = `tasks[${i}]`;
+      if (!task || typeof task !== 'object') {
+        errors.push(`${tag} is not an object`);
+        return;
+      }
+      if (typeof task.task_id !== 'string' || task.task_id.length === 0) {
+        errors.push(`${tag}.task_id is required (non-empty string)`);
+      }
+      if (typeof task.summary !== 'string' || task.summary.length < 3) {
+        errors.push(`${tag}.summary required, ≥3 chars`);
+      }
+      if (!Array.isArray(task.touches) || task.touches.some((t) => typeof t !== 'string')) {
+        errors.push(`${tag}.touches must be an array of strings`);
+      }
+      if (task.dependencies !== undefined &&
+          (!Array.isArray(task.dependencies) ||
+           task.dependencies.some((d) => typeof d !== 'string'))) {
+        errors.push(`${tag}.dependencies must be an array of strings`);
+      }
+      if (task.parallel_safe !== undefined && typeof task.parallel_safe !== 'boolean') {
+        errors.push(`${tag}.parallel_safe must be boolean`);
+      }
+      if (task.estimated_minutes !== undefined &&
+          (typeof task.estimated_minutes !== 'number' || task.estimated_minutes < 0)) {
+        errors.push(`${tag}.estimated_minutes must be a non-negative number`);
+      }
+    });
+  }
+  if (!Array.isArray(data.waves) || data.waves.length === 0) {
+    errors.push('waves must be a non-empty array');
+  } else {
+    data.waves.forEach((wave, i) => {
+      const tag = `waves[${i}]`;
+      if (!wave || typeof wave !== 'object') {
+        errors.push(`${tag} is not an object`);
+        return;
+      }
+      if (typeof wave.wave !== 'string' || wave.wave.length === 0) {
+        errors.push(`${tag}.wave required (non-empty string)`);
+      }
+      if (!Array.isArray(wave.task_ids) || wave.task_ids.length === 0) {
+        errors.push(`${tag}.task_ids must be a non-empty array`);
+      }
+    });
+  }
+  return errors.length === 0 ? { ok: true, data } : { ok: false, errors };
+}
+
+function validateVerifierDecision(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    return { ok: false, errors: ['Top-level value is not an object'] };
+  }
+  if (data.schema_version !== '1.0.0') {
+    errors.push(`schema_version must be "1.0.0" (got ${JSON.stringify(data.schema_version)})`);
+  }
+  if (!VALID_VERIFIER_VERDICTS.includes(data.verdict)) {
+    errors.push(`verdict must be one of [${VALID_VERIFIER_VERDICTS.join('|')}] (got ${JSON.stringify(data.verdict)})`);
+  }
+  if (!Array.isArray(data.gaps)) {
+    errors.push('gaps must be an array');
+  } else {
+    data.gaps.forEach((gap, i) => {
+      const tag = `gaps[${i}]`;
+      if (!gap || typeof gap !== 'object') {
+        errors.push(`${tag} is not an object`);
+        return;
+      }
+      if (typeof gap.id !== 'string' || gap.id.length === 0) {
+        errors.push(`${tag}.id is required (non-empty string)`);
+      }
+      if (!VALID_GAP_SEVERITIES.includes(gap.severity)) {
+        errors.push(`${tag}.severity must be one of [${VALID_GAP_SEVERITIES.join('|')}]`);
+      }
+      if (typeof gap.area !== 'string' || gap.area.length === 0) {
+        errors.push(`${tag}.area is required (non-empty string)`);
+      }
+      if (typeof gap.summary !== 'string' || gap.summary.length < 3) {
+        errors.push(`${tag}.summary required, ≥3 chars`);
+      }
+    });
+  }
+  if (!Array.isArray(data.must_fix_before_ship) ||
+      data.must_fix_before_ship.some((s) => typeof s !== 'string')) {
+    errors.push('must_fix_before_ship must be an array of strings');
+  }
+  if (!VALID_VERIFIER_CONFIDENCE.includes(data.confidence)) {
+    errors.push(`confidence must be one of [${VALID_VERIFIER_CONFIDENCE.join('|')}]`);
+  }
+  return errors.length === 0 ? { ok: true, data } : { ok: false, errors };
+}
+
+/**
+ * Extract + validate the planner decision JSON block from markdown output.
+ * @param {string} markdown
+ * @returns {{ ok: true, data: object } | { ok: false, error: string }}
+ */
+function parsePlannerDecision(markdown) {
+  const extracted = extractJsonBlock(markdown);
+  if (!extracted.ok) return { ok: false, error: extracted.error };
+  const parsed = parseJson(extracted.raw);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const validated = validatePlannerDecision(parsed.data);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      error: `Planner decision contract violations:\n${validated.errors.map((e) => `  - ${e}`).join('\n')}`,
+    };
+  }
+  return { ok: true, data: validated.data };
+}
+
+/**
+ * Extract + validate the verifier decision JSON block from markdown output.
+ * @param {string} markdown
+ * @returns {{ ok: true, data: object } | { ok: false, error: string }}
+ */
+function parseVerifierDecision(markdown) {
+  const extracted = extractJsonBlock(markdown);
+  if (!extracted.ok) return { ok: false, error: extracted.error };
+  const parsed = parseJson(extracted.raw);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const validated = validateVerifierDecision(parsed.data);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      error: `Verifier decision contract violations:\n${validated.errors.map((e) => `  - ${e}`).join('\n')}`,
+    };
+  }
+  return { ok: true, data: validated.data };
+}
+
 module.exports = {
   parseMotionMap,
+  parsePlannerDecision,
+  parseVerifierDecision,
   parseGenericContract,
   loadMotionMapSchema,
   validateMotionMap,
+  validatePlannerDecision,
+  validateVerifierDecision,
   extractJsonBlock,
   parseJson,
   // Exported for testing
@@ -217,4 +382,7 @@ module.exports = {
   VALID_TRANSITION_FAMILIES,
   VALID_DURATION_CLASSES,
   VALID_TRIGGERS,
+  VALID_VERIFIER_VERDICTS,
+  VALID_GAP_SEVERITIES,
+  VALID_VERIFIER_CONFIDENCE,
 };