@hegemonart/get-design-done 1.19.5 → 1.20.0

package/hooks/context-exhaustion.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * context-exhaustion.ts — PostToolUse hook
+ *
+ * Phase 20 Plan 20-13 rewrite of the original context-exhaustion.js.
+ * Behavior is byte-equivalent: when tool_response reports context
+ * consumption at or above THRESHOLD (default 0.85), the hook writes a
+ * <paused> resumption block into .design/STATE.md so the next session
+ * can resume with full context. Only writes once per session — if a
+ * <paused> block from the same trigger already exists, the hook exits
+ * silently.
+ *
+ * Phase 20 addition: every decision (ok / warn) fires a hook.fired
+ * event to .design/telemetry/events.jsonl via appendEvent() (Plan 20-06).
+ *
+ * Hook type: PostToolUse (any tool)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import { appendEvent } from '../scripts/lib/event-stream/index.ts';
+import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface ToolResponseMeta {
+  context_usage?: number | string;
+  contextUsage?: number | string;
+}
+interface ToolResponse {
+  context_usage?: number | string;
+  contextUsage?: number | string;
+  metadata?: ToolResponseMeta;
+  meta?: ToolResponseMeta;
+  [key: string]: unknown;
+}
+
+interface HookStdin {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_response?: ToolResponse;
+  [key: string]: unknown;
+}
+
+interface HookOutput {
+  continue: boolean;
+  suppressOutput?: boolean;
+  message?: string;
+}
+
+/** Hook decision emitted on the event stream. */
+export type HookDecision = 'ok' | 'warn';
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * Context-usage fraction above which the hook paints a <paused> block.
+ * Override via GDD_CONTEXT_THRESHOLD env var (float in [0,1]).
+ */
+export const THRESHOLD: number = (() => {
+  const raw = process.env['GDD_CONTEXT_THRESHOLD'];
+  const parsed = raw !== undefined ? Number.parseFloat(raw) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : 0.85;
+})();
+
+const STATE_PATH = join(process.cwd(), '.design', 'STATE.md');
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Claude Code injects context usage in several shapes across versions.
+ * Try direct fields, then metadata.meta alias, then string forms
+ * (fraction or percentage). Returns null when no usage data is present.
+ */
+export function extractContextUsage(
+  toolResponse: ToolResponse | null | undefined,
+): number | null {
+  if (typeof toolResponse !== 'object' || toolResponse === null) return null;
+
+  if (typeof toolResponse.context_usage === 'number') return toolResponse.context_usage;
+  if (typeof toolResponse.contextUsage === 'number') return toolResponse.contextUsage;
+
+  const meta: ToolResponseMeta =
+    toolResponse.metadata ?? toolResponse.meta ?? {};
+  if (typeof meta.context_usage === 'number') return meta.context_usage;
+  if (typeof meta.contextUsage === 'number') return meta.contextUsage;
+
+  const raw =
+    toolResponse.context_usage ??
+    toolResponse.contextUsage ??
+    meta.context_usage ??
+    meta.contextUsage;
+  if (typeof raw === 'string') {
+    if (raw.endsWith('%')) return Number.parseFloat(raw) / 100;
+    const n = Number.parseFloat(raw);
+    if (Number.isFinite(n)) return n > 1 ? n / 100 : n;
+  }
+  return null;
+}
+
+export function buildPausedBlock(toolName: string, usage: number): string {
+  const pct = Math.round(usage * 100);
+  const thresholdPct = Math.round(THRESHOLD * 100);
+  return `
+<paused>
+recorded: ${now()}
+trigger: context-exhaustion-hook
+context_usage: ${pct}%
+last_tool: ${toolName}
+
+## Resumption instructions
+
+Context reached ${pct}% during the previous session (threshold: ${thresholdPct}%).
+The session was auto-paused to preserve quality.
+
+To resume:
+1. Run \`/gdd:resume\` — it will read this block and restore working context
+2. If mid-plan: check .design/STATE.md for the last completed task
+3. Re-read the active PLAN.md to orient before continuing
+
+Intel store status at pause time:
+  ls .design/intel/files.json 2>/dev/null && echo "present" || echo "missing"
+</paused>
+`;
+}
+
+export function stateFileHasPausedBlock(): boolean {
+  if (!existsSync(STATE_PATH)) return false;
+  const content = readFileSync(STATE_PATH, 'utf8');
+  return (
+    content.includes('<paused>') &&
+    content.includes('context-exhaustion-hook')
+  );
+}
+
+function appendPausedBlock(block: string): void {
+  if (!existsSync(dirname(STATE_PATH))) {
+    mkdirSync(dirname(STATE_PATH), { recursive: true });
+  }
+  if (!existsSync(STATE_PATH)) {
+    writeFileSync(STATE_PATH, '# Design State\n\n', 'utf8');
+  }
+  appendFileSync(STATE_PATH, block, 'utf8');
+}
+
+// ── event-stream emitter ────────────────────────────────────────────────────
+
+let CACHED_SESSION_ID: string | null = null;
+function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) {
+    const iso = new Date().toISOString().replace(/[:.]/g, '-');
+    CACHED_SESSION_ID = `gdd-hook-${iso}-${process.pid}`;
+  }
+  return CACHED_SESSION_ID;
+}
+
+function emitHookFired(decision: HookDecision): void {
+  const ev: HookFiredEvent = {
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    payload: { hook: 'context-exhaustion', decision },
+  };
+  try {
+    appendEvent(ev);
+  } catch {
+    // Fail open — event-stream errors must never block the hook.
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function readStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin });
+  let data = '';
+  for await (const line of rl) data += line + '\n';
+  return data;
+}
+
+export async function main(): Promise<void> {
+  const inputData = await readStdin();
+
+  let parsed: HookStdin;
+  try {
+    parsed = JSON.parse(inputData) as HookStdin;
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName =
+    typeof parsed.tool_name === 'string' && parsed.tool_name.length > 0
+      ? parsed.tool_name
+      : 'unknown';
+  const toolResponse: ToolResponse = parsed.tool_response ?? {};
+
+  const usage = extractContextUsage(toolResponse);
+
+  // No usage data — cannot act. Do not emit a hook.fired event; this
+  // is a non-decision, not an "ok" outcome.
+  if (usage === null) process.exit(0);
+
+  // Below threshold — explicit "ok" decision.
+  if (usage < THRESHOLD) {
+    emitHookFired('ok');
+    process.exit(0);
+  }
+
+  // At or above threshold but block already present — emit ok (we did
+  // the right thing earlier) and bail.
+  if (stateFileHasPausedBlock()) {
+    emitHookFired('ok');
+    process.exit(0);
+  }
+
+  const block = buildPausedBlock(toolName, usage);
+  appendPausedBlock(block);
+  emitHookFired('warn');
+
+  const response: HookOutput = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-context-exhaustion: Context at ${Math.round(usage * 100)}% — auto-recorded <paused> block in .design/STATE.md. Run /gdd:resume in the next session to continue.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+}
+
+const isDirectInvocation =
+  process.argv[1] !== undefined &&
+  /context-exhaustion\.ts$/.test(process.argv[1]);
+
+if (isDirectInvocation) {
+  main().catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`context-exhaustion hook error: ${msg}\n`);
+    process.exit(0);
+  });
+}

