@hegemonart/get-design-done 1.19.6 → 1.21.0

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

@@ -0,0 +1,184 @@
+// scripts/lib/discuss-parallel-runner/types.ts — Plan 21-07 (SDK-19).
+//
+// Public type surface for the parallel discussion runner. The runner
+// spawns N design-discussant variants (each a different persona / angle
+// — user-journey, technical-constraint, brand-fit, accessibility)
+// concurrently via `session-runner`, collects each discussant's open
+// questions and concerns as a structured `DiscussionContribution`, and
+// runs an aggregator pass that deduplicates, clusters by theme, and
+// surfaces a single ranked question list for the user.
+//
+// Consumers: the `discuss` skill (standalone leaf) and the `gdd-sdk
+// discuss` CLI subcommand (Plan 21-09).
+//
+// Design invariants (see PLAN.md Context):
+//   * Discussant sessions are independent — none write to shared files;
+//     parallelism is always safe.
+//   * The aggregator runs AFTER all discussants complete.
+//   * Error isolation: one discussant's failure never cascades into
+//     other discussant sessions.
+//   * `AggregatedQuestion.key` is SHA-256-based (stable across runs)
+//     per the aggregator prompt contract.
+
+import type {
+  BudgetCap,
+  SessionResult,
+  SessionRunnerOptions,
+} from '../session-runner/types.ts';
+
+/**
+ * Named discussant variants. The default roster is the four values in
+ * the union below, but callers can pass any string (arbitrary custom
+ * discussant).
+ */
+export type DiscussantName =
+  | 'user-journey'
+  | 'technical-constraint'
+  | 'brand-fit'
+  | 'accessibility'
+  | string;
+
+/** Severity ordering is blocker > major > minor > nice-to-have. */
+export type Severity = 'blocker' | 'major' | 'minor' | 'nice-to-have';
+
+/**
+ * One discussant specification. The runner passes `prompt` verbatim
+ * through `session-runner.run()` as the prompt body.
+ *
+ * `agentPath` is optional; when absent, the runner defaults to the
+ * stage scope from tool-scoping (`discuss` maps to `custom` — see
+ * Plan 21-03). When present, the runner reads the agent markdown's
+ * `tools:` frontmatter via `parseAgentToolsByName` and passes the
+ * resolved list as `allowedTools`.
+ */
+export interface DiscussantSpec {
+  name: DiscussantName;
+  /** Optional agent frontmatter path; missing → stage scope from tool-scoping. */
+  agentPath?: string;
+  /** Per-discussant prompt body. */
+  prompt: string;
+}
+
+/**
+ * One parsed item from a discussant's DISCUSSION COMPLETE block.
+ *
+ * `kind` discriminates questions (things the discussant wants
+ * answered) from concerns (things they want to flag).
+ *
+ * `tag` captures the per-item annotation from the discussant output
+ * (`Concern: <stakeholder>` for questions, `Area: <scope>` for
+ * concerns). Optional because lenient parse allows missing.
+ */
+export interface DiscussionItem {
+  kind: 'question' | 'concern';
+  text: string;
+  /** Area / angle / concern tag per discussant output. */
+  tag?: string;
+  severity: Severity;
+  rationale?: string;
+}
+
+/**
+ * One discussant's complete contribution. `items` is empty when the
+ * session errored or the block was missing/malformed.
+ *
+ * `status`:
+ *   * `completed`    — session ended cleanly AND a DISCUSSION COMPLETE
+ *                      block was parsed successfully.
+ *   * `parse-error`  — session ended cleanly but the block was absent
+ *                      or malformed (items: []).
+ *   * `error`        — session failed (budget, turn cap, aborted, error);
+ *                      `error` populated; items: [].
+ */
+export interface DiscussionContribution {
+  discussant: DiscussantName;
+  items: readonly DiscussionItem[];
+  /** Raw final_text captured for audit / aggregator input. */
+  raw: string;
+  usage: { input_tokens: number; output_tokens: number; usd_cost: number };
+  status: 'completed' | 'error' | 'parse-error';
+  error?: { code: string; message: string };
+}
+
+/**
+ * One aggregated (post-dedup, post-cluster) question.
+ *
+ *   * `key`      — SHA-256 of the normalized question text (lowercase,
+ *                  whitespace-collapsed) truncated to 8 hex chars.
+ *                  Stable across runs.
+ *   * `raised_by` — discussants that raised (a semantic variant of)
+ *                   this question.
+ *   * `theme`    — cluster/theme name from aggregator.
+ *   * `rank`     — 0-indexed priority (0 = highest). Ranking combines
+ *                  severity + frequency per the aggregator prompt.
+ */
+export interface AggregatedQuestion {
+  /** Stable key across runs (hash of normalized question text). */
+  key: string;
+  text: string;
+  severity: Severity;
+  /** Discussants that raised this question. */
+  raised_by: readonly DiscussantName[];
+  /** Cluster/theme assignment from aggregator. */
+  theme: string;
+  /** Aggregator-assigned rank (0 = highest priority). */
+  rank: number;
+}
+
+/**
+ * The aggregator's final output. `output_path` is the Markdown file
+ * written to disk (`.design/DISCUSSION.md` by default). `usage` is
+ * the aggregator session's token/cost spend — separate from the
+ * per-discussant usage aggregated in `DiscussRunnerResult.total_usage`.
+ */
+export interface AggregatedDiscussion {
+  themes: readonly { name: string; summary: string }[];
+  questions: readonly AggregatedQuestion[];
+  /** Output path. */
+  output_path: string;
+  /** Aggregator session usage. */
+  usage: { input_tokens: number; output_tokens: number; usd_cost: number };
+}
+
+/**
+ * Options for `run()` — the top-level orchestrator entry point.
+ *
+ *   * `discussants` — omit to use `DEFAULT_DISCUSSANTS` (4 variants).
+ *   * `budget` + `maxTurnsPerDiscussant` — applied per-discussant.
+ *   * `aggregatorBudget` + `aggregatorMaxTurns` — applied to the
+ *     aggregator session specifically.
+ *   * `concurrency` — defaults to 4 (matches the default roster size).
+ *   * `runOverride` — test injection for `session-runner.run()`. All
+ *     discussants AND the aggregator receive the SAME override so one
+ *     mock controls the entire run.
+ *   * `aggregatorPrompt` — replace the default aggregator prompt
+ *     (advanced / debug use).
+ */
+export interface DiscussRunnerOptions {
+  /** Discussants to run. Default: the 4-variant roster. */
+  discussants?: readonly DiscussantSpec[];
+  budget: BudgetCap;
+  maxTurnsPerDiscussant: number;
+  aggregatorBudget: BudgetCap;
+  aggregatorMaxTurns: number;
+  concurrency?: number;
+  runOverride?: (opts: SessionRunnerOptions) => Promise<SessionResult>;
+  cwd?: string;
+  /** Custom aggregator prompt override. */
+  aggregatorPrompt?: string;
+}
+
+/**
+ * The final return value from `run()`.
+ *
+ *   * `contributions` — one per discussant, in input spec order (NOT
+ *     completion order). Failed discussants are included with
+ *     `status !== 'completed'`.
+ *   * `aggregated` — the aggregator's parsed output.
+ *   * `total_usage` — sum of per-discussant + aggregator usage.
+ */
+export interface DiscussRunnerResult {
+  contributions: readonly DiscussionContribution[];
+  aggregated: AggregatedDiscussion;
+  total_usage: { input_tokens: number; output_tokens: number; usd_cost: number };
+}

