@hegemonart/get-design-done 1.27.1 → 1.27.5

package/scripts/lib/bandit-router/integration.cjs

@@ -0,0 +1,309 @@
+/**
+ * scripts/lib/bandit-router/integration.cjs — Plan 27.5-01
+ *
+ * Production-integration shim for the Phase 23.5 bandit posterior +
+ * Phase 27-07 delegate dimension. Hides the `pull` vs `pullWithDelegate`
+ * + `update` vs `updateWithDelegate` choice from callers.
+ *
+ * Two functions:
+ *   consultBandit({agent, bin, delegate, agentFrontmatter, adaptiveMode, baseDir?, posteriorPath?})
+ *     → {tier, decision_log}
+ *   recordOutcome({agent, bin, delegate, tier, status, costUsd, adaptiveMode, baseDir?, posteriorPath?})
+ *     → void (best-effort write per D-04)
+ *
+ * Routing rules (D-05 + D-07):
+ *   1. agentFrontmatter.tier_override is set         → bypass bandit, return tier_override
+ *   2. adaptiveMode !== 'full'                       → bandit silent, return frontmatter.default_tier
+ *      (covers 'static' and 'hedge' per D-07)
+ *   3. adaptiveMode === 'full' && delegate is 'none' / undefined
+ *                                                    → call pull()
+ *   4. adaptiveMode === 'full' && delegate is a peer name
+ *                                                    → call pullWithDelegate({delegates:[delegate]})
+ *
+ * recordOutcome is symmetric on the adaptive_mode gate:
+ *   - non-'full'                                     → no-op
+ *   - 'full' && delegate 'none'/undefined            → update()
+ *   - 'full' && delegate is a peer                   → updateWithDelegate()
+ *
+ * Reward function = Phase 23.5's computeReward unchanged (D-08).
+ *
+ * Posterior writes are best-effort — all throws are swallowed. The
+ * shim's job is to plumb the call; telemetry resilience is downstream.
+ */
+
+'use strict';
+
+const banditRouter = require('../bandit-router.cjs');
+const adaptiveModeLib = require('../adaptive-mode.cjs');
+
+const DELEGATE_NONE = banditRouter.DELEGATE_NONE; // 'none'
+const VALID_DELEGATES = banditRouter.DEFAULT_DELEGATES; // ['none','gemini','codex','cursor','copilot','qwen']
+
+/**
+ * Validate that `delegate` is either undefined, DELEGATE_NONE, or a
+ * member of VALID_DELEGATES. Returns the canonical delegate string
+ * (undefined → 'none').
+ *
+ * @param {string|undefined} delegate
+ * @param {string} fnName — for error message context
+ * @returns {string}
+ */
+function resolveDelegate(delegate, fnName) {
+  if (delegate === undefined || delegate === null) return DELEGATE_NONE;
+  if (typeof delegate !== 'string') {
+    throw new TypeError(
+      `integration.${fnName}: delegate must be a string when provided, got ${typeof delegate}`,
+    );
+  }
+  if (!VALID_DELEGATES.includes(delegate)) {
+    throw new RangeError(
+      `integration.${fnName}: unknown delegate '${delegate}'; expected one of ${VALID_DELEGATES.join(',')}`,
+    );
+  }
+  return delegate;
+}
+
+/**
+ * Resolve the adaptive_mode for a call. If the caller passed it
+ * explicitly we use that; otherwise we read it from disk via
+ * adaptive-mode.getMode (D-07: single gating surface).
+ *
+ * @param {string|undefined} adaptiveMode
+ * @param {{baseDir?: string}} opts
+ * @returns {'static'|'hedge'|'full'}
+ */
+function resolveAdaptiveMode(adaptiveMode, opts) {
+  if (typeof adaptiveMode === 'string' && adaptiveMode.length > 0) {
+    return /** @type {'static'|'hedge'|'full'} */ (adaptiveMode);
+  }
+  return adaptiveModeLib.getMode({ baseDir: opts && opts.baseDir, quiet: true });
+}
+
+/**
+ * consultBandit — single canonical lookup that returns a tier + a
+ * decision_log explaining how the tier was chosen. Five paths:
+ *
+ *   Path 1 — static mode → frontmatter.default_tier (or 'sonnet' fallback)
+ *   Path 2 — tier_override set on frontmatter → bypass bandit
+ *   Path 3 — full mode + delegate='none' (or undefined) → pull()
+ *   Path 4 — full mode + delegate=<peer> → pullWithDelegate()
+ *   Path 5 — hedge mode → frontmatter.default_tier (bandit silent)
+ *
+ * Path 2 takes precedence over Path 1 / 3 / 4 / 5 (tier_override is the
+ * explicit operator override per D-05).
+ *
+ * @param {{
+ *   agent: string,
+ *   bin: string,
+ *   delegate?: string,
+ *   agentFrontmatter?: {tier_override?: string, default_tier?: string},
+ *   adaptiveMode?: 'static'|'hedge'|'full',
+ *   baseDir?: string,
+ *   posteriorPath?: string,
+ * }} input
+ * @returns {{
+ *   tier: string,
+ *   decision_log: {
+ *     source: 'frontmatter'|'tier_override_bypass'|'bandit_pull'|'bandit_pull_with_delegate',
+ *     samples?: object,
+ *     delegate?: string,
+ *     adaptive_mode: 'static'|'hedge'|'full',
+ *     reason?: string,
+ *   }
+ * }}
+ */
+function consultBandit(input) {
+  if (!input || typeof input !== 'object') {
+    throw new TypeError('integration.consultBandit: input object required');
+  }
+  if (typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('integration.consultBandit: agent (string) required');
+  }
+  if (typeof input.bin !== 'string' || input.bin.length === 0) {
+    throw new TypeError('integration.consultBandit: bin (string) required');
+  }
+
+  const agentFrontmatter = input.agentFrontmatter && typeof input.agentFrontmatter === 'object'
+    ? input.agentFrontmatter
+    : {};
+  const adaptiveMode = resolveAdaptiveMode(input.adaptiveMode, input);
+  const delegate = resolveDelegate(input.delegate, 'consultBandit');
+
+  // Step 1 — tier_override bypass (D-05). Highest priority; beats both
+  // bandit consultation and static/hedge frontmatter.default_tier.
+  if (typeof agentFrontmatter.tier_override === 'string' && agentFrontmatter.tier_override.length > 0) {
+    return {
+      tier: agentFrontmatter.tier_override,
+      decision_log: {
+        source: 'tier_override_bypass',
+        adaptive_mode: adaptiveMode,
+        reason: 'frontmatter_tier_override_set',
+      },
+    };
+  }
+
+  // Step 2 — non-full short-circuit (D-07). Static and hedge are both
+  // "bandit silent"; frontmatter.default_tier (or 'sonnet' fallback)
+  // is authoritative. No posterior read or write.
+  if (adaptiveMode !== 'full') {
+    const fallbackTier = (typeof agentFrontmatter.default_tier === 'string' && agentFrontmatter.default_tier.length > 0)
+      ? agentFrontmatter.default_tier
+      : 'sonnet';
+    return {
+      tier: fallbackTier,
+      decision_log: {
+        source: 'frontmatter',
+        adaptive_mode: adaptiveMode,
+        reason: adaptiveMode === 'hedge' ? 'hedge_mode_skips_bandit' : 'static_mode_authoritative',
+      },
+    };
+  }
+
+  // Step 3/4 — full mode → consult the bandit. Choice of pull vs
+  // pullWithDelegate is driven by `delegate`:
+  //   delegate === 'none' (or undefined → 'none')  → pull()
+  //   delegate ∈ {gemini,codex,cursor,copilot,qwen} → pullWithDelegate
+  if (delegate === DELEGATE_NONE) {
+    const result = banditRouter.pull({
+      agent: input.agent,
+      bin: input.bin,
+      baseDir: input.baseDir,
+      posteriorPath: input.posteriorPath,
+    });
+    return {
+      tier: result.tier,
+      decision_log: {
+        source: 'bandit_pull',
+        samples: result.samples,
+        delegate: DELEGATE_NONE,
+        adaptive_mode: 'full',
+      },
+    };
+  }
+
+  // Path 4 — peer delegate. Constrain the delegate axis to the single
+  // requested peer so the bandit samples the (tier × delegate) joint
+  // restricted to {delegate}. Same posterior file, same arm shape; the
+  // arm's `delegate` field is set so the slice is distinct from local.
+  const result = banditRouter.pullWithDelegate({
+    agent: input.agent,
+    bin: input.bin,
+    delegates: [delegate],
+    baseDir: input.baseDir,
+    posteriorPath: input.posteriorPath,
+  });
+  return {
+    tier: result.tier,
+    decision_log: {
+      source: 'bandit_pull_with_delegate',
+      samples: result.samples,
+      delegate: result.delegate,
+      adaptive_mode: 'full',
+    },
+  };
+}
+
+/**
+ * recordOutcome — post-spawn telemetry update. Computes a reward via
+ * computeReward (Phase 23.5 D-08, unchanged) and writes the posterior
+ * arm. Best-effort: all errors swallowed so telemetry can never break
+ * a session (D-04).
+ *
+ * No-op when adaptive_mode is not 'full' (D-07).
+ *
+ * @param {{
+ *   agent: string,
+ *   bin: string,
+ *   delegate?: string,
+ *   tier: string,
+ *   status: string,
+ *   costUsd?: number,
+ *   adaptiveMode?: 'static'|'hedge'|'full',
+ *   baseDir?: string,
+ *   posteriorPath?: string,
+ * }} input
+ * @returns {void}
+ */
+function recordOutcome(input) {
+  if (!input || typeof input !== 'object') {
+    throw new TypeError('integration.recordOutcome: input object required');
+  }
+  if (typeof input.agent !== 'string' || input.agent.length === 0) {
+    throw new TypeError('integration.recordOutcome: agent (string) required');
+  }
+  if (typeof input.bin !== 'string' || input.bin.length === 0) {
+    throw new TypeError('integration.recordOutcome: bin (string) required');
+  }
+  if (typeof input.tier !== 'string' || input.tier.length === 0) {
+    throw new TypeError('integration.recordOutcome: tier (string) required');
+  }
+  if (typeof input.status !== 'string') {
+    throw new TypeError('integration.recordOutcome: status (string) required');
+  }
+
+  const adaptiveMode = resolveAdaptiveMode(input.adaptiveMode, input);
+
+  // D-07 + D-04: posterior is silent in static/hedge. No-op early.
+  if (adaptiveMode !== 'full') {
+    return undefined;
+  }
+
+  const delegate = resolveDelegate(input.delegate, 'recordOutcome');
+
+  // D-08: reward function unchanged. wall_time_ms always 0 per
+  // Phase 23.5 / 27.5 — the wall-time tiebreaker is not used at the
+  // recordOutcome boundary; correctness + cost are the only signals.
+  const reward = banditRouter.computeReward({
+    solidify_pass: input.status === 'completed',
+    cost_usd: typeof input.costUsd === 'number' ? input.costUsd : 0,
+    wall_time_ms: 0,
+  });
+
+  // D-04: best-effort write. Swallow ALL exceptions so a broken
+  // posterior file never breaks a session.
+  try {
+    if (delegate === DELEGATE_NONE) {
+      banditRouter.update({
+        agent: input.agent,
+        bin: input.bin,
+        tier: input.tier,
+        reward,
+        baseDir: input.baseDir,
+        posteriorPath: input.posteriorPath,
+      });
+    } else {
+      banditRouter.updateWithDelegate({
+        agent: input.agent,
+        bin: input.bin,
+        tier: input.tier,
+        delegate,
+        reward,
+        baseDir: input.baseDir,
+        posteriorPath: input.posteriorPath,
+      });
+    }
+  } catch (err) {
+    // Live-tail breadcrumb opt-in via env var. Inner try/catch around
+    // the stderr write itself keeps the swallow guarantee even when
+    // stderr is closed/unavailable.
+    if (process.env.GDD_BANDIT_DEBUG === '1') {
+      try {
+        process.stderr.write(
+          '[bandit-integration] recordOutcome swallowed: ' +
+            (err && err.message ? err.message : String(err)) +
+            '\n',
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+
+  return undefined;
+}
+
+module.exports = {
+  consultBandit,
+  recordOutcome,
+  DELEGATE_NONE,
+};

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
@@ -680,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. -------------------------------------------
@@ -719,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;
   }
@@ -765,6 +913,37 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
       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;
@@ -796,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;
@@ -890,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.