@hegemonart/get-design-done 1.31.0 → 1.32.0

package/sdk/cli/index.ts

@@ -0,0 +1,172 @@
+// sdk/cli/index.ts — Plan 21-09 Task 7 (SDK-21).
+//
+// Main dispatcher for the `gdd-sdk` CLI. Invoked by `bin/gdd-sdk` (the
+// CJS trampoline) with `--experimental-strip-types` so TS runs without
+// a build step.
+//
+// Responsibilities:
+//   * Parse argv via parseArgs().
+//   * Route by first positional to the matching subcommand module.
+//   * Print top-level USAGE on bare `gdd-sdk` / `-h` / `--help`.
+//   * Exit with the subcommand's return code. Unknown subcommands
+//     exit 3 and print USAGE to stderr.
+//
+// The bottom of this file has the `main()` bootstrap that the trampoline
+// invokes. It catches any accidental throw (subcommands are contracted
+// not to throw) and translates to exit code 3.
+
+import { parseArgs, type ParsedArgs } from './parse-args.ts';
+import { runCommand } from './commands/run.ts';
+import { stageCommand } from './commands/stage.ts';
+import { queryCommand } from './commands/query.ts';
+import { auditCommand } from './commands/audit.ts';
+import { initCommand } from './commands/init.ts';
+
+// ---------------------------------------------------------------------------
+// Top-level USAGE.
+// ---------------------------------------------------------------------------
+
+export const USAGE = `gdd-sdk <command> [flags]
+
+Commands:
+  run              Run the full design pipeline headlessly.
+  stage <name>     Run a single stage (brief|explore|plan|design|verify|discuss).
+  query <op>       Typed STATE.md read operations.
+  audit            Probe connections + dry-run verify.
+  init             Bootstrap a new project.
+
+Use 'gdd-sdk <command> -h' for command-specific flags.
+
+Exit codes (general):
+  0  success
+  1  halted / regression / already-initialized
+  2  awaiting-gate / partial (init)
+  3  argument / config error
+`;
+
+// ---------------------------------------------------------------------------
+// Deps.
+// ---------------------------------------------------------------------------
+
+export interface DispatcherDeps {
+  readonly stdout?: NodeJS.WritableStream;
+  readonly stderr?: NodeJS.WritableStream;
+  readonly commands?: {
+    readonly run?: typeof runCommand;
+    readonly stage?: typeof stageCommand;
+    readonly query?: typeof queryCommand;
+    readonly audit?: typeof auditCommand;
+    readonly init?: typeof initCommand;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher.
+// ---------------------------------------------------------------------------
+
+/**
+ * Dispatch a parsed ParsedArgs to the appropriate subcommand. Exported
+ * for tests (they can construct a ParsedArgs manually and assert the
+ * exit code + captured stdout/stderr).
+ */
+export async function dispatch(
+  parsed: ParsedArgs,
+  deps: DispatcherDeps = {},
+): Promise<number> {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const commands = {
+    run: deps.commands?.run ?? runCommand,
+    stage: deps.commands?.stage ?? stageCommand,
+    query: deps.commands?.query ?? queryCommand,
+    audit: deps.commands?.audit ?? auditCommand,
+    init: deps.commands?.init ?? initCommand,
+  };
+
+  // Bare invocation or top-level help → USAGE.
+  if (parsed.subcommand === null) {
+    stdout.write(USAGE);
+    return 0;
+  }
+  if (
+    (parsed.flags['help'] === true || parsed.flags['h'] === true) &&
+    // Top-level --help (no subcommand recognized yet; --help before the
+    // first positional lands here). Subcommands also honor --help
+    // themselves, so this branch only fires for `gdd-sdk --help`.
+    parsed.positionals.length === 0 &&
+    !KNOWN_SUBCOMMANDS.has(parsed.subcommand)
+  ) {
+    stdout.write(USAGE);
+    return 0;
+  }
+
+  switch (parsed.subcommand) {
+    case 'run':
+      return await commands.run(parsed, { stdout, stderr });
+    case 'stage':
+      return await commands.stage(parsed, { stdout, stderr });
+    case 'query':
+      return await commands.query(parsed, { stdout, stderr });
+    case 'audit':
+      return await commands.audit(parsed, { stdout, stderr });
+    case 'init':
+      return await commands.init(parsed, { stdout, stderr });
+    default:
+      stderr.write(
+        `gdd-sdk: unknown subcommand "${parsed.subcommand}"\n${USAGE}`,
+      );
+      return 3;
+  }
+}
+
+const KNOWN_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  'run',
+  'stage',
+  'query',
+  'audit',
+  'init',
+]);
+
+// ---------------------------------------------------------------------------
+// Bootstrap entry point — called by bin/gdd-sdk trampoline.
+// ---------------------------------------------------------------------------
+
+/**
+ * Top-level main. Parses process.argv.slice(2), dispatches, prints
+ * USAGE + exit 3 on any uncaught error. Exported so tests can invoke
+ * it directly (bypassing the trampoline).
+ */
+export async function main(
+  argv: readonly string[] = process.argv.slice(2),
+  deps: DispatcherDeps = {},
+): Promise<number> {
+  const parsed = parseArgs(argv);
+  return await dispatch(parsed, deps);
+}
+
+// ---------------------------------------------------------------------------
+// When executed directly by the trampoline, invoke main() + exit.
+// ---------------------------------------------------------------------------
+
+// Only self-invoke when this module IS the entry point. We detect that
+// by checking process.argv[1] (trampoline passes this file's path).
+//
+// `import.meta.url` is the POSIX idiom but this TS runs under --experimental-strip-types
+// as Node16 modules — we use process.argv to stay ESM/CJS-agnostic.
+//
+// Extension-agnostic match (.ts | .js | .cjs): the dual-mode bin trampoline
+// (Plan 31-5-9.5, D-16) runs the raw `.ts` in-repo via --experimental-strip-types
+// AND the esbuild-bundled `.js` from a packed/installed tarball. argv[1] ends in
+// `.js` in the compiled path, so a `.ts`-only check would silently skip main().
+
+const entryPath: string = (process.argv[1] ?? '').replace(/\\/g, '/');
+if (/\/sdk\/cli\/index\.(ts|js|cjs|mjs)$/.test(entryPath)) {
+  main().then(
+    (code) => process.exit(code),
+    (err) => {
+      // eslint-disable-next-line no-console
+      console.error('gdd-sdk: unexpected error:', err);
+      process.exit(3);
+    },
+  );
+}

