@hegemonart/get-design-done 1.20.0 → 1.22.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/event-chain.cjs

@@ -0,0 +1,177 @@
+/**
+ * event-chain.cjs — append-only causal event chain (Plan 22-04).
+ *
+ * Lives at `.design/gep/events.jsonl` (gep = "GDD Event Provenance").
+ * One JSONL line per event with parent-id linkage so consumers can
+ * walk decision → agent-spawn → outcome chains for retroactive audit.
+ *
+ * Schema:
+ *   {
+ *     event_id:        UUIDv4 (random)
+ *     parent_event_id: string | null
+ *     ts:              ISO-8601
+ *     agent:           string
+ *     decision_refs:   string[]   // STATE.md decision IDs (D-NN, etc.)
+ *     outcome:         string     // free-form: 'pass' / 'fail' / 'rolled-back' / …
+ *     rollback_reason: string?    // present iff outcome = 'rolled-back'
+ *     ...rest:         opaque caller-supplied fields preserved verbatim
+ *   }
+ *
+ * Why a separate file from .design/telemetry/events.jsonl:
+ *   * the chain is a CAUSAL overlay — rows have semantic meaning
+ *   * the general event-stream is a high-volume firehose
+ *   * /gdd:audit --retroactive walks the chain; it should not have to
+ *     scan a 100k-line firehose for causal rows
+ */
+
+'use strict';
+
+const { appendFileSync, mkdirSync, readFileSync, existsSync } = require('node:fs');
+const { dirname, isAbsolute, join, resolve } = require('node:path');
+const { randomUUID } = require('node:crypto');
+
+const DEFAULT_CHAIN_PATH = '.design/gep/events.jsonl';
+
+/**
+ * Resolve the on-disk chain file path, honouring an absolute override.
+ *
+ * @param {{baseDir?: string, path?: string}} [opts]
+ * @returns {string}
+ */
+function chainPathFor(opts = {}) {
+  if (opts.path) {
+    return isAbsolute(opts.path) ? opts.path : resolve(opts.baseDir ?? process.cwd(), opts.path);
+  }
+  const base = opts.baseDir ?? process.cwd();
+  return resolve(base, DEFAULT_CHAIN_PATH);
+}
+
+/**
+ * Append one chain event. Returns the event_id (caller may not have
+ * supplied one).
+ *
+ * Required fields: agent, outcome.
+ * Optional: parent_event_id, decision_refs, rollback_reason, plus any
+ * opaque extra fields which are preserved verbatim.
+ *
+ * @param {{
+ *   event_id?: string,
+ *   parent_event_id?: string | null,
+ *   agent: string,
+ *   decision_refs?: string[],
+ *   outcome: string,
+ *   rollback_reason?: string,
+ *   ts?: string,
+ *   path?: string,
+ *   baseDir?: string,
+ *   [k: string]: unknown,
+ * }} input
+ * @returns {string} event_id
+ */
+function appendChainEvent(input) {
+  if (!input || typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('appendChainEvent: agent is required');
+  }
+  if (typeof input.outcome !== 'string' || input.outcome.length === 0) {
+    throw new TypeError('appendChainEvent: outcome is required');
+  }
+  const event_id = input.event_id || randomUUID();
+  const record = {
+    event_id,
+    parent_event_id: input.parent_event_id ?? null,
+    ts: input.ts || new Date().toISOString(),
+    agent: input.agent,
+    decision_refs: Array.isArray(input.decision_refs) ? input.decision_refs : [],
+    outcome: input.outcome,
+  };
+  if (input.rollback_reason !== undefined) {
+    record.rollback_reason = input.rollback_reason;
+  }
+  // Preserve opaque extras (any keys not already on `record`).
+  for (const key of Object.keys(input)) {
+    if (key === 'path' || key === 'baseDir') continue;
+    if (!(key in record)) {
+      record[key] = input[key];
+    }
+  }
+  const path = chainPathFor({ baseDir: input.baseDir, path: input.path });
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(record) + '\n', { flag: 'a' });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[event-chain] write failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  return event_id;
+}
+
+/**
+ * Read the chain file and yield each parsed record. Invalid JSON lines
+ * are skipped with a stderr warning.
+ *
+ * @param {{path?: string, baseDir?: string}} [opts]
+ * @returns {Generator<Record<string, unknown>>}
+ */
+function* readChain(opts = {}) {
+  const path = chainPathFor(opts);
+  if (!existsSync(path)) return;
+  const raw = readFileSync(path, 'utf8');
+  let lineNum = 0;
+  for (const line of raw.split('\n')) {
+    lineNum += 1;
+    if (line.trim() === '') continue;
+    try {
+      yield JSON.parse(line);
+    } catch (err) {
+      try {
+        process.stderr.write(
+          `[event-chain] skipping invalid line ${lineNum} at ${path}\n`,
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
+/**
+ * Walk parents of `event_id` until reaching a row with no parent.
+ * Returns the chain in caller-→-root order, i.e. `[event, parent, …]`.
+ *
+ * Returns an empty array if the event_id is not found.
+ *
+ * @param {string} event_id
+ * @param {{path?: string, baseDir?: string}} [opts]
+ * @returns {Array<Record<string, unknown>>}
+ */
+function walkParents(event_id, opts = {}) {
+  /** @type {Map<string, Record<string, unknown>>} */
+  const byId = new Map();
+  for (const ev of readChain(opts)) {
+    byId.set(/** @type {string} */ (ev.event_id), ev);
+  }
+  const chain = [];
+  /** @type {string | null | undefined} */
+  let id = event_id;
+  const visited = new Set();
+  while (id && byId.has(id) && !visited.has(id)) {
+    visited.add(id);
+    const ev = byId.get(id);
+    chain.push(ev);
+    id = /** @type {string | null | undefined} */ (ev.parent_event_id);
+  }
+  return chain;
+}
+
+module.exports = {
+  appendChainEvent,
+  readChain,
+  walkParents,
+  chainPathFor,
+  DEFAULT_CHAIN_PATH,
+};

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

@@ -33,11 +33,31 @@ export type {
   StageExitedEvent,
   HookFiredEvent,
   ErrorEvent,
+  WaveStartedEvent,
+  WaveCompletedEvent,
+  BlockerAddedEvent,
+  DecisionAddedEvent,
+  MustHaveAddedEvent,
+  ParallelismVerdictEvent,
+  CostUpdateEvent,
+  RateLimitEvent,
+  ApiRetryEvent,
+  CompactBoundaryEvent,
+  McpProbeEvent,
+  ReflectionProposedEvent,
+  ConnectionStatusChangeEvent,
+  ToolCallStartedEvent,
+  ToolCallCompletedEvent,
+  AgentSpawnEvent,
+  AgentOutcomeEvent,
 } from './types.ts';
+export { KNOWN_EVENT_TYPES } from './types.ts';
 export { EventBus } from './emitter.ts';
 export type { EventHandler, Unsubscribe } from './emitter.ts';
 export { EventWriter, DEFAULT_EVENTS_PATH, DEFAULT_MAX_LINE_BYTES } from './writer.ts';
 export type { WriterOptions } from './writer.ts';
+export { readEvents, aggregate } from './reader.ts';
+export type { ReadEventsOptions, AggregateResult } from './reader.ts';
 
 /**
  * Lazily-constructed module-level singletons. `getWriter()` honors the
@@ -61,7 +81,17 @@ let cachedHost: string | null = null;
  */
 export function getWriter(opts?: WriterOptions): EventWriter {
   if (defaultWriter === null) {
-    defaultWriter = new EventWriter(opts ?? {});
+    // Honor GDD_EVENTS_PATH env var as the first-choice default path
+    // when the caller doesn't pass an explicit `opts.path`. Lets test
+    // harnesses and Plan 21-11's E2E subprocess steer the on-disk
+    // stream into a fixture-specific directory without chdir'ing the
+    // entire process. Explicit `opts.path` always wins.
+    const envPath: string | undefined = process.env['GDD_EVENTS_PATH'];
+    const finalOpts: WriterOptions =
+      opts?.path === undefined && envPath !== undefined && envPath.length > 0
+        ? { ...(opts ?? {}), path: envPath }
+        : (opts ?? {});
+    defaultWriter = new EventWriter(finalOpts);
   }
   return defaultWriter;
 }

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

@@ -0,0 +1,139 @@
+// scripts/lib/event-stream/reader.ts — typed JSONL reader + aggregator
+// (Plan 22-05).
+//
+// `readEvents()` is a streaming async iterator over the persisted event
+// log. It uses `readline` over a `fs.createReadStream`, so the entire
+// file is never held in memory — events.jsonl can grow to gigabytes
+// without OOM-ing a tail consumer.
+//
+// `aggregate()` collects an event iterable into a structured rollup
+// (counts by type / stage / cycle / agent + totals). Aggregation
+// always materialises the iterator, so callers that already have very
+// large logs should pre-filter via `readEvents({filter: …})` before
+// aggregating.
+
+import { createReadStream, existsSync, type ReadStream } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import type { BaseEvent } from './types.ts';
+import { DEFAULT_EVENTS_PATH } from './writer.ts';
+
+/** Options for {@link readEvents}. */
+export interface ReadEventsOptions {
+  /** Source file path. Default: `.design/telemetry/events.jsonl` (resolved against cwd). */
+  path?: string;
+  /** Resolution base for relative `path`. Default: `process.cwd()`. */
+  baseDir?: string;
+  /** Match by event type — string is exact-equal, RegExp is `.test(type)`. */
+  type?: string | RegExp;
+  /** Custom predicate; runs after `type` filter if both are supplied. */
+  predicate?: (ev: BaseEvent) => boolean;
+  /** Inclusive lower bound on `timestamp` (ISO-8601 string). */
+  since?: string;
+  /** Inclusive upper bound on `timestamp` (ISO-8601 string). */
+  until?: string;
+}
+
+/** Result shape from {@link aggregate}. */
+export interface AggregateResult {
+  byType: Record<string, number>;
+  byStage: Record<string, number>;
+  byCycle: Record<string, number>;
+  byAgent: Record<string, number>;
+  totals: {
+    count: number;
+    error_count: number;
+    truncated_count: number;
+  };
+}
+
+/**
+ * Resolve the read path the same way the writer does: absolute paths
+ * win; relative paths resolve against `baseDir` (defaults to cwd).
+ */
+function resolveReadPath(opts: ReadEventsOptions): string {
+  const raw = opts.path ?? DEFAULT_EVENTS_PATH;
+  if (isAbsolute(raw)) return raw;
+  return resolve(opts.baseDir ?? process.cwd(), raw);
+}
+
+/**
+ * Stream events from the JSONL log line-by-line. Invalid JSON lines
+ * are skipped silently — the writer guarantees well-formed output, so
+ * a malformed line is a data-corruption signal that should not crash
+ * a tail consumer.
+ *
+ * Filters apply in this order: type → predicate → since/until. The
+ * type filter is the cheapest, so it short-circuits first.
+ */
+export async function* readEvents(
+  opts: ReadEventsOptions = {},
+): AsyncIterable<BaseEvent> {
+  const path = resolveReadPath(opts);
+  if (!existsSync(path)) return;
+
+  const stream: ReadStream = createReadStream(path, { encoding: 'utf8' });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  const typeRe = opts.type instanceof RegExp ? opts.type : null;
+  const typeStr = typeof opts.type === 'string' ? opts.type : null;
+
+  try {
+    for await (const line of rl) {
+      if (line.trim() === '') continue;
+      let ev: BaseEvent;
+      try {
+        ev = JSON.parse(line) as BaseEvent;
+      } catch {
+        continue;
+      }
+      if (typeStr !== null && ev.type !== typeStr) continue;
+      if (typeRe !== null && !typeRe.test(ev.type)) continue;
+      if (opts.predicate && !opts.predicate(ev)) continue;
+      if (opts.since !== undefined && ev.timestamp < opts.since) continue;
+      if (opts.until !== undefined && ev.timestamp > opts.until) continue;
+      yield ev;
+    }
+  } finally {
+    rl.close();
+    stream.close();
+  }
+}
+
+/**
+ * Synchronous aggregator that drains an iterable of events and rolls
+ * them up by type / stage / cycle / agent. `agent` is read from
+ * `payload.agent` (the trajectory + cost-update + agent.spawn shapes
+ * all expose it there).
+ */
+export async function aggregate(
+  events: AsyncIterable<BaseEvent> | Iterable<BaseEvent>,
+): Promise<AggregateResult> {
+  const result: AggregateResult = {
+    byType: {},
+    byStage: {},
+    byCycle: {},
+    byAgent: {},
+    totals: { count: 0, error_count: 0, truncated_count: 0 },
+  };
+
+  /** @param {Record<string, number>} bucket @param {string} key */
+  const inc = (bucket: Record<string, number>, key: string) => {
+    bucket[key] = (bucket[key] ?? 0) + 1;
+  };
+
+  for await (const ev of events as AsyncIterable<BaseEvent>) {
+    result.totals.count += 1;
+    inc(result.byType, ev.type);
+    if (ev.type === 'error') result.totals.error_count += 1;
+    if (ev._truncated === true) result.totals.truncated_count += 1;
+    if (ev.stage) inc(result.byStage, String(ev.stage));
+    if (ev.cycle) inc(result.byCycle, ev.cycle);
+    const payload = ev.payload as Record<string, unknown> | undefined;
+    if (payload && typeof payload['agent'] === 'string') {
+      inc(result.byAgent, payload['agent'] as string);
+    }
+  }
+  return result;
+}