@hegemonart/get-design-done 1.27.1 → 1.27.6

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.27.1",
+  "version": "1.27.6",
   "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,101 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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
+
+- **Phase 27.5 — Bandit Production Integration** (6 plans). Wires Phase 23.5's bandit posterior + Phase 27-07's `delegate?` dimension into a real production routing path. After v1.27.5, `default-tier:` becomes a default (cold-start prior), not a final answer — the bandit picks the final tier from measurement when `adaptive_mode: full`.
+  - `scripts/lib/bandit-router/integration.cjs` (Plan 27.5-01) — thin shim exposing `consultBandit({agent, bin, delegate, agentFrontmatter, adaptiveMode}) → {tier, decision_log}` and `recordOutcome({agent, bin, delegate, tier, status, costUsd, adaptiveMode}) → void`. Hides `pull` vs `pullWithDelegate` choice. Best-effort posterior write per D-04.
+  - `hooks/budget-enforcer.ts` (Plan 27.5-02) — bandit consultation per Agent spawn after `resolved_models` is computed, before SDK call. Overrides `resolved_models[agent]` via `tier-resolver.cjs` when the bandit picks a different tier than the router emitted. Emits `bandit.tier_selected` event per spawn. Respects `tier_override:` frontmatter bypass (D-05), `adaptive_mode` gate (D-07), and the 80% auto-downgrade guard.
+  - `scripts/lib/session-runner/index.ts` (Plan 27.5-03) — calls `recordOutcome()` after every `emit('session.completed', ...)` site (4 call sites: rate-limited, peer-success, turn-cap-zero, terminal retry-exit). Adds 3 optional fields to `SessionRunnerOptions`: `agent`, `bin`, `tier`. Posterior write is best-effort; missing fields silent.
+  - `agents/design-reflector.md` Section 8 (Plan 27.5-04) — bandit-arbitrage analysis surfaces "agent X frontmatter says sonnet but bandit picks opus" as `[FRONTMATTER]` proposals after 3+ pulls with credible interval < 0.05 and ≥ 50% mean delta vs second-best tier (D-10). New module `scripts/lib/bandit-arbitrage.cjs` mirrors Phase 26-06's cost-arbitrage shape.
+  - `skills/peers/SKILL.md` Step 5 + new `skills/bandit-status/SKILL.md` (Plan 27.5-05) — `/gdd:peers` now reads canonical posterior path `.design/telemetry/posterior.json` and renders real per-peer reward-delta when posterior is populated. New read-only `/gdd:bandit-status` skill surfaces per-`(agent, bin, delegate, tier)` posterior snapshots (alpha/beta/mean/stddev/count/last-used). Strictly read-only per D-11.
+  - `docs/BANDIT-INTEGRATION.md` + `reference/bandit-integration.md` (Plan 27.5-06) — operator guide + developer cheat sheet.
+
+### Decisions locked
+
+- D-01: `hooks/budget-enforcer.ts` is the bandit consultation site (single canonical routing decision point).
+- D-02: Per-spawn timing, after `resolved_models` computed, before SDK call.
+- D-03: Override `resolved_models[agent]` with bandit tier through `tier-resolver.cjs`. Preserve `model_tier_overrides[agent]` unchanged (back-compat).
+- D-04: `update()` called in session-runner's terminal-emit path after `session.completed`. Best-effort posterior write — errors swallowed.
+- D-05: `tier_override:` frontmatter is the explicit per-agent bandit-bypass surface.
+- D-06: Posterior path stays at `.design/telemetry/posterior.json` (Phase 23.5 D-08 unchanged).
+- D-07: Bandit consultation gated by `adaptive_mode` (static + hedge silent; full active).
+- D-08: Reward function unchanged from Phase 23.5 (two-stage lexicographic correctness + cost).
+- D-09: Cold-start prior for the 5 peer delegate arms uses neutral `TIER_PRIOR` (no bias toward any peer).
+- D-10: Reflector bandit-arbitrage reuses `cost-arbitrage.cjs` shape (50% threshold, mirror Phase 26-06).
+- D-11: `/gdd:bandit-status` is read-only (use `/gdd:bandit-reset` from Phase 23.5 to mutate).
+- D-12: All 6 plans land together with one CHANGELOG block; 4 manifests bump lockstep.
+
+### Out of scope (deferred)
+
+- Auto-failover when bandit recommends a delegate not in `enabled_peers` — bandit stays advisory.
+- Cross-cycle posterior decay — Phase 23.5 D-12 already specifies discounted Thompson sampling.
+- Per-task bandit dimensions beyond `(agent, bin, delegate)` — needs convergence proof first.
+- Removing frontmatter `default-tier:` — additive only; deprecation is Phase 30+.
+- Bandit-driven complexity_class selection — different decision domain.
+
+### Test coverage
+
+- `tests/bandit-router-integration.test.cjs` — 25+ tests covering all 5 paths × adaptive_mode × tier_override × delegate (Plan 27.5-01).
+- `tests/budget-enforcer-bandit.test.cjs` — 8+ tests for hook consultation branches (Plan 27.5-02).
+- `tests/session-runner-bandit-outcome.test.cjs` — 6+ tests for recordOutcome paths (Plan 27.5-03).
+- `tests/bandit-arbitrage.test.cjs` — 6+ tests for reflector analyzer (Plan 27.5-04).
+- `tests/phase-27-5-baseline.test.cjs` — manifests + baseline + integration-exports regression (Plan 27.5-06).
+
+---
+
 ## [1.27.1] — 2026-04-30
 
 Phase 27 wiring patch — closes the production-integration gaps left by v1.27.0's "structural ship". v1.27.0 landed all peer-CLI library code + tests + docs but the helpers were exported without callers, so `delegate_to:` on agent frontmatter was validated and then ignored at runtime. v1.27.1 wires the four integration points so delegation actually fires for users who set `delegate_to:` AND allowlist the peer.

