@hegemonart/get-design-done 1.21.0 → 1.23.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.21.0"
+    "version": "1.23.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.21.0",
+      "version": "1.23.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,190 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.23.0] — 2026-04-25
+
+Phase 23 GDD SDK Domain Primitives milestone — lands the highest-leverage code primitives from the ROADMAP "GDD SDK Domain Primitives" entry as typed Node modules with tests. 10 atomic plans (23-01 through 23-10), additive — every Phase 20/21/22 consumer keeps working unchanged. Distribution as separate `@hegemonart/gdd-sdk` npm package and screenshot-capture orchestration are explicitly deferred to follow-up phases.
+
+### Added
+
+- **JSON output contracts** — `reference/output-contracts/planner-decision.schema.json` + `verifier-decision.schema.json` (Draft-07). `scripts/lib/parse-contract.cjs` gains `parsePlannerDecision()` and `parseVerifierDecision()` riding the same extract→parse→validate pipeline as the existing `parseMotionMap`. Lets `/gdd:synthesize` consume planner output without regex-parsing markdown headings, and lets executor↔verifier ping-pong on a typed envelope. (Plan 23-01)
+
+- **Solidify-with-rollback gate** — `scripts/lib/design-solidify.mjs` runs the typecheck/build/targeted-test triplet for a task and, on any failure, rolls the working tree back via `git stash` (configurable: `stash` | `hard` | `none`) and emits a `solidify.rollback` event onto the Phase 22 causal chain. Optional `emit()` callback for event-stream telemetry sink. Authored as `.mjs` to sidestep the Phase 22 Node 24 + Windows + .mjs↔.ts loader bug. (Plan 23-02)
+
+- **Touches: analyzer + parallelism decision engine** — `scripts/lib/touches-analyzer/index.cjs` parses `Touches:` lines from task markdown into glob lists and produces a pairwise verdict (`parallel` | `sequential`) for any two tasks. Encodes today's prompt-only heuristic into auditable code. Verdict rules (first match wins): empty → unknown-touches; literal equality → shared-glob; shared component dir → shared-component-dir; resolved-file overlap → shared-file; otherwise → disjoint. (Plan 23-03)
+
+- **Audit aggregator** — `scripts/lib/audit-aggregator/index.cjs` takes `Array<Finding>` from N audit-agents, dedups by `{file, line, rule_id}`, scores via severity-weighted formula (P0:8/P1:4/P2:2/P3:1), and returns sorted top-N + tally summary. Default merge picks higher-confidence → higher-severity → lex-earliest agent → first-seen. Confidence outside `[0, 1]` clamped with one `process.emitWarning` per call. Cross-platform path normalization. (Plan 23-04)
+
+- **Reference resolver** — `scripts/lib/reference-resolver.cjs` adds the resolution direction on top of the Phase 14.5 reference-registry. `resolve('forms')` / `resolve('type:forms')` → `{name, path, type, excerpt}` with a 200-char excerpt suitable for inlining into agent prompts. Lookup order: exact name → slug match → singularize fuzzy → type-only-when-unique. Ambiguous match throws `RangeError` with candidates. `resolveAll(keys, {ignoreMissing})` for bulk. `excerptOf(path, {maxChars})` strips frontmatter / fenced code / HTML comments / markdown headers. (Plan 23-05)
+
+- **Touches pattern miner** — `scripts/lib/touches-pattern-miner.cjs` scans `.design/archive/cycle-*/tasks/*.md` after `/gdd:complete-cycle`, canonicalizes signatures (lowercase + backslash-normalize + cycle-slug strip + dedup + sort), and proposes crystallization candidates when a signature recurs in ≥3 tasks across ≥2 cycles. Writes `.design/learnings/touches-patterns.json` atomically (`.tmp` + rename). **NEVER auto-applies** — `/gdd:apply-reflections` is the materialization gate. (Plan 23-06)
+
+- **Image diff + visual baseline manager** — `scripts/lib/visual-baseline/diff.cjs` compares two PNG buffers. With `pngjs` installed (probeOptional), decodes both and counts pixels whose R/G/B/A channels differ beyond the tolerance (default 4). Without `pngjs`, falls back to bytewise SHA-256 equality. `scripts/lib/visual-baseline/index.cjs` exposes `compareToBaseline(key, pngBuffer)` and `applyBaseline(key, pngBuffer)`; reads/writes `.design/baselines/<key>.png`; rejects path-traversal keys. `pngjs@7` declared as optional dep. Defers Playwright/Preview MCP screenshot capture orchestration to a later phase. (Plan 23-07)
+
+- **Design-token reader (multi-source)** — `scripts/lib/design-tokens/index.cjs` facades over four pure-JS readers producing the uniform `{tokens, source, format, warnings}` shape:
+  - `css-vars.cjs` — extracts `--token: value;` from CSS/SCSS, last-write-wins, strips block comments, warns on `$scss-vars`
+  - `js-const.cjs` — spawn-node harness evaluates CJS/ESM exports, recognises `{tokens: …}` / default / direct bag, flattens nested with `.` separator
+  - `tailwind.cjs` — same harness, walks `theme` + `theme.extend` per scale (extend overrides base)
+  - `figma.cjs` — parses `{variableCollections}` shape OR already-flattened bag; emits `rgb(R, G, B)` for color values, per-mode tokens for multi-mode variables
+  Auto-detection by extension + content sniff. (Plan 23-08)
+
+- **Domain primitives bundle** — three checkers sharing a single hit shape (`{rule_id, severity P0-P3, summary, evidence?, line?, file}`):
+  - `domain-primitives/nng.cjs` — runs grep-style heuristic rules loaded from `reference/heuristics.md` fenced yaml blocks; caller may inject `opts.rules` to bypass file-load
+  - `domain-primitives/anti-patterns.cjs` — same yaml extractor against `reference/anti-patterns.md`
+  - `domain-primitives/wcag.cjs` (no axe-core dep) — `contrastRatio()` (WCAG 1.4.3 luminance), `checkContrast({fg, bg, level: AA|AAA})`, `checkTapTarget({width, height, level})` (AA 24×24, AAA 44×44), `checkAriaLabels({content})` (interactive elements without text + aria-label)
+  Both NNG + anti-pattern files allow no parseable yaml today (treated as empty registry); robust to gradual rule population. (Plan 23-09)
+
+### Changed
+
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.23.0`.
+- `test-fixture/baselines/phase-20/resilience-primitives.txt` gains `reference-resolver.cjs` (alphabetical between `reference-registry.cjs` and `relevance-counter.cjs`) and `touches-pattern-miner.cjs` (alphabetical at end).
+
+### Tests
+
+- `tests/output-contracts-23-01.test.cjs` — planner + verifier contracts (14 tests)
+- `tests/design-solidify.test.cjs` — solidify gate, all rollback modes (6)
+- `tests/touches-analyzer.test.cjs` — parser + verdict + matrix (17)
+- `tests/audit-aggregator.test.cjs` — dedup + score + tallies (15)
+- `tests/reference-resolver.test.cjs` — resolution rules + excerpts (12)
+- `tests/touches-pattern-miner.test.cjs` — canonicalize + thresholds + atomic write (10)
+- `tests/visual-baseline.test.cjs` — diff modes + baseline round-trip (14, pngjs-optional path skipped when absent)
+- `tests/design-tokens.test.cjs` — 4 readers + facade auto-detect (15)
+- `tests/domain-primitives.test.cjs` — NNG + anti-pattern + WCAG checkers (18)
+- `tests/phase-23-baseline.test.cjs` — Phase 23 regression baseline (12)
+
+Total: 133 new tests. All Phase 20/21/22 tests still green.
+
+### Deferred
+
+- **`@hegemonart/gdd-sdk` separate npm package** — out of scope; build/packaging project of its own.
+- **Screenshot capture orchestration** (Playwright + Claude Preview MCP wrapper) — needs live MCP infra to validate.
+- **Spec↔code↔visual triangulation verifier** — depends on Phase 16/17 component specs being fleshed out.
+- **Knowledge-graph typed query layer** + cycle/workstream model SDK + pause/resume context serializer SDK + per-stage budget allocator SDK + git operations primitive + handoff bundle parser + intel store typed reader/writer — each is roadmap-text-sized and warrants its own phase scope.
+
+---
+
+## [1.22.0] — 2026-04-25
+
+Phase 22 GDD SDK Observability milestone — the single-typed `BaseEvent` envelope from Phase 20 grows into a queryable, redacted, transport-able observability layer with tail/grep/WebSocket consumers and a causal event chain. 10 plans (22-01 through 22-10), additive — every Phase 20 + Phase 21 consumer keeps working unchanged.
+
+### Added
+
+- **Expanded event-type registry** — 17 new pre-registered subtypes alongside
+  the 6 from Phase 20: `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`. The envelope
+  remains open (`type: string`); the `KnownEvent` union is an additive
+  overlay for typed `switch` consumers. Runtime `KNOWN_EVENT_TYPES` list
+  exported for the CLI's `list-types` subcommand. (Plan 22-01)
+
+- **Secret scrubber** — `scripts/lib/redact.cjs` deep-walks every event
+  payload and replaces secret-shaped strings with `[REDACTED:<type>]`
+  placeholders. Patterns: `sk-ant-…` (anthropic), `sk_live_…` (stripe),
+  `xox[baprs]-…` (slack), `ghp_…` (github_pat), `AKIA…` (aws), generic
+  `sk-…`, `eyJ…` JWTs, and full `-----BEGIN/END-----` PEM blocks.
+  Wired into `EventWriter.serialize()` so every event hitting disk and
+  every bus subscriber sees the scrubbed form — single rule everywhere,
+  no escape hatch. (Plan 22-02)
+
+- **Per-tool-call trajectory stream** — `.design/telemetry/trajectories/<cycle>.jsonl`
+  receives one line per agent tool-use:
+  `{ts, agent, tool, args_hash, result_hash, latency_ms, status}`.
+  Args + result are sha256-prefix-hashed (16 chars) — line size stays
+  bounded; prompt content stays de-identified. Captured by the new
+  PostToolUse:Agent hook `hooks/gdd-trajectory-capture.js`. (Plan 22-03)
+
+- **Append-only event chain** — `.design/gep/events.jsonl` (gep =
+  "GDD Event Provenance"). One line per causal hop: `{event_id,
+  parent_event_id, ts, agent, decision_refs, outcome, rollback_reason?}`.
+  `appendChainEvent()` auto-generates UUIDs; `walkParents()` traces a
+  row up to its root for `/gdd:audit --retroactive`. Cycle-safe; skips
+  invalid lines; lives separately from the firehose so audits don't
+  scan unrelated rows. (Plan 22-04)
+
+- **Typed event reader + aggregator** — `readEvents({path, type,
+  predicate, since, until})` returns an async streaming iterator over
+  `events.jsonl` (readline + createReadStream — no full-file load,
+  GB-scale logs OK). `aggregate()` rolls events up by type, stage,
+  cycle, agent + totals (count, error_count, truncated_count). Exposed
+  from the public event-stream API. (Plan 22-05)
+
+- **CLI transport** — `gdd-events` bin entry, subcommands:
+  `tail [--follow]` (250ms-poll follow mode, no native inotify dep);
+  `grep <terms…>` with hand-rolled filter language
+  (`type=foo`, `payload.x.y=bar`, `!type=baz`, multiple = AND);
+  `cat` pretty-print with timestamp+type prefix; `list-types` runtime
+  registry dump; `serve` for the WebSocket transport. (Plan 22-06)
+
+- **WebSocket transport** — `scripts/lib/transports/ws.cjs` exposes
+  `startServer({port, token, tailFrom?, subscribe?})`. Loaded via
+  `probeOptional('ws')` — clear install hint when absent. Auth:
+  `Authorization: Bearer <token>` on the upgrade; mismatched →
+  HTTP 401 close. Tail replay sends `tailFrom`'s contents to new
+  clients before subscribing them to the live bus. Fire-and-forget
+  delivery; closed sockets dropped silently. `ws@8` declared as
+  optional dep. (Plan 22-07)
+
+- **Connection probe primitive** — `scripts/lib/connection-probe/`
+  exposes `probe({name, cmd, timeout, retries, fallback})` →
+  `{status: 'ok'|'degraded'|'down', latency_ms, attempts,
+  fallback_used, error?}`. Backoff between retries via
+  `jittered-backoff.cjs`. State persisted at
+  `.design/telemetry/connection-state.json` (atomic .tmp+rename).
+  Status transitions emit `connection.status_change` events through a
+  caller-supplied `emit` callback — transitions only, not every probe.
+  Replaces ad-hoc bash probe snippets in `connections/`. (Plan 22-08)
+
+- **Hook → event-stream wire-in** — new `hooks/_hook-emit.js` shared
+  helper wraps `appendEvent()` in try/catch (hooks must NEVER throw on
+  telemetry failure). Wired hooks emit `hook.fired` events on every
+  decision: `gdd-bash-guard` (allow/block + severity + pattern),
+  `gdd-protected-paths` (allow/block + matched glob),
+  `gdd-decision-injector` (inject/no-hits + backend label).
+  Trajectory-capture (Plan 22-03) already emits via its own path.
+  Additive — zero behavior change to existing hook contracts. (Plan 22-09)
+
+### Changed
+
+- `EventWriter.serialize()` now runs `redact()` on the event before
+  JSON-stringifying. Persisted form is the canonical scrubbed form.
+  All 27 Phase 20 event-stream tests still pass. (Plan 22-02 wire-in)
+
+- `hooks.json` registers a new `PostToolUse:Agent` matcher pointing at
+  `gdd-trajectory-capture.js`. The existing `PreToolUse:Agent`
+  budget-enforcer is unaffected. (Plan 22-03 registration)
+
+### Tests
+
+- `tests/event-types-registry.test.ts` — registry expansion (4 tests)
+- `tests/redact.test.cjs` — secret scrubber (12 tests)
+- `tests/event-stream-redact-integration.test.ts` — write-time wire-in (2 tests)
+- `tests/trajectory-capture.test.cjs` — module + hook subprocess (7 tests)
+- `tests/event-chain.test.cjs` — chain + walk + cycle defense (10 tests)
+- `tests/event-reader.test.ts` — reader + aggregator (8 tests)
+- `tests/cli-events.test.cjs` — CLI subcommands + filter language (10 tests)
+- `tests/ws-transport.test.cjs` — WebSocket auth + replay + live (5 + 1 skip)
+- `tests/connection-probe-primitive.test.cjs` — retry + fallback + emit (9 tests)
+- `tests/hook-emit-wire.test.cjs` — bash-guard + protected-paths emission (4 tests)
+- `tests/phase-22-baseline.test.cjs` — Phase 22 regression baseline (12 tests)
+
+Total: 84 new tests. All Phase 20/21 tests still green.
+
+### Deferred
+
+- Grafana / Prometheus exporter (out of scope; code-primitive
+  observability shipped first).
+- Event-stream compaction / retention (`events.jsonl` grows unbounded;
+  Phase 22.x if needed).
+- Replay-on-subscribe semantics (bus stays live-only; transports that
+  want replay read `events.jsonl` directly, then subscribe live).
+- Wire-in for `gdd-mcp-circuit-breaker.js`, `budget-enforcer.ts`,
+  `context-exhaustion.ts`, `gdd-read-injection-scanner.ts` — flow is
+  more intricate; follow-up phase.
+
+---
+
 ## [1.21.0] — 2026-04-24
 
 Phase 21 GDD SDK Headless milestone — the plugin now runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI, and ships a full `gdd-sdk` CLI that executes the design pipeline without a harness. 12 plans (21-01 through 21-12), 50+ commits, 936 tests.

package/hooks/_hook-emit.js

@@ -0,0 +1,81 @@
+/**
+ * hooks/_hook-emit.js — shared `hook.fired` emitter for Phase 22 wire-in
+ * (Plan 22-09).
+ *
+ * Hooks must NEVER throw on telemetry failure — a broken event stream
+ * cannot block a tool call. This helper wraps appendEvent in try/catch
+ * and silently swallows.
+ *
+ * Why a wrapper instead of importing directly:
+ *   * Centralizes the try/catch so each hook stays terse.
+ *   * Loads the .ts event-stream lazily — hooks invoked via plain `node`
+ *     (no --experimental-strip-types) just no-op on telemetry instead
+ *     of crashing. The hooks.json registrations vary on whether they
+ *     pass --experimental-strip-types, and we don't want to forbid
+ *     plain-node invocation paths.
+ *   * Single place to add structured event sinks later (e.g. mirror to
+ *     CLI transport) without touching every hook file.
+ *
+ * Usage:
+ *   const { emitHookFired } = require('./_hook-emit.js');
+ *   // …decision computed…
+ *   emitHookFired('budget-enforcer', 'allow');
+ */
+
+'use strict';
+
+let cachedAppendEvent = null;
+let resolutionAttempted = false;
+
+/**
+ * Lazy-resolve `appendEvent` — only loads the event-stream module the
+ * first time a hook fires. Falls back to a no-op if the module is not
+ * loadable in the current runtime (e.g. plain `node` without
+ * --experimental-strip-types).
+ *
+ * @returns {(ev: unknown) => void}
+ */
+function getAppendEvent() {
+  if (cachedAppendEvent !== null || resolutionAttempted) {
+    return cachedAppendEvent || (() => {});
+  }
+  resolutionAttempted = true;
+  try {
+    // event-stream/index.ts requires --experimental-strip-types. Try
+    // require()'ing — if Node refuses to parse `.ts`, we silently fall
+    // back to no-op.
+    // eslint-disable-next-line node/no-missing-require, global-require
+    cachedAppendEvent = require('../scripts/lib/event-stream/index.ts').appendEvent;
+    return cachedAppendEvent;
+  } catch {
+    cachedAppendEvent = null;
+    return () => {};
+  }
+}
+
+/**
+ * Emit a `hook.fired` event. Silent on every failure mode.
+ *
+ * @param {string} hookName
+ * @param {string} decision
+ * @param {Record<string, unknown>} [extras] — opaque additional payload fields
+ */
+function emitHookFired(hookName, decision, extras) {
+  try {
+    const appendEvent = getAppendEvent();
+    const payload = { hook: hookName, decision };
+    if (extras && typeof extras === 'object') {
+      Object.assign(payload, extras);
+    }
+    appendEvent({
+      type: 'hook.fired',
+      timestamp: new Date().toISOString(),
+      sessionId: process.env.GDD_SESSION_ID || 'hook',
+      payload,
+    });
+  } catch {
+    /* hooks must never throw on telemetry */
+  }
+}
+
+module.exports = { emitHookFired };

package/hooks/gdd-bash-guard.js

@@ -15,6 +15,7 @@
 
 const path = require('path');
 const { match } = require(path.join(__dirname, '..', 'scripts', 'lib', 'dangerous-patterns.cjs'));
+const { emitHookFired } = require('./_hook-emit.js'); // Plan 22-09 wire-in
 
 async function main() {
   let buf = '';
@@ -22,11 +23,13 @@ async function main() {
 
   let payload;
   try { payload = JSON.parse(buf || '{}'); } catch {
+    emitHookFired('gdd-bash-guard', 'allow', { reason: 'parse-error' });
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
 
   if (payload?.tool_name && payload.tool_name !== 'Bash') {
+    emitHookFired('gdd-bash-guard', 'allow', { reason: 'non-bash-tool' });
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
@@ -34,6 +37,10 @@ async function main() {
   const command = payload?.tool_input?.command ?? '';
   const r = match(command);
   if (r.matched) {
+    emitHookFired('gdd-bash-guard', 'block', {
+      severity: r.severity,
+      pattern: r.pattern,
+    });
     process.stdout.write(JSON.stringify({
       continue: false,
       stopReason: `gdd-bash-guard: dangerous command blocked (${r.severity}): ${r.description} [${r.pattern}]`,
@@ -41,6 +48,7 @@ async function main() {
     return;
   }
 
+  emitHookFired('gdd-bash-guard', 'allow', { reason: 'no-match' });
   process.stdout.write(JSON.stringify({ continue: true }));
 }
 

package/hooks/gdd-decision-injector.js

@@ -203,10 +203,12 @@ async function main() {
   const backendLabel = BACKEND || (useRgGlobal ? 'ripgrep' : 'node-grep');
   const block = buildRecallBlock(hits, basename, backendLabel);
   if (!block) {
+    try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'no-hits', { backend: backendLabel }); } catch { /* swallow */ }
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
 
+  try { require('./_hook-emit.js').emitHookFired('gdd-decision-injector', 'inject', { backend: backendLabel, hit_count: hits.length }); } catch { /* swallow */ }
   process.stdout.write(JSON.stringify({
     continue: true,
     hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: block },

package/hooks/gdd-protected-paths.js

@@ -98,6 +98,11 @@ async function main() {
       : cand.replace(/\\/g, '/');
     const r = matches(rel, protectedPaths);
     if (r.matched) {
+      try {
+        require('./_hook-emit.js').emitHookFired('gdd-protected-paths', 'block', {
+          path: rel, pattern: r.pattern,
+        });
+      } catch { /* swallow */ }
       process.stdout.write(JSON.stringify({
         continue: false,
         stopReason: `gdd-protected-paths: '${rel}' is a protected path (matched '${r.pattern}'). To override, lift the path from the default glob list or explicitly edit via an approved workflow (e.g., /gdd:update, plan execution).`,
@@ -106,6 +111,9 @@ async function main() {
     }
   }
 
+  try {
+    require('./_hook-emit.js').emitHookFired('gdd-protected-paths', 'allow');
+  } catch { /* swallow */ }
   process.stdout.write(JSON.stringify({ continue: true }));
 }
 

package/hooks/gdd-trajectory-capture.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * gdd-trajectory-capture.js — PostToolUse:Agent hook (Plan 22-03).
+ *
+ * Reads the standard Claude Code hook JSON from stdin:
+ *   { tool_name, tool_input, tool_response, session_id, ... }
+ *
+ * Writes one JSONL line to `.design/telemetry/trajectories/<cycle>.jsonl`
+ * via `scripts/lib/trajectory/index.cjs`. Silent-on-failure: telemetry
+ * never blocks the parent agent's tool call.
+ *
+ * Cycle resolution:
+ *   * env var GDD_CYCLE wins (used by Phase 21 pipeline runner)
+ *   * fallback: 'current'
+ */
+
+'use strict';
+
+const { recordCall } = require('../scripts/lib/trajectory/index.cjs');
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  raw += chunk;
+});
+process.stdin.on('end', () => {
+  try {
+    const input = raw.trim() ? JSON.parse(raw) : {};
+    const toolName = input.tool_name || input.toolName || 'unknown';
+    const toolInput = input.tool_input ?? input.toolInput ?? null;
+    const toolResponse = input.tool_response ?? input.toolResponse ?? null;
+    const sessionId = input.session_id ?? input.sessionId ?? null;
+    const status =
+      toolResponse && typeof toolResponse === 'object' && toolResponse.is_error === true
+        ? 'error'
+        : 'ok';
+    const latency = typeof input.latency_ms === 'number' ? input.latency_ms : 0;
+
+    recordCall({
+      cycle: process.env.GDD_CYCLE || 'current',
+      session_id: sessionId,
+      agent: input.agent || process.env.GDD_AGENT || 'unknown',
+      tool: toolName,
+      args: toolInput,
+      result: toolResponse,
+      latency_ms: latency,
+      status,
+    });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[gdd-trajectory] hook failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  // Always emit a non-blocking continue verdict.
+  try {
+    process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }));
+  } catch {
+    /* swallow */
+  }
+});

package/hooks/hooks.json

@@ -83,6 +83,15 @@
           }
         ]
       },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-trajectory-capture.js\""
+          }
+        ]
+      },
       {
         "hooks": [
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -29,7 +29,8 @@
   "bin": {
     "get-design-done": "./scripts/install.cjs",
     "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
-    "gdd-sdk": "./bin/gdd-sdk"
+    "gdd-sdk": "./bin/gdd-sdk",
+    "gdd-events": "./scripts/cli/gdd-events.mjs"
   },
   "publishConfig": {
     "access": "public",
@@ -84,5 +85,9 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.119",
     "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "optionalDependencies": {
+    "pngjs": "^7.0.0",
+    "ws": "^8.20.0"
   }
 }

package/reference/output-contracts/planner-decision.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "planner-decision.schema.json",
+  "title": "Planner Decision Output Contract",
+  "description": "Schema for the structured JSON block emitted by design-planner. Lets /gdd:synthesize and downstream consumers (executor, audit aggregator) read planner output without regex-parsing markdown.",
+  "type": "object",
+  "required": ["schema_version", "plan_id", "tasks", "waves"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "plan_id": {
+      "type": "string",
+      "description": "Stable identifier — e.g. '23-04' or 'PLAN.md'.",
+      "minLength": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["task_id", "summary", "touches"],
+        "additionalProperties": false,
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable per-plan task identifier (e.g. T-01, 23-04-T-1)."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 3
+          },
+          "touches": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "File globs the task is expected to read or write."
+          },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Other task_ids that must complete first.",
+            "default": []
+          },
+          "parallel_safe": {
+            "type": "boolean",
+            "description": "Hint from the planner — the parallelism decision engine confirms via Touches: analysis.",
+            "default": false
+          },
+          "estimated_minutes": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Rough wall-clock estimate; consumed by budget allocator."
+          },
+          "acceptance": {
+            "type": "string",
+            "description": "Free-form acceptance criteria copy."
+          }
+        }
+      }
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["wave", "task_ids"],
+        "additionalProperties": false,
+        "properties": {
+          "wave": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Wave label (e.g. 'A', 'B', 'C')."
+          },
+          "task_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Free-form planner-side rationale — not consumed by code."
+    }
+  }
+}

package/reference/output-contracts/verifier-decision.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "verifier-decision.schema.json",
+  "title": "Verifier Decision Output Contract",
+  "description": "Schema for the structured JSON block emitted by design-verifier. Drives executor↔verifier ping-pong with a typed envelope rather than free-form prose.",
+  "type": "object",
+  "required": ["schema_version", "verdict", "gaps", "must_fix_before_ship", "confidence"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["pass", "fail", "gap"],
+      "description": "pass = ship-ready, gap = remediable, fail = re-plan."
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "area", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": {
+            "type": "string",
+            "enum": ["P0", "P1", "P2", "P3"]
+          },
+          "area": {
+            "type": "string",
+            "description": "Free-form domain tag — e.g. 'a11y', 'motion', 'tokens'."
+          },
+          "summary": { "type": "string", "minLength": 3 },
+          "evidence": {
+            "type": "string",
+            "description": "Citation: file:line reference or audit excerpt."
+          },
+          "remediation": {
+            "type": "string",
+            "description": "One-line proposed fix."
+          }
+        }
+      }
+    },
+    "must_fix_before_ship": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Subset of gap.id values that block ship — typically the P0/P1 ones."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "med", "low"],
+      "description": "Verifier's self-rated confidence — drives whether to escalate to a second pass."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Free-form notes — not code-consumed."
+    }
+  }
+}