package/scripts/lib/error-classifier.cjs

@@ -0,0 +1,232 @@
+// scripts/lib/error-classifier.cjs
+//
+// Plan 20-14 — classify raw errors into a recovery-action vocabulary.
+//
+// Plan 20-04 shipped the GDDError taxonomy (ValidationError /
+// StateConflictError / OperationFailedError). This module is one layer
+// lower: it maps LOW-LEVEL errors (fetch rejections, Anthropic API
+// responses, Node errno rejections) onto a small enum that recovery
+// code can switch on without needing to know which SDK produced the
+// error.
+//
+// Consumers (e.g. budget-enforcer retry, figma probe retry, MCP
+// transport) check `classify(err).reason` and decide whether to retry,
+// compress, surface, or fail.
+//
+// Classification rules — evaluated in order; first match wins:
+//   1. HTTP 429  OR  message ~ /rate.?limit/       → RATE_LIMITED      (retryable)
+//   2. HTTP 413  OR  /context.?(length|window|overflow)/
+//                OR  /context_length_exceeded/     → CONTEXT_OVERFLOW  (retryable with compression)
+//   3. HTTP 401/403                                → AUTH_ERROR        (NOT retryable)
+//   4. /tool not found|unknown tool/               → TOOL_NOT_FOUND    (NOT retryable)
+//   5. HTTP 5xx  OR  errno ECONNRESET/ETIMEDOUT/EAI_AGAIN/ECONNREFUSED
+//                OR  /network|timeout|socket/       → NETWORK_TRANSIENT (retryable)
+//   6. HTTP 4xx (non-auth, non-rate, non-overflow) → VALIDATION        (NOT retryable)
+//   7. HTTP >= 400 with no other match             → NETWORK_PERMANENT (NOT retryable)
+//   8. Anything else (null, undefined, plain Error) → UNKNOWN          (NOT retryable)
+//
+// Rule order matters: the tool-not-found string can land inside
+// otherwise-validation-shaped errors, so it's checked early. Anthropic
+// "context_length_exceeded" returns HTTP 400 in some surfaces and HTTP
+// 413 in others — rule 2 catches it either way.
+//
+// Reference: `reference/error-recovery.md` describes the protocol layer
+// that sits on top of this module.
+
+'use strict';
+
+/**
+ * @readonly
+ * @enum {string}
+ */
+const FailoverReason = Object.freeze({
+  RATE_LIMITED: 'rate_limited',
+  CONTEXT_OVERFLOW: 'context_overflow',
+  AUTH_ERROR: 'auth_error',
+  NETWORK_TRANSIENT: 'network_transient',
+  NETWORK_PERMANENT: 'network_permanent',
+  TOOL_NOT_FOUND: 'tool_not_found',
+  VALIDATION: 'validation',
+  UNKNOWN: 'unknown',
+});
+
+/** Suggested actions per reason — keyed by FailoverReason. */
+const SUGGESTED_ACTIONS = Object.freeze({
+  [FailoverReason.RATE_LIMITED]:
+    'consult scripts/lib/rate-guard.cjs → blockUntilReady(provider); then retry with scripts/lib/jittered-backoff.cjs',
+  [FailoverReason.CONTEXT_OVERFLOW]:
+    'compress context (drop oldest non-system turns; target 50% reduction) and retry once',
+  [FailoverReason.AUTH_ERROR]:
+    'surface to user — do not retry; credentials or OAuth session need refresh',
+  [FailoverReason.NETWORK_TRANSIENT]:
+    'retry with scripts/lib/jittered-backoff.cjs; max 3 attempts',
+  [FailoverReason.NETWORK_PERMANENT]:
+    'surface to user; do not retry — endpoint is wrong or resource is gone',
+  [FailoverReason.TOOL_NOT_FOUND]:
+    'do not retry; verify tool name and MCP registration',
+  [FailoverReason.VALIDATION]:
+    'do not retry same input; surface validation detail to caller',
+  [FailoverReason.UNKNOWN]:
+    'surface to user — cannot determine safe recovery action',
+});
+
+/** Which reasons are safe to retry by policy. */
+const RETRYABLE = Object.freeze({
+  [FailoverReason.RATE_LIMITED]: true,
+  [FailoverReason.CONTEXT_OVERFLOW]: true,
+  [FailoverReason.NETWORK_TRANSIENT]: true,
+  [FailoverReason.AUTH_ERROR]: false,
+  [FailoverReason.NETWORK_PERMANENT]: false,
+  [FailoverReason.TOOL_NOT_FOUND]: false,
+  [FailoverReason.VALIDATION]: false,
+  [FailoverReason.UNKNOWN]: false,
+});
+
+/** Extract a numeric HTTP status from an error shape. Returns null on miss. */
+function statusOf(err) {
+  if (err === null || err === undefined) return null;
+  if (typeof err !== 'object') return null;
+  // Direct status / statusCode field.
+  if (Number.isFinite(err.status)) return Number(err.status);
+  if (Number.isFinite(err.statusCode)) return Number(err.statusCode);
+  // Fetch / node-fetch responses wrap status under .response.
+  if (err.response && typeof err.response === 'object') {
+    if (Number.isFinite(err.response.status)) return Number(err.response.status);
+    if (Number.isFinite(err.response.statusCode)) return Number(err.response.statusCode);
+  }
+  return null;
+}
+
+/** Extract a string message; tolerant of anything. */
+function messageOf(err) {
+  if (err === null || err === undefined) return '';
+  if (typeof err === 'string') return err;
+  if (typeof err === 'object') {
+    // Gather every string-ish field in priority order; join with ' | ' so
+    // classification regexes can match against any of them without the
+    // caller needing to know which SDK shaped the error. OpenAI-style
+    // wraps the interesting discriminator in `error.code` while keeping
+    // a generic top-level message; the join lets both contribute.
+    const parts = [];
+    if (typeof err.message === 'string' && err.message.length > 0) parts.push(err.message);
+    if (err.error && typeof err.error === 'object') {
+      if (typeof err.error.code === 'string') parts.push(err.error.code);
+      if (typeof err.error.type === 'string') parts.push(err.error.type);
+      if (typeof err.error.message === 'string') parts.push(err.error.message);
+    }
+    // Only use top-level `code` when it is NOT an errno (errnoOf handles
+    // those). Errnos always match /^E[A-Z0-9_]+$/, so filter them out.
+    if (typeof err.code === 'string' && !/^E[A-Z0-9_]+$/.test(err.code)) {
+      parts.push(err.code);
+    }
+    if (parts.length > 0) return parts.join(' | ');
+  }
+  return '';
+}
+
+/** Extract a low-level errno code (ECONNRESET, ETIMEDOUT, ...). */
+function errnoOf(err) {
+  if (err === null || err === undefined || typeof err !== 'object') return '';
+  if (typeof err.code === 'string' && /^E[A-Z0-9_]+$/.test(err.code)) return err.code;
+  // fetch native in newer Node wraps the cause
+  if (err.cause && typeof err.cause === 'object') {
+    const code = err.cause.code;
+    if (typeof code === 'string' && /^E[A-Z0-9_]+$/.test(code)) return code;
+  }
+  return '';
+}
+
+/**
+ * Classify a raw error into a {@link FailoverReason}.
+ *
+ * @param {unknown} err
+ * @returns {{reason: string, retryable: boolean, suggestedAction: string, raw: unknown}}
+ */
+function classify(err) {
+  const status = statusOf(err);
+  const message = messageOf(err).toLowerCase();
+  const errno = errnoOf(err);
+
+  // 1. Rate limit.
+  if (status === 429 || /rate.?limit/.test(message) || /too many requests/.test(message)) {
+    return build(FailoverReason.RATE_LIMITED, err);
+  }
+
+  // 2. Context overflow. Anthropic returns 400 with type=invalid_request and
+  //    message containing "prompt is too long"; OpenAI returns 400 with
+  //    code=context_length_exceeded; some edge surfaces use 413.
+  if (
+    status === 413 ||
+    /context_length_exceeded/.test(message) ||
+    /context.{0,10}(length|window|overflow|too.?long)/.test(message) ||
+    /prompt is too long/.test(message) ||
+    /maximum context length/.test(message)
+  ) {
+    return build(FailoverReason.CONTEXT_OVERFLOW, err);
+  }
+
+  // 3. Auth.
+  if (status === 401 || status === 403) {
+    return build(FailoverReason.AUTH_ERROR, err);
+  }
+  if (
+    /not authenticated/.test(message) ||
+    /invalid[_ ]api[_ ]key/.test(message) ||
+    /unauthorized/.test(message) ||
+    /authentication/.test(message)
+  ) {
+    return build(FailoverReason.AUTH_ERROR, err);
+  }
+
+  // 4. Tool not found.
+  if (/tool not found/.test(message) || /unknown tool/.test(message) || /no such tool/.test(message)) {
+    return build(FailoverReason.TOOL_NOT_FOUND, err);
+  }
+
+  // 5. Network transient: 5xx or low-level errno.
+  if (typeof status === 'number' && status >= 500 && status < 600) {
+    return build(FailoverReason.NETWORK_TRANSIENT, err);
+  }
+  if (
+    errno === 'ECONNRESET' ||
+    errno === 'ETIMEDOUT' ||
+    errno === 'EAI_AGAIN' ||
+    errno === 'ECONNREFUSED' ||
+    errno === 'ENETUNREACH' ||
+    errno === 'EPIPE'
+  ) {
+    return build(FailoverReason.NETWORK_TRANSIENT, err);
+  }
+  if (/\bsocket\b/.test(message) || /network/.test(message) || /\btimeout\b/.test(message)) {
+    return build(FailoverReason.NETWORK_TRANSIENT, err);
+  }
+
+  // 6. Other 4xx → validation.
+  if (typeof status === 'number' && status >= 400 && status < 500) {
+    return build(FailoverReason.VALIDATION, err);
+  }
+
+  // 7. Other >= 400 (e.g. 6xx exotic gateway codes).
+  if (typeof status === 'number' && status >= 400) {
+    return build(FailoverReason.NETWORK_PERMANENT, err);
+  }
+
+  // 8. Fallthrough.
+  return build(FailoverReason.UNKNOWN, err);
+}
+
+function build(reason, raw) {
+  return {
+    reason,
+    retryable: RETRYABLE[reason] === true,
+    suggestedAction: SUGGESTED_ACTIONS[reason],
+    raw,
+  };
+}
+
+module.exports = {
+  FailoverReason,
+  classify,
+  SUGGESTED_ACTIONS,
+  RETRYABLE,
+};

