@hegemonart/get-design-done 1.27.1 → 1.27.6

package/scripts/lib/bandit-router/integration.cjs

@@ -0,0 +1,309 @@
+/**
+ * scripts/lib/bandit-router/integration.cjs — Plan 27.5-01
+ *
+ * Production-integration shim for the Phase 23.5 bandit posterior +
+ * Phase 27-07 delegate dimension. Hides the `pull` vs `pullWithDelegate`
+ * + `update` vs `updateWithDelegate` choice from callers.
+ *
+ * Two functions:
+ *   consultBandit({agent, bin, delegate, agentFrontmatter, adaptiveMode, baseDir?, posteriorPath?})
+ *     → {tier, decision_log}
+ *   recordOutcome({agent, bin, delegate, tier, status, costUsd, adaptiveMode, baseDir?, posteriorPath?})
+ *     → void (best-effort write per D-04)
+ *
+ * Routing rules (D-05 + D-07):
+ *   1. agentFrontmatter.tier_override is set         → bypass bandit, return tier_override
+ *   2. adaptiveMode !== 'full'                       → bandit silent, return frontmatter.default_tier
+ *      (covers 'static' and 'hedge' per D-07)
+ *   3. adaptiveMode === 'full' && delegate is 'none' / undefined
+ *                                                    → call pull()
+ *   4. adaptiveMode === 'full' && delegate is a peer name
+ *                                                    → call pullWithDelegate({delegates:[delegate]})
+ *
+ * recordOutcome is symmetric on the adaptive_mode gate:
+ *   - non-'full'                                     → no-op
+ *   - 'full' && delegate 'none'/undefined            → update()
+ *   - 'full' && delegate is a peer                   → updateWithDelegate()
+ *
+ * Reward function = Phase 23.5's computeReward unchanged (D-08).
+ *
+ * Posterior writes are best-effort — all throws are swallowed. The
+ * shim's job is to plumb the call; telemetry resilience is downstream.
+ */
+
+'use strict';
+
+const banditRouter = require('../bandit-router.cjs');
+const adaptiveModeLib = require('../adaptive-mode.cjs');
+
+const DELEGATE_NONE = banditRouter.DELEGATE_NONE; // 'none'
+const VALID_DELEGATES = banditRouter.DEFAULT_DELEGATES; // ['none','gemini','codex','cursor','copilot','qwen']
+
+/**
+ * Validate that `delegate` is either undefined, DELEGATE_NONE, or a
+ * member of VALID_DELEGATES. Returns the canonical delegate string
+ * (undefined → 'none').
+ *
+ * @param {string|undefined} delegate
+ * @param {string} fnName — for error message context
+ * @returns {string}
+ */
+function resolveDelegate(delegate, fnName) {
+  if (delegate === undefined || delegate === null) return DELEGATE_NONE;
+  if (typeof delegate !== 'string') {
+    throw new TypeError(
+      `integration.${fnName}: delegate must be a string when provided, got ${typeof delegate}`,
+    );
+  }
+  if (!VALID_DELEGATES.includes(delegate)) {
+    throw new RangeError(
+      `integration.${fnName}: unknown delegate '${delegate}'; expected one of ${VALID_DELEGATES.join(',')}`,
+    );
+  }
+  return delegate;
+}
+
+/**
+ * Resolve the adaptive_mode for a call. If the caller passed it
+ * explicitly we use that; otherwise we read it from disk via
+ * adaptive-mode.getMode (D-07: single gating surface).
+ *
+ * @param {string|undefined} adaptiveMode
+ * @param {{baseDir?: string}} opts
+ * @returns {'static'|'hedge'|'full'}
+ */
+function resolveAdaptiveMode(adaptiveMode, opts) {
+  if (typeof adaptiveMode === 'string' && adaptiveMode.length > 0) {
+    return /** @type {'static'|'hedge'|'full'} */ (adaptiveMode);
+  }
+  return adaptiveModeLib.getMode({ baseDir: opts && opts.baseDir, quiet: true });
+}
+
+/**
+ * consultBandit — single canonical lookup that returns a tier + a
+ * decision_log explaining how the tier was chosen. Five paths:
+ *
+ *   Path 1 — static mode → frontmatter.default_tier (or 'sonnet' fallback)
+ *   Path 2 — tier_override set on frontmatter → bypass bandit
+ *   Path 3 — full mode + delegate='none' (or undefined) → pull()
+ *   Path 4 — full mode + delegate=<peer> → pullWithDelegate()
+ *   Path 5 — hedge mode → frontmatter.default_tier (bandit silent)
+ *
+ * Path 2 takes precedence over Path 1 / 3 / 4 / 5 (tier_override is the
+ * explicit operator override per D-05).
+ *
+ * @param {{
+ *   agent: string,
+ *   bin: string,
+ *   delegate?: string,
+ *   agentFrontmatter?: {tier_override?: string, default_tier?: string},
+ *   adaptiveMode?: 'static'|'hedge'|'full',
+ *   baseDir?: string,
+ *   posteriorPath?: string,
+ * }} input
+ * @returns {{
+ *   tier: string,
+ *   decision_log: {
+ *     source: 'frontmatter'|'tier_override_bypass'|'bandit_pull'|'bandit_pull_with_delegate',
+ *     samples?: object,
+ *     delegate?: string,
+ *     adaptive_mode: 'static'|'hedge'|'full',
+ *     reason?: string,
+ *   }
+ * }}
+ */
+function consultBandit(input) {
+  if (!input || typeof input !== 'object') {
+    throw new TypeError('integration.consultBandit: input object required');
+  }
+  if (typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('integration.consultBandit: agent (string) required');
+  }
+  if (typeof input.bin !== 'string' || input.bin.length === 0) {
+    throw new TypeError('integration.consultBandit: bin (string) required');
+  }
+
+  const agentFrontmatter = input.agentFrontmatter && typeof input.agentFrontmatter === 'object'
+    ? input.agentFrontmatter
+    : {};
+  const adaptiveMode = resolveAdaptiveMode(input.adaptiveMode, input);
+  const delegate = resolveDelegate(input.delegate, 'consultBandit');
+
+  // Step 1 — tier_override bypass (D-05). Highest priority; beats both
+  // bandit consultation and static/hedge frontmatter.default_tier.
+  if (typeof agentFrontmatter.tier_override === 'string' && agentFrontmatter.tier_override.length > 0) {
+    return {
+      tier: agentFrontmatter.tier_override,
+      decision_log: {
+        source: 'tier_override_bypass',
+        adaptive_mode: adaptiveMode,
+        reason: 'frontmatter_tier_override_set',
+      },
+    };
+  }
+
+  // Step 2 — non-full short-circuit (D-07). Static and hedge are both
+  // "bandit silent"; frontmatter.default_tier (or 'sonnet' fallback)
+  // is authoritative. No posterior read or write.
+  if (adaptiveMode !== 'full') {
+    const fallbackTier = (typeof agentFrontmatter.default_tier === 'string' && agentFrontmatter.default_tier.length > 0)
+      ? agentFrontmatter.default_tier
+      : 'sonnet';
+    return {
+      tier: fallbackTier,
+      decision_log: {
+        source: 'frontmatter',
+        adaptive_mode: adaptiveMode,
+        reason: adaptiveMode === 'hedge' ? 'hedge_mode_skips_bandit' : 'static_mode_authoritative',
+      },
+    };
+  }
+
+  // Step 3/4 — full mode → consult the bandit. Choice of pull vs
+  // pullWithDelegate is driven by `delegate`:
+  //   delegate === 'none' (or undefined → 'none')  → pull()
+  //   delegate ∈ {gemini,codex,cursor,copilot,qwen} → pullWithDelegate
+  if (delegate === DELEGATE_NONE) {
+    const result = banditRouter.pull({
+      agent: input.agent,
+      bin: input.bin,
+      baseDir: input.baseDir,
+      posteriorPath: input.posteriorPath,
+    });
+    return {
+      tier: result.tier,
+      decision_log: {
+        source: 'bandit_pull',
+        samples: result.samples,
+        delegate: DELEGATE_NONE,
+        adaptive_mode: 'full',
+      },
+    };
+  }
+
+  // Path 4 — peer delegate. Constrain the delegate axis to the single
+  // requested peer so the bandit samples the (tier × delegate) joint
+  // restricted to {delegate}. Same posterior file, same arm shape; the
+  // arm's `delegate` field is set so the slice is distinct from local.
+  const result = banditRouter.pullWithDelegate({
+    agent: input.agent,
+    bin: input.bin,
+    delegates: [delegate],
+    baseDir: input.baseDir,
+    posteriorPath: input.posteriorPath,
+  });
+  return {
+    tier: result.tier,
+    decision_log: {
+      source: 'bandit_pull_with_delegate',
+      samples: result.samples,
+      delegate: result.delegate,
+      adaptive_mode: 'full',
+    },
+  };
+}
+
+/**
+ * recordOutcome — post-spawn telemetry update. Computes a reward via
+ * computeReward (Phase 23.5 D-08, unchanged) and writes the posterior
+ * arm. Best-effort: all errors swallowed so telemetry can never break
+ * a session (D-04).
+ *
+ * No-op when adaptive_mode is not 'full' (D-07).
+ *
+ * @param {{
+ *   agent: string,
+ *   bin: string,
+ *   delegate?: string,
+ *   tier: string,
+ *   status: string,
+ *   costUsd?: number,
+ *   adaptiveMode?: 'static'|'hedge'|'full',
+ *   baseDir?: string,
+ *   posteriorPath?: string,
+ * }} input
+ * @returns {void}
+ */
+function recordOutcome(input) {
+  if (!input || typeof input !== 'object') {
+    throw new TypeError('integration.recordOutcome: input object required');
+  }
+  if (typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('integration.recordOutcome: agent (string) required');
+  }
+  if (typeof input.bin !== 'string' || input.bin.length === 0) {
+    throw new TypeError('integration.recordOutcome: bin (string) required');
+  }
+  if (typeof input.tier !== 'string' || input.tier.length === 0) {
+    throw new TypeError('integration.recordOutcome: tier (string) required');
+  }
+  if (typeof input.status !== 'string') {
+    throw new TypeError('integration.recordOutcome: status (string) required');
+  }
+
+  const adaptiveMode = resolveAdaptiveMode(input.adaptiveMode, input);
+
+  // D-07 + D-04: posterior is silent in static/hedge. No-op early.
+  if (adaptiveMode !== 'full') {
+    return undefined;
+  }
+
+  const delegate = resolveDelegate(input.delegate, 'recordOutcome');
+
+  // D-08: reward function unchanged. wall_time_ms always 0 per
+  // Phase 23.5 / 27.5 — the wall-time tiebreaker is not used at the
+  // recordOutcome boundary; correctness + cost are the only signals.
+  const reward = banditRouter.computeReward({
+    solidify_pass: input.status === 'completed',
+    cost_usd: typeof input.costUsd === 'number' ? input.costUsd : 0,
+    wall_time_ms: 0,
+  });
+
+  // D-04: best-effort write. Swallow ALL exceptions so a broken
+  // posterior file never breaks a session.
+  try {
+    if (delegate === DELEGATE_NONE) {
+      banditRouter.update({
+        agent: input.agent,
+        bin: input.bin,
+        tier: input.tier,
+        reward,
+        baseDir: input.baseDir,
+        posteriorPath: input.posteriorPath,
+      });
+    } else {
+      banditRouter.updateWithDelegate({
+        agent: input.agent,
+        bin: input.bin,
+        tier: input.tier,
+        delegate,
+        reward,
+        baseDir: input.baseDir,
+        posteriorPath: input.posteriorPath,
+      });
+    }
+  } catch (err) {
+    // Live-tail breadcrumb opt-in via env var. Inner try/catch around
+    // the stderr write itself keeps the swallow guarantee even when
+    // stderr is closed/unavailable.
+    if (process.env.GDD_BANDIT_DEBUG === '1') {
+      try {
+        process.stderr.write(
+          '[bandit-integration] recordOutcome swallowed: ' +
+            (err && err.message ? err.message : String(err)) +
+            '\n',
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+
+  return undefined;
+}
+
+module.exports = {
+  consultBandit,
+  recordOutcome,
+  DELEGATE_NONE,
+};

package/scripts/lib/cache/gdd-cache-manager.cjs

@@ -0,0 +1,292 @@
+/**
+ * scripts/lib/cache/gdd-cache-manager.cjs — Plan 27.6-03
+ *
+ * Cache-warming heuristic (Phase 10.1 cost-governance refinement,
+ * Phase 27.6 D-06): score each candidate entry as the multiplicative
+ * product of three [0,1]-normalized components — recency, frequency,
+ * cost — and warm the top-N entries per cycle.
+ *
+ * Eviction policy: LRU within the warmed set. When a new top-rank
+ * candidate arrives, it displaces the oldest-touched entry from the
+ * warmed slot (D-06 wording).
+ *
+ * Telemetry: each per-cycle decision emits a `cache.warm_decision`
+ * event via Phase 22 event-stream so the Phase 27.6-01 perf-analyzer
+ * can surface "false-positive rate exceeds threshold" proposals
+ * (D-02: 20% default; configurable via
+ * `.design/budget.json#cache_warming_falsepositive_threshold`).
+ *
+ * Pure functions + side-effects-via-appendEvent. No external deps
+ * beyond `node:` builtins and the lazy event-stream require.
+ *
+ * @module scripts/lib/cache/gdd-cache-manager
+ */
+'use strict';
+
+// `node:fs` and `node:path` are required by the contract (lazy
+// future-extension surface for budget.json reads); event-stream is
+// loaded lazily via try/catch so this library is consumable from pure
+// CommonJS runtimes that cannot strip TypeScript on the fly.
+const path = require('node:path'); // eslint-disable-line no-unused-vars
+const fs = require('node:fs');     // eslint-disable-line no-unused-vars
+
+/**
+ * Default top-N candidates warmed per cycle. Override per-call via
+ * `rankWarmCandidates({ entries, topN })` or via
+ * `.design/budget.json#cache_warm_topn` at the caller level.
+ *
+ * @type {number}
+ */
+const DEFAULT_TOPN = 10;
+
+/**
+ * Default false-positive tolerance threshold percentage (D-02).
+ * When more than this percent of warmed entries are evicted before
+ * being read in a single cycle, the heuristic emits a per-cycle
+ * `cache.warm_decision` summary event so the perf-analyzer can flag
+ * the heuristic as mis-tuned.
+ *
+ * Configurable per-call via the `falsePositiveThresholdPct` argument
+ * to `summarizeFalsePositiveRate`, or at the project level via
+ * `.design/budget.json#cache_warming_falsepositive_threshold`.
+ *
+ * @type {number}
+ */
+const DEFAULT_FALSE_POSITIVE_THRESHOLD_PCT = 20;
+
+/**
+ * Clamp a number to the [0, 1] range. Non-finite / non-numeric inputs
+ * collapse to 0 — by design, since a non-numeric component cannot
+ * meaningfully participate in the multiplicative score.
+ *
+ * @param {unknown} n
+ * @returns {number}
+ */
+function clamp01(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+/**
+ * Lazily resolve the Phase 22 event-stream `appendEvent` function.
+ * The event-stream is shipped as `index.ts` (TypeScript); under a
+ * pure-CommonJS runtime that cannot strip TS on the fly, the require
+ * will throw. We swallow that and return a no-op so this library
+ * stays usable in any caller — tests, CJS scripts, or the
+ * cache-manager slash skill — without forcing them to install a
+ * TS loader.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    // Resolved relative to this file: `scripts/lib/cache/` → `../event-stream`.
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    // Swallow — fall through to the no-op below. The event is
+    // best-effort telemetry; losing one decision is acceptable.
+  }
+  return function noopAppend(_ev) { /* event-stream unavailable */ };
+}
+
+/**
+ * Compute the multiplicative warming score for a single candidate
+ * (D-06). Each component is clamped to [0, 1] before multiplication;
+ * any zero component zeroes the entire score by design — all three
+ * dimensions (recency, frequency, cost) must be non-zero for an
+ * entry to be a warm candidate at all.
+ *
+ * @param {{recency_score:number, frequency_score:number, cost_score:number}} components
+ * @returns {number} score in [0, 1]
+ */
+function computeWarmingScore({ recency_score, frequency_score, cost_score } = {}) {
+  const r = clamp01(recency_score);
+  const f = clamp01(frequency_score);
+  const c = clamp01(cost_score);
+  return r * f * c;
+}
+
+/**
+ * Rank a list of cache candidates by multiplicative warming score and
+ * return the top-N as the warmed set, with the remainder as eviction
+ * candidates. Pure: no I/O, no event emission.
+ *
+ * Component normalization:
+ *   recency_score   = 1 / (1 + days_since_last_use)
+ *   frequency_score = uses_in_window / window_size              (clamped)
+ *   cost_score      = est_cost_usd / max(est_cost_usd)          (clamped)
+ *
+ * If all entries have `est_cost_usd === 0`, all cost_scores collapse
+ * to 0 (and therefore all final scores collapse to 0) — the heuristic
+ * never warms cost-free entries, by design.
+ *
+ * Eviction policy: entries beyond the top-N rank are returned in
+ * `evictionCandidates`. The caller (cache-manager skill) treats the
+ * warmed set as LRU internally — when a new entry beats an existing
+ * warmed entry, the LRU entry in the warmed set is the one displaced.
+ *
+ * @param {{
+ *   entries?: Array<{
+ *     key: string,
+ *     days_since_last_use?: number,
+ *     uses_in_window?: number,
+ *     window_size?: number,
+ *     est_cost_usd?: number,
+ *     last_touched_at?: string,
+ *   }>,
+ *   topN?: number,
+ * }} args
+ * @returns {{warmed: Array<object>, evictionCandidates: Array<object>}}
+ */
+function rankWarmCandidates({ entries, topN } = {}) {
+  const N = typeof topN === 'number' && topN > 0 ? Math.floor(topN) : DEFAULT_TOPN;
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length === 0) return { warmed: [], evictionCandidates: [] };
+
+  // Determine the per-cycle max cost for normalization. If everything
+  // is free, the cost dimension contributes 0 to every score (which
+  // zeroes the multiplicative product — that's intentional).
+  let maxCost = 0;
+  for (const e of list) {
+    const c = typeof e.est_cost_usd === 'number' && e.est_cost_usd > 0 ? e.est_cost_usd : 0;
+    if (c > maxCost) maxCost = c;
+  }
+
+  const scored = list.map((e) => {
+    const days = typeof e.days_since_last_use === 'number' && e.days_since_last_use >= 0
+      ? e.days_since_last_use
+      : Infinity;
+    const recency_score = days === Infinity ? 0 : 1 / (1 + days);
+
+    const usesIn = typeof e.uses_in_window === 'number' && e.uses_in_window >= 0
+      ? e.uses_in_window
+      : 0;
+    const win = typeof e.window_size === 'number' && e.window_size > 0
+      ? e.window_size
+      : 1;
+    const frequency_score = clamp01(usesIn / win);
+
+    const cost = typeof e.est_cost_usd === 'number' && e.est_cost_usd >= 0
+      ? e.est_cost_usd
+      : 0;
+    const cost_score = maxCost > 0 ? clamp01(cost / maxCost) : 0;
+
+    const score = computeWarmingScore({ recency_score, frequency_score, cost_score });
+    return { ...e, recency_score, frequency_score, cost_score, score };
+  });
+
+  // Sort by score descending. Stable order on ties is fine for v1.
+  scored.sort((a, b) => b.score - a.score);
+
+  const warmed = scored.slice(0, N);
+  const evictionCandidates = scored.slice(N);
+  return { warmed, evictionCandidates };
+}
+
+/**
+ * Emit one `cache.warm_decision` event recording the outcome of a
+ * single warmed entry: was it used before being evicted, or did the
+ * heuristic mis-warm (false-positive)?
+ *
+ * Called per warmed entry at eviction time by the cache layer. The
+ * 27.6-01 perf-analyzer aggregates these to compute per-cycle
+ * false-positive rates.
+ *
+ * Side effect only — returns void. The function is best-effort:
+ * if the event-stream is unavailable, the emission silently no-ops.
+ *
+ * @param {{
+ *   entry: {key:string, score:number, recency_score:number, frequency_score:number, cost_score:number},
+ *   usedBeforeEviction: boolean,
+ *   evictionEvent?: {at?: string, reason?: string},
+ *   sessionId?: string,
+ * }} args
+ * @returns {void}
+ */
+function evaluateWarmingDecision({ entry, usedBeforeEviction, evictionEvent, sessionId } = {}) {
+  const append = getAppendEvent();
+  const e = entry && typeof entry === 'object' ? entry : {};
+  append({
+    type: 'cache.warm_decision',
+    timestamp: new Date().toISOString(),
+    sessionId: typeof sessionId === 'string' && sessionId.length > 0
+      ? sessionId
+      : 'cache-manager',
+    payload: {
+      entry_key: typeof e.key === 'string' ? e.key : 'unknown',
+      score: typeof e.score === 'number' ? e.score : 0,
+      recency_score: typeof e.recency_score === 'number' ? e.recency_score : 0,
+      frequency_score: typeof e.frequency_score === 'number' ? e.frequency_score : 0,
+      cost_score: typeof e.cost_score === 'number' ? e.cost_score : 0,
+      used_before_eviction: !!usedBeforeEviction,
+      evicted_at: evictionEvent && typeof evictionEvent.at === 'string'
+        ? evictionEvent.at
+        : undefined,
+    },
+  });
+}
+
+/**
+ * Aggregate a cycle's worth of per-entry decisions into a single
+ * false-positive rate. If the rate exceeds the configured threshold
+ * (D-02 default 20%), emit a per-cycle summary `cache.warm_decision`
+ * event so the perf-analyzer can flag the heuristic as mis-tuned.
+ *
+ * Returns the computed rate + threshold context regardless of whether
+ * an event was emitted, so the caller can route the result into its
+ * own reporting surface (e.g. the cache-manager slash skill's status
+ * output).
+ *
+ * @param {{
+ *   decisions?: Array<{entry_key?:string, used_before_eviction?:boolean, score?:number}>,
+ *   falsePositiveThresholdPct?: number,
+ *   sessionId?: string,
+ * }} args
+ * @returns {{false_positive_rate:number, count:number, threshold_pct:number, exceeds_threshold:boolean}}
+ */
+function summarizeFalsePositiveRate({ decisions, falsePositiveThresholdPct, sessionId } = {}) {
+  const list = Array.isArray(decisions) ? decisions : [];
+  const total = list.length;
+  let evictedUnused = 0;
+  for (const d of list) {
+    if (d && d.used_before_eviction === false) evictedUnused++;
+  }
+  const false_positive_rate = total === 0 ? 0 : evictedUnused / total;
+  const threshold_pct = typeof falsePositiveThresholdPct === 'number' && Number.isFinite(falsePositiveThresholdPct)
+    ? falsePositiveThresholdPct
+    : DEFAULT_FALSE_POSITIVE_THRESHOLD_PCT;
+  const exceeds_threshold = false_positive_rate * 100 > threshold_pct;
+
+  if (exceeds_threshold) {
+    const append = getAppendEvent();
+    append({
+      type: 'cache.warm_decision',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0
+        ? sessionId
+        : 'cache-manager',
+      payload: {
+        entry_key: '<cycle-summary>',
+        score: 0,
+        recency_score: 0,
+        frequency_score: 0,
+        cost_score: 0,
+        false_positive_rate,
+      },
+    });
+  }
+
+  return { false_positive_rate, count: total, threshold_pct, exceeds_threshold };
+}
+
+module.exports = {
+  computeWarmingScore,
+  rankWarmCandidates,
+  evaluateWarmingDecision,
+  summarizeFalsePositiveRate,
+  DEFAULT_TOPN,
+  DEFAULT_FALSE_POSITIVE_THRESHOLD_PCT,
+};

package/scripts/lib/discuss-parallel-runner/index.ts

@@ -29,6 +29,7 @@
 
 import { OperationFailedError } from '../gdd-errors/index.ts';
 import { getLogger } from '../logger/index.ts';
+import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
 
 import {
   spawnAggregator,
@@ -137,9 +138,12 @@ export async function run(
 ): Promise<DiscussRunnerResult> {
   const logger = getLogger();
   const specs = opts.discussants ?? DEFAULT_DISCUSSANTS;
+  // Phase 27.6 D-07: data-driven concurrency default. Falls back to
+  // min(cpu-1, 8) when no `parallelism.verdict` events exist in
+  // .design/telemetry/events.jsonl. Explicit `opts.concurrency` still wins.
   const concurrency = opts.concurrency !== undefined && opts.concurrency > 0
     ? opts.concurrency
-    : 4;
+    : resolveConcurrency();
   const cwd = opts.cwd ?? process.cwd();
 
   logger.info('discuss.runner.started', {

package/scripts/lib/explore-parallel-runner/index.ts

@@ -25,6 +25,7 @@
 import { resolve as resolvePath } from 'node:path';
 
 import { getLogger } from '../logger/index.ts';
+import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
 
 import {
   isParallelismSafe,
@@ -120,7 +121,10 @@ export async function run(
 ): Promise<ExploreRunnerResult> {
   const specs: readonly MapperSpec[] = opts.mappers ?? DEFAULT_MAPPERS;
   const cwd: string = opts.cwd ?? process.cwd();
-  const concurrency: number = opts.concurrency ?? 4;
+  // Phase 27.6 D-07: data-driven concurrency default. Falls back to
+  // min(cpu-1, 8) when no `parallelism.verdict` events exist in
+  // .design/telemetry/events.jsonl. Explicit `opts.concurrency` still wins.
+  const concurrency: number = opts.concurrency ?? resolveConcurrency();
 
   const logger = getLogger().child('explore.runner');