@hegemonart/get-design-done 1.27.0 → 1.27.5

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.27.0",
+  "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.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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.
+
+### Fixed
+
+- **`session-runner.run()` now invokes `tryDelegate` (Plan 27-06 wiring)** — when `opts.delegateTo` is set to a `<peer>-<role>` value AND the registry can route AND the peer is in `.design/config.json#peer_cli.enabled_peers`, the prompt runs on the peer-CLI and `run()` returns the peer result. On peer-absent / peer-error / null result, falls through transparently to the local Anthropic SDK loop (D-07). Previously the `tryDelegate` helper existed in the file but `run()` never called it.
+
+- **Real `appendEvent('peer_call_started|complete|failed', ...)` emission (Plan 27-08 wiring)** — replaced the stderr-only placeholder in session-runner with three real event-emission calls. Events flow through Phase 22's `appendEvent()` API using the constants registered in v1.27.0, tagged with `runtime_role: 'peer'` and `peer_id`. Reflector cross-runtime cost-arbitrage (Plan 26-06) now sees peer telemetry. `GDD_PEER_DEBUG=1` continues to mirror the failed events to stderr for live tailing.
+
+- **`install.cjs` interactive peer-detection nudge (Plan 27-11 wiring)** — after a successful (non-uninstall, non-dry-run) install in a TTY, scans `peerBinary` paths via `detectInstalledPeers()`. If 1+ peer detected, prompts via `@clack/prompts` with `confirm()` (default: NO). On yes, writes `.design/config.json#peer_cli.enabled_peers`. New `--no-peer-prompt` flag suppresses the prompt entirely (CI-friendly). Silent skip when zero peers detected. Default-NO preserves the opt-in trust contract (D-11).
+
+### Out of scope (known, deferred)
+
+- **Bandit `pullWithDelegate` caller (Plan 27-07 wiring)** — `pullWithDelegate` and `updateWithDelegate` ship in the bandit module surface (v1.27.0) but no production caller invokes them yet. Wiring requires `gdd-router` SKILL.md change (procedural, not code) which is out of scope for a wiring patch. Phase 28+ territory once the integration shape is decided. The `delegate?` dimension stays exported as a library extension for ad-hoc use.
+
+### Tests
+
+- Existing 23 peer-CLI session-runner / events / end-to-end tests pass after wiring.
+- Existing 33 install.cjs + peer-detect tests pass after the nudge addition.
+- Full Phase 27 surface tests stay green; no new test files (this is a wiring patch, not a new surface).
+
+---
+
 ## [1.27.0] — 2026-04-30
 
 Phase 27 Peer-CLI Delegation Layer milestone — closes the **outbound** half of multi-runtime. Phase 24 made gdd installable on 14 runtimes; Phase 21 made the same pipeline run on each; Phase 26 made tier→model resolve correctly per runtime. v1.27.0 adds the missing piece: gdd agents OPTIONALLY delegate to local peer CLIs (Codex via App Server Protocol; Gemini/Cursor/Copilot/Qwen via Agent Client Protocol) when measurably cheaper or higher-quality for the role. Falls back to in-process Anthropic SDK when peer is unavailable. Honors Phase 26 tier maps + Phase 22 event chain + Phase 23.5 bandit posterior — `delegate?` becomes another arm in `(agent_type × tier × delegate)` Thompson sampling, no new ML.

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/hooks/budget-enforcer.ts

@@ -105,6 +105,76 @@ interface RuntimeDetectModule {
 }
 const runtimeDetect = nodeRequire('../scripts/lib/runtime-detect.cjs') as RuntimeDetectModule;
 