package/hooks/gdd-read-injection-scanner.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * gdd-read-injection-scanner.ts — PostToolUse hook (matcher: Read)
+ *
+ * Phase 20 Plan 20-13 rewrite of the original
+ * gdd-read-injection-scanner.js. Scans Read tool output for common
+ * prompt-injection patterns and warns (does not block) when suspicious
+ * content is found in a read file. Advisory-only — output is a JSON
+ * response containing a `message` field the user / agent can act on.
+ *
+ * Injection patterns come from scripts/injection-patterns.cjs (Tier-2;
+ * not TypeScript-converted per Plan 20-00's policy). We require-load
+ * them through Node's CJS interop using `createRequire()` — this works
+ * under --experimental-strip-types without `package.json "type":"module"`
+ * changes and keeps the .cjs module shared with
+ * scripts/run-injection-scanner-ci.cjs unchanged.
+ *
+ * Phase 20 addition: every decision (block / allow) fires a hook.fired
+ * event via appendEvent() (Plan 20-06). "block" is used for the
+ * warning-emission path even though the hook itself never hard-blocks
+ * — it signals the advisory decision to downstream consumers.
+ *
+ * Hook type: PostToolUse (matcher: Read)
+ * Input:  JSON on stdin { tool_name, tool_input, tool_response }
+ * Output: JSON on stdout { continue, suppressOutput, message } or nothing
+ */
+
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import { appendEvent } from '../scripts/lib/event-stream/index.ts';
+import type { HookFiredEvent } from '../scripts/lib/event-stream/index.ts';
+
+// ── require-bridge to the shared .cjs pattern file ──────────────────────────
+
+/**
+ * Load injection-patterns.cjs through Node's CJS require even though
+ * this TS file runs under --experimental-strip-types (which auto-detects
+ * ES-module mode). createRequire() can be anchored on any absolute
+ * filesystem path (or a `file://` URL string) — we deliberately avoid
+ * `import.meta.url` so this module stays compatible with the `Node16`
+ * tsconfig module setting without forcing `"type":"module"` in
+ * package.json (which would break the Tier-2 .cjs tests per Plan 20-00).
+ *
+ * Path resolution: when Claude Code invokes the hook, it passes the
+ * absolute path as argv[1]. We anchor against that (so the .cjs
+ * resolves relative to this file's own directory). Falls back to
+ * process.cwd() — scripts/injection-patterns.cjs lives under the
+ * package root, which is cwd in both CI and npm script contexts.
+ */
+function loadPatterns(): readonly RegExp[] {
+  const hookPath =
+    typeof process.argv[1] === 'string' && process.argv[1].length > 0
+      ? isAbsolute(process.argv[1])
+        ? process.argv[1]
+        : resolve(process.argv[1])
+      : resolve('hooks/gdd-read-injection-scanner.ts');
+  const require = createRequire(hookPath);
+  const candidatePaths: string[] = [
+    join(dirname(hookPath), '..', 'scripts', 'injection-patterns.cjs'),
+    join(process.cwd(), 'scripts', 'injection-patterns.cjs'),
+  ];
+  let lastErr: unknown = null;
+  for (const p of candidatePaths) {
+    try {
+      const mod = require(p) as {
+        INJECTION_PATTERNS: Array<{ name: string; re: RegExp }>;
+      };
+      return mod.INJECTION_PATTERNS.map((entry) => entry.re);
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  const msg =
+    lastErr instanceof Error ? lastErr.message : String(lastErr);
+  throw new Error(
+    `gdd-read-injection-scanner: failed to load injection-patterns.cjs (${msg})`,
+  );
+}
+
+const INJECTION_PATTERNS: readonly RegExp[] = loadPatterns();
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface HookStdin {
+  tool_name?: string;
+  tool_input?: { file_path?: string };
+  tool_response?: { content?: string };
+  [key: string]: unknown;
+}
+
+interface HookOutput {
+  continue: boolean;
+  suppressOutput?: boolean;
+  message?: string;
+}
+
+/** Hook decision tag for the event stream. */
+export type HookDecision = 'block' | 'allow';
+
+// ── event-stream emitter ────────────────────────────────────────────────────
+
+let CACHED_SESSION_ID: string | null = null;
+function getSessionId(): string {
+  if (CACHED_SESSION_ID === null) {
+    const iso = new Date().toISOString().replace(/[:.]/g, '-');
+    CACHED_SESSION_ID = `gdd-hook-${iso}-${process.pid}`;
+  }
+  return CACHED_SESSION_ID;
+}
+
+function emitHookFired(decision: HookDecision): void {
+  const ev: HookFiredEvent = {
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    payload: { hook: 'gdd-read-injection-scanner', decision },
+  };
+  try {
+    appendEvent(ev);
+  } catch {
+    // Fail open.
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function readStdin(): Promise<string> {
+  const rl = createInterface({ input: process.stdin });
+  let data = '';
+  for await (const line of rl) data += line + '\n';
+  return data;
+}
+
+export async function main(): Promise<void> {
+  const inputData = await readStdin();
+
+  let parsed: HookStdin;
+  try {
+    parsed = JSON.parse(inputData) as HookStdin;
+  } catch {
+    process.exit(0);
+  }
+
+  if (parsed.tool_name !== 'Read') process.exit(0);
+
+  const content = parsed.tool_response?.content ?? '';
+  const matched = INJECTION_PATTERNS.some((p) => p.test(content));
+  if (!matched) {
+    emitHookFired('allow');
+    process.exit(0);
+  }
+
+  const file = parsed.tool_input?.file_path ?? 'unknown';
+  emitHookFired('block');
+  const response: HookOutput = {
+    continue: true,
+    suppressOutput: false,
+    message: `gdd-injection-scanner: Suspicious prompt-injection pattern detected in content read from "${file}". Review before acting on instructions contained in that file.`,
+  };
+  process.stdout.write(JSON.stringify(response));
+  process.exit(0);
+}
+
+const isDirectInvocation =
+  process.argv[1] !== undefined &&
+  /gdd-read-injection-scanner\.ts$/.test(process.argv[1]);
+
+if (isDirectInvocation) {
+  main().catch(() => process.exit(0));
+}

package/hooks/hooks.json

@@ -32,7 +32,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.ts\""
           }
         ]
       },
@@ -70,7 +70,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-read-injection-scanner.ts\""
           }
         ]
       },
