@hegemonart/get-design-done 1.27.5 → 1.27.6

package/hooks/gdd-sessionstart-recap.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * hooks/gdd-sessionstart-recap.js — Plan 27.6-05
+ *
+ * Claude Code SessionStart hook. Emits a "what changed while you were
+ * away" diff between the most-recent PreCompact snapshot and the
+ * current STATE.md.
+ *
+ * Phase 27.6 D-09: markdown summary to stderr + structured JSON to
+ *   `.design/snapshots/last-recap.json` (the JSON is a sidecar for
+ *   downstream tools: progress dashboard, resume skill).
+ * Phase 27.6 D-10: harness-aware Codex no-op (Phase 45 dep for full
+ *   pre-large-context recap integration).
+ *
+ * Silent-on-failure: tolerable errors exit 0 with breadcrumb.
+ * Emits `recap.emitted` event via lazy appendEvent (best-effort).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SNAPSHOT_DIR = path.resolve(process.cwd(), '.design', 'snapshots');
+const STATE_MD_PATH = path.resolve(process.cwd(), '.design', 'STATE.md');
+const EVENTS_PATH = path.resolve(process.cwd(), '.design', 'telemetry', 'events.jsonl');
+const RECAP_JSON_PATH = path.join(SNAPSHOT_DIR, 'last-recap.json');
+const SCHEMA_VERSION = '1.0.0';
+
+// ---------------------------------------------------------------------------
+// Harness detection (D-10) — mirrors gdd-precompact-snapshot.js
+// ---------------------------------------------------------------------------
+
+function detectHarness() {
+  const explicit = (process.env.CLAUDE_HARNESS || process.env.GDD_HARNESS || '')
+    .toLowerCase()
+    .trim();
+  if (explicit === 'codex' || explicit === 'codex-cli') return 'codex';
+  return 'claude-code';
+}
+
+// ---------------------------------------------------------------------------
+// Lazy event-stream emit (best-effort)
+// ---------------------------------------------------------------------------
+
+function getAppendEvent() {
+  try {
+    const m = require('../scripts/lib/event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    /* swallow — event-stream is optional infrastructure */
+  }
+  return function noopAppend(_ev) {
+    /* no-op */
+  };
+}
+
+// ---------------------------------------------------------------------------
+// STATE.md tolerant parser (lighter than the PreCompact version — only
+// needs frontmatter + a flat decisions list for the diff)
+// ---------------------------------------------------------------------------
+
+function readStateMd() {
+  if (!fs.existsSync(STATE_MD_PATH)) return { frontmatter: {}, decisions: [] };
+  let body;
+  try {
+    body = fs.readFileSync(STATE_MD_PATH, 'utf8');
+  } catch {
+    return { frontmatter: {}, decisions: [] };
+  }
+
+  const frontmatter = {};
+  const fmMatch = body.match(/^---\n([\s\S]*?)\n---\n/);
+  if (fmMatch) {
+    for (const line of fmMatch[1].split('\n')) {
+      const m = line.match(/^(\w+):\s*(.+)$/);
+      if (m) frontmatter[m[1]] = m[2].trim();
+    }
+  }
+
+  // All D-XX entries anywhere in the body — broad sweep is fine for diff.
+  const decisions = [];
+  const dRe = /D-\d+:[^\n]+/g;
+  let m2;
+  while ((m2 = dRe.exec(body)) !== null) {
+    decisions.push(m2[0].trim());
+  }
+  return { frontmatter, decisions };
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot discovery — highest-mtime *.json (excluding last-recap.json)
+// ---------------------------------------------------------------------------
+
+function findLatestSnapshot() {
+  if (!fs.existsSync(SNAPSHOT_DIR)) return null;
+  let files;
+  try {
+    files = fs.readdirSync(SNAPSHOT_DIR);
+  } catch {
+    return null;
+  }
+  const candidates = files.filter(
+    (f) => f.endsWith('.json') && f !== 'last-recap.json' && !f.endsWith('.tmp'),
+  );
+  if (candidates.length === 0) return null;
+
+  let best = null;
+  let bestMtime = -1;
+  for (const name of candidates) {
+    const full = path.join(SNAPSHOT_DIR, name);
+    try {
+      const mtime = fs.statSync(full).mtimeMs;
+      if (mtime > bestMtime) {
+        best = full;
+        bestMtime = mtime;
+      }
+    } catch {
+      /* swallow */
+    }
+  }
+  return best;
+}
+
+// ---------------------------------------------------------------------------
+// Event count since snapshot timestamp (JSONL-tolerant)
+// ---------------------------------------------------------------------------
+
+function countEventsSince(isoTimestamp) {
+  if (!fs.existsSync(EVENTS_PATH)) return 0;
+  let body;
+  try {
+    body = fs.readFileSync(EVENTS_PATH, 'utf8');
+  } catch {
+    return 0;
+  }
+  let count = 0;
+  for (const line of body.split(/\r?\n/)) {
+    const t = line.trim();
+    if (t.length === 0) continue;
+    try {
+      const ev = JSON.parse(t);
+      if (typeof ev.timestamp === 'string' && ev.timestamp > isoTimestamp) {
+        count++;
+      }
+    } catch {
+      /* tolerate malformed */
+    }
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const harness = detectHarness();
+  if (harness === 'codex') {
+    // D-10: SessionStart on Codex skips recap; Phase 45 dep for full
+    // pre-large-context-action integration.
+    process.stderr.write('[gdd-sessionstart-recap] codex harness no-op (Phase 45 dep)\n');
+    process.exit(0);
+  }
+
+  const snapshotPath = findLatestSnapshot();
+  if (!snapshotPath) {
+    process.stderr.write('[gdd-sessionstart-recap] no prior snapshot\n');
+    process.exit(0);
+  }
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(fs.readFileSync(snapshotPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(
+      '[gdd-sessionstart-recap] snapshot unreadable: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+    process.exit(0);
+  }
+
+  const current = readStateMd();
+  const priorDecisions = Array.isArray(snapshot.last_n_decisions)
+    ? snapshot.last_n_decisions
+    : [];
+  const priorSet = new Set(priorDecisions);
+  const newDecisions = current.decisions.filter((d) => !priorSet.has(d));
+  const newEventCount = countEventsSince(snapshot.timestamp || '1970-01-01T00:00:00.000Z');
+
+  const priorCycle = snapshot.cycle_id || 'unknown';
+  const currentCycle = current.frontmatter.milestone || 'unknown';
+  const cycleChanged = priorCycle !== currentCycle ? `${priorCycle} → ${currentCycle}` : null;
+
+  const snapshotTime = snapshot.timestamp ? new Date(snapshot.timestamp).getTime() : 0;
+  const timeElapsedMs =
+    snapshotTime > 0 && Number.isFinite(snapshotTime) ? Date.now() - snapshotTime : 0;
+
+  // Markdown summary to stderr (D-09).
+  const md = [
+    '## Session Recap',
+    `Snapshot taken: ${snapshot.timestamp || 'unknown'}`,
+    `Time elapsed: ${(timeElapsedMs / 60000).toFixed(1)} min`,
+    cycleChanged ? `Cycle: ${cycleChanged}` : `Cycle: ${currentCycle} (unchanged)`,
+    `New decisions: ${newDecisions.length}`,
+    ...newDecisions.slice(0, 5).map((d) => `  - ${d}`),
+    `New events since snapshot: ${newEventCount}`,
+    '',
+  ].join('\n');
+  process.stderr.write(md + '\n');
+
+  // JSON sidecar (D-09) — atomic .tmp + rename for consistency.
+  const recap = {
+    schema_version: SCHEMA_VERSION,
+    previous_snapshot: snapshotPath,
+    current_timestamp: new Date().toISOString(),
+    diff: {
+      new_decisions: newDecisions,
+      new_events_since_snapshot: newEventCount,
+      cycle_changed: cycleChanged,
+      time_elapsed_ms: timeElapsedMs,
+    },
+  };
+
+  try {
+    // mkdir -p for safety — directory should exist if snapshotPath was found,
+    // but defensive ensure for race conditions.
+    fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
+    fs.writeFileSync(RECAP_JSON_PATH + '.tmp', JSON.stringify(recap, null, 2), 'utf8');
+    fs.renameSync(RECAP_JSON_PATH + '.tmp', RECAP_JSON_PATH);
+  } catch (err) {
+    process.stderr.write(
+      '[gdd-sessionstart-recap] sidecar write failed: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+  }
+
+  // Best-effort event emit.
+  const appendEvent = getAppendEvent();
+  try {
+    appendEvent({
+      type: 'recap.emitted',
+      timestamp: new Date().toISOString(),
+      sessionId: process.env.GDD_SESSION_ID || 'sessionstart-hook',
+      payload: {
+        new_decisions: newDecisions.length,
+        new_events: newEventCount,
+        time_elapsed_ms: timeElapsedMs,
+        harness,
+      },
+    });
+  } catch {
+    /* swallow */
+  }
+
+  // Emit non-blocking continue verdict on stdout.
+  try {
+    process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }));
+  } catch {
+    /* swallow */
+  }
+
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  try {
+    process.stderr.write(
+      '[gdd-sessionstart-recap] uncaught: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+  } catch {
+    /* swallow */
+  }
+  process.exit(0);
+}

package/hooks/hooks.json

@@ -24,6 +24,14 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/first-run-nudge.sh\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-sessionstart-recap.js\""
+          }
+        ]
       }
     ],
     "PreToolUse": [
@@ -110,6 +118,16 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-precompact-snapshot.js\""
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.27.5",
+  "version": "1.27.6",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -83,7 +83,7 @@
   ],
   "hooks": "hooks/hooks.json",
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.119",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@clack/prompts": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.0.0"
   },