package/{scripts/lib → sdk}/cli/parse-args.ts

@@ -1,4 +1,4 @@
-// scripts/lib/cli/parse-args.ts — Plan 21-09 Task 1 (SDK-21).
+// sdk/cli/parse-args.ts — Plan 21-09 Task 1 (SDK-21).
 //
 // Hand-rolled argv parser used by the `gdd-sdk` CLI. No external
 // dependency (no yargs / commander / minimist). Supports the exact
@@ -21,7 +21,7 @@
 //     (e.g., non-numeric input for a numeric flag). Callers ideally catch
 //     and route to exit code 3.
 
-import { ValidationError } from '../gdd-errors/index.ts';
+import { ValidationError } from '../errors/index.ts';
 
 // ---------------------------------------------------------------------------
 // Public types.

package/{scripts/lib/gdd-errors → sdk/errors}/classification.ts

@@ -1,4 +1,4 @@
-// scripts/lib/gdd-errors/classification.ts — error classification + MCP helpers.
+// sdk/errors/classification.ts — error classification + MCP helpers.
 //
 // Two exports:
 //   * classify(err)      — normalize any thrown value into an

package/sdk/errors/index.ts

@@ -0,0 +1,218 @@
+// sdk/errors/index.ts — unified GDD error taxonomy.
+//
+// Three classes exactly — mirrors the GSD errors.ts discipline:
+//
+//   * ValidationError       — throw at boundary; "fix your input"
+//   * StateConflictError    — throw; lockfile contention or transition guard
+//                             failed; retryable by upstream
+//   * OperationFailedError  — return in data.error; "couldn't complete in
+//                             this state"; expected failure mode the caller
+//                             should branch on, not crash on
+//
+// MCP tool handlers place OperationFailedError instances into data.error
+// so the model can see and reason about them. ValidationError and
+// StateConflictError are thrown (non-zero exit path).
+//
+// Plan 20-01 introduced LockAcquisitionError and TransitionGateFailed as
+// local Error subclasses; this module re-exports taxonomy-compliant
+// versions so the existing `gdd-state` surface (tests + consumers) keeps
+// working unchanged. Plan 20-05 wires `toToolError` into MCP tool
+// handlers; Plan 20-06 emits error events to the telemetry stream.
+
+/** Short machine-readable code. Example: "VALIDATION_MISSING_FIELD". */
+export type GDDErrorCode = string;
+
+/**
+ * Abstract base class — every GDD taxonomy error inherits from this.
+ *
+ * Subclasses set a literal `kind` discriminant so `classify()` can
+ * branch on it without `instanceof` chains, and `toJSON()` produces a
+ * lossless payload for tool-result transport.
+ */
+export abstract class GDDError extends Error {
+  abstract readonly kind: 'validation' | 'state_conflict' | 'operation_failed';
+  readonly code: GDDErrorCode;
+  readonly context: Readonly<Record<string, unknown>>;
+
+  constructor(
+    message: string,
+    code: GDDErrorCode,
+    context: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.code = code;
+    this.context = Object.freeze({ ...context });
+    // Set .name to the concrete subclass name (LockAcquisitionError,
+    // ValidationError, etc.) so error serialization is human-meaningful.
+    this.name = new.target.name;
+  }
+
+  /**
+   * Serialize to a plain object safe for JSON.stringify. Round-trips
+   * through JSON without loss of `name`, `kind`, `code`, `message`, or
+   * `context`. Does NOT include the stack trace — MCP tool handlers do
+   * not forward stacks to the model.
+   */
+  toJSON(): {
+    name: string;
+    kind: GDDError['kind'];
+    code: GDDErrorCode;
+    message: string;
+    context: Readonly<Record<string, unknown>>;
+  } {
+    return {
+      name: this.name,
+      kind: this.kind,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+    };
+  }
+}
+
+/**
+ * Throw at boundary when the caller's input is malformed.
+ *
+ * Example: MCP tool handler receives an argument that fails schema
+ * validation; the correct response is `throw new ValidationError(...)`
+ * so the harness catches it and returns a structured error to the model.
+ * The model should fix its input and retry.
+ */
+export class ValidationError extends GDDError {
+  readonly kind = 'validation' as const;
+  constructor(
+    message: string,
+    code: GDDErrorCode = 'VALIDATION',
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, context);
+  }
+}
+
+/**
+ * Throw when a concurrency primitive or transition guard vetoes the
+ * operation. Retryable by upstream — the caller may try again after a
+ * backoff, or surface the blocker to the operator.
+ *
+ * Examples: lockfile contention (LockAcquisitionError), transition
+ * gate failure (TransitionGateFailed).
+ */
+export class StateConflictError extends GDDError {
+  readonly kind = 'state_conflict' as const;
+  constructor(
+    message: string,
+    code: GDDErrorCode = 'STATE_CONFLICT',
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, context);
+  }
+}
+
+/**
+ * Return as `data.error` — do NOT throw. This is the expected failure
+ * mode the caller should branch on: the operation is well-formed, the
+ * state is valid, but the specific request cannot complete right now.
+ *
+ * Example: "try to advance to `design`, but no plan exists yet" — the
+ * model should be told, not crashed on.
+ */
+export class OperationFailedError extends GDDError {
+  readonly kind = 'operation_failed' as const;
+  constructor(
+    message: string,
+    code: GDDErrorCode = 'OPERATION_FAILED',
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, context);
+  }
+}
+
+// -----------------------------------------------------------------------
+// Plan 20-01 compatibility re-exports.
+//
+// These keep the `gdd-state` module's public surface stable post-refactor:
+// - LockAcquisitionError — lockfile contention (plan 20-01 lockfile.ts)
+// - TransitionGateFailed — transition gate veto (plan 20-01 transition())
+// Both are StateConflictError subclasses (retryable / contention-class
+// errors).
+// -----------------------------------------------------------------------
+
+/**
+ * Error thrown when `acquire()` cannot obtain the lockfile within
+ * `maxWaitMs`. Carries the contents of the offending lockfile (as
+ * text — may be JSON, may be garbage if corrupted) so callers can
+ * surface them to operators.
+ *
+ * The `lockPath` and `lockContents` instance properties are preserved
+ * from the Plan 20-01 shape for API compat; they're also stored in
+ * the frozen `context` object for uniform GDDError serialization.
+ */
+export class LockAcquisitionError extends StateConflictError {
+  readonly lockPath: string;
+  readonly lockContents: string;
+  readonly waitedMs: number;
+  constructor(
+    lockPath: string,
+    lockContents: string,
+    waitedMs: number,
+    context?: Record<string, unknown>,
+  ) {
+    super(
+      `failed to acquire lock at ${lockPath} after ${waitedMs}ms; current holder: ${lockContents}`,
+      'LOCK_ACQUISITION',
+      { ...context, lockPath, lockContents, waitedMs },
+    );
+    this.lockPath = lockPath;
+    this.lockContents = lockContents;
+    this.waitedMs = waitedMs;
+  }
+}
+
+/**
+ * Error thrown when a transition gate vetoes a stage advance. Carries
+ * the frozen list of blocker messages so callers can surface them to
+ * operators or retry after resolving.
+ *
+ * The `blockers` instance property is preserved from the Plan 20-01
+ * shape (readonly string[]) for API compat; it's also mirrored into
+ * the frozen `context` object for uniform GDDError serialization.
+ */
+export class TransitionGateFailed extends StateConflictError {
+  readonly blockers: readonly string[];
+  readonly toStage: string;
+  constructor(
+    toStage: string,
+    blockers: string[],
+    context?: Record<string, unknown>,
+  ) {
+    super(
+      `transition to "${toStage}" blocked by gate: ${blockers.join('; ') || '(no detail)'}`,
+      'TRANSITION_GATE_FAILED',
+      { ...context, toStage, blockers: [...blockers] },
+    );
+    this.toStage = toStage;
+    this.blockers = Object.freeze([...blockers]);
+  }
+}
+
+/**
+ * Error thrown by STATE.md `parse()` when the input cannot be
+ * interpreted. `ValidationError` semantics: the caller (likely the
+ * operator or an upstream generator) gave us malformed input — fix
+ * your STATE.md and retry.
+ *
+ * The `line` instance property points at the 1-indexed line in the
+ * source markdown where the parser gave up. It's also mirrored into
+ * the frozen `context` object.
+ */
+export class ParseError extends ValidationError {
+  readonly line: number;
+  constructor(message: string, line: number, context?: Record<string, unknown>) {
+    super(
+      `STATE.md parse error at line ${line}: ${message}`,
+      'PARSE_ERROR',
+      { ...context, line },
+    );
+    this.line = line;
+  }
+}

