@hegemonart/get-design-done 1.20.0 → 1.22.0

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

@@ -0,0 +1,430 @@
+// scripts/lib/discuss-parallel-runner/discussants.ts — Plan 21-07 (SDK-19).
+//
+// Discussant dispatch + DISCUSSION COMPLETE block parser.
+//
+// Public surface:
+//   * spawnDiscussant        — one session per spec, parses final_text
+//                              into DiscussionItem[].
+//   * spawnDiscussantsParallel — N sessions with semaphore concurrency.
+//   * parseDiscussionBlock    — pure parser for the DISCUSSION COMPLETE
+//                               block (used standalone + by spawnDiscussant).
+//
+// Block grammar (lenient, regex-based — no YAML dep):
+//
+//   ## DISCUSSION COMPLETE
+//
+//   ### Questions
+//   - Q: <text>
+//     Concern: <stakeholder>
+//     Severity: <blocker|major|minor|nice-to-have>
+//     Rationale: <one sentence>
+//
+//   ### Concerns
+//   - C: <text>
+//     Area: <scope>
+//     Severity: <...>
+//
+// Parse rules:
+//   * DISCUSSION COMPLETE heading match is case-insensitive.
+//   * Items start with `- Q:` or `- C:`.
+//   * Field lines (Concern/Area/Severity/Rationale) continue until the
+//     next `- Q:`/`- C:` item or the next heading.
+//   * Severity normalization:
+//       blocker / critical                 → 'blocker'
+//       major / high                       → 'major'
+//       minor / low                        → 'minor'
+//       nice-to-have / nice to have / nth  → 'nice-to-have'
+//       unknown / missing                  → 'minor' (default)
+//   * Empty `- Q:` / `- C:` (no text after the colon) is skipped with
+//     a logger warn.
+
+import { run as defaultRun } from '../session-runner/index.ts';
+import type {
+  BudgetCap,
+  SessionResult,
+  SessionRunnerOptions,
+} from '../session-runner/types.ts';
+import { getLogger } from '../logger/index.ts';
+import { parseAgentTools } from '../tool-scoping/parse-agent-tools.ts';
+import type {
+  DiscussantSpec,
+  DiscussionContribution,
+  DiscussionItem,
+  Severity,
+} from './types.ts';
+
+/** Shared run-override shape consumed by both spawn* functions. */
+export type DiscussantRunOverride = (
+  opts: SessionRunnerOptions,
+) => Promise<SessionResult>;
+
+/** Options for `spawnDiscussant`. */
+export interface SpawnDiscussantOptions {
+  budget: BudgetCap;
+  maxTurns: number;
+  runOverride?: DiscussantRunOverride;
+  cwd: string;
+}
+
+/** Options for `spawnDiscussantsParallel`. */
+export interface SpawnDiscussantsParallelOptions {
+  concurrency: number;
+  budget: BudgetCap;
+  maxTurns: number;
+  runOverride?: DiscussantRunOverride;
+  cwd: string;
+}
+
+// ---------------------------------------------------------------------------
+// spawnDiscussant
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn one discussant session via `session-runner.run()`. Parses the
+ * DISCUSSION COMPLETE block from `session.final_text` into
+ * `DiscussionItem[]`. Parse failures surface as `status: 'parse-error'`
+ * with `raw` preserved. Session failures surface as `status: 'error'`
+ * with `error` populated and `items: []`.
+ *
+ * NEVER throws — every failure mode becomes a typed Contribution.
+ */
+export async function spawnDiscussant(
+  spec: DiscussantSpec,
+  opts: SpawnDiscussantOptions,
+): Promise<DiscussionContribution> {
+  const logger = getLogger();
+  const runImpl = opts.runOverride ?? defaultRun;
+
+  // Resolve per-discussant allowedTools from agent frontmatter (if any).
+  // `undefined` = stage default; empty list = MCP-only.
+  let allowedTools: readonly string[] | undefined;
+  if (spec.agentPath !== undefined && spec.agentPath !== '') {
+    const parsed = parseAgentTools(spec.agentPath);
+    // parseAgentTools returns null when the file is missing or the
+    // frontmatter is absent — we treat null the same as undefined
+    // (no override → stage default).
+    if (parsed !== null) {
+      allowedTools = parsed;
+    }
+  }
+
+  const sessionOpts: SessionRunnerOptions = {
+    prompt: spec.prompt,
+    stage: 'custom',
+    budget: opts.budget,
+    turnCap: { maxTurns: opts.maxTurns },
+  };
+  if (allowedTools !== undefined) {
+    sessionOpts.allowedTools = [...allowedTools];
+  }
+
+  logger.info('discuss.discussant.started', {
+    discussant: spec.name,
+    cwd: opts.cwd,
+  });
+
+  const result = await runImpl(sessionOpts);
+
+  // Session-level failures (budget, turn cap, aborted, error) all
+  // surface as status: 'error'. Items stay empty.
+  if (result.status !== 'completed') {
+    const contribution: DiscussionContribution = {
+      discussant: spec.name,
+      items: Object.freeze([]),
+      raw: result.final_text ?? '',
+      usage: { ...result.usage },
+      status: 'error',
+    };
+    if (result.error !== undefined) {
+      contribution.error = {
+        code: result.error.code,
+        message: result.error.message,
+      };
+    } else {
+      contribution.error = {
+        code: 'SESSION_FAILED',
+        message: `session ended with status: ${result.status}`,
+      };
+    }
+    logger.warn('discuss.discussant.error', {
+      discussant: spec.name,
+      status: result.status,
+      code: contribution.error.code,
+    });
+    return contribution;
+  }
+
+  const raw = result.final_text ?? '';
+  const parsed = parseDiscussionBlock(raw);
+
+  if (parsed === null) {
+    logger.warn('discuss.discussant.parse_error', {
+      discussant: spec.name,
+      reason: 'missing or malformed DISCUSSION COMPLETE block',
+    });
+    return {
+      discussant: spec.name,
+      items: Object.freeze([]),
+      raw,
+      usage: { ...result.usage },
+      status: 'parse-error',
+    };
+  }
+
+  logger.info('discuss.discussant.completed', {
+    discussant: spec.name,
+    items: parsed.length,
+  });
+
+  return {
+    discussant: spec.name,
+    items: parsed,
+    raw,
+    usage: { ...result.usage },
+    status: 'completed',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// spawnDiscussantsParallel
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn N discussants with a semaphore bounding concurrency. All
+ * discussants START as soon as a slot is free; none cascade on error.
+ *
+ * Output order: matches input `specs` order (NOT completion order).
+ * Implementation detail: each slot runs `spawnDiscussant`; the outer
+ * `Promise.all` preserves index → contribution mapping.
+ *
+ * NEVER throws — per-discussant failures are captured as contribution
+ * records with `status: 'error'` or `'parse-error'`.
+ */
+export async function spawnDiscussantsParallel(
+  specs: readonly DiscussantSpec[],
+  opts: SpawnDiscussantsParallelOptions,
+): Promise<readonly DiscussionContribution[]> {
+  const concurrency = Math.max(1, Math.floor(opts.concurrency));
+  const results: Array<DiscussionContribution | undefined> = new Array(specs.length);
+
+  // Semaphore via next-pointer: each worker pulls the next unclaimed
+  // index until the list is exhausted. This preserves order in
+  // `results[]` because workers write to their claimed index.
+  let nextIndex = 0;
+  const total = specs.length;
+
+  async function worker(): Promise<void> {
+    while (true) {
+      const idx = nextIndex;
+      nextIndex += 1;
+      if (idx >= total) return;
+      const spec = specs[idx];
+      if (spec === undefined) continue;
+      const spawnOpts: SpawnDiscussantOptions = {
+        budget: opts.budget,
+        maxTurns: opts.maxTurns,
+        cwd: opts.cwd,
+      };
+      if (opts.runOverride !== undefined) {
+        spawnOpts.runOverride = opts.runOverride;
+      }
+      // spawnDiscussant never throws, so the worker never aborts on
+      // one discussant's failure.
+      const contribution = await spawnDiscussant(spec, spawnOpts);
+      results[idx] = contribution;
+    }
+  }
+
+  const workers: Array<Promise<void>> = [];
+  const workerCount = Math.min(concurrency, total);
+  for (let i = 0; i < workerCount; i += 1) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+
+  // Replace any undefined slots (shouldn't happen, but defensively
+  // surface as an error contribution so callers never see undefined).
+  const finalized: DiscussionContribution[] = [];
+  for (let i = 0; i < results.length; i += 1) {
+    const entry = results[i];
+    if (entry === undefined) {
+      const spec = specs[i];
+      finalized.push({
+        discussant: spec?.name ?? 'unknown',
+        items: Object.freeze([]),
+        raw: '',
+        usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+        status: 'error',
+        error: {
+          code: 'INTERNAL_SCHEDULER_ERROR',
+          message: 'discussant slot was never claimed',
+        },
+      });
+    } else {
+      finalized.push(entry);
+    }
+  }
+  return Object.freeze(finalized);
+}
+
+// ---------------------------------------------------------------------------
+// parseDiscussionBlock — pure parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a DISCUSSION COMPLETE block from the given text. Returns null
+ * when the block is absent. Malformed individual items are skipped
+ * with a logger.warn; the function never throws.
+ *
+ * Heading match is case-insensitive; the block extends from the
+ * `## DISCUSSION COMPLETE` line to end-of-text (or the next top-level
+ * `## ` heading — whichever is first).
+ */
+export function parseDiscussionBlock(text: string): readonly DiscussionItem[] | null {
+  const logger = getLogger();
+
+  // Locate the DISCUSSION COMPLETE heading, case-insensitive.
+  // Use a regex that anchors on a `## ` or start-of-line with optional
+  // leading whitespace for robustness.
+  const headingRe = /^[ \t]*##[ \t]+DISCUSSION[ \t]+COMPLETE[ \t]*$/im;
+  const headingMatch = headingRe.exec(text);
+  if (headingMatch === null) return null;
+
+  // Slice from after the heading.
+  const afterHeading = text.slice(headingMatch.index + headingMatch[0].length);
+
+  // Find the end of the block: next top-level `## ` heading, else end.
+  // We allow `###` subheadings inside the block.
+  const nextBlockRe = /^[ \t]*##[ \t]+(?!#)/m;
+  const endMatch = nextBlockRe.exec(afterHeading);
+  const blockText = endMatch === null
+    ? afterHeading
+    : afterHeading.slice(0, endMatch.index);
+
+  // Split into Questions + Concerns subsections.
+  const lines = blockText.split(/\r?\n/);
+  const items: DiscussionItem[] = [];
+
+  // Walk line-by-line, tracking active subsection kind.
+  //   'question' when we're in a ### Questions subsection
+  //   'concern'  when we're in a ### Concerns subsection
+  //   null       outside any subsection
+  let sectionKind: 'question' | 'concern' | null = null;
+  let pending: PendingItem | null = null;
+
+  const flushPending = (): void => {
+    if (pending === null) return;
+    const text = pending.text.trim();
+    if (text === '') {
+      logger.warn('discuss.parse.skipped_item', {
+        reason: 'empty text',
+        kind: pending.kind,
+      });
+      pending = null;
+      return;
+    }
+    const item: DiscussionItem = {
+      kind: pending.kind,
+      text,
+      severity: normalizeSeverity(pending.severity),
+    };
+    if (pending.tag !== undefined) item.tag = pending.tag;
+    if (pending.rationale !== undefined) item.rationale = pending.rationale;
+    items.push(item);
+    pending = null;
+  };
+
+  for (const rawLine of lines) {
+    const line = rawLine;
+    const trimmed = line.trim();
+
+    // Subsection heading: ### Questions / ### Concerns
+    const subMatch = /^[ \t]*###[ \t]+(Questions|Concerns)[ \t]*$/i.exec(trimmed);
+    if (subMatch !== null) {
+      flushPending();
+      const label = (subMatch[1] ?? '').toLowerCase();
+      sectionKind = label === 'questions' ? 'question' : 'concern';
+      continue;
+    }
+
+    // Item start: - Q: ... or - C: ... (honor explicit kind marker over section)
+    const itemMatch = /^[ \t]*-[ \t]+([QqCc]):[ \t]*(.*)$/.exec(line);
+    if (itemMatch !== null) {
+      flushPending();
+      const markerRaw = itemMatch[1] ?? '';
+      const marker = markerRaw.toUpperCase();
+      const textRest = (itemMatch[2] ?? '').trim();
+      // If inside a section, trust the section kind; otherwise infer
+      // from the marker. The explicit marker is also honored even
+      // when it disagrees with the section (e.g., a `- Q:` inside
+      // Concerns is treated as a question).
+      const kind: 'question' | 'concern' =
+        marker === 'Q' ? 'question'
+        : marker === 'C' ? 'concern'
+        : sectionKind ?? 'question';
+      pending = {
+        kind,
+        text: textRest,
+      };
+      continue;
+    }
+
+    // Field line: indented Concern: / Area: / Severity: / Rationale:
+    const fieldMatch = /^[ \t]+(Concern|Area|Severity|Rationale):[ \t]*(.*)$/.exec(line);
+    if (fieldMatch !== null && pending !== null) {
+      const fieldRaw = fieldMatch[1] ?? '';
+      const field = fieldRaw.toLowerCase();
+      const value = (fieldMatch[2] ?? '').trim();
+      if (field === 'concern' || field === 'area') {
+        if (value !== '') pending.tag = value;
+      } else if (field === 'severity') {
+        pending.severity = value;
+      } else if (field === 'rationale') {
+        if (value !== '') pending.rationale = value;
+      }
+      continue;
+    }
+
+    // Blank lines or irrelevant prose: leave pending open so a trailing
+    // field on the next line still attaches to the same item.
+    if (trimmed === '') continue;
+
+    // Unrecognized non-blank line inside a section terminates the current
+    // item but does not abort parsing — this is the "lenient" rule.
+    // We flush and keep walking.
+    if (pending !== null && !line.startsWith(' ') && !line.startsWith('\t')) {
+      flushPending();
+    }
+  }
+
+  flushPending();
+
+  return Object.freeze(items);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+interface PendingItem {
+  kind: 'question' | 'concern';
+  text: string;
+  tag?: string;
+  severity?: string;
+  rationale?: string;
+}
+
+/**
+ * Normalize a raw severity string to the `Severity` union. Unknown /
+ * empty / missing values fall back to `'minor'` per the parse rules.
+ */
+function normalizeSeverity(raw: string | undefined): Severity {
+  if (raw === undefined) return 'minor';
+  const v = raw.trim().toLowerCase();
+  if (v === '') return 'minor';
+  if (v === 'blocker' || v === 'critical') return 'blocker';
+  if (v === 'major' || v === 'high') return 'major';
+  if (v === 'minor' || v === 'low') return 'minor';
+  if (v === 'nice-to-have' || v === 'nice to have' || v === 'nth') return 'nice-to-have';
+  return 'minor';
+}

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

@@ -0,0 +1,223 @@
+// scripts/lib/discuss-parallel-runner/index.ts — Plan 21-07 (SDK-19).
+//
+// Top-level orchestrator for the parallel discussion runner.
+//
+// Public surface:
+//   * run(opts)              — the entry point. Spawns N discussants,
+//                              aggregates their contributions, returns
+//                              typed DiscussRunnerResult.
+//   * DEFAULT_DISCUSSANTS     — the 4-variant default roster (frozen).
+//   * Re-exports              — every type + named function from the
+//                              three internal modules so consumers need
+//                              only one import site.
+//
+// Algorithm (per PLAN.md Task 4):
+//   1. specs = opts.discussants ?? DEFAULT_DISCUSSANTS.
+//   2. Spawn all via `spawnDiscussantsParallel` with concurrency
+//      default 4.
+//   3. Keep ALL contributions in the return value (successful + failed).
+//      The aggregator only receives the successful ones.
+//   4. If zero successful contributions → throw OperationFailedError
+//      code 'NO_DISCUSSANTS_SUCCEEDED'.
+//   5. Run `spawnAggregator(successfulContributions, {...})` with the
+//      separate aggregator budget + max turns.
+//   6. Aggregate usage: sum per-discussant usage + aggregator usage.
+//   7. Return DiscussRunnerResult.
+//
+// Consumers: `discuss` skill (Plan 21-08 / future) + `gdd-sdk discuss`
+// CLI subcommand (Plan 21-09).
+
+import { OperationFailedError } from '../gdd-errors/index.ts';
+import { getLogger } from '../logger/index.ts';
+
+import {
+  spawnAggregator,
+} from './aggregator.ts';
+import {
+  spawnDiscussantsParallel,
+} from './discussants.ts';
+import type {
+  DiscussantSpec,
+  DiscussionContribution,
+  DiscussRunnerOptions,
+  DiscussRunnerResult,
+} from './types.ts';
+
+// ---------------------------------------------------------------------------
+// Re-exports — one import site for consumers
+// ---------------------------------------------------------------------------
+
+export type {
+  AggregatedDiscussion,
+  AggregatedQuestion,
+  DiscussantName,
+  DiscussantSpec,
+  DiscussionContribution,
+  DiscussionItem,
+  DiscussRunnerOptions,
+  DiscussRunnerResult,
+  Severity,
+} from './types.ts';
+
+export {
+  parseDiscussionBlock,
+  spawnDiscussant,
+  spawnDiscussantsParallel,
+} from './discussants.ts';
+export type {
+  DiscussantRunOverride,
+  SpawnDiscussantOptions,
+  SpawnDiscussantsParallelOptions,
+} from './discussants.ts';
+
+export {
+  buildAggregatorPrompt,
+  computeQuestionKey,
+  parseAggregatorOutput,
+  spawnAggregator,
+} from './aggregator.ts';
+export type {
+  AggregatorRunOverride,
+  SpawnAggregatorOptions,
+} from './aggregator.ts';
+
+// ---------------------------------------------------------------------------
+// DEFAULT_DISCUSSANTS
+// ---------------------------------------------------------------------------
+
+/**
+ * Default discussant roster — four variants covering user-journey,
+ * technical-constraint, brand-fit, accessibility angles. Frozen so
+ * callers can safely spread into new arrays without worrying about
+ * mutation.
+ */
+export const DEFAULT_DISCUSSANTS: readonly DiscussantSpec[] = Object.freeze([
+  Object.freeze({
+    name: 'user-journey',
+    prompt:
+      'You are a UX researcher reviewing the design brief. Surface friction points in the user journey you would want to validate. Emit the DISCUSSION COMPLETE block at the end.',
+  }),
+  Object.freeze({
+    name: 'technical-constraint',
+    prompt:
+      'You are a senior engineer reviewing the design brief. Surface feasibility, performance, and cross-platform concerns. Emit the DISCUSSION COMPLETE block at the end.',
+  }),
+  Object.freeze({
+    name: 'brand-fit',
+    prompt:
+      'You are a brand director reviewing the design brief. Surface brand-archetype misalignment or visual-tone questions. Emit the DISCUSSION COMPLETE block at the end.',
+  }),
+  Object.freeze({
+    name: 'accessibility',
+    prompt:
+      'You are an accessibility specialist reviewing the design brief. Surface inclusion concerns you would need answered. Emit the DISCUSSION COMPLETE block at the end.',
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// run — top-level orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Orchestrate a parallel discussion run.
+ *
+ * Failure modes:
+ *   * Zero successful discussants → `OperationFailedError` code
+ *     `'NO_DISCUSSANTS_SUCCEEDED'` (with per-discussant errors in context).
+ *   * Aggregator parse failure → `ValidationError` code
+ *     `'AGGREGATOR_PARSE_ERROR'` (propagated from spawnAggregator).
+ *   * Aggregator session failure → `ValidationError` code
+ *     `'AGGREGATOR_SESSION_FAILED'`.
+ *
+ * Per-discussant failures do NOT abort the run — they surface as
+ * `status !== 'completed'` contributions in the return value.
+ */
+export async function run(
+  opts: DiscussRunnerOptions,
+): Promise<DiscussRunnerResult> {
+  const logger = getLogger();
+  const specs = opts.discussants ?? DEFAULT_DISCUSSANTS;
+  const concurrency = opts.concurrency !== undefined && opts.concurrency > 0
+    ? opts.concurrency
+    : 4;
+  const cwd = opts.cwd ?? process.cwd();
+
+  logger.info('discuss.runner.started', {
+    discussants: specs.length,
+    concurrency,
+    cwd,
+  });
+
+  const contributions = await spawnDiscussantsParallel(specs, {
+    concurrency,
+    budget: opts.budget,
+    maxTurns: opts.maxTurnsPerDiscussant,
+    ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+    cwd,
+  });
+
+  const successful: DiscussionContribution[] = contributions.filter(
+    (c): c is DiscussionContribution => c.status === 'completed',
+  );
+
+  if (successful.length === 0) {
+    // Collect per-discussant error details for the operator.
+    const errorSummary = contributions.map((c) => ({
+      discussant: c.discussant,
+      status: c.status,
+      error: c.error ?? null,
+    }));
+    logger.error('discuss.runner.no_successes', {
+      attempted: contributions.length,
+      errors: errorSummary,
+    });
+    throw new OperationFailedError(
+      `all ${contributions.length} discussants failed — aggregator cannot run`,
+      'NO_DISCUSSANTS_SUCCEEDED',
+      { attempted: contributions.length, contributions: errorSummary },
+    );
+  }
+
+  const aggregated = await spawnAggregator(successful, {
+    budget: opts.aggregatorBudget,
+    maxTurns: opts.aggregatorMaxTurns,
+    ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+    cwd,
+    ...(opts.aggregatorPrompt !== undefined
+      ? { customPrompt: opts.aggregatorPrompt }
+      : {}),
+  });
+
+  // Aggregate usage = sum(contributions.usage) + aggregated.usage.
+  let totalInput = 0;
+  let totalOutput = 0;
+  let totalCost = 0;
+  for (const c of contributions) {
+    totalInput += c.usage.input_tokens;
+    totalOutput += c.usage.output_tokens;
+    totalCost += c.usage.usd_cost;
+  }
+  totalInput += aggregated.usage.input_tokens;
+  totalOutput += aggregated.usage.output_tokens;
+  totalCost += aggregated.usage.usd_cost;
+
+  logger.info('discuss.runner.completed', {
+    attempted: contributions.length,
+    successful: successful.length,
+    themes: aggregated.themes.length,
+    questions: aggregated.questions.length,
+    total_input_tokens: totalInput,
+    total_output_tokens: totalOutput,
+    total_usd_cost: totalCost,
+  });
+
+  return {
+    contributions,
+    aggregated,
+    total_usage: {
+      input_tokens: totalInput,
+      output_tokens: totalOutput,
+      usd_cost: totalCost,
+    },
+  };
+}