@hegemonart/get-design-done 1.27.1 → 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.1",
+  "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/bandit-integration.md

@@ -0,0 +1,163 @@
+---
+name: bandit-integration
+phase: 27.5
+version: 1.0.0
+type: meta-rules
+description: Bandit posterior + production-integration shim cheat sheet — signatures, reward function semantics, adaptive_mode gate, posterior path conventions.
+---
+
+# Bandit Integration — Developer Cheat Sheet
+
+**Phase 27.5 (v1.27.5).** Reference for the bandit production-integration surface. Authoring or modifying a caller of the bandit posterior? Debugging a routing decision at the code level? Start here.
+
+For ops-level guidance (when bandit fires, how to disable, posterior inspection), see `docs/BANDIT-INTEGRATION.md`.
+
+In-scope modules:
+
+- `scripts/lib/bandit-router.cjs` (Phase 23.5 primitives).
+- `scripts/lib/bandit-router/integration.cjs` (Phase 27.5 shim).
+
+---
+
+## The two-stage architecture
+
+Phase 23.5 ships the bandit primitives — Thompson-sampling pull, posterior update, computeReward, atomic persistence. Phase 27-07 added the `delegate?` arm dimension (5 peer-CLI arms + the local `none` arm). Both phases shipped library-only with no production callers.
+
+Phase 27.5 ships the production-integration shim that wraps the primitives behind two purpose-built entry points and hides the `pull` vs `pullWithDelegate` choice. Callers pass a `delegate` argument and the shim routes internally.
+
+### Phase 23.5 + 27-07 surface — `scripts/lib/bandit-router.cjs`
+
+Exports: `pull`, `update`, `pullWithDelegate`, `updateWithDelegate`, `computeReward`, `loadPosterior`, `savePosterior`, `reset`, `decayArm`, `sampleBeta`, `priorFor`, `binForGlobCount`, `DEFAULT_DELEGATES`, `DELEGATE_NONE`, `TIER_PRIOR`, `PRIOR_STRENGTH`, `TOUCHES_BINS`, `DEFAULT_POSTERIOR_PATH`, `SCHEMA_VERSION`.
+
+The two-pair primitive split:
+
+- `pull({agent, bin, ...})` / `update({agent, bin, tier, reward, ...})` — operate on the `(agent, bin, tier)` arm slice. Equivalent to `delegate='none'`.
+- `pullWithDelegate({agent, bin, delegates, ...})` / `updateWithDelegate({agent, bin, tier, delegate, reward, ...})` — operate on the `(agent, bin, tier, delegate)` arm slice for any `delegate ∈ DEFAULT_DELEGATES`.
+
+### Phase 27.5 surface — `scripts/lib/bandit-router/integration.cjs`
+
+Exports: `consultBandit`, `recordOutcome`, `DELEGATE_NONE`.
+
+Routing rules (D-05, D-07):
+
+1. `agentFrontmatter.tier_override` set → bypass bandit, return `tier_override`.
+2. `adaptiveMode !== 'full'` → bandit silent, return `frontmatter.default_tier`.
+3. `adaptiveMode === 'full'` + delegate `'none'` or undefined → call `pull()`.
+4. `adaptiveMode === 'full'` + delegate is a peer name → call `pullWithDelegate({delegates: [delegate]})`.
+
+`recordOutcome` is symmetric on the adaptive-mode gate.
+
+---
+
+## `consultBandit` signature
+
+```javascript
+consultBandit({
+  agent: string,            // required
+  bin: string,              // required: 'tiny' | 'small' | 'medium' | 'large'
+  delegate: string,         // 'none' or one of DEFAULT_DELEGATES
+  agentFrontmatter: {
+    tier_override?: string,
+    default_tier?: string,
+  },
+  adaptiveMode?: 'static' | 'hedge' | 'full',  // omit to read on-disk
+  baseDir?: string,         // override workspace root (test-injection)
+  posteriorPath?: string,   // override posterior file path (test-injection)
+}) → {
+  tier: 'haiku' | 'sonnet' | 'opus',
+  decision_log: {
+    source: 'frontmatter' | 'tier_override_bypass' | 'bandit_pull' | 'bandit_pull_with_delegate',
+    samples?: { haiku?: number, sonnet?: number, opus?: number },
+    delegate?: string,
+    adaptive_mode: string,
+    reason?: string,
+  },
+}
+```
+
+`decision_log.source` is the audit trail — it tells observability tools which routing branch ran. Tests use it to assert the correct path was taken.
+
+---
+
+## `recordOutcome` signature
+
+```javascript
+recordOutcome({
+  agent: string,
+  bin: string,
+  delegate: string,
+  tier: string,
+  status: string,           // SessionResult.status — only 'completed' triggers reward.solidify_pass
+  costUsd?: number,
+  adaptiveMode?: 'static' | 'hedge' | 'full',
+  baseDir?: string,
+  posteriorPath?: string,
+}) → void  // best-effort per D-04 — write errors are swallowed
+```
+
+Reward semantics:
+
+- `solidify_pass = (status === 'completed')`.
+- If `!solidify_pass`, reward is `0`. If true, reward is `1 - lambda * normalize(costUsd + epsilon * wallTimeMs)`.
+
+Phase 27.5 passes `wallTimeMs: 0` always (D-08 unchanged from Phase 23.5).
+
+---
+
+## `adaptive_mode` gate semantics
+
+Phase 23.5 ladder (D-07):
+
+- `static` — default. Bandit silent. `default-tier:` is authoritative. No reads, no writes.
+- `hedge` — measurement-only. Bandit silent on reads, but `recordOutcome` may still write to seed the posterior. Currently identical to `static` in Phase 27.5; reserved for Phase 28+ explicit "hedge mode".
+- `full` — bandit active. Reads pick via Thompson sampling; writes update posterior.
+
+The shim respects the gate transparently. Operators flip via `.design/budget.json#adaptive_mode`.
+
+---
+
+## Reward function
+
+`computeReward({solidify_pass, cost_usd, wall_time_ms, lambda?, epsilon?, costNormalizer?}) → number`
+
+Two-stage lexicographic (D-08, unchanged from Phase 23.5):
+
+- Stage 1 — correctness: if `solidify_pass !== true`, return `0`.
+- Stage 2 — cost: return `1 - lambda * normalize(cost_usd + epsilon * wall_time_ms)`.
+
+Defaults: `lambda = 0.3`, `epsilon = 0.05`. `normalize` maps `[0, $5]` linearly to `[0, 1]`, clamped.
+
+Cheaper successful spawns get higher reward. Failed spawns are flat zero. Tune `lambda` to weight cost less.
+
+---
+
+## Posterior path
+
+Canonical path: `.design/telemetry/posterior.json` (Phase 23.5 D-08, Phase 27.5 D-06 unchanged). Path is owned by `DEFAULT_POSTERIOR_PATH` constant in `scripts/lib/bandit-router.cjs`.
+
+Test injection: pass `baseDir` (anchors path under a different workspace root) or `posteriorPath` (overrides the file path directly). Both `consultBandit` and `recordOutcome` accept these options.
+
+Write discipline: atomic via `.tmp` + rename. Read failures yield an empty posterior; subsequent writes overwrite. Concurrent writers within the same process are not synchronized — gdd's session-runner is single-threaded.
+
+---
+
+## Call sites
+
+Phase 27.5 wires these consumers:
+
+- **`hooks/budget-enforcer.ts`** (Plan 27.5-02) — per Agent spawn, after `resolved_models` is computed, before SDK call. Calls `consultBandit({agent, bin, delegate, agentFrontmatter, adaptiveMode})`. Overrides `resolved_models[agent]` with the bandit tier via `tier-resolver.cjs`. Emits `bandit.tier_selected` event for observability.
+- **`scripts/lib/session-runner/index.ts`** (Plan 27.5-03) — terminal-emit path. Calls `recordOutcome({agent, bin, delegate, tier, status, costUsd})` after every `emit('session.completed', ...)` site (4 sites: rate-limited, peer-success, turn-cap-zero, terminal retry-exit). Posterior write is best-effort; missing optional fields silent.
+- **`agents/design-reflector.md` Section 8** (Plan 27.5-04) — bandit-arbitrage analysis. `scripts/lib/bandit-arbitrage.cjs` reads `.design/telemetry/posterior.json` and surfaces stale-frontmatter proposals. Mirrors Phase 26-06's `cost-arbitrage.cjs` shape.
+- **`skills/peers/SKILL.md` Step 5 + `skills/bandit-status/SKILL.md`** (Plan 27.5-05) — read-only diagnostic surfaces. `/gdd:peers` posterior delta column populated; `/gdd:bandit-status` renders per-`(agent, bin, delegate, tier)` snapshots.
+
+---
+
+## Cross-references
+
+- `docs/BANDIT-INTEGRATION.md` — operator guide (when bandit fires, how to disable, troubleshooting).
+- `reference/peer-protocols.md` — Phase 27 ACP/ASP cheat sheet (peer-CLI delegation transport).
+- `scripts/lib/bandit-router.cjs` — Phase 23.5 primitives surface.
+- `scripts/lib/bandit-router/integration.cjs` — Phase 27.5 production shim.
+- `scripts/lib/bandit-arbitrage.cjs` — Phase 27.5 reflector analyzer (Section 8 of `design-reflector.md`).
+- `hooks/budget-enforcer.ts` — bandit consultation site.
+- `scripts/lib/session-runner/index.ts` — `recordOutcome` site.

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

@@ -95,6 +95,13 @@
       "type": "authority-feed",
       "description": "Whitelist of design-authority feed sources for the watcher"
     },
+    {
+      "name": "bandit-integration",
+      "path": "reference/bandit-integration.md",
+      "type": "meta-rules",
+      "phase": 27.5,
+      "description": "Phase 27.5 bandit production-integration cheat sheet — consultBandit + recordOutcome shim signatures, adaptive_mode gate semantics, reward function (Phase 23.5 D-08 unchanged), posterior path .design/telemetry/posterior.json, call-site map (budget-enforcer + session-runner + design-reflector Section 8)"
+    },
     {
       "name": "brand-voice",
       "path": "reference/brand-voice.md",
@@ -652,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",