package/SKILL.md

@@ -89,6 +89,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `skill-manifest [--refresh]` | `get-design-done:skill-manifest` | List or refresh the local skill manifest used by the router for discovery |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 — parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 — Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
+| `bandit-status` | `get-design-done:bandit-status` | Phase 27.5 — read-only diagnostic surface for the bandit posterior; per-(agent, bin, delegate, tier) snapshots (alpha, beta, mean, stddev, count, last-used). Use `/gdd:bandit-reset` to mutate. |
 | `peers` | `get-design-done:peers` | Phase 27 — `/gdd:peers` capability matrix command; shows installed peer-CLIs (codex/gemini/cursor/copilot/qwen), allowlist status, claimed roles, posterior delta vs local |
 | `peer-cli-customize` | `get-design-done:peer-cli-customize` | Phase 27 — rewire role→peer mappings on a per-agent basis (edits frontmatter `delegate_to:` directly) |
 | `peer-cli-add` | `get-design-done:peer-cli-add` | Phase 27 — guided ladder for adding a brand-new peer (verification ladder + adapter scaffolding + capability-matrix update) |

package/agents/design-reflector.md

@@ -151,6 +151,58 @@ Render each `cost_arbitrage` entry into the Proposals section as a `[BUDGET]`-ta
 
 ---
 