@@ -87,7 +87,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.js\""
+            "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.ts\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.19.5",
+  "version": "1.20.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -26,24 +26,34 @@
     "LICENSE"
   ],
   "bin": {
-    "get-design-done": "./scripts/install.cjs"
+    "get-design-done": "./scripts/install.cjs",
+    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
-    "test": "node --test \"tests/**/*.cjs\"",
+    "test": "node --test --experimental-strip-types \"tests/**/*.cjs\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
-    "validate:schemas": "node scripts/validate-schemas.cjs",
-    "validate:frontmatter": "node scripts/validate-frontmatter.cjs agents/",
+    "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",
+    "validate:frontmatter": "node --experimental-strip-types scripts/validate-frontmatter.ts agents/",
     "detect:stale-refs": "node scripts/detect-stale-refs.cjs",
     "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
     "test:size-budget": "node --test tests/agent-size-budget.test.cjs",
     "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
     "verify:version-sync": "node scripts/verify-version-sync.cjs"
   },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ajv-cli": "^5.0.0",
+    "ajv-formats": "^3.0.1",
+    "json-schema-to-typescript": "^15.0.0",
+    "typescript": "^5.5.0"
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -89,10 +99,22 @@
     "experience-archive",
     "recall",
     "relevance-counter",
-    "record-contract"
+    "record-contract",
+    "first-principles",
+    "emotional-design",
+    "component-authoring",
+    "disney-12-principles",
+    "peak-end-rule",
+    "loss-aversion",
+    "cognitive-load",
+    "doherty-threshold",
+    "rams-lens"
   ],
   "skills": [
     "SKILL.md"
   ],