package/reference/perf-budget.md

@@ -0,0 +1,142 @@
+---
+name: perf-budget
+phase: 27.6
+version: 1.0.0
+type: meta-rules
+description: Per-agent token-cost budget reference and CI regression-gate documentation. Budgets sourced from current p50 + 25% buffer (Phase 27.6 D-05); CI gate fails on >25% regression vs baseline across 3 cycles (D-01); thresholds configurable via .design/budget.json.
+---
+
+# Per-Agent Performance Budgets — Phase 27.6
+
+This reference documents the token-cost budgets that the pipeline measures itself against. Two surfaces consume this document:
+
+1. `tests/perf-budget.test.cjs` — CI regression gate. Fails the build when any agent's p50 USD-cost has regressed > 25% vs baseline across the last 3 cycles.
+2. `agents/perf-analyzer.md` — cross-cycle reflector. Reads the same budget + telemetry; surfaces top-3 regressions as `[REGRESSION]` proposals.
+
+Phase 27.5 (v1.27.5, shipped 2026-05-17) made production telemetry real by wiring the bandit into routing. Phase 27.6 reads what 27.5 writes.
+
+---
+
+## How budgets are derived
+
+Per **D-05**, each per-agent budget is the agent's current p50 USD-cost plus a 25% buffer (`p50 × 1.25`). The buffer absorbs natural cycle-to-cycle variance without firing the gate, while still flagging genuine cost growth.
+
+Per **D-03**, the v1.27.6 baseline data lives at `test-fixture/baselines/phase-27-6/perf-baseline.json` and is built from **synthetic cycle replay**. Real-cycle calibration ships as a follow-up after 1-2 production cycles accumulate, via the commit:
+
+```
+chore(27.6): recalibrate perf-budget against measured cycles
+```
+
+Per **D-01**, the regression-gate threshold is **25%**, configurable via `.design/budget.json#perf_regression_threshold`. A minimum of **3 distinct cycles** must be observed per agent before that agent is evaluated for regression. Agents with fewer than 3 cycles are silently skipped (cold-start tolerance).
+
+This conservative-then-tighten discipline matches Phase 23.5 `PRIOR_STRENGTH` calibration — start wide to avoid noise, tighten once enough samples accumulate to compute realistic p95 bounds.
+
+---
+
+## Per-agent budget table
+
+| Agent | p50 budget (USD) | Buffer | Hit-rate baseline | p95 wall (ms) | Notes |
+|---|---|---|---|---|---|
+| design-verifier | 0.04 | 0.05 (+25%) | 0.55 | 12000 | Stage 5; reads DESIGN-VERIFICATION.md scoring rubric |
+| design-planner | 0.08 | 0.10 (+25%) | 0.40 | 18000 | Stage 3; opus default |
+| design-executor | 0.06 | 0.075 (+25%) | 0.50 | 15000 | Stage 4 |
+| design-context-checker | 0.02 | 0.025 (+25%) | 0.65 | 6000 | Gate; pre-stage validator |
+| design-reflector | 0.10 | 0.125 (+25%) | 0.35 | 22000 | XL reflector tier |
+| design-discussant | 0.05 | 0.0625 (+25%) | 0.45 | 11000 | Spawned by `/gdd:discuss` |
+| perf-analyzer | 0.10 | 0.125 (+25%) | 0.30 | 22000 | XL reflector tier (this phase) |
+
+These values are **seed numbers**, re-calibrated after 1-2 real production cycles. The authoritative numbers live in `test-fixture/baselines/phase-27-6/perf-baseline.json` (created at Phase 27.6 closeout in Plan 27.6-06). The CI gate reads that file at runtime, not this table.
+
+When the baseline JSON is **absent** (first run after this plan lands but before 27.6-06), the gate passes silently with a stderr notice — it does NOT block Wave A from shipping.
+
+---
+
+## CI Regression Gate
+
+File: `tests/perf-budget.test.cjs`
+
+Algorithm (single source of truth — re-uses `detectCostRegressions` from `scripts/lib/perf-analyzer/cost-regression.cjs`):
+
+1. Load `test-fixture/baselines/phase-27-6/perf-baseline.json`. If absent, exit early — gate passes with stderr notice. (Phase 27.6-06 creates this file at closeout.)
+2. Load `.design/telemetry/costs.jsonl` via `loadCosts`. If absent or empty, exit early — no data to regress against.
+3. Read `perf_regression_threshold` from `.design/budget.json` (default 25 per D-01).
+4. Call `detectCostRegressions({rows, baseline: parsedBaseline.agents, thresholdPct, cyclesRequired: 3})`.
+5. If `result.regressions.length === 0`, gate passes.
+6. Otherwise, fail the test with the regression details (agent, baseline_p50_usd, current_p50_usd, delta_pct, cycles_observed).
+
+The gate is intentionally **low-noise**:
+
+- Skips agents with fewer than 3 distinct cycles of data (avoids false positives during cold-start).
+- Only fires on the **regression rule** — NOT on cache-hit-rate drops or p95 latency spikes; those surface as `agents/perf-analyzer.md` proposals only.
+- Top-3 cap on the regressions list — a "noisy day" can flag at most three agents, never the entire roster.
+
+The gate runs as a regular `node --test` entry under the `tests/**/*.test.cjs` glob — no special CI wiring required. If you can run `npm test`, you run the gate.
+
+---
+
+## Tuning the Gate
+
+Override the regression threshold by adding to `.design/budget.json`:
+
+```json
+{
+  "perf_regression_threshold": 30
+}
+```
+
+Override the cache-warming false-positive tolerance (used by Phase 27.6-03):
+
+```json
+{
+  "cache_warming_falsepositive_threshold": 25
+}
+```
+
+**Defaults** (per Phase 27.6 D-01 + D-02):
+
+- `perf_regression_threshold: 25`
+- `cache_warming_falsepositive_threshold: 20`
+
+After 5 measured cycles accumulate, re-tune based on observed natural variance. The 25%-default is conservative — likely too loose once real telemetry stabilizes. The first tightening pass belongs to a measurement-gated follow-up, not v1.27.6 itself.
+
+---
+
+## Recalibration (Phase 27.6 D-03 follow-up)
+
+v1.27.6 ships with synthetic-cycle-replay baselines. After 1-2 real production cycles accumulate, re-lock the baseline:
+
+```
+chore(27.6): recalibrate perf-budget against measured cycles
+```
+
+That commit:
+
+1. Re-runs the baseline-fixture build against real telemetry.
+2. Updates `test-fixture/baselines/phase-27-6/perf-baseline.json` with the measured p50, hit_rate, and p95_ms per agent.
+3. Bumps the budget numbers in this document to match.
+4. Optionally tightens `perf_regression_threshold` from 25 toward 15-20 if measured variance permits.
+
+The synthetic baseline is **not a hack** — it's the documented v1 path per spec Success Criterion #7. Real-cycle data simply doesn't exist yet at v1.27.6 cut, because Phase 27.5 only shipped 2026-05-17.
+
+---
+
+## Cross-references
+
+- `agents/perf-analyzer.md` — cross-cycle reflector that reads the same baseline. Surfaces top-3 cost regressions, hit-rate deltas, and p95 spikes as `[REGRESSION]` proposals per `/gdd:reflect`.
+- `scripts/lib/perf-analyzer/cost-regression.cjs` — **single source of truth** for the regression rule. The CI gate re-uses `detectCostRegressions` from this module; it does NOT re-implement the rule.
+- `scripts/lib/perf-analyzer/index.cjs` — telemetry loader (`loadCosts`, `loadTrajectories`). JSONL-tolerant; blank lines silently ignored, malformed lines counted in `skipped_count`.
+- `tests/perf-budget.test.cjs` — the CI gate itself. Always-green when no baseline + no data; fails on >25% regression vs baseline once both exist.
+- `reference/bandit-integration.md` — Phase 27.5 routing reference (precursor; the bandit picks tier **within** the budget — the gate evaluates whether the picked tier behaved within budget).
+- `.design/budget.json` — operator-tunable thresholds. Optional file; absent file means defaults (`perf_regression_threshold: 25`, `cache_warming_falsepositive_threshold: 20`).
+- `test-fixture/baselines/phase-27-6/perf-baseline.json` — authoritative per-agent p50 / hit_rate / p95_ms values. Created in Plan 27.6-06 closeout.
+
+---
+
+## Boundary semantics (matching detectCostRegressions)
+
+- **>= threshold** is a regression. A current p50 exactly 25% above baseline (e.g., baseline 0.05, current 0.0625) fires the gate. This matches the Phase 27.6-01 test contract.
+- **base = 0 + current > 0** → flagged as `delta_pct: Infinity`. A previously-zero-cost agent becoming non-zero is always a regression.
+- **base = 0 + current = 0** → NOT a regression (both `delta_pct = 0`).
+- **Missing baseline entry** → agent silently skipped (no false positive on new agents that haven't been calibrated yet).
+
+The gate's "fail loud, false-positive rare" character comes from these boundary choices plus the 3-cycle minimum — together they make the gate safe to wire into CI without flaking on first-run noise.

package/reference/registry.json

@@ -659,6 +659,13 @@
       "phase": 27,
       "description": "Phase 27 peer-CLI delegation capability matrix — which peer (codex/copilot/cursor/gemini/qwen) claims which agent role, protocol (ACP/ASP), tie-break order, and opt-in gating semantics"
     },