+// Plan 27.5-01: bandit production-integration shim. Hides pull /
+// pullWithDelegate choice from the hook; reads adaptive_mode + frontmatter
+// tier_override under the same gating discipline as Phase 23.5 D-07 and
+// Phase 27.5 D-05.
+interface BanditIntegrationModule {
+  consultBandit(args: {
+    agent: string;
+    bin: string;
+    delegate: string;
+    agentFrontmatter: { tier_override?: string; default_tier?: string };
+    adaptiveMode?: 'static' | 'hedge' | 'full';
+    baseDir?: string;
+    posteriorPath?: string;
+  }): {
+    tier: 'haiku' | 'sonnet' | 'opus';
+    decision_log: {
+      source:
+        | 'frontmatter'
+        | 'tier_override_bypass'
+        | 'bandit_pull'
+        | 'bandit_pull_with_delegate';
+      samples?: Record<string, number> | Record<string, Record<string, number>>;
+      delegate?: string;
+      adaptive_mode: 'static' | 'hedge' | 'full';
+      reason?: string;
+    };
+  };
+  recordOutcome(args: unknown): void;
+  DELEGATE_NONE: 'none';
+}
+const banditIntegration = nodeRequire(
+  '../scripts/lib/bandit-router/integration.cjs',
+) as BanditIntegrationModule;
+
+// Plan 27.5-02: adaptive-mode module surfaces the single gating predicate.
+interface AdaptiveModeModule {
+  getMode(opts?: {
+    baseDir?: string;
+    budgetPath?: string;
+    quiet?: boolean;
+  }): 'static' | 'hedge' | 'full';
+  isBanditEnabled(opts?: { baseDir?: string; budgetPath?: string }): boolean;
+}
+const adaptiveMode = nodeRequire(
+  '../scripts/lib/adaptive-mode.cjs',
+) as AdaptiveModeModule;
+
+// Plan 27.5-02: bin selection helper for bandit (agent, bin) addressing.
+// budget-enforcer doesn't currently surface glob_count; default to 'medium'
+// as a safe per-agent partition until a future plan wires the real count.
+interface BanditRouterCoreModule {
+  binForGlobCount(n: number): 'tiny' | 'small' | 'medium' | 'large';
+  DEFAULT_DELEGATES: readonly string[];
+}
+const banditRouterCore = nodeRequire(
+  '../scripts/lib/bandit-router.cjs',
+) as BanditRouterCoreModule;
+
+// Plan 27.5-02: tier-resolver translates bandit tier → concrete model.
+interface TierResolverModule {
+  resolve(
+    runtime: string,
+    tier: string,
+    opts?: { silent?: boolean },
+  ): string | null;
+}
+const tierResolver = nodeRequire(
+  '../scripts/lib/tier-resolver.cjs',
+) as TierResolverModule;
+
 // ── Types ───────────────────────────────────────────────────────────────────
 
 /**
@@ -618,6 +688,50 @@ function emitCostRecorded(
   }
 }
 
+/**
+ * Plan 27.5-02 / D-03: emit `bandit.tier_selected` event when the bandit
+ * is consulted (regardless of whether it overrode the prior tier). The
+ * event captures the prior tier, the bandit's pick, the sampled posterior
+ * (when applicable), the delegate dimension, and the runtime tag so
+ * Phase 11 reflector (27.5-04) and `/gdd:bandit-status` (27.5-05) can
+ * reconstruct decision history without re-reading the posterior file.
+ *
+ * Fail-open like every other emit in this hook.
+ */
+function emitBanditTierSelected(
+  payload: {
+    agent: string;
+    bin: string;
+    prior_tier: string;
+    selected_tier: 'haiku' | 'sonnet' | 'opus';
+    source:
+      | 'frontmatter'
+      | 'tier_override_bypass'
+      | 'bandit_pull'
+      | 'bandit_pull_with_delegate';
+    delegate: string;
+    adaptive_mode: 'static' | 'hedge' | 'full';
+    samples?: unknown;
+    runtime: string;
+    model_id: string | null;
+    reason?: string;
+  },
+  cycle?: string,
+): void {
+  const ev = {
+    type: 'bandit.tier_selected',
+    timestamp: new Date().toISOString(),
+    sessionId: getSessionId(),
+    ...(cycle !== undefined && cycle !== 'unknown' ? { cycle } : {}),
+    payload,
+  };
+  try {
+    appendEvent(ev as unknown as HookFiredEvent);
+  } catch {
+    // Fail open.
+  }
+}
+
 // ── main ────────────────────────────────────────────────────────────────────
 
 async function readStdin(): Promise<string> {
@@ -905,12 +1019,142 @@ export async function main(): Promise<void> {
       ? routerDecision.runtime
       : runtimeDetect.detect()) ?? 'claude';
 
+  // ── Plan 27.5-02 — bandit consultation ────────────────────────────────────
+  //
+  // D-01 / D-02 / D-03 / D-07: per-spawn after `resolved_models` is computed,
+  // before the SDK call. Skip conditions (all silent — no event, no override):
+  //   - adaptive_mode !== 'full' (D-07)
+  //   - toolInput._tier_downgraded === true (80% downgrade fired upstream —
+  //     bandit must not undo budget)
+  //
+  // When bandit fires, override resolved_models[agent] through tier-resolver
+  // so downstream consumers see the bandit's pick as the actual model.
+  // model_tier_overrides[agent] is preserved (D-03 back-compat).
+  const currentMode = adaptiveMode.getMode({ quiet: true });
+  const priorTier = resolvedTier; // captured before bandit override
+  // Mutable references for the cost/telemetry path; bandit may rewrite.
+  let effectiveTier: string = resolvedTier;
+  let effectiveModelId: string | null = resolvedModelId;
+
+  if (currentMode === 'full' && toolInput._tier_downgraded !== true) {
+    // Bin defaults to 'medium' — budget-enforcer doesn't currently surface
+    // glob_count; future plan can wire it. Per-agent bandit arms still
+    // converge correctly under a fixed bin (Phase 23.5 D-08). The function
+    // call below makes the integration point explicit for future plans.
+    void banditRouterCore.binForGlobCount(0);
+    const bin = 'medium';
+
+    // Source the frontmatter view from the in-flight toolInput. The hook
+    // reads frontmatter indirectly: _default_tier carries the agent's
+    // declared default-tier, _tier_override (if any) carries an explicit
+    // override the router emitted. For bandit purposes, _tier_override
+    // means "operator has already taken control" — the shim returns
+    // source='tier_override_bypass' (no posterior side effect).
+    const agentFrontmatter: {
+      tier_override?: string;
+      default_tier?: string;
+    } = {};
+    if (
+      typeof toolInput._tier_override === 'string' &&
+      toolInput._tier_override.length > 0
+    ) {
+      agentFrontmatter.tier_override = toolInput._tier_override;
+    }
+    if (
+      typeof toolInput._default_tier === 'string' &&
+      toolInput._default_tier.length > 0
+    ) {
+      agentFrontmatter.default_tier = toolInput._default_tier;
+    }
+
+    // Delegate dimension: budget-enforcer doesn't currently see the
+    // agent's delegate_to: frontmatter (session-runner does). For 27.5-02
+    // we always consult the local-call slice (delegate='none'); 27.5-03
+    // wires delegate=<peer> for the recordOutcome side.
+    const banditDelegate = banditIntegration.DELEGATE_NONE;
+
+    let banditResult: ReturnType<
+      BanditIntegrationModule['consultBandit']
+    > | null = null;
+    try {
+      banditResult = banditIntegration.consultBandit({
+        agent,
+        bin,
+        delegate: banditDelegate,
+        agentFrontmatter,
+        adaptiveMode: currentMode,
+      });
+    } catch {
+      // Fail open — never let a bandit error block a spawn.
+    }
+
+    if (banditResult !== null) {
+      // Translate the bandit tier into a concrete model. The tier-resolver
+      // emits its own fallback events (tier_resolution_fallback /
+      // tier_resolution_failed) when the runtime row is incomplete, so we
+      // don't need to re-emit those here.
+      const banditModel = tierResolver.resolve(
+        runtimeId,
+        banditResult.tier,
+        { silent: true },
+      );
+
+      // Apply override only when:
+      //   1. bandit actually picked a different tier than priorTier
+      //      (no-op write avoided)
+      //   2. tier-resolver returned a non-null model (fall back to
+      //      existing resolvedModelId on null)
+      //   3. source is 'bandit_pull' or 'bandit_pull_with_delegate'
+      //      (frontmatter/bypass paths don't override resolved_models)
+      if (
+        banditResult.tier !== priorTier &&
+        banditModel !== null &&
+        (banditResult.decision_log.source === 'bandit_pull' ||
+          banditResult.decision_log.source === 'bandit_pull_with_delegate')
+      ) {
+        // Override resolved_models[agent] without touching
+        // model_tier_overrides[agent] (D-03 back-compat).
+        if (routerDecision !== undefined) {
+          const rm = routerDecision.resolved_models ?? {};
+          rm[agent] = banditModel;
+          routerDecision.resolved_models = rm;
+        }
+        // Also stamp _tier_override on toolInput so downstream readers
+        // see the bandit's pick.
+        toolInput._tier_override = banditResult.tier;
+        effectiveTier = banditResult.tier;
+        effectiveModelId = banditModel;
+      }
+
+      // Emit one bandit.tier_selected event regardless of override outcome
+      // (the event captures the decision, not the override side effect).
+      emitBanditTierSelected(
+        {
+          agent,
+          bin,
+          prior_tier: priorTier,
+          selected_tier: banditResult.tier,
+          source: banditResult.decision_log.source,
+          delegate: banditResult.decision_log.delegate ?? banditDelegate,
+          adaptive_mode: banditResult.decision_log.adaptive_mode,
+          samples: banditResult.decision_log.samples,
+          runtime: runtimeId,
+          model_id: effectiveModelId ?? resolvedModelId,
+          ...(banditResult.decision_log.reason !== undefined
+            ? { reason: banditResult.decision_log.reason }
+            : {}),
+        },
+        cycle,
+      );
+    }
+  }
+
   // Compute runtime-aware cost via the shared backend. Failures return
   // null cost; we emit the event regardless so the cost-aggregator sees
   // the lookup attempt (Phase 22 events.jsonl tagging).
   const costLookup = budgetBackend.computeCost({
-    model_id: resolvedModelId,
-    tier: resolvedTier,
+    model_id: effectiveModelId,
+    tier: effectiveTier,
     runtime: runtimeId,
     tokens_in: Number(toolInput._tokens_in_est ?? 0),
     tokens_out: Number(toolInput._tokens_out_est ?? 0),
@@ -920,8 +1164,8 @@ export async function main(): Promise<void> {
     {
       runtime: runtimeId,
       agent,
-      model_id: resolvedModelId ?? costLookup.model,
-      tier: costLookup.tier ?? resolvedTier,
+      model_id: effectiveModelId ?? costLookup.model,
+      tier: costLookup.tier ?? effectiveTier,
       tokens_in: Number(toolInput._tokens_in_est ?? 0),
       tokens_out: Number(toolInput._tokens_out_est ?? 0),
       cost_usd: costLookup.cost_usd,
@@ -932,7 +1176,7 @@ export async function main(): Promise<void> {
   // Branch E: standard spawn-allowed (includes tier-downgraded path).
   writeTelemetry({
     agent,
-    tier: resolvedTier,
+    tier: effectiveTier,
     tokens_in: Number(toolInput._tokens_in_est ?? 0),
     tokens_out: Number(toolInput._tokens_out_est ?? 0),
     cache_hit: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.27.0",
+  "version": "1.27.5",
   "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",
@@ -37,7 +37,7 @@
     "provenance": true
   },
   "scripts": {
-    "test": "node --test --experimental-strip-types \"tests/**/*.cjs\" \"tests/**/*.ts\"",
+    "test": "node --test --experimental-strip-types \"tests/**/*.test.cjs\" \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.planning\" \"#.claude\" \"#test-fixture/baselines\"",

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.