package/{scripts/lib → sdk}/event-stream/emitter.ts

@@ -1,4 +1,4 @@
-// scripts/lib/event-stream/emitter.ts — in-process pub-sub for Phase 20+
+// sdk/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

package/sdk/event-stream/index.ts

@@ -0,0 +1,197 @@
+// sdk/event-stream/index.ts — public API for the Phase 20+
+// telemetry stream (Plan 20-06, SDK-08).
+//
+// Consumers import ONLY from this file. The internal parts
+// (`./types.ts`, `./writer.ts`, `./emitter.ts`) are implementation
+// detail; changing them without updating this export surface is a
+// breaking change for downstream plans (20-05 MCP handlers, 20-13 hooks).
+//
+// Surface:
+//   * appendEvent(ev)          — persist + broadcast one event
+//   * getWriter(opts?)         — lazy singleton EventWriter
+//   * getBus()                 — lazy singleton EventBus
+//   * reset()                  — clear module-level singletons (tests)
+//   * types                    — BaseEvent, KnownEvent, and every pre-
+//                                registered subtype (StateMutationEvent,
+//                                StateTransitionEvent, …).
+
+import { hostname } from 'node:os';
+
+import { EventBus } from './emitter.ts';
+import type { Unsubscribe, EventHandler } from './emitter.ts';
+import { EventWriter } from './writer.ts';
+import type { WriterOptions } from './writer.ts';
+import type { BaseEvent, EventMeta } from './types.ts';
+
+export type {
+  BaseEvent,
+  EventMeta,
+  KnownEvent,
+  StateMutationEvent,
+  StateTransitionEvent,
+  StageEnteredEvent,
+  StageExitedEvent,
+  HookFiredEvent,
+  ErrorEvent,
+  WaveStartedEvent,
+  WaveCompletedEvent,
+  BlockerAddedEvent,
+  DecisionAddedEvent,
+  MustHaveAddedEvent,
+  ParallelismVerdictEvent,
+  CostUpdateEvent,
+  RateLimitEvent,
+  ApiRetryEvent,
+  CompactBoundaryEvent,
+  McpProbeEvent,
+  ReflectionProposedEvent,
+  ConnectionStatusChangeEvent,
+  ToolCallStartedEvent,
+  ToolCallCompletedEvent,
+  AgentSpawnEvent,
+  AgentOutcomeEvent,
+  // Phase 27 / Plan 27-08 — peer-CLI delegation events (D-09).
+  RuntimeRole,
+  PeerCallStartedEvent,
+  PeerCallCompleteEvent,
+  PeerCallFailedEvent,
+} from './types.ts';
+export {
+  KNOWN_EVENT_TYPES,
+  // Phase 27 / Plan 27-08 — symbolic constants for peer-CLI event names.
+  PEER_CALL_STARTED,
+  PEER_CALL_COMPLETE,
+  PEER_CALL_FAILED,
+  PEER_CALL_EVENT_TYPES,
+  DEFAULT_RUNTIME_ROLE,
+} 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
+ * first `opts` it receives; subsequent calls with different options are
+ * ignored. Tests that need to vary options across runs should call
+ * {@link reset} between runs.
+ */
+let defaultWriter: EventWriter | null = null;
+let defaultBus: EventBus | null = null;
+/**
+ * Cached host name. `os.hostname()` is cheap but not free (syscall on
+ * some platforms) and we stamp it onto every event; compute once.
+ */
+let cachedHost: string | null = null;
+
+/**
+ * Return the module-level default writer, constructing it on first
+ * call. Passing `opts` on subsequent calls is a no-op (the first
+ * caller wins); that matches the "single shared file per process"
+ * intent.
+ */
+export function getWriter(opts?: WriterOptions): EventWriter {
+  if (defaultWriter === null) {
+    // 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;
+}
+
+/** Return the module-level default bus, constructing it on first call. */
+export function getBus(): EventBus {
+  if (defaultBus === null) {
+    defaultBus = new EventBus();
+  }
+  return defaultBus;
+}
+
+/**
+ * Persist `ev` to the on-disk JSONL stream AND broadcast it to the
+ * in-process bus. This is the normal emission path for every Phase 20+
+ * event producer.
+ *
+ * Ordering:
+ *   1. Stamp `_meta` (pid/host/source) if the caller didn't supply it.
+ *   2. Persist via `getWriter().append(ev)` — sync, never throws.
+ *   3. Broadcast via `getBus().emit(ev.type, ev)` AND `emit('*', ev)`
+ *      so typed subscribers and `subscribeAll` observers both see it.
+ *
+ * Bus emission can still throw if a subscriber handler throws; we
+ * intentionally surface that rather than silently swallowing, since a
+ * failing handler is a programming bug, not an expected runtime
+ * condition. Plan 20-13's hooks wrap their handler bodies defensively
+ * for this reason.
+ */
+export function appendEvent(ev: BaseEvent): void {
+  // Stamp writer-injected metadata if absent. We don't clone the full
+  // event — callers typically build it fresh per emission — but we do
+  // need to ensure `_meta` is present by the time we persist.
+  if (ev._meta === undefined) {
+    if (cachedHost === null) {
+      try {
+        cachedHost = hostname();
+      } catch {
+        cachedHost = 'unknown';
+      }
+    }
+    const meta: EventMeta = {
+      pid: process.pid,
+      host: cachedHost,
+      source: 'event-stream',
+    };
+    ev._meta = meta;
+  }
+
+  // Persist first. Bus emission is synchronous; if a subscriber throws
+  // after we've persisted, the durable record is already safe.
+  getWriter().append(ev);
+
+  const bus = getBus();
+  bus.emit(ev.type, ev);
+  bus.emit('*', ev);
+}
+
+/**
+ * Reset module-level singletons. Intended for tests that want a fresh
+ * writer (e.g. pointed at a new temp directory) or a fresh bus (e.g.
+ * to assert isolation between test cases).
+ *
+ * Safe to call from production code but the intended caller is a test.
+ * `appendEvent()` will lazily reconstruct both singletons on the next
+ * emission.
+ */
+export function reset(): void {
+  if (defaultBus !== null) {
+    defaultBus.removeAllListeners();
+  }
+  defaultWriter = null;
+  defaultBus = null;
+}
+
+// Re-export `subscribe`/`subscribeAll` convenience: some callers only
+// need to subscribe, not emit, and `getBus().subscribe(…)` reads fine
+// but the shorter form keeps consumer code terse.
+/** Convenience: subscribe to one event type on the default bus. */
+export function subscribe<T extends BaseEvent = BaseEvent>(
+  type: T['type'],
+  handler: EventHandler<T>,
+): Unsubscribe {
+  return getBus().subscribe<T>(type, handler);
+}
+
+/** Convenience: subscribe to every event on the default bus. */
+export function subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
+  return getBus().subscribeAll(handler);
+}

