@hegemonart/get-design-done 1.27.0 → 1.27.5

package/scripts/lib/session-runner/index.ts

@@ -80,12 +80,130 @@ const rateGuard = _nodeRequire(
   ingestHeaders: (provider: string, headers: unknown) => Promise<unknown>;
 };
 
+// ── Plan 27.5-03 — Bandit posterior feedback loop ────────────────────────────
+//
+// `integration.cjs` is the Phase 27.5-01 production-integration shim for the
+// Phase 23.5 bandit posterior. It exposes `recordOutcome({agent, bin, delegate,
+// tier, status, costUsd, adaptiveMode, baseDir?, posteriorPath?})` which writes
+// the (status + cost) reward back to the posterior arm for the (agent × bin ×
+// tier × delegate) joint. Per CONTEXT D-04, the call fires AFTER every
+// `emit('session.completed', …)` site so the posterior reflects the measured
+// signal — correctness + cost.
+//
+// The shim is no-throw (best-effort write). The session-runner wraps each
+// `recordOutcome` call in its own try/catch as a defensive belt-and-braces
+// guard against future shim changes.
+const banditIntegration = _nodeRequire(
+  _resolve(_REPO_ROOT, 'scripts/lib/bandit-router/integration.cjs'),
+) as {
+  recordOutcome: (input: {
+    agent: string;
+    bin: string;
+    delegate?: string;
+    tier: string;
+    status: string;
+    costUsd?: number;
+    adaptiveMode?: 'static' | 'hedge' | 'full';
+    baseDir?: string;
+    posteriorPath?: string;
+  }) => void;
+  DELEGATE_NONE: string;
+};
+
+// ── Plan 27.5-03 — adaptive-mode read once per run ──────────────────────────
+//
+// `adaptive-mode.cjs.getMode({quiet: true})` reads `.design/budget.json` and
+// returns `'static' | 'hedge' | 'full'`. We cache the resolved mode locally
+// on each `run()` invocation so the recordOutcome calls at the 4 terminal
+// emit sites all see the same value (consistent gating per session).
+const adaptiveModeLib = _nodeRequire(
+  _resolve(_REPO_ROOT, 'scripts/lib/adaptive-mode.cjs'),
+) as {
+  getMode: (opts?: { baseDir?: string; budgetPath?: string; quiet?: boolean }) => 'static' | 'hedge' | 'full';
+};
+
 /** Rate-guard provider key for the Anthropic Agent SDK. */
 const RATE_GUARD_PROVIDER = 'anthropic';
 
 /** Default retries (first attempt + 1 retry). */
 const DEFAULT_MAX_RETRIES = 2;
 