+    {
+      "name": "perf-budget",
+      "path": "reference/perf-budget.md",
+      "type": "meta-rules",
+      "phase": 27.6,
+      "description": "Phase 27.6 per-agent token-cost budget reference and CI regression-gate documentation; budgets sourced from current p50 + 25% buffer (D-05), CI gate fails on >25% regression vs baseline across 3 cycles (D-01); thresholds configurable via .design/budget.json"
+    },
     {
       "name": "performance",
       "path": "reference/performance.md",

package/reference/retrieval-contract.md

@@ -25,6 +25,22 @@ A `/gdd:recall "term"` query that returns 5 Layer-1 hits ≈ 400 tokens. Opening
 
 Layer 1 becomes `scripts/lib/design-search.cjs` — same protocol, same output shape, but backed by `.design/search.db` instead of grep. Agents do not need to change anything; the backend swap is transparent.
 
+## Phase 27.6 — Shared-Context Dedup (D-11)
+
+When >= 3 distinct agents in the same cycle read the same `reference/*.md` file, the Phase 14.5 retrieval-contract preamble is extended with a "shared context loaded once" marker — subsequent agents see a content-hash reference instead of the full file body. This reduces redundant token consumption per cycle.
+
+The detection lives in `scripts/lib/prompt-dedup/index.cjs::detectDuplicateReferenceReads` and runs at retrieval-contract injection time. The threshold (3 agents) matches Phase 27.6 D-11 and is tunable via the `threshold` argument to `detectDuplicateReferenceReads`.
+
+Operator opt-out: set `GDD_DEDUP_OPT_OUT=1` in the spawning agent's environment to bypass dedup for that read.
+
+Event emission: each dedup decision emits a `dedup.injection` event via `appendEvent` so the Phase 27.6-01 perf-analyzer can surface "the same file is read N agents times per cycle" as a `[CONTEXT-WASTE]` proposal.
+
+Cross-references:
+
+- `scripts/lib/prompt-dedup/index.cjs` — analyzer + injection text builder.
+- `tests/prompt-dedup.test.cjs` — detection rule tests.
+- `agents/perf-analyzer.md` — consumes `dedup.injection` events for cross-cycle analysis.
+
 ---
 
 *Imported by every skill that reads `.design/` artifacts: `/gdd:progress`, `/gdd:resume`, `/gdd:reflect`, `/gdd:pause`, `/gdd:recall` (Phase 19.5+), `/gdd:timeline` (Phase 19.5+). Tier: preamble. Phase: 14.5.*