package/{scripts/lib → sdk}/event-stream/reader.ts

@@ -1,4 +1,4 @@
-// scripts/lib/event-stream/reader.ts — typed JSONL reader + aggregator
+// sdk/event-stream/reader.ts — typed JSONL reader + aggregator
 // (Plan 22-05).
 //
 // `readEvents()` is a streaming async iterator over the persisted event

package/{scripts/lib → sdk}/event-stream/types.ts

@@ -1,4 +1,4 @@
-// scripts/lib/event-stream/types.ts — typed event envelope + pre-registered
+// sdk/event-stream/types.ts — typed event envelope + pre-registered
 // event shapes, per Plan 20-06 (SDK-08).
 //
 // The event stream is the Phase 20+ observability primitive that every
@@ -24,7 +24,7 @@
 // Plan 20-04 owns the error taxonomy that feeds `ErrorEvent.payload`:
 // `{ code, message, kind }` mirrors `toToolError(err)` output.
 
-import type { Stage } from '../gdd-state/types.ts';
+import type { Stage } from '../state/types.ts';
 
 /** Writer-injected metadata. Never populated by callers. */
 export interface EventMeta {

package/{scripts/lib → sdk}/event-stream/writer.ts

@@ -1,4 +1,4 @@
-// scripts/lib/event-stream/writer.ts — append-only JSONL writer for the
+// sdk/event-stream/writer.ts — append-only JSONL writer for the
 // Phase 20+ telemetry stream (Plan 20-06, SDK-08).
 //
 // Design:

package/sdk/index.ts

@@ -0,0 +1,19 @@
+// sdk/index.ts — public SDK barrel (SC#15, D-04).
+//
+// Storybloq-style two-line-per-module re-export of the public SDK surface.
+// The documented import contract (sdk/README.md, D-04) prefers EXPLICIT
+// per-module paths (`@hegemonart/get-design-done/sdk/state`, `/sdk/cli`, …);
+// this barrel exists for callers who want a single entry point.
+//
+// NOTE: `state` re-exports the three taxonomy error classes
+// (TransitionGateFailed, LockAcquisitionError, ParseError) verbatim from
+// `errors`, so the overlapping names resolve to a single shared binding —
+// `export *` keeps them (no ambiguity, since both paths point at the same
+// identity). The full public surface (read/mutate/transition, appendEvent/
+// getWriter/…, the GDDError taxonomy, the CLI dispatch/main/USAGE) is
+// reachable through this barrel and through the explicit per-module paths.
+
+export * from './state/index.ts';
+export * from './event-stream/index.ts';
+export * from './errors/index.ts';
+export * from './cli/index.ts';