@hegemonart/get-design-done 1.20.0 → 1.22.0

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

@@ -112,6 +112,112 @@ export type ErrorEvent = BaseEvent & {
   payload: { code: string; message: string; kind: string };
 };
 
+// ---------------------------------------------------------------------------
+// Phase 22 — pre-registered subtypes expansion (Plan 22-01)
+// ---------------------------------------------------------------------------
+
+/** Wave orchestration — Plan 21 parallel-mapper / wave execution. */
+export type WaveStartedEvent = BaseEvent & {
+  type: 'wave.started';
+  payload: { wave: string; plan_count: number };
+};
+export type WaveCompletedEvent = BaseEvent & {
+  type: 'wave.completed';
+  payload: { wave: string; duration_ms: number; outcome: 'pass' | 'fail' };
+};
+
+/** STATE.md mutation lifecycle (Plan 20-03). */
+export type BlockerAddedEvent = BaseEvent & {
+  type: 'blocker.added';
+  payload: { id: string; summary: string; source: string };
+};
+export type DecisionAddedEvent = BaseEvent & {
+  type: 'decision.added';
+  payload: { id: string; summary: string; source: string };
+};
+export type MustHaveAddedEvent = BaseEvent & {
+  type: 'must_have.added';
+  payload: { id: string; summary: string; source: string };
+};
+
+/** Parallelism decision engine output — Plan 21 explore-parallel-runner. */
+export type ParallelismVerdictEvent = BaseEvent & {
+  type: 'parallelism.verdict';
+  payload: { task_ids: string[]; verdict: 'parallel' | 'sequential'; reason: string };
+};
+
+/** Phase 10.1 cost-telemetry event-stream sink. */
+export type CostUpdateEvent = BaseEvent & {
+  type: 'cost.update';
+  payload: { agent: string; tier: string; usd: number; tokens_in: number; tokens_out: number };
+};
+
+/** Rate-guard / backoff stream (Plan 20-10, 20-11). */
+export type RateLimitEvent = BaseEvent & {
+  type: 'rate_limit';
+  payload: { provider: string; reset_at: string; remaining: number };
+};
+export type ApiRetryEvent = BaseEvent & {
+  type: 'api.retry';
+  payload: { provider: string; attempt: number; delay_ms: number; reason: string };
+};
+
+/** Context-window churn; emitted by `hooks/context-exhaustion.ts`. */
+export type CompactBoundaryEvent = BaseEvent & {
+  type: 'compact.boundary';
+  payload: { tokens_before: number; tokens_after: number };
+};
+
+/** MCP liveness probe from connection-probe primitive (Plan 22-08). */
+export type McpProbeEvent = BaseEvent & {
+  type: 'mcp.probe';
+  payload: { name: string; status: 'ok' | 'degraded' | 'down'; latency_ms?: number };
+};
+
+/** Reflector proposal (Phase 11 post-cycle reflector → event stream). */
+export type ReflectionProposedEvent = BaseEvent & {
+  type: 'reflection.proposed';
+  payload: { kind: string; target_file: string; summary: string };
+};
+
+/** Connection state transitions emitted by `connection-probe` (Plan 22-08). */
+export type ConnectionStatusChangeEvent = BaseEvent & {
+  type: 'connection.status_change';
+  payload: { name: string; from: string; to: string };
+};
+
+/** Per-tool-call trajectory (Plan 22-03). */
+export type ToolCallStartedEvent = BaseEvent & {
+  type: 'tool_call.started';
+  payload: { tool: string; args_hash: string };
+};
+export type ToolCallCompletedEvent = BaseEvent & {
+  type: 'tool_call.completed';
+  payload: {
+    tool: string;
+    args_hash: string;
+    result_hash: string;
+    latency_ms: number;
+    status: 'ok' | 'error';
+  };
+};
+
+/** Agent-level lifecycle (Plan 21 pipeline-runner / subagent spawn). */
+export type AgentSpawnEvent = BaseEvent & {
+  type: 'agent.spawn';
+  payload: { agent: string; task_id?: string; tier?: string };
+};
+export type AgentOutcomeEvent = BaseEvent & {
+  type: 'agent.outcome';
+  payload: {
+    agent: string;
+    task_id?: string;
+    outcome: 'pass' | 'fail' | 'halted';
+    duration_ms: number;
+    cost_usd?: number;
+  };
+};
+
 /**
  * Union of all pre-registered event types. Not a closed enum at the
  * envelope level — callers can emit unknown types — but downstream
@@ -124,4 +230,52 @@ export type KnownEvent =
   | StageEnteredEvent
   | StageExitedEvent
   | HookFiredEvent
-  | ErrorEvent;
+  | ErrorEvent
+  | WaveStartedEvent
+  | WaveCompletedEvent
+  | BlockerAddedEvent
+  | DecisionAddedEvent
+  | MustHaveAddedEvent
+  | ParallelismVerdictEvent
+  | CostUpdateEvent
+  | RateLimitEvent
+  | ApiRetryEvent
+  | CompactBoundaryEvent
+  | McpProbeEvent
+  | ReflectionProposedEvent
+  | ConnectionStatusChangeEvent
+  | ToolCallStartedEvent
+  | ToolCallCompletedEvent
+  | AgentSpawnEvent
+  | AgentOutcomeEvent;
+
+/**
+ * Runtime list of all pre-registered event `type` strings. Used by the
+ * Phase 22 baseline test and the CLI transport's `--list-types`
+ * subcommand.
+ */
+export const KNOWN_EVENT_TYPES: readonly string[] = [
+  'state.mutation',
+  'state.transition',
+  'stage.entered',
+  'stage.exited',
+  'hook.fired',
+  'error',
+  'wave.started',
+  'wave.completed',
+  'blocker.added',
+  'decision.added',
+  'must_have.added',
+  'parallelism.verdict',
+  'cost.update',
+  'rate_limit',
+  'api.retry',
+  'compact.boundary',
+  'mcp.probe',
+  'reflection.proposed',
+  'connection.status_change',
+  'tool_call.started',
+  'tool_call.completed',
+  'agent.spawn',
+  'agent.outcome',
+] as const;

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