package/scripts/lib/error-classifier.d.cts

@@ -0,0 +1,44 @@
+// scripts/lib/error-classifier.d.cts — types for error-classifier.cjs.
+
+/** Recovery-action categories. Values are stable strings — safe to log. */
+export type FailoverReasonValue =
+  | 'rate_limited'
+  | 'context_overflow'
+  | 'auth_error'
+  | 'network_transient'
+  | 'network_permanent'
+  | 'tool_not_found'
+  | 'validation'
+  | 'unknown';
+
+/** String-constant map of FailoverReason names to values. */
+export const FailoverReason: {
+  readonly RATE_LIMITED: 'rate_limited';
+  readonly CONTEXT_OVERFLOW: 'context_overflow';
+  readonly AUTH_ERROR: 'auth_error';
+  readonly NETWORK_TRANSIENT: 'network_transient';
+  readonly NETWORK_PERMANENT: 'network_permanent';
+  readonly TOOL_NOT_FOUND: 'tool_not_found';
+  readonly VALIDATION: 'validation';
+  readonly UNKNOWN: 'unknown';
+};
+
+/** Result of {@link classify}. */
+export interface ClassifiedError {
+  reason: FailoverReasonValue;
+  retryable: boolean;
+  suggestedAction: string;
+  raw: unknown;
+}
+
+/**
+ * Map a raw error value onto a stable recovery-action category.
+ * Tolerant of null/undefined/non-Error inputs.
+ */
+export function classify(err: unknown): ClassifiedError;
+
+/** Keyed suggested-action strings (read-only). */
+export const SUGGESTED_ACTIONS: Readonly<Record<FailoverReasonValue, string>>;
+
+/** Which reasons are considered safe to retry by policy. */
+export const RETRYABLE: Readonly<Record<FailoverReasonValue, boolean>>;