-  "hooks": "hooks/hooks.json"
+  "hooks": "hooks/hooks.json",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
 }

package/reference/authority-feeds.md

@@ -4,8 +4,8 @@
 >
 > **Anti-slop thesis:** No Dribbble. No Behance. No LinkedIn. No generic trending aggregators. See `.planning/PROJECT.md` and `.planning/phases/13.2-external-authority-watcher/13.2-CONTEXT.md` §D-08.
 
-**Last reviewed:** 2026-04-19
-**Feed count:** 26 (updated each time a feed is added or removed)
+**Last reviewed:** 2026-04-24
+**Feed count:** 28 (updated each time a feed is added or removed)
 
 ---
 
@@ -46,6 +46,8 @@
 - **[Scott Jehl](https://scottjehl.com/)** — `kind: named-practitioner` · `url: https://scottjehl.com/feed/` · `cadence-hint: monthly` · *Progressive enhancement and web performance; long-form durable analysis.*
 - **[Heydon Pickering](https://heydonworks.com/)** — `kind: named-practitioner` · `url: https://heydonworks.com/feed.xml` · `cadence-hint: irregular` · *Accessibility-first component design; Inclusive Components author.*
 - **[Una Kravets](https://una.im/)** — `kind: named-practitioner` · `url: https://una.im/feed.xml` · `cadence-hint: monthly` · *Chrome DevRel on CSS; surfaces and explains new platform capabilities.*
+- **[Don Norman — jnd.org](https://jnd.org/)** — `kind: named-practitioner` · `url: https://jnd.org/feed/` · `cadence-hint: monthly` · *Don Norman's essays on emotional design, affordances, cognitive design, and human-centered AI. Primary source for `reference/emotional-design.md`.*
+- **[Vitsœ — Dieter Rams](https://www.vitsoe.com/gb/about/good-design)** — `kind: named-practitioner` · `url: https://www.vitsoe.com/feed` · `cadence-hint: irregular` · *Canonical source for Rams's 10 Principles of Good Design. Published by Vitsœ, who worked directly with Rams at Braun. Primary source for the Rams Lens in `reference/checklists.md`.*
 
 ## User-added Are.na channels (user-extensible)
 

package/reference/checklists.md

@@ -162,3 +162,33 @@ Use this checklist after the main design review for pixel-level craft verificati
 - [ ] No `transition: all` anywhere (see BAN-12 transition-all)
 - [ ] No `will-change: all` anywhere (see BAN-13 will-change-all)
 - [ ] `prefers-reduced-motion` respected via `MotionConfig` or `useReducedMotion()`
+
+---
+
+## Rams Lens — 10 Design Questions
+
+Dieter Rams's 10 principles of good design (Vitsœ/Braun, 1970s–80s) applied as a self-audit lens. Each question maps to one principle.
+
+- [ ] **Innovative** — Does this design solve the problem in a way that was not possible or obvious before?
+- [ ] **Useful** — Does every element serve the primary function? Nothing decorative that doesn't earn its place?
+- [ ] **Aesthetic** — Is the visual appearance the minimum necessary for legibility and emotional resonance?
+- [ ] **Understandable** — Can the user figure out how to use this without reading documentation or a tooltip?
+- [ ] **Unobtrusive** — Does the design stay in the background and let the content or task take focus?
+- [ ] **Honest** — Does the design not imply capabilities, quality, or status that the product doesn't have?
+- [ ] **Long-lasting** — Is this design free of trend-dependent choices (gradients, micro-styles) that will age in 12 months?
+- [ ] **Thorough** — Have edge cases been considered and handled (empty states, error states, loading states, overflow text)?
+- [ ] **Environmentally friendly** — Is the performance footprint minimal? (image sizes, JS bundle, font weight)
+- [ ] **As little design as possible** — If you removed 20% of the design decisions, would the product be worse? If not, remove them.
+
+---
+
+## Sonner / Component-Authoring Lens — 6 Questions
+
+Emil Kowalski's component-authoring principles applied as a per-component self-audit. Full reference: `reference/component-authoring.md`.
+
+- [ ] **P-01 API surface** — Does this component work correctly in 1 line with zero configuration?
+- [ ] **P-02 Composability** — Does this component compose via slots/children, not via style-configuration props?
+- [ ] **P-03 Defaults** — Are the defaults so sensible that most consumers never need to pass any props?
+- [ ] **P-04 Animation** — Does every animation in this component communicate a state change? No decorative loops?
+- [ ] **P-05 Accessibility** — Does this component have a complete ARIA contract before any visual styling?
+- [ ] **P-06 Edge honesty** — Are known failure modes documented with `// KNOWN:` or `// EDGE:` comments?