@hegemonart/get-design-done 1.27.1 → 1.27.6

package/scripts/lib/parallelism-engine/concurrency-tuner.cjs

@@ -0,0 +1,259 @@
+/**
+ * scripts/lib/parallelism-engine/concurrency-tuner.cjs — Plan 27.6-04
+ *
+ * Data-driven concurrency resolver per Phase 27.6 D-07. Reads the
+ * most-recent `parallelism.verdict` event from .design/telemetry/
+ * events.jsonl (Phase 22 stream) and computes:
+ *
+ *   resolveConcurrency = max(1, min(min(cpu-1, last_observed), ceiling))
+ *
+ * where:
+ *   cpu           = os.cpus().length (override via cpuCount opt)
+ *   last_observed = payload.observed_concurrency from the latest
+ *                   parallelism.verdict event (null if absent)
+ *   ceiling       = process.env.GDD_CONCURRENCY_CEILING (default 8)
+ *
+ * Hard ceiling of 8 prevents pathological process-spawn storms on
+ * high-core machines (D-07 wording: "Hard ceiling prevents pathological
+ * process-spawn storms").
+ *
+ * Public surface:
+ *   * resolveConcurrency({cpuCount?, lastObservedOptimum?, hardCeiling?,
+ *                        eventsPath?, baseDir?}) -> number  (>=1)
+ *   * readLastObservedOptimum({eventsPath?, baseDir?}) -> number|null
+ *   * emitParallelismVerdict({task_ids, verdict, reason,
+ *                            intended_concurrency?, observed_concurrency?,
+ *                            contention_detected?, wall_clock_ms?,
+ *                            sessionId?}) -> void
+ *   * DEFAULT_HARD_CEILING (=8)
+ *   * DEFAULT_EVENTS_PATH (='.design/telemetry/events.jsonl')
+ *
+ * The `parallelism.verdict` payload extension is purely additive
+ * (`intended_concurrency`, `observed_concurrency`, `contention_detected`,
+ * `wall_clock_ms` are all optional). Existing consumers that only read
+ * `{task_ids, verdict, reason}` keep working unchanged.
+ *
+ * No external deps. Lazy event-stream require for emit (best-effort
+ * telemetry — a failed event-stream load must not break the resolver).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const DEFAULT_HARD_CEILING = 8;
+const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
+
+/**
+ * Lazy-require the event-stream module. Returns a no-op `appendEvent`
+ * when the module is unavailable so callers never have to wrap emit
+ * calls in try/catch themselves.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    // Resolved relative to this file: scripts/lib/parallelism-engine/
+    // -> ../event-stream. The event-stream module is .ts; Node 22+
+    // with --experimental-strip-types (or Node 24 built-in TS) can
+    // require it. If require fails (e.g., older runtime, missing
+    // module), fall through to the no-op.
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    // Swallow — best-effort telemetry. Losing one verdict is
+    // acceptable; breaking concurrency resolution is not.
+  }
+  return function noopAppend(_ev) {
+    /* event-stream unavailable */
+  };
+}
+
+/**
+ * Resolve the hard ceiling. Operator override via GDD_CONCURRENCY_CEILING
+ * env var (parsed as integer) takes precedence; the explicit `override`
+ * argument wins over the env. Default is 8 (D-07).
+ *
+ * @param {number|undefined} override
+ * @returns {number}
+ */
+function resolveCeiling(override) {
+  if (typeof override === 'number' && override >= 1) return Math.floor(override);
+  const env = process.env.GDD_CONCURRENCY_CEILING;
+  if (typeof env === 'string' && env.length > 0) {
+    const parsed = parseInt(env, 10);
+    if (Number.isFinite(parsed) && parsed >= 1) return parsed;
+  }
+  return DEFAULT_HARD_CEILING;
+}
+
+/**
+ * Compose the JSONL events path. Relative paths are joined to baseDir
+ * when supplied; absolute paths are returned as-is.
+ *
+ * @param {{eventsPath?: string, baseDir?: string}} opts
+ * @returns {string}
+ */
+function resolvePath({ eventsPath, baseDir }) {
+  let p = typeof eventsPath === 'string' && eventsPath.length > 0
+    ? eventsPath
+    : DEFAULT_EVENTS_PATH;
+  if (baseDir && !path.isAbsolute(p)) p = path.join(baseDir, p);
+  return p;
+}
+
+/**
+ * Read .design/telemetry/events.jsonl and return the
+ * `observed_concurrency` from the MOST RECENT parallelism.verdict event
+ * (sequential read order). Tolerates malformed lines and absent file.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.eventsPath] override events.jsonl path
+ * @param {string} [opts.baseDir]    base for relative eventsPath
+ * @returns {number|null}
+ */
+function readLastObservedOptimum({ eventsPath, baseDir } = {} ) {
+  const target = resolvePath({ eventsPath, baseDir });
+  if (!fs.existsSync(target)) return null;
+  let body;
+  try {
+    body = fs.readFileSync(target, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = body.split(/\r?\n/);
+  let lastOptimum = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const ev = JSON.parse(trimmed);
+      if (
+        ev
+        && ev.type === 'parallelism.verdict'
+        && ev.payload
+        && typeof ev.payload.observed_concurrency === 'number'
+      ) {
+        lastOptimum = Math.floor(ev.payload.observed_concurrency);
+      }
+    } catch {
+      // Tolerate malformed line — JSONL is best-effort.
+    }
+  }
+  return lastOptimum;
+}
+
+/**
+ * Resolve the recommended concurrency per D-07.
+ *
+ *   1. base       = max(1, cpuCount - 1)         // never below 1
+ *   2. optimum    = lastObservedOptimum         // explicit override
+ *                   ?? readLastObservedOptimum() // or read from JSONL
+ *   3. candidate  = optimum > 0 ? min(base, optimum) : base
+ *   4. ceiling    = override ?? GDD_CONCURRENCY_CEILING ?? 8
+ *   5. return max(1, min(candidate, ceiling))
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.cpuCount]            override os.cpus().length
+ * @param {number|null} [opts.lastObservedOptimum] explicit override; null/undefined triggers JSONL read
+ * @param {number} [opts.hardCeiling]         override the env/default ceiling
+ * @param {string} [opts.eventsPath]          override events.jsonl path
+ * @param {string} [opts.baseDir]             base for relative eventsPath
+ * @returns {number} integer >= 1
+ */
+function resolveConcurrency({
+  cpuCount,
+  lastObservedOptimum,
+  hardCeiling,
+  eventsPath,
+  baseDir,
+} = {}) {
+  const cpu = typeof cpuCount === 'number' && cpuCount >= 1
+    ? Math.floor(cpuCount)
+    : os.cpus().length;
+  const base = Math.max(1, cpu - 1);
+  let optimum = lastObservedOptimum;
+  if (optimum === undefined || optimum === null) {
+    optimum = readLastObservedOptimum({ eventsPath, baseDir });
+  }
+  const candidate = typeof optimum === 'number' && optimum >= 1
+    ? Math.min(base, Math.floor(optimum))
+    : base;
+  const ceiling = resolveCeiling(hardCeiling);
+  return Math.max(1, Math.min(candidate, ceiling));
+}
+
+/**
+ * Emit a `parallelism.verdict` event with the Phase 27.6 superset
+ * payload. Existing fields ({task_ids, verdict, reason}) are always
+ * present; the new fields (intended_concurrency, observed_concurrency,
+ * contention_detected, wall_clock_ms) are appended only when supplied.
+ *
+ * Side effect: appendEvent({type: 'parallelism.verdict', ...}). When
+ * event-stream is unavailable, this is a no-op (lazy require fallback).
+ *
+ * @param {object} opts
+ * @param {string[]} opts.task_ids
+ * @param {'parallel'|'sequential'} opts.verdict
+ * @param {string}  opts.reason
+ * @param {number}  [opts.intended_concurrency]
+ * @param {number}  [opts.observed_concurrency]
+ * @param {boolean} [opts.contention_detected]
+ * @param {number}  [opts.wall_clock_ms]
+ * @param {string}  [opts.sessionId]
+ * @returns {void}
+ */
+function emitParallelismVerdict({
+  task_ids,
+  verdict,
+  reason,
+  intended_concurrency,
+  observed_concurrency,
+  contention_detected,
+  wall_clock_ms,
+  sessionId,
+} = {}) {
+  const append = getAppendEvent();
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    task_ids: Array.isArray(task_ids) ? task_ids : [],
+    verdict: verdict === 'parallel' || verdict === 'sequential' ? verdict : 'sequential',
+    reason: typeof reason === 'string' ? reason : 'unspecified',
+  };
+  // Additive 27.6 fields — only include when set, to keep payloads
+  // compact and avoid noisy `undefined` keys on the wire.
+  if (typeof intended_concurrency === 'number') {
+    payload.intended_concurrency = intended_concurrency;
+  }
+  if (typeof observed_concurrency === 'number') {
+    payload.observed_concurrency = observed_concurrency;
+  }
+  if (typeof contention_detected === 'boolean') {
+    payload.contention_detected = contention_detected;
+  }
+  if (typeof wall_clock_ms === 'number') {
+    payload.wall_clock_ms = wall_clock_ms;
+  }
+  try {
+    append({
+      type: 'parallelism.verdict',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0
+        ? sessionId
+        : 'concurrency-tuner',
+      payload,
+    });
+  } catch {
+    // Best-effort telemetry. A failed write must never break the
+    // caller's wave-execution flow.
+  }
+}
+
+module.exports = {
+  resolveConcurrency,
+  readLastObservedOptimum,
+  emitParallelismVerdict,
+  DEFAULT_HARD_CEILING,
+  DEFAULT_EVENTS_PATH,
+};