+/**
+ * Default bin marker for bandit posterior writes from session-runner.
+ *
+ * Per CONTEXT D-12, session-runner uses a deterministic placeholder bin
+ * (`'medium'`) for now; real complexity-class-based bin selection is
+ * deferred to a later plan. This matches the 27.5-02 budget-enforcer
+ * convention so the (agent × bin) posterior slices stay consistent
+ * across both write paths.
+ */
+const SESSION_RUNNER_DEFAULT_BIN = 'medium';
+
+/**
+ * Infer a tier ('opus' | 'sonnet' | 'haiku') from a model identifier.
+ *
+ * Used at the 4 terminal-emit sites where the final tier isn't already
+ * carried on `opts` — we fall back to inspecting `usage.model` (folded
+ * during the run loop from SDK chunks). Unknown / empty model names
+ * default to 'sonnet' (matches the DEFAULT_MODEL_RATE choice and is
+ * the safest middle tier for posterior arms).
+ */
+function tierFromModel(modelName: string | null | undefined): 'opus' | 'sonnet' | 'haiku' {
+  if (typeof modelName !== 'string' || modelName.length === 0) return 'sonnet';
+  const lower = modelName.toLowerCase();
+  if (lower.includes('opus')) return 'opus';
+  if (lower.includes('haiku')) return 'haiku';
+  return 'sonnet';
+}
+
+/**
+ * Best-effort bandit posterior write following `emit('session.completed', …)`.
+ *
+ * Per CONTEXT D-04: posterior updates happen AT the terminal emit site so the
+ * recorded reward reflects the same (status + cost) the rest of the system
+ * just observed. The shim (`integration.cjs`) is no-throw and short-circuits
+ * silently in static/hedge mode; the outer try/catch here is a defensive
+ * belt-and-braces guard for any future shim change.
+ *
+ * Failures NEVER bubble out — the session-runner contract is that `run()`
+ * never throws, and that contract MUST hold even when telemetry is broken.
+ */
+function _recordBanditOutcome(input: {
+  agent: string;
+  bin: string;
+  delegate: string;
+  tier: string;
+  status: string;
+  costUsd: number;
+  adaptiveMode: 'static' | 'hedge' | 'full';
+}): void {
+  try {
+    banditIntegration.recordOutcome({
+      agent: input.agent,
+      bin: input.bin,
+      delegate: input.delegate,
+      tier: input.tier,
+      status: input.status,
+      costUsd: input.costUsd,
+      adaptiveMode: input.adaptiveMode,
+    });
+  } catch (err) {
+    // Defensive: shim is no-throw, but a future change could regress.
+    // Telemetry failure must never break a session — swallow.
+    if (process.env['GDD_BANDIT_DEBUG'] === '1') {
+      try {
+        process.stderr.write(
+          '[session-runner] _recordBanditOutcome swallowed: ' +
+            (err instanceof Error ? err.message : String(err)) +
+            '\n',
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+}
+
 // ── Plan 27-06 — Peer-CLI delegation primitives ─────────────────────────────
 //
 // Lazy registry loader: the registry is a .cjs module under scripts/lib/peer-cli
@@ -200,15 +318,22 @@ async function tryDelegate(args: {
     return reg !== null ? reg.dispatch : null;
   })();
   if (dispatcher === null) {
-    // No registry available at all — fall through to local. Phase 22
-    // event emission (Plan 27-08) hooks here as `peer_call_failed`
-    // with reason="registry_missing". For now, a placeholder stderr
-    // breadcrumb so operators can grep for delegation drops without
-    // CI-failing on stdout pollution.
-    _logPeerCallFailed({ peer: parsed.peer, role, errorClass: 'registry_missing' });
+    // No registry available at all — fall through to local.
+    _logPeerCallFailed({
+      peer: parsed.peer, role, errorClass: 'registry_missing',
+      sessionId: args.sessionId, stage: opts.stage,
+    });
     return null;
   }
 
+  // v1.27.1 — emit peer_call_started before dispatcher invocation so the
+  // events.jsonl trail captures the attempt even if the dispatcher hangs.
+  _logPeerCallStarted({
+    peer: parsed.peer, role,
+    sessionId: args.sessionId, stage: opts.stage,
+  });
+  const dispatchStartedAt = Date.now();
+
   let dispatchResult: { result: unknown; peer: string; protocol: 'acp' | 'asp' } | null = null;
   try {
     dispatchResult = await dispatcher(role, tier, sanitizedPrompt, { cwd: process.cwd() });
@@ -218,6 +343,8 @@ async function tryDelegate(args: {
       role,
       errorClass: 'dispatch_threw',
       message: err instanceof Error ? err.message : String(err),
+      sessionId: args.sessionId,
+      stage: opts.stage,
     });
     return null; // transparent fallback
   }
@@ -225,10 +352,28 @@ async function tryDelegate(args: {
   if (dispatchResult === null) {
     // Registry returned null — peer absent, capability mismatch, or
     // adapter-side error. Per D-07 we fall back silently.
-    _logPeerCallFailed({ peer: parsed.peer, role, errorClass: 'registry_returned_null' });
+    _logPeerCallFailed({
+      peer: parsed.peer, role, errorClass: 'registry_returned_null',
+      sessionId: args.sessionId, stage: opts.stage,
+    });
     return null;
   }
 
+  // v1.27.1 — peer round-trip succeeded. Emit peer_call_complete with the
+  // measured latency. Token counts + cost are 0 / null because adapters
+  // don't surface usage in v1.27 (Plan 27-04 spec deferred it); reflector
+  // tolerates null cost (Plan 26-06 cost-arbitrage analysis).
+  _logPeerCallComplete({
+    peer: dispatchResult.peer,
+    role,
+    latencyMs: Date.now() - dispatchStartedAt,
+    tokensIn: 0,
+    tokensOut: 0,
+    costUsd: null,
+    sessionId: args.sessionId,
+    stage: opts.stage,
+  });
+
   // Peer succeeded. Build a SessionResult that mirrors the local path's
   // shape so downstream consumers (stage-handlers, transcript readers,
   // tests) treat both paths uniformly. We do NOT write a transcript file
@@ -271,34 +416,122 @@ function _coerceFinalText(result: unknown): string | undefined {
 }
 
 /**
- * Placeholder for Plan 27-08's `peer_call_failed` event. Until 27-08
- * wires real `appendEvent('peer_call_failed', ...)`, we write a single
- * stderr line so operators can grep for silent delegation drops. We
- * deliberately don't go through `appendEvent` here because the Phase 22
- * event-stream hasn't gained a `peer_call_failed` type yet (that's
- * 27-08's job) and pushing an unknown event type today would create a
- * migration mess for the reflector.
+ * v1.27.1 — wires Plan 27-08's `peer_call_failed` event for real.
+ * Phase 22 `appendEvent` accepts the new event type (registered in
+ * KNOWN_EVENT_TYPES via Plan 27-08), so the reflector and downstream
+ * telemetry consumers see delegation drops as a measurement signal.
+ *
+ * Errors from `appendEvent` (e.g., events.jsonl unwritable) are
+ * swallowed — peer-call telemetry is observability, not critical
+ * path. STATE.md remains the durable record of session outcomes.
+ *
+ * Operators can additionally set `GDD_PEER_DEBUG=1` to emit a
+ * one-line stderr breadcrumb mirroring the event for live tailing.
  */
 function _logPeerCallFailed(args: {
   peer: string;
   role: string;
   errorClass: string;
   message?: string;
+  sessionId?: string;
+  stage?: SessionRunnerOptions['stage'];
 }): void {
-  // One-line, machine-greppable. Quiet by default in test runs (NODE_ENV)
-  // so the test output stays clean. Operators set GDD_PEER_DEBUG=1 to see
-  // the breadcrumb in production logs.
-  if (process.env['GDD_PEER_DEBUG'] !== '1') return;
-  const payload = JSON.stringify({
-    type: 'peer_call_failed',
-    peer_id: args.peer,
-    role: args.role,
-    error_class: args.errorClass,
-    ...(args.message !== undefined ? { message: args.message } : {}),
-    ts: new Date().toISOString(),
-  });
-  // eslint-disable-next-line no-console
-  console.error(`[peer-cli] ${payload}`);
+  try {
+    appendEvent({
+      type: 'peer_call_failed',
+      timestamp: new Date().toISOString(),
+      sessionId: args.sessionId ?? 'unknown',
+      ...(args.stage !== undefined && args.stage !== 'init' && args.stage !== 'custom' ? { stage: args.stage } : {}),
+      payload: {
+        runtime_role: 'peer',
+        peer_id: args.peer,
+        role: args.role,
+        error_class: args.errorClass,
+        ...(args.message !== undefined ? { message: args.message } : {}),
+      },
+    });
+  } catch {
+    // Telemetry is best-effort — never let an event-stream failure
+    // break the actual session flow.
+  }
+  if (process.env['GDD_PEER_DEBUG'] === '1') {
+    const payload = JSON.stringify({
+      type: 'peer_call_failed',
+      peer_id: args.peer,
+      role: args.role,
+      error_class: args.errorClass,
+      ...(args.message !== undefined ? { message: args.message } : {}),
+      ts: new Date().toISOString(),
+    });
+    // eslint-disable-next-line no-console
+    console.error(`[peer-cli] ${payload}`);
+  }
+}
+
+/**
+ * v1.27.1 — emit `peer_call_started` event. Fired once at the beginning
+ * of a delegation attempt, before the dispatcher is invoked. Pairs with
+ * `peer_call_complete` (success path) or `peer_call_failed` (any failure
+ * path, transparent to caller per D-07).
+ */
+function _logPeerCallStarted(args: {
+  peer: string;
+  role: string;
+  sessionId?: string;
+  stage?: SessionRunnerOptions['stage'];
+}): void {
+  try {
+    appendEvent({
+      type: 'peer_call_started',
+      timestamp: new Date().toISOString(),
+      sessionId: args.sessionId ?? 'unknown',
+      ...(args.stage !== undefined && args.stage !== 'init' && args.stage !== 'custom' ? { stage: args.stage } : {}),
+      payload: {
+        runtime_role: 'peer',
+        peer_id: args.peer,
+        role: args.role,
+      },
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * v1.27.1 — emit `peer_call_complete` event. Fired after a successful
+ * dispatcher round-trip. Cost is null when the adapter doesn't return
+ * usage data (some peers don't surface token counts); the reflector
+ * tolerates null cost for arbitrage analysis (Plan 26-06).
+ */
+function _logPeerCallComplete(args: {
+  peer: string;
+  role: string;
+  latencyMs: number;
+  tokensIn: number;
+  tokensOut: number;
+  costUsd: number | null;
+  sessionId?: string;
+  stage?: SessionRunnerOptions['stage'];
+}): void {
+  try {
+    appendEvent({
+      type: 'peer_call_complete',
+      timestamp: new Date().toISOString(),
+      sessionId: args.sessionId ?? 'unknown',
+      ...(args.stage !== undefined && args.stage !== 'init' && args.stage !== 'custom' ? { stage: args.stage } : {}),
+      payload: {
+        runtime_role: 'peer',
+        peer_id: args.peer,
+        role: args.role,
+        latency_ms: args.latencyMs,
+        tokens_in: args.tokensIn,
+        tokens_out: args.tokensOut,
+        cost_usd: args.costUsd,
+      },
+    });
+  } catch {
+    // best-effort
+  }
 }
 
 /** Baseline retry backoff parameters (matches jittered-backoff defaults for
@@ -565,6 +798,22 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
   const toolCalls: SessionResult['tool_calls'] = [];
   const usage = { input: 0, output: 0, model: null as string | null };
   let turns = 0;
+
+  // -- 3a. Resolve adaptive-mode once for the entire session (Plan 27.5-03). --
+  // Cached locally so all four `recordOutcome()` call sites below see the
+  // same gating decision (consistent posterior-write semantics across
+  // rate-limit, peer, turnCap=0, and terminal-completion paths).
+  //
+  // Wrapped in try/catch because adaptive-mode.getMode reads
+  // `.design/budget.json`; a broken fs.readFile / JSON.parse must not
+  // crash the session before it even starts. Fallback = 'static' which
+  // short-circuits the recordOutcome shim (no-op).
+  let adaptiveMode: 'static' | 'hedge' | 'full' = 'static';
+  try {
+    adaptiveMode = adaptiveModeLib.getMode({ quiet: true });
+  } catch {
+    // swallow — fallback to 'static' means no posterior writes
+  }
   let finalText: string | undefined;
 
   // -- 4. Emit session.started. -------------------------------------------
@@ -604,6 +853,20 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
       transcript_path: transcriptPath,
       sanitizer: { applied: [...result.sanitizer.applied], removedSections: [...result.sanitizer.removedSections] },
     });
+    // Plan 27.5-03 — feedback loop. Posterior records the
+    // measured outcome (status + cost) for the (agent × bin × tier × delegate)
+    // slice. The rate-limit preflight failure path has no peer dispatch and no
+    // usage data (zero cost), so delegate=DELEGATE_NONE and tier falls back to
+    // 'sonnet' via tierFromModel(null). Shim no-ops in static/hedge mode.
+    _recordBanditOutcome({
+      agent: opts.stage,
+      bin: SESSION_RUNNER_DEFAULT_BIN,
+      delegate: banditIntegration.DELEGATE_NONE,
+      tier: tierFromModel(usage.model),
+      status: result.status,
+      costUsd: result.usage.usd_cost,
+      adaptiveMode,
+    });
     transcript.close();
     return result;
   }
@@ -623,6 +886,69 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
     }
   }
 
+  // -- 6.5. Peer-CLI delegation try (Plan 27-06 wiring, v1.27.1). ---------
+  // If the agent's frontmatter declares `delegate_to: <peer>-<role>` AND the
+  // peer is allowlisted AND the registry can route, run the prompt on the
+  // peer-CLI and return early. On peer-absent / peer-error / null result,
+  // fall through transparently to the local SDK loop (D-07).
+  //
+  // tryDelegate is a no-op when opts.delegateTo is undefined / 'none', when
+  // the registry can't load, when the peer isn't allowlisted, when the
+  // dispatcher returns null, or when the dispatcher throws. In all those
+  // cases tryDelegate returns null and we proceed to the local SDK path.
+  const peerResult = await tryDelegate({
+    opts,
+    sanitizedPrompt,
+    transcriptPath,
+    sessionId,
+    sanitizer: sanResult,
+  });
+  if (peerResult !== null) {
+    emit('session.completed', opts.stage, sessionId, {
+      stage: opts.stage,
+      sessionId,
+      status: peerResult.status,
+      turns: peerResult.turns,
+      usage: peerResult.usage,
+      transcript_path: transcriptPath,
+      sanitizer: { applied: [...peerResult.sanitizer.applied], removedSections: [...peerResult.sanitizer.removedSections] },
+    });
+    // Plan 27.5-03 — feedback loop, peer path. The
+    // delegate dimension is the peer name parsed from opts.delegateTo (e.g.
+    // 'gemini-research' → 'gemini'). Per CONTEXT D-04 we use the peer name
+    // for the delegate slice of the posterior so peer-success arms get the
+    // reward signal separately from local arms. Tier is 'sonnet' by default
+    // since the peer adapter doesn't surface a model identifier in v1.27.
+    // Re-parse opts.delegateTo here — tryDelegate already validated it but
+    // didn't expose the peer name on the returned SessionResult.
+    const _peerParsed = parseDelegateTo(opts.delegateTo);
+    const _delegate = _peerParsed !== null
+      ? _peerParsed.peer
+      : banditIntegration.DELEGATE_NONE;
+    // Tier resolution priority for the peer path:
+    //   1. opts.delegateTier when it's a bare tier name (opus/sonnet/haiku)
+    //   2. tierFromModel(opts.delegateTier) when it's a model id string
+    //   3. tierFromModel(usage.model) fallback
+    // tierFromModel() is safe for any string and returns 'sonnet' on miss,
+    // so the second branch covers both bare-tier and model-id inputs.
+    const _peerTier: 'opus' | 'sonnet' | 'haiku' =
+      typeof opts.delegateTier === 'string' && opts.delegateTier.length > 0
+        ? tierFromModel(opts.delegateTier)
+        : tierFromModel(usage.model);
+    _recordBanditOutcome({
+      agent: opts.stage,
+      bin: SESSION_RUNNER_DEFAULT_BIN,
+      delegate: _delegate,
+      tier: _peerTier,
+      status: peerResult.status,
+      costUsd: peerResult.usage.usd_cost,
+      adaptiveMode,
+    });
+    transcript.close();
+    if (opts.signal !== undefined) opts.signal.removeEventListener('abort', onExternalAbort);
+    return peerResult;
+  }
+
   // -- 7. Retry-once loop. ------------------------------------------------
   const maxAttempts = opts.maxRetries !== undefined && opts.maxRetries > 0
     ? opts.maxRetries
@@ -649,6 +975,18 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
       transcript_path: transcriptPath,
       sanitizer: { applied: [...sanResult.applied], removedSections: [...sanResult.removedSections] },
     });
+    // Plan 27.5-03 — feedback loop, turnCap=0 path. No
+    // SDK call was ever made, so no peer involvement and no model id was
+    // ever observed. Reward will be 0 (status !== 'completed') with cost 0.
+    _recordBanditOutcome({
+      agent: opts.stage,
+      bin: SESSION_RUNNER_DEFAULT_BIN,
+      delegate: banditIntegration.DELEGATE_NONE,
+      tier: tierFromModel(usage.model),
+      status,
+      costUsd: result.usage.usd_cost,
+      adaptiveMode,
+    });
     transcript.close();
     if (opts.signal !== undefined) opts.signal.removeEventListener('abort', onExternalAbort);
     return result;
@@ -743,6 +1081,21 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
     transcript_path: transcriptPath,
     sanitizer: { applied: [...sanResult.applied], removedSections: [...sanResult.removedSections] },
   });
+  // Plan 27.5-03 — feedback loop, terminal main-loop path.
+  // This is the dominant write site: covers natural completion, budget cap,
+  // turn cap (after first turn), abort, and error (post-retry-exhaustion).
+  // Tier is inferred from the model actually observed during the run
+  // (usage.model). Delegate=DELEGATE_NONE because tryDelegate either returned
+  // null (we wouldn't be here otherwise) or wasn't invoked at all.
+  _recordBanditOutcome({
+    agent: opts.stage,
+    bin: SESSION_RUNNER_DEFAULT_BIN,
+    delegate: banditIntegration.DELEGATE_NONE,
+    tier: tierFromModel(usage.model),
+    status: result.status,
+    costUsd: result.usage.usd_cost,
+    adaptiveMode,
+  });
 
   return result;
 }

package/skills/bandit-status/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: gdd-bandit-status
+description: "Surface read-only per-(agent, bin, delegate) bandit posterior snapshot — alpha/beta/mean/stddev/count/last-used per arm. Phase 27.5 (v1.27.5) diagnostic. Use when investigating 'why did the bandit pick tier X for agent Y?' or when verifying posterior convergence after enabling adaptive_mode: full."
+argument-hint: ""
+tools: Read, Bash
+---
+
+# gdd-bandit-status
+
+## Role
+
+You are a deterministic, read-only diagnostic skill. You do not spawn agents and do not modify the bandit posterior. You read `.design/telemetry/posterior.json` (the path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` constant), aggregate per-`(agent, bin, delegate, tier)` arm state, and emit a single Markdown table summarizing the posterior. The user runs this when they want to inspect bandit decisions without touching the posterior.
+
+Strictly read-only per Phase 27.5 D-11. To reset the posterior, use `/gdd:bandit-reset` from Phase 23.5.
+
+## Invocation Contract
+
+- **Input**: none. The skill takes no arguments.
+- **Output**: a Markdown bandit-status table to stdout. No JSON wrapper. The table is the entire output.
+
+## Procedure
+
+### 1. Locate the posterior file
+
+Read `.design/telemetry/posterior.json`. If the file does not exist:
+
+- Emit the empty-state message:
+
+  ```
+  ## Bandit Posterior Snapshot
+
+  No posterior data yet — run a few pipeline cycles with `adaptive_mode: full` first.
+
+  No posterior data found at `.design/telemetry/posterior.json`.
+
+  Possible reasons:
+  - `adaptive_mode` is `static` or `hedge` (bandit is silent — see `.design/budget.json` `adaptive_mode` setting).
+  - No spawns have fired since Phase 27.5 wiring landed.
+  - Posterior was cleared via `/gdd:bandit-reset`.
+
+  See `reference/bandit-integration.md` for setup guidance.
+  ```
+
+- Skip to Section 4 (Record).
+
+### 2. Parse the posterior
+
+Parse the file as JSON. If parsing fails (truncated/corrupted file), emit:
+
+```
+## Bandit Posterior Snapshot
+
+Posterior file at `.design/telemetry/posterior.json` exists but is unparseable (truncated or corrupted).
+
+Run `/gdd:bandit-reset` to start fresh, or restore from a backup.
+```
+
+The posterior schema is:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "<ISO timestamp>",
+  "arms": [
+    { "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }
+  ]
+}
+```
+
+The `delegate` field is optional — when absent, the arm is the Phase 23.5 legacy slice (equivalent to `delegate: 'none'`). The status output renders `delegate: '-'` for legacy arms to distinguish them visually from explicit `'none'` arms.
+
+### 3. Render the table
+
+Compute per arm:
+
+- `mean = alpha / (alpha + beta)` (rounded to 3 decimals)
+- `stddev = sqrt(alpha * beta / ((alpha + beta)^2 * (alpha + beta + 1)))` (rounded to 3 decimals)
+
+Sort arms by `(agent ascending, bin ascending, delegate ascending where '-' sorts first, tier ascending where opus < sonnet < haiku is the canonical tier ordering, last_used descending tiebreaker)`. Group rows by agent for readability.
+
+Emit:
+
+```
+## Bandit Posterior Snapshot
+
+Per-(agent, bin, delegate, tier) posterior state. Read-only — to reset the posterior, use `/gdd:bandit-reset` (Phase 23.5).
+
+Posterior file: `.design/telemetry/posterior.json` (last updated: <generated_at>)
+Total arms: <count>
+
+| Agent           | Bin    | Delegate | Tier   | Alpha | Beta  | Mean  | Stddev | Count | Last Used            |
+|-----------------|--------|----------|--------|-------|-------|-------|--------|-------|----------------------|
+| <agent>         | <bin>  | <deleg>  | <tier> | <a>   | <b>   | <m>   | <s>    | <c>   | <last_used or '-'>   |
+
+> Mean = alpha / (alpha + beta). Stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1))).
+> Delegate '-' = Phase 23.5 legacy slice (equivalent to 'none').
+> See `reference/bandit-integration.md` for interpretation.
+> Read-only — use `/gdd:bandit-reset` to clear posterior state.
+```
+
+Format numbers to fixed precision: alpha/beta to 2 decimals, mean/stddev to 3 decimals, count as integer, last_used truncated to the minute precision (`YYYY-MM-DDTHH:MM`).
+
+When `last_used` is null (arm exists but never selected — possible if the arm was created by `ensureArm` without a subsequent `pull`), render `-` in the Last Used column.
+
+After the table, surface a brief best-arm summary per `(agent, bin)` slice — for each unique `(agent, bin)` pair, identify the arm with the highest `mean` (tie-broken by `count` descending) and display it as the "best-arm" recommendation. This helps the operator answer "why did the bandit pick tier X?" at a glance.
+
+### 4. Record
+
+After execution, append one JSONL line to `.design/skill-records.jsonl`:
+
+```json
+{"skill": "gdd-bandit-status", "ts": "<ISO timestamp>", "arms_seen": <count>, "posterior_present": <bool>}
+```
+
+The skill writes ONLY to `.design/skill-records.jsonl` for telemetry purposes. It never touches `.design/telemetry/posterior.json`.
+
+## Cross-references
+
+- `scripts/lib/bandit-router.cjs` (Phase 23.5) — posterior shape, `DEFAULT_POSTERIOR_PATH` constant, `loadPosterior()` helper.
+- `scripts/lib/bandit-router/integration.cjs` (Phase 27.5-01) — production-integration shim.
+- `hooks/budget-enforcer.ts` (Phase 27.5-02) — bandit consultation site.
+- `scripts/lib/session-runner/index.ts` (Phase 27.5-03) — outcome recording site.
+- `scripts/lib/bandit-arbitrage.cjs` (Phase 27.5-04) — automated stale-frontmatter analysis.
+- `reference/bandit-integration.md` (Phase 27.5-06) — operator guide.
+- `/gdd:bandit-reset` (Phase 23.5) — the ONLY surface that mutates the posterior.
+
+## Record
+
+See Section 4 above.