@@ -21,11 +21,64 @@
 //     `payload` with `{ _truncated_placeholder: true }`, then re-serialize
 //     and stamp `_truncated: true` on the line.
 
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, resolve, isAbsolute, join } from 'node:path';
+import { createRequire } from 'node:module';
 
 import type { BaseEvent } from './types.ts';
 
+// Phase 22 Plan 22-02: write-time secret scrubbing. `redact()` deep-walks
+// the event and replaces secret-shaped strings with `[REDACTED:<type>]`
+// placeholders before serialization. Loaded via createRequire so the
+// CommonJS `redact.cjs` interops cleanly. We avoid `import.meta.url` —
+// tsc's Node16 module mode classifies this .ts file as CJS output for
+// typecheck purposes (even though it runs as ESM under
+// `--experimental-strip-types`), and `import.meta` is forbidden in CJS
+// output. Mirror the pattern from `scripts/lib/session-runner/errors.ts`:
+// anchor createRequire on the repo-root package.json discovered by
+// walking up from `process.cwd()`.
+function _findRepoRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+// Soft load: if redact.cjs is unreachable from the runtime cwd (e.g. a
+// hook subprocess running in a temp test dir three directories above
+// the plugin root), fall through to the identity function. The writer
+// keeps working — events just aren't scrubbed in that environment.
+// Production callers always run from inside the plugin tree.
+let _redact: (v: unknown) => unknown;
+try {
+  const _root = _findRepoRoot();
+  const _candidate = resolve(_root, 'scripts/lib/redact.cjs');
+  if (existsSync(_candidate)) {
+    const _redactRequire = createRequire(join(_root, 'package.json'));
+    const _mod = _redactRequire(_candidate) as { redact: (v: unknown) => unknown };
+    _redact = _mod.redact;
+  } else {
+    // Fallback: also try walking up from this source file's logical
+    // position (3 dirs above writer.ts → repo root).
+    const _altRoot = resolve(_root, '..', '..');
+    const _altCandidate = resolve(_altRoot, 'scripts/lib/redact.cjs');
+    if (existsSync(_altCandidate)) {
+      const _altRequire = createRequire(join(_altRoot, 'package.json'));
+      const _altMod = _altRequire(_altCandidate) as { redact: (v: unknown) => unknown };
+      _redact = _altMod.redact;
+    } else {
+      _redact = (v) => v;
+    }
+  }
+} catch {
+  _redact = (v) => v;
+}
+const redact = _redact;
+
 /** Default relative path for the persisted event stream. */
 export const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
 