package/scripts/lib/parallelism-engine/concurrency-tuner.d.cts

@@ -0,0 +1,53 @@
+// scripts/lib/parallelism-engine/concurrency-tuner.d.cts — types for concurrency-tuner.cjs (Phase 27.6 D-07).
+
+export interface ResolveConcurrencyOptions {
+  /** Override CPU count detection (defaults to `os.cpus().length`). */
+  cpuCount?: number;
+  /** Override last-observed optimum (else read from event-chain). */
+  lastObservedOptimum?: number;
+  /** Hard ceiling cap. Defaults to `DEFAULT_HARD_CEILING` (8). */
+  hardCeiling?: number;
+  /** Event-chain path override (else use `DEFAULT_EVENTS_PATH`). */
+  eventsPath?: string;
+  /** Base directory override (else `process.cwd()`). */
+  baseDir?: string;
+}
+
+export interface ReadLastObservedOptimumOptions {
+  eventsPath?: string;
+  baseDir?: string;
+}
+
+export interface EmitParallelismVerdictPayload {
+  task_ids?: string[];
+  verdict?: string;
+  reason?: string;
+  intended_concurrency?: number;
+  observed_concurrency?: number;
+  contention_detected?: boolean;
+  wall_clock_ms?: number;
+}
+
+/**
+ * Resolve the concurrency default per D-07: `min(cpu-1, last_observed_optimum, hard_ceiling)`.
+ * Falls back to `cpu-1` capped at `hard_ceiling` when no prior verdict exists.
+ */
+export function resolveConcurrency(opts?: ResolveConcurrencyOptions): number;
+
+/**
+ * Read the latest `parallelism.verdict` event's optimum from the event chain.
+ * Returns null when no prior verdict exists.
+ */
+export function readLastObservedOptimum(
+  opts?: ReadLastObservedOptimumOptions,
+): number | null;
+
+/**
+ * Emit a `parallelism.verdict` event (additive payload — back-compat preserved).
+ */
+export function emitParallelismVerdict(
+  payload?: EmitParallelismVerdictPayload,
+): void;
+
+export const DEFAULT_HARD_CEILING: number;
+export const DEFAULT_EVENTS_PATH: string;

