@hegemonart/get-design-done 1.27.5 → 1.27.7

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.27.5"
+    "version": "1.27.7"
   },
   "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.27.5",
+      "version": "1.27.7",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.27.5",
-  "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.",
+  "version": "1.27.7",
+  "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. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming.",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"
@@ -59,7 +59,10 @@
     "gemini",
     "mcp",
     "parallel-agents",
-    "agent-sdk"
+    "agent-sdk",
+    "mcp-server",
+    "context-loading",
+    "cross-session"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,105 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.27.7] — 2026-05-18
+
+### Added
+
+- **Phase 27.7 — GDD MCP Server** (7 plans). Ships `gdd-mcp`, a read-only Model Context Protocol server that exposes STATE.md sections, phases, decisions, plans, telemetry, intel slices, and the latest reflection as 12 typed MCP tools backed by the same `scripts/lib/*` modules the CLI uses. Sub-3-second priming target on a synthetic project (Storybloq §4.6 pattern transplant). Off-cadence v1.27.7 (CHANGELOG-only; mainline cadence resumes at v1.28.0).
+  - `scripts/mcp-servers/gdd-mcp/server.ts` (Plan 27.7-01) — MCP server scaffold using `@modelcontextprotocol/sdk` low-level Server + StdioServerTransport. Project-root discovery walks from `process.cwd()` looking for `.design/` OR `.planning/` OR `.claude-plugin/plugin.json`. `bin/gdd-mcp` shim added to `package.json` (alphabetized: gdd-events → gdd-mcp → gdd-sdk → gdd-state-mcp). Tests on handshake + walk-up + missing-marker behavior. (MCP-01)
+  - `scripts/mcp-servers/gdd-mcp/tools/` + `reference/schemas/mcp-gdd-tools.schema.json` (Plan 27.7-02) — 12 read-only tools: `gdd_status`, `gdd_cycle_recap`, `gdd_decisions_list`, `gdd_events_tail`, `gdd_health`, `gdd_intel_get`, `gdd_learnings_digest`, `gdd_phase_current`, `gdd_phases_list`, `gdd_plans_list`, `gdd_reflections_latest`, `gdd_telemetry_query`. Each tool ≤ 30 LOC (D-06), with per-tool Draft-07 JSON Schema, plus 5 helper libs (state-reader, intel-slicer, telemetry-grouper, reflection-loader, paths-resolver) and a `directory_not_found` typed projection. Tests on input schema + output shape + thin-wrapper assertion. (MCP-02)
+  - `scripts/lib/mcp-tools-lint/index.cjs` (Plan 27.7-03) — Static lint enforcing 4 invariants: forbid-fs-path (D-06: no direct `fs.*`/`path.*` in tool files), max-loc (≤ 30 LOC per tool), no-write-names (D-04: hard-blocks `_(create|update|delete|append|clear|write|set)` patterns), tool-count-cap (D-03: ≤ 12 files). Tests on each rule + exemptions for `index.ts`/`shared.ts`. (MCP-03)
+  - `scripts/lib/install/mcp-register.cjs` + `scripts/install.cjs --register-mcp` extension (Plan 27.7-04) — Idempotent registration with `claude mcp add` + `codex mcp add` (D-07 opt-in; absent-CLI fallback). `skills/health/SKILL.md` gains a `check-mcp-registration` step with 4 SKILL-row outputs (registered_with_both, not_registered, dismissed, unknown). Tests on idempotent re-run + absent-CLI paths + `--` arg-injection guard. (MCP-04)
+  - `skills/progress/SKILL.md` + `skills/resume/SKILL.md` + `skills/next/SKILL.md` adopted MCP-path + File-read-path fork (Plan 27.7-05). Each skill prefers `gdd-mcp` tools when registered, falls back to direct file reads when not. Structural-compliance tests via the Phase 28.5 validator. (MCP-05)
+  - `scripts/mcp-servers/gdd-mcp/README.md` (≤ 120 lines, Plan 27.7-06) + `test-fixture/baselines/phase-27-7/priming-benchmark.json` capturing −31.18% token reduction on a synthetic project (Storybloq's −30% floor met). Tests on README structure + benchmark fixture shape + token-reduction ≥ 30%. (MCP-06)
+  - `test-fixture/baselines/phase-27-7/` regression snapshots (Plan 27.7-07): `tool-registry.json` (12 tools, zero write-tools), `handshake-fixture.json` (canonical initialize response shape), `install-doctor-fixture.json` (4 SKILL-row scenarios), `manifests-version.txt` (pinned at 1.27.7). 4-manifest lockstep bump to v1.27.7. CHANGELOG entry. `OFF_CADENCE_VERSIONS.add('1.27.7')`. `reference/registry.json` gains `mcp-gdd-tools-schema` entry. `plugin.json` keywords gain `mcp-server`, `context-loading`, `cross-session`. ROADMAP scoped flip (7 plan checkboxes + 1 top-level overview entry). New `tests/phase-27-7-baseline.test.cjs` (>= 6 version-agnostic baseline tests) + new `tests/gdd-mcp-headless-e2e.test.cjs` (5 E2E tests: pack -> install -> spawn -> MCP initialize handshake -> tools/list returns 12; skip-on-Windows path documented for npm pack symlink false-negatives — Blocker #2 acceptance per ROADMAP SC #11). (MCP-07)
+
+### Decisions locked
+
+- D-01: MCP server is read-mostly (read-only in v1; mutations stay in slash-skills + lockfile-safe writers — re-examine at Phase 30/41).
+- D-02: Tool count capped at 12 — `TOOL_COUNT > 12` throws at module load. Adding a 13th tool requires re-scoping in a new plan.
+- D-03: 12-tool cap is the hard ceiling baselined in `test-fixture/baselines/phase-27-7/tool-registry.json`.
+- D-04: No write-verb tool names — `mcp-tools-lint` blocks `_(create|update|delete|append|clear|write|set)(_|$)` patterns. Baseline asserts `write_tools.length === 0`.
+- D-05: stdio-only transport — no port allocation, no HTTP surface. Project-root discovery walks up from `process.cwd()` (`.design/` OR `.planning/` OR `.claude-plugin/plugin.json` marker).
+- D-06: Each tool file ≤ 30 non-blank-non-comment LOC. Tools must be thin wrappers — no direct `node:fs`/`node:path` imports (enforced by `mcp-tools-lint`). All filesystem I/O routes through `scripts/lib/*` helpers.
+- D-07: Installer `--register-mcp` is opt-in (default off). Absent-CLI fallback emits a non-blocking notice. Dismissable nudge via `.design/config.json#mcp_nudge: false`.
+- D-08: Skill-side adoption is forked — MCP path (preferred) + File-read path (fallback). Both produce identical output shape. Skills do not hard-depend on MCP registration.
+- D-09: Server name `gdd-mcp` (matches package bin); version read from `package.json#version` (single source of truth — D-12 lockstep maintains alignment).
+- D-10: `bin/gdd-mcp` block in `package.json` alphabetized at scaffold time (Plan 27.7-01). Manifest bump preserves the alphabetization.
+- D-11: New schema `reference/schemas/mcp-gdd-tools.schema.json` registered in `reference/registry.json` as `mcp-gdd-tools-schema`.
+- D-12: 4-manifest lockstep — `package.json#version`, `.claude-plugin/plugin.json#version`, `.claude-plugin/marketplace.json#metadata.version`, `.claude-plugin/marketplace.json#plugins[0].version` all ship together at v1.27.7. `OFF_CADENCE_VERSIONS.add('1.27.7')` added to `tests/semver-compare.test.cjs`.
+
+### Tests added
+
+~69 new tests across 10 test files: 5 server scaffold (Plan 27.7-01), 27 tool + helper (Plan 27.7-02), 4 lint (Plan 27.7-03), 6 install + 4 SKILL row (Plan 27.7-04), 3 skill adoption (Plan 27.7-05), 5 README + benchmark (Plan 27.7-06), 8 baseline + 5 headless E2E (Plan 27.7-07).
+
+### Out of scope (deferred or rejected)
+
+- Write tools in v1 — `gdd_decision_append`, `gdd_blocker_clear`, `gdd_plan_complete` etc. Mutation belongs to slash-skills + lockfile-safe writers (Phase 20 surface), not callable-by-any-client MCP tools. Re-examine at Phase 30 (issue reporter) or Phase 41 (team mode).
+- Tool sprawl past 12 — Storybloq grew to 43 tools because read + write + autonomous + review-lens orchestration share the surface. GDD's autonomous surface is `/gdd:do`, review is `agents/*`. Re-examine when measured token-cost data justifies an additional tool.
+- Live (streaming) MCP resources — Phase 48 (`/gdd:live`) handles long-lived browser sessions via `channel/`-style subprocess registry; MCP stays request/response in v1.
+- Multi-project federation — one server, one project root. Two GDD projects in two terminals = two MCP servers. Federation is a Phase 41 (team mode) question.
+
+### Benchmark
+
+`test-fixture/baselines/phase-27-7/priming-benchmark.json` — synthetic-fixture priming run shows −31.18% token reduction (3 MCP calls vs equivalent file-reading path), with a 34× wall-clock speedup vs file-reading. Floor target was −30% (Storybloq's measured number); GDD exceeds the floor. Real-cycle calibration follows in a patch after 1-2 production cycles.
+
+### Headless E2E (ROADMAP SC #11)
+
+`tests/gdd-mcp-headless-e2e.test.cjs` — `npm pack` produces tarball -> `npm install <tarball>` into mkdtempSync prefix -> spawn `gdd-mcp` via the installed bin -> MCP initialize handshake asserts `serverInfo.name === 'gdd-mcp'` + `serverInfo.version === package.json#version` -> follow-up `tools/list` asserts `result.tools.length === 12`. Cleanup at end. Marked `skip: process.platform === 'win32'` for npm pack symlink false-negatives (Blocker #2 acceptance); POSIX CI runs all 5 E2E tests.
+
+---
+
+## [1.27.6] — 2026-05-18
+
+### Added
+
+- **Phase 27.6 — Pipeline Performance + Token-Cost Optimization** (6 plans). After 27.5 wired the bandit into production routing, telemetry from `.design/telemetry/{costs,trajectories,events}.jsonl` finally measures real spawns; this phase converts that telemetry into concrete optimizations.
+  - `agents/perf-analyzer.md` + `scripts/lib/perf-analyzer/` (Plan 27.6-01) — reflector-tier agent that reads telemetry cross-cycle and surfaces top-3 token-cost regressions per agent + cache-hit-rate deltas + p95 latency spikes. Spawned by `/gdd:reflect` or `/gdd:audit`, NOT per-cycle (D-04).
+  - `reference/perf-budget.md` + `tests/perf-budget.test.cjs` (Plan 27.6-02) — per-agent budget table + CI regression gate that fails on >25% regression vs baseline across 3 cycles (D-01). Thresholds configurable via `.design/budget.json#perf_regression_threshold`.
+  - `scripts/lib/cache/gdd-cache-manager.cjs` (Plan 27.6-03) — cache-warming heuristic refinement: multiplicative `recency × frequency × cost` score (D-06) + top-N ranking + LRU eviction within warmed set + false-positive event emission when >20% of warmed entries evict before use (D-02).
+  - `scripts/lib/parallelism-engine/concurrency-tuner.cjs` (Plan 27.6-04) — data-driven concurrency resolver reading `parallelism.verdict` events; default becomes `min(cpu-1, last_observed_optimum)` capped at 8 (D-07). Both explore-parallel-runner and discuss-parallel-runner now use the resolver when `opts.concurrency` is omitted.
+  - `hooks/gdd-precompact-snapshot.js` + `hooks/gdd-sessionstart-recap.js` (Plan 27.6-05) — Storybloq §4.6 transplant. PreCompact hook writes atomic snapshots to `.design/snapshots/<ts>.json` (D-08; retention last-10 LRU); SessionStart recap emits markdown to stderr + JSON sidecar at `.design/snapshots/last-recap.json` (D-09). Harness-aware: Codex no-op with stderr notice (D-10, Phase 45 dep for full path).
+  - `scripts/lib/prompt-dedup/index.cjs` + `reference/retrieval-contract.md` extension (Plan 27.6-06) — D-11 dedup: when ≥ 3 agents in same cycle read same `reference/*.md`, the retrieval-contract preamble adds a "shared context loaded once" marker.
+  - `docs/PERF-OPTIMIZATION.md` (Plan 27.6-06) — operator guide covering all 6 plans, 12 D-XX decisions, the CI regression gate, perf-analyzer proposals, cache-warming tuning, concurrency resolver, snapshot/recap hooks, Codex no-op fallback, prompt-dedup, recalibration process, and troubleshooting.
+
+### Decisions locked
+
+- D-01: Regression-gate threshold = 25% (configurable via `.design/budget.json#perf_regression_threshold`).
+- D-02: Cache-warming false-positive tolerance = 20% (configurable via `.design/budget.json#cache_warming_falsepositive_threshold`).
+- D-03: Baseline data = synthetic cycle replay; real-cycle calibration in a follow-up patch after 1-2 production cycles.
+- D-04: `perf-analyzer` is reflector-tier (not per-cycle).
+- D-05: Per-agent budgets = current p50 + 25% buffer initially.
+- D-06: Cache-warming heuristic = multiplicative `recency × frequency × cost`.
+- D-07: Parallel-mapper concurrency reads `parallelism.verdict` events; default = `min(cpu-1, last_optimum)` capped at 8.
+- D-08: PreCompact snapshot uses `scripts/lib/lockfile.cjs` for atomicity (atomic `.tmp` + rename); retention last-10 LRU.
+- D-09: SessionStart recap emits markdown to stderr + JSON sidecar to `.design/snapshots/last-recap.json`.
+- D-10: Codex no-op fallback (stderr notice; Phase 45 dep for full path).
+- D-11: Prompt-dedup injects at Phase 14.5 retrieval-contract preamble (≥ 3 agents reading same ref → shared-context marker).
+- D-12: 4 manifests lockstep + CHANGELOG + OFF_CADENCE + baseline at `test-fixture/baselines/phase-27-6/`.
+
+### Out of scope (deferred)
+
+- Cross-runtime cost arbitrage (Phase 26 territory).
+- Per-call model substitution (Phase 23.5 bandit territory).
+- Rewriting reference files (Phase 46 territory).
+- Codex `pre-large-context-action` interception (Phase 45 dep).
+- Cache-warming auto-tuning of heuristic weights — measurement-gated follow-up.
+- Real-cycle baseline calibration — deferred to follow-up patch.
+
+### Test coverage
+
+- `tests/perf-analyzer-cost-regression.test.cjs` — ≥10 tests for detection rules (Plan 27.6-01).
+- `tests/perf-budget.test.cjs` — ≥6 tests for CI gate including cold-start tolerance (Plan 27.6-02).
+- `tests/gdd-cache-manager-warming.test.cjs` — ≥6 tests for warming heuristic (Plan 27.6-03).
+- `tests/concurrency-tuner.test.cjs` — ≥5 tests for D-07 algorithm (Plan 27.6-04).
+- `tests/gdd-precompact-snapshot.test.cjs` — ≥6 tests including atomicity + harness fallback (Plan 27.6-05).
+- `tests/gdd-sessionstart-recap.test.cjs` — ≥4 tests for diff + Codex no-op (Plan 27.6-05).
+- `tests/prompt-dedup.test.cjs` — 12 tests for D-11 threshold + cycle scoping + alphabetic sort + malformed-event filter (Plan 27.6-06).
+- `tests/phase-27-6-baseline.test.cjs` — version-agnostic regression baseline (Plan 27.6-06).
+
+---
+
 ## [1.27.5] — 2026-05-17
 
 ### Added

package/agents/perf-analyzer.md

@@ -0,0 +1,166 @@
+---
+name: perf-analyzer
+description: Cross-cycle performance reflector. Reads .design/telemetry/{costs,trajectories,events}.jsonl and surfaces top-3 token-cost regressions per agent + cache-hit-rate deltas + p95 latency spikes. Spawned by /gdd:reflect or /gdd:audit (NOT per-cycle). Phase 27.6 D-04.
+tools: Read, Write, Bash, Grep, Glob
+color: yellow
+model: inherit
+default-tier: opus
+tier-rationale: "Phase 27.6 reflector — analyzes cross-cycle telemetry, proposes pipeline-level perf improvements; opus matches design-reflector tier per D-04"
+size_budget: XL
+parallel-safe: never
+typical-duration-seconds: 45
+reads-only: false
+writes:
+  - ".design/perf/*.md"
+---
+
+@reference/shared-preamble.md
+
+# perf-analyzer
+
+## Role
+
+You are a cross-cycle performance reflector. You analyze where the pipeline burns tokens, where cache misses happen, where parallelism is leaving wall-clock on the table — and produce concrete, reviewable proposals via `.design/perf/<cycle-slug>.md`. You never auto-apply anything; the operator reviews via `/gdd:apply-reflections` (Phase 11 wiring).
+
+You run **cross-cycle, not per-cycle** (Phase 27.6 D-04). Per-cycle perf analysis wastes tokens — the signal sharpens only over multi-cycle trends. Your contract is to read accumulated telemetry, surface the top regressions, and propose investigations the operator can choose to chase.
+
+## When to Run
+
+Spawn this agent from:
+
+- `/gdd:reflect` — on-demand reflection (Phase 11)
+- `/gdd:audit` — end-of-cycle audit roll-up
+- `/gdd:perf` — direct invocation (if/when added; currently the two above suffice)
+
+**Do NOT spawn from any per-cycle stage** (brief / explore / plan / design / verify). Per-cycle invocation violates D-04 and wastes tokens — the analysis needs `>= 3` cycles of accumulated data to be meaningful (D-01). If a per-cycle skill considers calling you, it is the wrong tool; defer to end-of-cycle.
+
+## Required Reading
+
+The orchestrating skill supplies a `<required_reading>` block in the prompt. Read every listed file before acting.
+
+Minimum expected inputs (skip gracefully if absent, note what's missing in the output):
+
+- `.design/telemetry/costs.jsonl` — per-agent-spawn cost data (Phase 10.1)
+- `.design/telemetry/trajectories/*.jsonl` — agent wall-time data (Phase 22)
+- `.design/telemetry/events.jsonl` — full event stream (Phase 22)
+- `reference/perf-budget.md` — per-agent budgets + baseline pointers (Phase 27.6-02, may not exist yet on first run; skip gracefully)
+- `test-fixture/baselines/phase-27-6/perf-baseline.json` — synthetic baseline (Phase 27.6 D-03, exists after 27.6-06 closeout)
+
+Helper library (use Bash to require):
+
+- `scripts/lib/perf-analyzer/index.cjs` — `loadCosts({path, sinceCycle?})`, `loadTrajectories({dir})`
+- `scripts/lib/perf-analyzer/cost-regression.cjs` — `detectCostRegressions({rows, baseline, thresholdPct, cyclesRequired})`, `computeCacheHitDelta(...)`, `computeP95Spikes(...)`
+
+The helper library is a CommonJS module with no external deps — safe to require from Bash without dragging the gdd-state MCP graph.
+
+## Output
+
+Write `.design/perf/<cycle-slug>.md`. If `--dry-run` is set in the spawning prompt, print proposals to stdout only — do not write the file.
+
+Terminate with `## PERF ANALYSIS COMPLETE`.
+
+## 1. Top-3 Token-Cost Regressions
+
+Use `scripts/lib/perf-analyzer/cost-regression.cjs::detectCostRegressions` over `loadCosts({})`. Threshold = 25% (Phase 27.6 D-01 default; read `.design/budget.json#perf_regression_threshold` if present for an override). Minimum 3 distinct cycles required (D-01). Top-3 cap is enforced by the library.
+
+For each regression, render a `[REGRESSION]` proposal:
+
+```
+[REGRESSION] perf-analyzer-{agent}-{slug}
+- agent: <agent>
+- baseline_p50_usd: <number>
+- current_p50_usd: <number>
+- delta_pct: <number>%
+- cycles_observed: <count>
+- hypothesis: <one-line plausible cause; e.g., "added reference reads per spawn", "tier upgrade from sonnet→opus">
+- next_action: <one-line operator action; e.g., "/gdd:perf-investigate <agent>", "consider tier_override: sonnet">
+```
+
+For each regression, emit a `perf.regression_detected` event via `appendEvent` from the Phase 22 event stream:
+
+```javascript
+// Pseudo-instruction for the executor — the agent runs Bash with this shape
+const { appendEvent } = require('./scripts/lib/event-stream');
+appendEvent({
+  type: 'perf.regression_detected',
+  timestamp: new Date().toISOString(),
+  sessionId: process.env.GDD_SESSION_ID ?? 'perf-analyzer',
+  payload: { agent, baseline_p50_usd, current_p50_usd, delta_pct, cycles_observed },
+});
+```
+
+The `perf.regression_detected` event type is additive to the Phase 22 registry — the writer accepts unknown types (per `scripts/lib/event-stream/types.ts` envelope invariant: "unknown types are allowed; validation is structural, not a closed enum").
+
+If `detectCostRegressions` returns `summary.regressions_count === 0`, write a single line: `No token-cost regressions detected (threshold 25%, >=3 cycles).` and skip event emission for this section.
+
+## 2. Cache-Hit-Rate Deltas
+
+Use `computeCacheHitDelta` over the same row set. Report agents whose `delta_pct < -20` (hit rate dropped by 20% or more) as `[CACHE-MISS]` proposals:
+
+```
+[CACHE-MISS] perf-analyzer-{agent}-cache-{slug}
+- agent: <agent>
+- baseline_hit_rate: <0..1>
+- current_hit_rate: <0..1>
+- delta_pct: <negative number>%
+- cycles_observed: <count>
+- hypothesis: <one-line cause; e.g., "preamble churn invalidated prefix cache", "new reference reads broke cache key">
+- next_action: <one-line; e.g., "/gdd:cache-investigate <agent>", "audit shared-preamble.md drift">
+```
+
+If no agent crosses the -20% threshold, write a single line acknowledging that the cache hit rates are within tolerance.
+
+## 3. p95 Latency Spikes
+
+Use `computeP95Spikes` over `loadTrajectories({})`. Report any agent with `multiplier >= 1.5` as a `[LATENCY-SPIKE]` proposal:
+
+```
+[LATENCY-SPIKE] perf-analyzer-{agent}-p95-{slug}
+- agent: <agent>
+- baseline_p95_ms: <number>
+- current_p95_ms: <number>
+- multiplier: <number>x
+- cycles_observed: <count>
+- hypothesis: <one-line; e.g., "model upgrade increased latency", "Bash tool blocked on lock">
+- next_action: <one-line; e.g., "/gdd:trace-agent <agent>", "review recent tool-args distribution">
+```
+
+If no agent crosses the 1.5x threshold, write a single line confirming p95 wall-time is stable.
+
+## 4. Roll-up Summary
+
+At the bottom, print a single table for at-a-glance cycle review:
+
+| Metric                              | Value |
+| ----------------------------------- | ----- |
+| regressions_count                   | N     |
+| cache_miss_count                    | N     |
+| latency_spike_count                 | N     |
+| agents_evaluated                    | N     |
+| agents_skipped_insufficient_data    | N     |
+| threshold_pct                       | 25    |
+| cycles_required                     | 3     |
+
+The numbers come straight from `detectCostRegressions().summary` and the lengths of the cache-miss / latency-spike arrays. Do not synthesize counts — read them from the library output.
+
+## What This Agent Does NOT Do
+
+- Does NOT auto-tune heuristics (out of scope per CONTEXT.md "auto-tuning of heuristic weights").
+- Does NOT modify model selection (Phase 23.5 bandit territory; 27.5 wired the bandit, 27.6 only measures outcomes).
+- Does NOT rewrite reference files (Phase 46 territory — canonical reference index).
+- Does NOT analyze cross-runtime cost arbitrage (Phase 26 territory).
+- Does NOT run on every cycle. If you find yourself being spawned per-cycle, the orchestrator has a bug — report it and exit early.
+
+Stay within the cross-cycle measurement loop. Surface proposals; the operator reviews and applies.
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"perf-analyzer","cycle":"<cycle from STATE.md>","stage":"reflection","one_line_insight":"<top regression hypothesis or 'no regressions detected'>","artifacts_written":[".design/perf/<cycle-slug>.md"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. The `artifacts_written` array MUST list the per-cycle perf proposal file. If no proposals were generated (cold-start tolerance), still write the `.md` (with a "no regressions detected" body) and emit the line with the artifact path.
+
+## PERF ANALYSIS COMPLETE

package/hooks/gdd-precompact-snapshot.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * hooks/gdd-precompact-snapshot.js — Plan 27.6-05
+ *
+ * Claude Code PreCompact hook. Immediately before context compaction,
+ * writes an atomic snapshot of STATE.md sections + last-N event-chain
+ * entries + last-N decisions to `.design/snapshots/<ts>.json`.
+ *
+ * Phase 27.6 D-08: atomic .tmp + rename via scripts/lib/lockfile.cjs.
+ *   - Lockfile serializes concurrent PreCompact writers.
+ *   - .tmp + rename guarantees no partial file ever appears at target path
+ *     (a SIGKILL between writeFileSync and renameSync leaves an orphan
+ *     .tmp file, never a corrupted snapshot).
+ *
+ * Phase 27.6 D-10: harness-aware — Codex has no PreCompact, so on
+ *   harness=codex this is a one-line stderr no-op (Phase 45 dep for
+ *   full pre-large-context-action interception).
+ *
+ * Silent-on-failure: tolerable errors exit 0 with stderr breadcrumb.
+ * Emits `snapshot.written` 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 RETENTION_COUNT = 10;
+const EVENTS_TAIL_COUNT = 50;
+const DECISIONS_TAIL_COUNT = 10;
+const SCHEMA_VERSION = '1.0.0';
+
+// ---------------------------------------------------------------------------
+// Harness detection (D-10)
+// ---------------------------------------------------------------------------
+
+function detectHarness() {
+  const explicit = (process.env.CLAUDE_HARNESS || process.env.GDD_HARNESS || '')
+    .toLowerCase()
+    .trim();
+  if (explicit === 'codex' || explicit === 'codex-cli') return 'codex';
+  // Default — Claude Code (only harness that emits PreCompact today).
+  return 'claude-code';
+}
+
+// ---------------------------------------------------------------------------
+// Lazy event-stream emit (best-effort — never blocks the hook)
+// ---------------------------------------------------------------------------
+
+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 — extracts frontmatter + decisions + blockers
+// ---------------------------------------------------------------------------
+
+function readStateSections() {
+  if (!fs.existsSync(STATE_MD_PATH)) {
+    return { frontmatter: {}, decisions: [], blockers: [], session: '' };
+  }
+  let body;
+  try {
+    body = fs.readFileSync(STATE_MD_PATH, 'utf8');
+  } catch {
+    return { frontmatter: {}, decisions: [], blockers: [], session: '' };
+  }
+
+  // Extract YAML frontmatter (between leading '---' delimiters)
+  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();
+    }
+  }
+
+  // Decisions: extract D-XX entries from a '<decisions>' or '## Decisions' section
+  const decisions = [];
+  const decisionsMatch = body.match(
+    /(?:<decisions>|## Decisions)([\s\S]*?)(?:<\/decisions>|^##\s|\Z)/m,
+  );
+  if (decisionsMatch) {
+    const dRe = /D-\d+:[^\n]+/g;
+    let m2;
+    while ((m2 = dRe.exec(decisionsMatch[1])) !== null) {
+      decisions.push(m2[0].trim());
+    }
+  }
+
+  // Blockers: similar to decisions
+  const blockers = [];
+  const blockersMatch = body.match(
+    /(?:<blockers>|## Blockers)([\s\S]*?)(?:<\/blockers>|^##\s|\Z)/m,
+  );
+  if (blockersMatch) {
+    const bRe = /B-\d+:[^\n]+/g;
+    let m3;
+    while ((m3 = bRe.exec(blockersMatch[1])) !== null) {
+      blockers.push(m3[0].trim());
+    }
+  }
+
+  // Session prefix (first ~500 chars after '## Session' or '<session>')
+  const sessionMatch = body.match(/(?:## Session|<session>)([\s\S]{0,500})/);
+  const session = sessionMatch ? sessionMatch[1].trim().slice(0, 500) : '';
+
+  return { frontmatter, decisions, blockers, session };
+}
+
+// ---------------------------------------------------------------------------
+// Events tail reader — JSONL-tolerant (malformed lines are skipped)
+// ---------------------------------------------------------------------------
+
+function readEventsTail(count) {
+  if (!fs.existsSync(EVENTS_PATH)) return [];
+  let body;
+  try {
+    body = fs.readFileSync(EVENTS_PATH, 'utf8');
+  } catch {
+    return [];
+  }
+  const events = [];
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      /* tolerate malformed line — T-27.6.05-05 mitigation */
+    }
+  }
+  return events.slice(-count);
+}
+
+// ---------------------------------------------------------------------------
+// Retention prune — LRU by mtime, keep last RETENTION_COUNT (D-08)
+// ---------------------------------------------------------------------------
+
+function pruneSnapshots() {
+  let files;
+  try {
+    files = fs.readdirSync(SNAPSHOT_DIR);
+  } catch {
+    return;
+  }
+  const jsonFiles = files
+    .filter((f) => f.endsWith('.json') && f !== 'last-recap.json')
+    .map((f) => ({ name: f, full: path.join(SNAPSHOT_DIR, f), mtime: 0 }));
+
+  for (const entry of jsonFiles) {
+    try {
+      entry.mtime = fs.statSync(entry.full).mtimeMs;
+    } catch {
+      /* swallow */
+    }
+  }
+
+  jsonFiles.sort((a, b) => a.mtime - b.mtime);
+  while (jsonFiles.length > RETENTION_COUNT) {
+    const oldest = jsonFiles.shift();
+    try {
+      fs.unlinkSync(oldest.full);
+    } catch {
+      /* swallow — race with another writer; LRU eventually wins */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main — atomic write with lockfile serialization
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const harness = detectHarness();
+  if (harness === 'codex') {
+    // D-10: Codex has no PreCompact event; emit notice + exit. Phase 45 dep
+    // for full `pre-large-context-action` interception.
+    process.stderr.write(
+      '[gdd-precompact-snapshot] this harness does not emit PreCompact; snapshots disabled\n',
+    );
+    process.exit(0);
+  }
+
+  // Drain stdin (Claude Code may pipe a hook event JSON; we don't need it
+  // but draining avoids EPIPE on the parent's writer side).
+  try {
+    if (!process.stdin.isTTY) {
+      // Best-effort, non-blocking — we have nothing time-sensitive in stdin.
+      process.stdin.on('error', () => {
+        /* swallow */
+      });
+      process.stdin.resume();
+    }
+  } catch {
+    /* swallow */
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const snapshotPath = path.join(SNAPSHOT_DIR, ts + '.json');
+  const tmpPath = snapshotPath + '.tmp';
+
+  // Ensure snapshot dir exists (mkdir -p semantics).
+  try {
+    fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
+  } catch {
+    /* swallow — write will fail loudly below if truly missing */
+  }
+
+  // Acquire lockfile on the target path (T-27.6.05-02 mitigation).
+  // The lock file lives at <snapshotPath>.lock and serializes concurrent
+  // PreCompact writers; the second writer either waits or fails-silent.
+  let release = null;
+  try {
+    const lockfile = require('../scripts/lib/lockfile.cjs');
+    release = await lockfile.acquire(snapshotPath, {
+      staleMs: 60_000,
+      maxWaitMs: 10_000,
+      pollMs: 50,
+    });
+  } catch (err) {
+    process.stderr.write(
+      '[gdd-precompact-snapshot] lock acquire failed: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+    process.exit(0);
+  }
+
+  try {
+    const sections = readStateSections();
+    const events = readEventsTail(EVENTS_TAIL_COUNT);
+    const decisions = sections.decisions.slice(-DECISIONS_TAIL_COUNT);
+    const cycleId =
+      sections.frontmatter && sections.frontmatter.milestone
+        ? sections.frontmatter.milestone
+        : 'unknown';
+
+    const snapshot = {
+      schema_version: SCHEMA_VERSION,
+      timestamp: new Date().toISOString(),
+      cycle_id: cycleId,
+      state_md_sections: sections,
+      last_n_events: events,
+      last_n_decisions: decisions,
+    };
+
+    const body = JSON.stringify(snapshot, null, 2);
+
+    // Atomic write: .tmp + rename (T-27.6.05-01 mitigation).
+    // A SIGKILL between writeFileSync and renameSync leaves <snapshotPath>.tmp
+    // orphaned but NEVER a partial file at <snapshotPath> itself.
+    try {
+      fs.writeFileSync(tmpPath, body, 'utf8');
+      fs.renameSync(tmpPath, snapshotPath);
+    } catch (err) {
+      process.stderr.write(
+        '[gdd-precompact-snapshot] atomic write failed: ' +
+          (err && err.message ? err.message : String(err)) +
+          '\n',
+      );
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        /* swallow orphan cleanup */
+      }
+      process.exit(0);
+    }
+
+    // Retention prune (T-27.6.05-04 DoS mitigation).
+    pruneSnapshots();
+
+    // Best-effort event emit.
+    const appendEvent = getAppendEvent();
+    try {
+      appendEvent({
+        type: 'snapshot.written',
+        timestamp: new Date().toISOString(),
+        sessionId: process.env.GDD_SESSION_ID || 'precompact-hook',
+        payload: {
+          path: snapshotPath,
+          size_bytes: Buffer.byteLength(body, 'utf8'),
+          events_count: events.length,
+          decisions_count: decisions.length,
+          harness,
+        },
+      });
+    } catch {
+      /* swallow — telemetry never blocks */
+    }
+
+    // Emit non-blocking continue verdict on stdout (matches other hooks).
+    try {
+      process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }));
+    } catch {
+      /* swallow */
+    }
+
+    process.exit(0);
+  } finally {
+    if (release) {
+      try {
+        await release();
+      } catch {
+        /* swallow — stale-detection reclaims */
+      }
+    }
+  }
+}
+
+main().catch((err) => {
+  try {
+    process.stderr.write(
+      '[gdd-precompact-snapshot] uncaught: ' +
+        (err && err.message ? err.message : String(err)) +
+        '\n',
+    );
+  } catch {
+    /* swallow */
+  }
+  process.exit(0);
+});