@@ -113,22 +166,26 @@ export class EventWriter {
    * {@link append}.
    */
   serialize(ev: BaseEvent): string {
-    const raw = JSON.stringify(ev) + '\n';
+    // Phase 22 Plan 22-02: scrub secrets from the entire event (envelope +
+    // payload) before serialization. Redaction is non-mutating and runs
+    // exactly once per event, here at the write boundary.
+    const scrubbed = redact(ev) as BaseEvent;
+    const raw = JSON.stringify(scrubbed) + '\n';
     if (Buffer.byteLength(raw, 'utf8') <= this.maxLineBytes) {
       return raw;
     }
 
     // Truncate: keep envelope fields, drop payload content.
     const truncated: BaseEvent = {
-      type: ev.type,
-      timestamp: ev.timestamp,
-      sessionId: ev.sessionId,
+      type: scrubbed.type,
+      timestamp: scrubbed.timestamp,
+      sessionId: scrubbed.sessionId,
       payload: { _truncated_placeholder: true },
       _truncated: true,
     };
-    if (ev.stage !== undefined) truncated.stage = ev.stage;
-    if (ev.cycle !== undefined) truncated.cycle = ev.cycle;
-    if (ev._meta !== undefined) truncated._meta = ev._meta;
+    if (scrubbed.stage !== undefined) truncated.stage = scrubbed.stage;
+    if (scrubbed.cycle !== undefined) truncated.cycle = scrubbed.cycle;
+    if (scrubbed._meta !== undefined) truncated._meta = scrubbed._meta;
     return JSON.stringify(truncated) + '\n';
   }
 

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

@@ -0,0 +1,294 @@
+// scripts/lib/explore-parallel-runner/index.ts — Plan 21-06 (SDK-18).
+//
+// Public surface:
+//
+//   run(opts: ExploreRunnerOptions): Promise<ExploreRunnerResult>
+//   DEFAULT_MAPPERS — the locked Phase-21 4-mapper roster (frozen).
+//   isParallelismSafe, spawnMapper, spawnMappersParallel (from mappers.ts)
+//   synthesizeStreaming (from synthesizer.ts)
+//   Types (from types.ts) — MapperName, MapperSpec, MapperOutcome,
+//     ExploreRunnerOptions, ExploreRunnerResult.
+//
+// Algorithm:
+//   1. specs = opts.mappers ?? DEFAULT_MAPPERS.
+//   2. Partition by isParallelismSafe(spec.agentPath).
+//   3. Run safe mappers via spawnMappersParallel(concurrency).
+//   4. Run unsafe mappers sequentially (tail phase).
+//   5. Run synthesizer via synthesizeStreaming.
+//   6. Aggregate total_usage = sum mapper + synthesizer.
+//   7. Emit logger + explore.runner.* lifecycle events.
+//   8. Return ExploreRunnerResult.
+//
+// Empty specs short-circuits: no mappers spawned, synthesizer skipped,
+// returns an all-zero result.
+
+import { resolve as resolvePath } from 'node:path';
+
+import { getLogger } from '../logger/index.ts';
+
+import {
+  isParallelismSafe,
+  spawnMapper,
+  spawnMappersParallel,
+} from './mappers.ts';
+import { synthesizeStreaming } from './synthesizer.ts';
+import type {
+  ExploreRunnerOptions,
+  ExploreRunnerResult,
+  MapperOutcome,
+  MapperSpec,
+} from './types.ts';
+
+// Re-exports.
+export type {
+  MapperName,
+  MapperSpec,
+  MapperOutcome,
+  ExploreRunnerOptions,
+  ExploreRunnerResult,
+} from './types.ts';
+export {
+  isParallelismSafe,
+  spawnMapper,
+  spawnMappersParallel,
+} from './mappers.ts';
+export { synthesizeStreaming } from './synthesizer.ts';
+
+// ---------------------------------------------------------------------------
+// DEFAULT_MAPPERS — locked Phase-21 roster
+// ---------------------------------------------------------------------------
+
+/**
+ * Locked 4-mapper roster for the explore stage. Frozen end-to-end so
+ * consumers can't mutate entries; override via ExploreRunnerOptions.mappers.
+ *
+ * Agent paths use the exact filenames from `agents/` (as of Phase 21):
+ *   token-mapper.md, component-taxonomy-mapper.md, a11y-mapper.md,
+ *   visual-hierarchy-mapper.md.
+ *
+ * When an agent file is missing, session-runner scope computation
+ * gracefully falls through to the stage default (see mappers.ts).
+ */
+export const DEFAULT_MAPPERS: readonly MapperSpec[] = Object.freeze([
+  Object.freeze({
+    name: 'token' as const,
+    agentPath: 'agents/token-mapper.md',
+    outputPath: '.design/map/token.md',
+    prompt:
+      'Enumerate every design token found in the UI source: colors, typography, spacing, radii, shadows, motion durations. Output to .design/map/token.md as a canonical token inventory.',
+  }),
+  Object.freeze({
+    name: 'component-taxonomy' as const,
+    agentPath: 'agents/component-taxonomy-mapper.md',
+    outputPath: '.design/map/component-taxonomy.md',
+    prompt:
+      'Enumerate component archetypes and their variants. Output to .design/map/component-taxonomy.md — one entry per archetype with variant list, slot inventory, and usage count.',
+  }),
+  Object.freeze({
+    name: 'a11y' as const,
+    agentPath: 'agents/a11y-mapper.md',
+    outputPath: '.design/map/a11y.md',
+    prompt:
+      'WCAG-axis scan: contrast ratios, keyboard navigation, ARIA semantics, focus management, reduced-motion respect. Output to .design/map/a11y.md — one section per axis with findings.',
+  }),
+  Object.freeze({
+    name: 'visual-hierarchy' as const,
+    agentPath: 'agents/visual-hierarchy-mapper.md',
+    outputPath: '.design/map/visual-hierarchy.md',
+    prompt:
+      'Describe z-order, focal points, and attention grammar. Output to .design/map/visual-hierarchy.md — one section per surface describing layering, emphasis, and scan path.',
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// run — main orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn the 4 mapper sessions (parallel) + the synthesizer (sequential
+ * after mappers become stable), aggregate usage, emit lifecycle events,
+ * return terminal ExploreRunnerResult.
+ *
+ * Contract:
+ *   * Never throws. All failure modes land as outcomes / synth status.
+ *   * Individual mapper errors do NOT abort other mappers.
+ *   * parallelism_safe: false mappers run serially AFTER the safe batch.
+ *   * total_usage aggregates mappers + synthesizer.
+ */
+export async function run(
+  opts: ExploreRunnerOptions,
+): Promise<ExploreRunnerResult> {
+  const specs: readonly MapperSpec[] = opts.mappers ?? DEFAULT_MAPPERS;
+  const cwd: string = opts.cwd ?? process.cwd();
+  const concurrency: number = opts.concurrency ?? 4;
+
+  const logger = getLogger().child('explore.runner');
+
+  const outputPath: string = resolvePath(cwd, '.design/DESIGN-PATTERNS.md');
+
+  logger.info('explore.runner.started', {
+    mapper_count: specs.length,
+    concurrency,
+  });
+
+  // Empty-spec short-circuit — no mappers, no synthesizer, zero usage.
+  if (specs.length === 0) {
+    logger.info('explore.runner.completed', {
+      parallel_count: 0,
+      serial_count: 0,
+      synthesizer_status: 'skipped',
+      total_usd_cost: 0,
+    });
+    return Object.freeze({
+      mappers: Object.freeze([]),
+      synthesizer: Object.freeze({
+        status: 'skipped' as const,
+        output_path: outputPath,
+        usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+        files_fed: Object.freeze([]),
+      }),
+      parallel_count: 0,
+      serial_count: 0,
+      total_usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    });
+  }
+
+  // --- Partition specs by parallelism_safe frontmatter ---------------------
+  const safeSpecs: MapperSpec[] = [];
+  const serialSpecs: MapperSpec[] = [];
+  for (const spec of specs) {
+    const resolvedAgentPath: string = resolvePath(cwd, spec.agentPath);
+    if (isParallelismSafe(resolvedAgentPath)) {
+      safeSpecs.push(spec);
+    } else {
+      serialSpecs.push(spec);
+    }
+  }
+
+  // --- Parallel batch ------------------------------------------------------
+  const parallelOutcomes: readonly MapperOutcome[] =
+    safeSpecs.length > 0
+      ? await spawnMappersParallel(safeSpecs, {
+          concurrency,
+          budget: opts.budget,
+          maxTurns: opts.maxTurnsPerMapper,
+          cwd,
+          ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+        })
+      : Object.freeze([]);
+
+  for (const o of parallelOutcomes) {
+    logger.info('explore.runner.mapper_done', {
+      mapper: o.name,
+      status: o.status,
+      duration_ms: o.duration_ms,
+      output_exists: o.output_exists,
+      output_bytes: o.output_bytes,
+      mode: 'parallel',
+    });
+  }
+
+  // --- Serial tail --------------------------------------------------------
+  const serialOutcomes: MapperOutcome[] = [];
+  for (const spec of serialSpecs) {
+    const spawnOpts: Parameters<typeof spawnMapper>[1] = {
+      budget: opts.budget,
+      maxTurns: opts.maxTurnsPerMapper,
+      cwd,
+      ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+    };
+    const outcome = await spawnMapper(spec, spawnOpts);
+    serialOutcomes.push(outcome);
+    logger.info('explore.runner.mapper_done', {
+      mapper: outcome.name,
+      status: outcome.status,
+      duration_ms: outcome.duration_ms,
+      output_exists: outcome.output_exists,
+      output_bytes: outcome.output_bytes,
+      mode: 'serial',
+    });
+  }
+
+  // --- Merge outcomes in ORIGINAL spec order -------------------------------
+  //
+  // Callers rely on `.mappers[i]` pairing with `opts.mappers[i]` (or
+  // DEFAULT_MAPPERS[i]). We rebuild by indexing the name→outcome map.
+  const byName: Map<string, MapperOutcome> = new Map();
+  for (const o of parallelOutcomes) byName.set(o.name, o);
+  for (const o of serialOutcomes) byName.set(o.name, o);
+  const mergedOutcomes: MapperOutcome[] = specs.map((s) => {
+    const o = byName.get(s.name);
+    if (o === undefined) {
+      // Shouldn't happen unless partitioning dropped a spec. Surface
+      // as a synthetic error outcome rather than throwing.
+      return Object.freeze({
+        name: s.name,
+        status: 'error',
+        output_exists: false,
+        output_bytes: 0,
+        usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+        duration_ms: 0,
+        error: Object.freeze({
+          code: 'PARTITION_LOST',
+          message: `mapper ${s.name} was not executed by either batch`,
+        }),
+      });
+    }
+    return o;
+  });
+
+  // --- Synthesizer --------------------------------------------------------
+  logger.info('explore.runner.synthesizer_started', {
+    mappers_ready: mergedOutcomes.filter((m) => m.output_exists).length,
+    mappers_total: mergedOutcomes.length,
+  });
+
+  const synthResult = await synthesizeStreaming({
+    mapperNames: specs.map((s) => s.name),
+    mapperOutputPaths: specs.map((s) => s.outputPath),
+    synthesizerPrompt: opts.synthesizerPrompt,
+    budget: opts.synthesizerBudget,
+    maxTurns: opts.synthesizerMaxTurns,
+    cwd,
+    ...(opts.runOverride !== undefined ? { runOverride: opts.runOverride } : {}),
+    ...(opts.pollIntervalMs !== undefined ? { pollIntervalMs: opts.pollIntervalMs } : {}),
+    ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+  });
+
+  // --- Aggregate usage ----------------------------------------------------
+  let totalInput = synthResult.usage.input_tokens;
+  let totalOutput = synthResult.usage.output_tokens;
+  let totalCost = synthResult.usage.usd_cost;
+  for (const m of mergedOutcomes) {
+    totalInput += m.usage.input_tokens;
+    totalOutput += m.usage.output_tokens;
+    totalCost += m.usage.usd_cost;
+  }
+
+  logger.info('explore.runner.completed', {
+    parallel_count: safeSpecs.length,
+    serial_count: serialSpecs.length,
+    synthesizer_status: synthResult.status,
+    total_usd_cost: totalCost,
+    total_input_tokens: totalInput,
+    total_output_tokens: totalOutput,
+  });
+
+  return Object.freeze({
+    mappers: Object.freeze(mergedOutcomes),
+    synthesizer: Object.freeze({
+      status: synthResult.status,
+      output_path: synthResult.output_path,
+      usage: synthResult.usage,
+      files_fed: synthResult.files_fed,
+      ...(synthResult.error !== undefined ? { error: synthResult.error } : {}),
+    }),
+    parallel_count: safeSpecs.length,
+    serial_count: serialSpecs.length,
+    total_usage: {
+      input_tokens: totalInput,
+      output_tokens: totalOutput,
+      usd_cost: totalCost,
+    },
+  });
+}