package/scripts/lib/perf-analyzer/cost-regression.cjs

@@ -0,0 +1,299 @@
+/**
+ * scripts/lib/perf-analyzer/cost-regression.cjs — Plan 27.6-01
+ *
+ * Stateless detection rules over the telemetry row arrays returned by
+ * scripts/lib/perf-analyzer/index.cjs. Three pure functions:
+ *
+ *   detectCostRegressions  — top-3 agents whose p50 USD-cost has
+ *                            regressed >= thresholdPct (default 25%
+ *                            per Phase 27.6 D-01) vs baseline across
+ *                            cyclesRequired distinct cycles (default 3).
+ *   computeCacheHitDelta   — per-agent current hit rate vs baseline.
+ *   computeP95Spikes       — per-agent p95 wall-time multiplier vs
+ *                            baseline. Flag when multiplier >= 1.5.
+ *
+ * All inputs are plain arrays / objects. No I/O. No external deps.
+ */
+'use strict';
+
+/**
+ * Median (p50) of a numeric array. Returns 0 for empty input.
+ * Even-length arrays return the mean of the two middle values.
+ *
+ * @param {number[]} arr
+ * @returns {number}
+ */
+function p50(arr) {
+  if (!arr || arr.length === 0) return 0;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * p95 of a numeric array (nearest-rank, floor index, clamped to last).
+ * Returns 0 for empty input.
+ *
+ * @param {number[]} arr
+ * @returns {number}
+ */
+function p95(arr) {
+  if (!arr || arr.length === 0) return 0;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95));
+  return sorted[idx];
+}
+
+/**
+ * Group cost rows by agent, then by cycle. Filters out rows missing
+ * the required shape (agent, est_cost_usd, cycle).
+ *
+ * @param {object[]} rows
+ * @returns {Map<string, { cycles: Map<string, number[]> }>}
+ */
+function groupRowsByAgentCycle(rows) {
+  const byAgent = new Map();
+  for (const row of rows || []) {
+    if (
+      !row ||
+      typeof row.agent !== 'string' ||
+      typeof row.est_cost_usd !== 'number' ||
+      typeof row.cycle !== 'string'
+    ) {
+      continue;
+    }
+    let bucket = byAgent.get(row.agent);
+    if (!bucket) {
+      bucket = { cycles: new Map() };
+      byAgent.set(row.agent, bucket);
+    }
+    let cycleArr = bucket.cycles.get(row.cycle);
+    if (!cycleArr) {
+      cycleArr = [];
+      bucket.cycles.set(row.cycle, cycleArr);
+    }
+    cycleArr.push(row.est_cost_usd);
+  }
+  return byAgent;
+}
+
+/**
+ * Top-3 token-cost regressions across the most recent `cyclesRequired`
+ * distinct cycles per agent. Honours D-01 defaults (25% / 3 cycles).
+ *
+ * @param {object}   opts
+ * @param {object[]} opts.rows             - cost rows (from loadCosts)
+ * @param {Record<string, {p50_usd:number, hit_rate?:number, p95_ms?:number}>} opts.baseline
+ * @param {number}   [opts.thresholdPct=25] - regression threshold (D-01)
+ * @param {number}   [opts.cyclesRequired=3] - minimum distinct cycles (D-01)
+ * @returns {{
+ *   regressions: Array<{agent:string, baseline_p50_usd:number, current_p50_usd:number, delta_pct:number, cycles_observed:number}>,
+ *   summary: {agents_evaluated:number, agents_skipped_insufficient_data:number, regressions_count:number, threshold_pct:number, cycles_required:number}
+ * }}
+ */
+function detectCostRegressions({ rows, baseline, thresholdPct, cyclesRequired } = {}) {
+  const _thresholdPct = thresholdPct ?? 25;
+  const _cyclesRequired = cyclesRequired ?? 3;
+  const _baseline = baseline || {};
+
+  const byAgent = groupRowsByAgentCycle(rows);
+
+  /** @type {Array<{agent:string, baseline_p50_usd:number, current_p50_usd:number, delta_pct:number, cycles_observed:number}>} */
+  const candidates = [];
+  let agents_evaluated = 0;
+  let agents_skipped = 0;
+
+  for (const [agent, bucket] of byAgent.entries()) {
+    // Newest cycles first (lexicographic descending) — take up to N.
+    const cycleKeys = [...bucket.cycles.keys()].sort().reverse();
+    const recentCycles = cycleKeys.slice(0, _cyclesRequired);
+
+    if (recentCycles.length < _cyclesRequired) {
+      agents_skipped += 1;
+      continue;
+    }
+
+    const baselineEntry = _baseline[agent];
+    if (!baselineEntry || typeof baselineEntry.p50_usd !== 'number') {
+      agents_skipped += 1;
+      continue;
+    }
+
+    const flatCosts = recentCycles.flatMap((c) => bucket.cycles.get(c));
+    const current = p50(flatCosts);
+    const base = baselineEntry.p50_usd;
+
+    // Contract (plan 27.6-01 behavior): "an agent's p50 USD-cost across
+    // the LAST cyclesRequired cycles is >= baseline_p50 × (1 + thresholdPct/100)".
+    // Apply the multiplicative form directly so the threshold-boundary case
+    // (e.g. baseline=0.05, current=0.0625, thresholdPct=25) is exact rather
+    // than dropping a ULP into the < side after a divide-and-multiply.
+    let delta_pct;
+    let isRegression;
+    if (base === 0) {
+      delta_pct = current === 0 ? 0 : Infinity;
+      isRegression = current > 0; // base=0+current>0 → always regression (D-01 edge)
+    } else {
+      const threshold = base * (1 + _thresholdPct / 100);
+      delta_pct = ((current - base) / base) * 100;
+      isRegression = current >= threshold;
+    }
+
+    agents_evaluated += 1;
+
+    if (isRegression) {
+      candidates.push({
+        agent,
+        baseline_p50_usd: base,
+        current_p50_usd: current,
+        delta_pct,
+        cycles_observed: recentCycles.length,
+      });
+    }
+  }
+
+  candidates.sort((a, b) => b.delta_pct - a.delta_pct);
+  const regressions = candidates.slice(0, 3);
+
+  return {
+    regressions,
+    summary: {
+      agents_evaluated,
+      agents_skipped_insufficient_data: agents_skipped,
+      regressions_count: regressions.length,
+      threshold_pct: _thresholdPct,
+      cycles_required: _cyclesRequired,
+    },
+  };
+}
+
+/**
+ * Cache-hit-rate delta per agent: current hit rate over the most recent
+ * `cyclesRequired` distinct cycles vs baseline hit rate.
+ *
+ * @param {object} opts
+ * @param {object[]} opts.rows
+ * @param {Record<string, {hit_rate?:number}>} opts.baseline
+ * @param {number} [opts.cyclesRequired=3]
+ * @returns {{ perAgent: Array<{agent:string, baseline_hit_rate:number, current_hit_rate:number, delta_pct:number, cycles_observed:number}> }}
+ */
+function computeCacheHitDelta({ rows, baseline, cyclesRequired } = {}) {
+  const _cyclesRequired = cyclesRequired ?? 3;
+  const _baseline = baseline || {};
+
+  // Group by agent: { agent -> Map<cycle, { hits: number, total: number }> }
+  const byAgent = new Map();
+  for (const row of rows || []) {
+    if (!row || typeof row.agent !== 'string' || typeof row.cycle !== 'string') continue;
+    let bucket = byAgent.get(row.agent);
+    if (!bucket) {
+      bucket = { cycles: new Map() };
+      byAgent.set(row.agent, bucket);
+    }
+    let cycleEntry = bucket.cycles.get(row.cycle);
+    if (!cycleEntry) {
+      cycleEntry = { hits: 0, total: 0 };
+      bucket.cycles.set(row.cycle, cycleEntry);
+    }
+    cycleEntry.total += 1;
+    if (row.cache_hit === true) cycleEntry.hits += 1;
+  }
+
+  /** @type {Array<{agent:string, baseline_hit_rate:number, current_hit_rate:number, delta_pct:number, cycles_observed:number}>} */
+  const perAgent = [];
+  for (const [agent, bucket] of byAgent.entries()) {
+    const cycleKeys = [...bucket.cycles.keys()].sort().reverse();
+    const recentCycles = cycleKeys.slice(0, _cyclesRequired);
+    if (recentCycles.length === 0) continue;
+
+    let hits = 0;
+    let total = 0;
+    for (const c of recentCycles) {
+      const entry = bucket.cycles.get(c);
+      hits += entry.hits;
+      total += entry.total;
+    }
+    if (total === 0) continue;
+
+    const current_hit_rate = hits / total;
+    const baselineEntry = _baseline[agent];
+    const baseline_hit_rate =
+      baselineEntry && typeof baselineEntry.hit_rate === 'number' ? baselineEntry.hit_rate : 0;
+
+    let delta_pct;
+    if (baseline_hit_rate === 0) {
+      delta_pct = current_hit_rate === 0 ? 0 : Infinity;
+    } else {
+      delta_pct = ((current_hit_rate - baseline_hit_rate) / baseline_hit_rate) * 100;
+    }
+
+    perAgent.push({
+      agent,
+      baseline_hit_rate,
+      current_hit_rate,
+      delta_pct,
+      cycles_observed: recentCycles.length,
+    });
+  }
+
+  return { perAgent };
+}
+
+/**
+ * Aggregate wall_time_ms per agent across all cycles in `byCycle` and
+ * compare current p95 to baseline p95. Flag agents whose
+ * `current_p95 / baseline_p95 >= multiplierThreshold` (default 1.5).
+ *
+ * @param {object} opts
+ * @param {Record<string, object[]>} opts.byCycle
+ * @param {Record<string, {p95_ms?:number}>} opts.baseline
+ * @param {number} [opts.multiplierThreshold=1.5]
+ * @returns {{ spikes: Array<{agent:string, baseline_p95_ms:number, current_p95_ms:number, multiplier:number, cycles_observed:number}> }}
+ */
+function computeP95Spikes({ byCycle, baseline, multiplierThreshold } = {}) {
+  const _multiplier = multiplierThreshold ?? 1.5;
+  const _baseline = baseline || {};
+  const _byCycle = byCycle || {};
+
+  // Aggregate per agent: agent -> { walls: number[], cycles: Set<string> }
+  /** @type {Map<string, { walls: number[], cycles: Set<string> }>} */
+  const byAgent = new Map();
+  for (const [cycle, entries] of Object.entries(_byCycle)) {
+    for (const entry of entries || []) {
+      if (!entry || typeof entry.agent !== 'string' || typeof entry.wall_time_ms !== 'number') {
+        continue;
+      }
+      let bucket = byAgent.get(entry.agent);
+      if (!bucket) {
+        bucket = { walls: [], cycles: new Set() };
+        byAgent.set(entry.agent, bucket);
+      }
+      bucket.walls.push(entry.wall_time_ms);
+      bucket.cycles.add(cycle);
+    }
+  }
+
+  /** @type {Array<{agent:string, baseline_p95_ms:number, current_p95_ms:number, multiplier:number, cycles_observed:number}>} */
+  const spikes = [];
+  for (const [agent, bucket] of byAgent.entries()) {
+    const baselineEntry = _baseline[agent];
+    if (!baselineEntry || typeof baselineEntry.p95_ms !== 'number') continue;
+    const base = baselineEntry.p95_ms;
+    if (base === 0) continue; // can't form a multiplier against zero
+    const current_p95_ms = p95(bucket.walls);
+    const multiplier = current_p95_ms / base;
+    if (multiplier >= _multiplier) {
+      spikes.push({
+        agent,
+        baseline_p95_ms: base,
+        current_p95_ms,
+        multiplier,
+        cycles_observed: bucket.cycles.size,
+      });
+    }
+  }
+
+  return { spikes };
+}
+
+module.exports = { detectCostRegressions, computeCacheHitDelta, computeP95Spikes };