@hegemonart/get-design-done 1.27.1 → 1.27.6

package/scripts/lib/perf-analyzer/index.cjs

@@ -0,0 +1,139 @@
+/**
+ * scripts/lib/perf-analyzer/index.cjs — Plan 27.6-01
+ *
+ * Telemetry reader for the Phase 27.6 perf-analyzer reflector agent.
+ * Reads `.design/telemetry/costs.jsonl` (cost rows, Phase 10.1) and
+ * `.design/telemetry/trajectories/<cycle>.jsonl` files (agent trace
+ * lines per Phase 22).
+ *
+ * JSONL discipline (same as scripts/lib/event-stream/reader.ts):
+ *   - One JSON object per line.
+ *   - Blank lines / whitespace-only lines ignored silently.
+ *   - Malformed lines tolerated — counted in skipped_count, NOT thrown.
+ *
+ * No external deps. Stateless. Safe to require from CommonJS callers
+ * (agents, hooks, CI gates) without dragging the gdd-state MCP graph.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_COSTS_PATH = '.design/telemetry/costs.jsonl';
+const DEFAULT_TRAJECTORIES_DIR = '.design/telemetry/trajectories';
+
+/**
+ * Resolve a path against an optional baseDir. Absolute paths win.
+ * @param {string} p
+ * @param {string|undefined} baseDir
+ * @returns {string}
+ */
+function resolvePath(p, baseDir) {
+  if (path.isAbsolute(p)) return p;
+  if (baseDir) return path.join(baseDir, p);
+  return p;
+}
+
+/**
+ * Parse a JSONL file tolerantly: blank lines silently skipped,
+ * malformed lines counted in skipped_count without throwing.
+ *
+ * @param {string} contents - raw file contents (utf-8)
+ * @returns {{ rows: object[], skipped: number }}
+ */
+function parseJsonl(contents) {
+  const rows = [];
+  let skipped = 0;
+  const lines = contents.split(/\r?\n/);
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    try {
+      const obj = JSON.parse(line);
+      rows.push(obj);
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { rows, skipped };
+}
+
+/**
+ * Read `.design/telemetry/costs.jsonl` (or override) into row objects.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]       Override (default: DEFAULT_COSTS_PATH)
+ * @param {string} [opts.sinceCycle] Drop rows with row.cycle < this string (lex)
+ * @param {string} [opts.baseDir]    Resolve relative paths against this dir
+ * @returns {{ rows: object[], parsed_count: number, skipped_count: number }}
+ */
+function loadCosts(opts) {
+  const o = opts || {};
+  const rawPath = o.path !== undefined ? o.path : DEFAULT_COSTS_PATH;
+  const targetPath = resolvePath(rawPath, o.baseDir);
+
+  if (!fs.existsSync(targetPath)) {
+    return { rows: [], parsed_count: 0, skipped_count: 0 };
+  }
+
+  const contents = fs.readFileSync(targetPath, 'utf8');
+  const { rows: parsed, skipped: skipped_count } = parseJsonl(contents);
+
+  let rows = parsed;
+  if (o.sinceCycle !== undefined) {
+    const since = o.sinceCycle;
+    rows = parsed.filter(
+      (row) => row && typeof row.cycle === 'string' && row.cycle >= since,
+    );
+  }
+
+  return { rows, parsed_count: rows.length, skipped_count };
+}
+
+/**
+ * Read `.design/telemetry/trajectories/<cycle>.jsonl` files (or override
+ * directory) into a per-cycle map keyed by basename-without-extension.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir]     Override (default: DEFAULT_TRAJECTORIES_DIR)
+ * @param {string} [opts.baseDir] Resolve relative paths against this dir
+ * @returns {{ byCycle: Record<string, object[]>, files_read: number }}
+ */
+function loadTrajectories(opts) {
+  const o = opts || {};
+  const rawDir = o.dir !== undefined ? o.dir : DEFAULT_TRAJECTORIES_DIR;
+  const targetDir = resolvePath(rawDir, o.baseDir);
+
+  if (!fs.existsSync(targetDir)) {
+    return { byCycle: {}, files_read: 0 };
+  }
+
+  /** @type {Record<string, object[]>} */
+  const byCycle = {};
+  let files_read = 0;
+
+  const entries = fs.readdirSync(targetDir);
+  for (const entry of entries) {
+    if (!entry.endsWith('.jsonl')) continue;
+    const filePath = path.join(targetDir, entry);
+    let contents;
+    try {
+      contents = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      // Permission / IO error on one file should not abort the whole read.
+      continue;
+    }
+    const cycleSlug = path.basename(entry, '.jsonl');
+    const { rows } = parseJsonl(contents);
+    byCycle[cycleSlug] = rows;
+    files_read += 1;
+  }
+
+  return { byCycle, files_read };
+}
+
+module.exports = {
+  loadCosts,
+  loadTrajectories,
+  DEFAULT_COSTS_PATH,
+  DEFAULT_TRAJECTORIES_DIR,
+};

package/scripts/lib/prompt-dedup/index.cjs

@@ -0,0 +1,161 @@
+/**
+ * scripts/lib/prompt-dedup/index.cjs — Plan 27.6-06
+ *
+ * Phase 27.6 D-11 prompt-deduplication analyzer. Detects cases where
+ * >= 3 distinct agents in the same cycle read the same reference/*.md
+ * file. Produces a preamble injection that gets prepended to the
+ * Phase 14.5 retrieval-contract preamble during cycle execution.
+ *
+ * v1.27.6 ships the analyzer + injection text builder. The event-
+ * emission side-effect is wired here for downstream consumers. The
+ * actual `reference.read` event emission from agent-read paths is
+ * deferred to a follow-up phase (this library is ready to consume
+ * those events when they exist).
+ *
+ * No external deps. Pure analyzer + lazy event-stream require.
+ */
+'use strict';
+
+const DEFAULT_THRESHOLD = 3;  // D-11 — '>= 3 agents'
+
+/**
+ * Lazy require for the event-stream appendEvent helper. Returns a
+ * no-op if event-stream is unavailable so emitDedupInjection can be
+ * called in tests / Codex no-PreCompact paths without throwing.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch { /* swallow — event-stream not on path */ }
+  return function noopAppend(_ev) {};
+}
+
+/**
+ * Detect reference/*.md files that have been read by >= threshold
+ * distinct agents in the same cycle. The detection is pure — it
+ * consumes an in-memory events array and returns a structured result.
+ *
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.events]   Event-stream entries (any shape)
+ * @param {number} [opts.threshold]       Override DEFAULT_THRESHOLD (3)
+ * @param {string} [opts.cycle]           Filter — only consider events
+ *                                        whose event.cycle === this value
+ * @returns {{duplicates: Array<{ref_path: string, agents: string[], hash?: string, cycle?: string}>}}
+ */
+function detectDuplicateReferenceReads({ events, threshold, cycle } = {}) {
+  const list = Array.isArray(events) ? events : [];
+  const N = typeof threshold === 'number' && threshold >= 1
+    ? Math.floor(threshold)
+    : DEFAULT_THRESHOLD;
+  const cycleFilter = typeof cycle === 'string' && cycle.length > 0 ? cycle : null;
+
+  // Group by (cycle, ref_path) → Set<agent>
+  const groups = new Map();
+  for (const ev of list) {
+    if (!ev || ev.type !== 'reference.read') continue;
+    if (!ev.payload || typeof ev.payload.ref_path !== 'string' || typeof ev.payload.agent !== 'string') continue;
+    const evCycle = typeof ev.cycle === 'string'
+      ? ev.cycle
+      : (typeof ev.payload.cycle === 'string' ? ev.payload.cycle : '');
+    if (cycleFilter !== null && evCycle !== cycleFilter) continue;
+    const key = evCycle + ' ' + ev.payload.ref_path;
+    let group = groups.get(key);
+    if (!group) {
+      group = { cycle: evCycle, ref_path: ev.payload.ref_path, agents: new Set(), hash: undefined };
+      groups.set(key, group);
+    }
+    group.agents.add(ev.payload.agent);
+    if (typeof ev.payload.content_hash === 'string' && !group.hash) {
+      group.hash = ev.payload.content_hash;
+    }
+  }
+
+  const duplicates = [];
+  for (const group of groups.values()) {
+    if (group.agents.size >= N) {
+      duplicates.push({
+        ref_path: group.ref_path,
+        agents: [...group.agents].sort(),
+        hash: group.hash,
+        cycle: group.cycle || undefined,
+      });
+    }
+  }
+  duplicates.sort((a, b) => a.ref_path.localeCompare(b.ref_path));
+  return { duplicates };
+}
+
+/**
+ * Build the markdown preamble injection text that gets prepended to
+ * the Phase 14.5 retrieval-contract preamble during cycle execution.
+ * Returns an empty string when duplicates is empty (no injection).
+ *
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.duplicates]  From detectDuplicateReferenceReads
+ * @param {string}        [opts.sessionId]   Optional breadcrumb
+ * @returns {string}
+ */
+function buildPreambleInjection({ duplicates, sessionId } = {}) {
+  const list = Array.isArray(duplicates) ? duplicates : [];
+  if (list.length === 0) return '';
+  const lines = [
+    '## Shared Context (Phase 27.6 dedup)',
+    '',
+    'The following reference files have been read by >= 3 agents in this cycle and are now loaded ONCE as shared context. Subsequent agents see a content-hash reference instead of the full file body:',
+    '',
+  ];
+  for (const d of list) {
+    const hashSuffix = d.hash ? ` [hash: ${d.hash}]` : '';
+    lines.push(`- \`${d.ref_path}\` (read by: ${d.agents.join(', ')})${hashSuffix}`);
+  }
+  lines.push('');
+  lines.push('To opt out of dedup for a specific read, set `GDD_DEDUP_OPT_OUT=1` in the agent\'s environment.');
+  lines.push('');
+  // sessionId is consumed as a breadcrumb hint; not embedded in the
+  // preamble text by default to keep the markdown minimal.
+  if (typeof sessionId === 'string' && sessionId.length > 0) {
+    lines.push(`<!-- dedup-session: ${sessionId} -->`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Emit one `dedup.injection` event per duplicate via the event-stream
+ * appendEvent helper. Lazy-required; safe when event-stream is
+ * unavailable (no-op fallback). Returns void.
+ *
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.duplicates]
+ * @param {string}        [opts.sessionId]
+ * @returns {void}
+ */
+function emitDedupInjection({ duplicates, sessionId } = {}) {
+  const list = Array.isArray(duplicates) ? duplicates : [];
+  if (list.length === 0) return;
+  const append = getAppendEvent();
+  for (const d of list) {
+    append({
+      type: 'dedup.injection',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'prompt-dedup',
+      payload: {
+        ref_path: d.ref_path,
+        agents: d.agents,
+        agent_count: d.agents.length,
+        content_hash: d.hash,
+        cycle: d.cycle,
+      },
+    });
+  }
+}
+
+module.exports = {
+  detectDuplicateReferenceReads,
+  buildPreambleInjection,
+  emitDedupInjection,
+  DEFAULT_THRESHOLD,
+};

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.