@hegemonart/get-design-done 1.21.0 → 1.22.0

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

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;
+}

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';
   }