package/scripts/lib/event-stream/emitter.ts

@@ -0,0 +1,88 @@
+// scripts/lib/event-stream/emitter.ts — in-process pub-sub for Phase 20+
+// telemetry events (Plan 20-06, SDK-08).
+//
+// Thin wrapper around Node's built-in `EventEmitter`. Two additions over
+// the raw primitive:
+//
+//   1. `subscribe(type, handler)` returns an unsubscribe closure — the
+//      standard `on()` / `off()` dance is easy to forget, and our
+//      subscribers (hook consumers, Phase 22 transports) need tidy
+//      lifecycle management.
+//
+//   2. `subscribeAll(handler)` lets observability infra (dashboard,
+//      log transport) see every event without enumerating known types.
+//      We re-emit on a dedicated `'*'` channel so listeners on that
+//      channel observe every `emit()`.
+//
+// Replay semantics:
+//   The bus is live-only. Subscribing does NOT deliver historical
+//   events from `events.jsonl` — that's a Phase 22 transport concern.
+
+import { EventEmitter } from 'node:events';
+
+import type { BaseEvent } from './types.ts';
+
+/**
+ * Default max listeners raised above Node's 10-listener default. Mapper
+ * parallelism + multiple hook consumers + a dashboard transport can
+ * easily stack above 10; 50 is conservative headroom before Node warns.
+ */
+export const DEFAULT_MAX_LISTENERS = 50;
+
+/**
+ * Typed handler for a specific event subtype. `T extends BaseEvent`
+ * means callers can narrow via `subscribe<StateMutationEvent>(…)` and
+ * the handler sees the narrowed shape.
+ */
+export type EventHandler<T extends BaseEvent = BaseEvent> = (ev: T) => void;
+
+/** Unsubscribe closure returned from `subscribe` / `subscribeAll`. */
+export type Unsubscribe = () => void;
+
+/**
+ * In-process event bus. Extends `EventEmitter` so raw consumers can
+ * still call `on()` / `off()` if they need Node-native semantics, but
+ * prefer `subscribe` / `subscribeAll` for ergonomic cleanup.
+ */
+export class EventBus extends EventEmitter {
+  constructor() {
+    super();
+    this.setMaxListeners(DEFAULT_MAX_LISTENERS);
+  }
+
+  /**
+   * Subscribe to one specific event type. The handler fires for every
+   * subsequent `emit(type, ev)` call where `ev.type === type`. Returns
+   * a closure that detaches the listener on invocation.
+   *
+   * @example
+   * const off = bus.subscribe<StateMutationEvent>('state.mutation', (ev) => {
+   *   console.log(ev.payload.tool);
+   * });
+   * // …later
+   * off();
+   */
+  subscribe<T extends BaseEvent = BaseEvent>(
+    type: T['type'],
+    handler: EventHandler<T>,
+  ): Unsubscribe {
+    const listener = handler as unknown as (...args: unknown[]) => void;
+    this.on(type, listener);
+    return () => {
+      this.off(type, listener);
+    };
+  }
+
+  /**
+   * Subscribe to *every* event regardless of type. Listeners registered
+   * here fire on the special `'*'` channel, which `appendEvent()`
+   * re-emits to on every event. Returns an unsubscribe closure.
+   */
+  subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
+    const listener = handler as unknown as (...args: unknown[]) => void;
+    this.on('*', listener);
+    return () => {
+      this.off('*', listener);
+    };
+  }
+}