+### 8. Bandit-arbitrage analysis (Phase 27.5 — D-10)
+
+**Why this exists:** Phase 27.5 (v1.27.5) wired the bandit posterior + delegate dimension into production. The posterior now accumulates per-`(agent, bin, delegate, tier)` win-rates from real spawns. Once the posterior has enough data, the bandit's best-arm tier for an agent may differ from that agent's frontmatter `default-tier:` — a measurement signal that the frontmatter is stale. This section surfaces that signal as a `[FRONTMATTER]` proposal.
+
+**Data sources:**
+
+- `.design/telemetry/posterior.json` — the bandit posterior file written by Phase 23.5's `bandit-router.cjs` + Phase 27.5-02/03's production callers. Path matches `bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`. If the file does not exist, skip this section with note "posterior.json not found — Phase 27.5 wiring required."
+- `agents/*.md` — read each agent's frontmatter `default-tier:` value. The reflector already parses frontmatter in Section 3 ("Agent Performance"); reuse that parse pass and build a `{agent: defaultTier}` map keyed by the agent's `name:` field.
+
+**The rule:**
+
+For each `(agent, bin)` slice in the posterior (defaulting to `delegate='none'` arms — focuses on local-call routing):
+
+1. Compute per-tier posterior mean = `α / (α + β)` and stddev = `sqrt(αβ / ((α+β)² · (α+β+1)))`.
+2. Identify `posterior_best_tier = argmax(mean)` across the tiers present in the slice.
+3. Gates (all must hold to emit):
+    - `sum(arm.count)` across the slice's tier rows >= 3 (D-10's "3+ cycles" proxy).
+    - `(best_mean - second_best_mean) / second_best_mean >= 0.5` (50% delta heuristic).
+    - `stddev(best_tier) < 0.05` (credible interval narrow enough).
+    - `frontmatter[agent].default-tier !== posterior_best_tier` (the actual stale signal).
+4. If all gates hold, emit a structured `bandit_arbitrage` proposal.
+
+**Important guardrails (failure modes the rule must avoid):**
+
+- **Single-tier-only history is silent.** If only one tier has been pulled for `(agent, bin)`, no comparison is possible — emit nothing rather than a misleading "winner" proposal.
+- **Wide credible intervals are silent.** Bandit posteriors are noisy early on; the 0.05 stddev gate ensures we only surface signals where the bandit is confident.
+- **The 50% threshold is a starting heuristic.** Same discipline as cost-arbitrage Section 7 — bandit-learning over which arbitrage proposals were APPLIED (and whether the posterior subsequently shifted) is a separate (future) phase.
+- **delegateFilter='none' is the v1.27.5 default.** Arbitrage analysis on the 5 peer-delegate slices is left for a future plan; current peer data is too sparse to credibly disagree with frontmatter.
+
+**Helper:** `scripts/lib/bandit-arbitrage.cjs` exports `analyze(posterior, options) → proposals[]` implementing the above rule deterministically. The executor agent following this skill loads the posterior via `bandit-router.loadPosterior()`, builds the `{agent: defaultTier}` map from `agents/*.md` frontmatter, and passes both to `analyze()`. No re-derivation of the rule in prose — call the helper.
+
+**Proposal output shape** (one entry per stale-frontmatter signal, JSON-serializable for `/gdd:apply-reflections`):
+
+```json
+{
+  "type": "bandit_arbitrage",
+  "agent": "design-verifier",
+  "bin": "medium",
+  "current_frontmatter_tier": "sonnet",
+  "posterior_best_tier": "opus",
+  "posterior_mean": { "haiku": 0.50, "sonnet": 0.62, "opus": 0.95 },
+  "posterior_stddev": { "haiku": 0.04, "sonnet": 0.03, "opus": 0.02 },
+  "pull_count": 18,
+  "proposal": "design-verifier (medium bin) frontmatter says sonnet but bandit picks opus (posterior mean 0.950 vs 0.620, 18 pulls, stddev 0.020) — update frontmatter or add tier_override: sonnet if intentional",
+  "evidence": "posterior_cred_int_narrow"
+}
+```
+
+Render each `bandit_arbitrage` entry into the Proposals section as a `[FRONTMATTER]`-tagged proposal carrying the structured payload verbatim. `/gdd:apply-reflections` routes the proposal to either (a) an `agents/<name>.md` frontmatter `default-tier:` update OR (b) a new `tier_override: <existing-tier>` add when the operator explicitly wants to keep the existing default-tier despite the measured drift.
+
+---
+
 ## Proposals
 
 After all sections, write a **Proposals** section. Number proposals sequentially. Every proposal must include evidence — no vague observations.

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