@hegemonart/get-design-done 1.22.0 → 1.23.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.22.0"
+    "version": "1.23.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.22.0",
+      "version": "1.23.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.22.0",
+  "version": "1.23.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,118 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.23.5] — 2026-04-25
+
+Phase 23.5 No-Regret Adaptive Layer milestone — turns the passive Phase 22–23 observability + validation infrastructure into a closed self-tuning loop. Three tightly-scoped no-regret algorithms sharing one feature-flag ladder. Single-user viable via informed Beta-prior bootstrap (no shared telemetry required). Ships as a decimal patch on the v1.23 minor — does NOT shift Phase 24 → v1.24.0.
+
+### Added
+
+- **Bandit router** — `scripts/lib/bandit-router.cjs` implements contextual Thompson sampling over `(agent_type, touches_size_bin) → {haiku, sonnet, opus}`. Per-arm `Beta(α, β)` posterior at `.design/telemetry/posterior.json` (atomic .tmp + rename). Discounted Thompson via per-arm time-decay factor `ρ^days_since_last_use` applied at sample time (default ρ=0.988 → 60-day half-life). Informed bootstrap: each arm starts at `Beta(α, β)` with α weighted toward the historical tier success rate (haiku=0.6, sonnet=0.8, opus=0.85) and `α + β ≈ 10` so 5–10 local samples shift the posterior. Two-stage lexicographic reward: `if !solidify_pass: 0; elif user_undo_in_session: 0; else: 1 − λ · normalize(cost + ε · wall_time)`. API: `pull / update / reset / loadPosterior / savePosterior / computeReward`. Touches-size bins: `tiny <5`, `small 5–15`, `medium 16–50`, `large >50` globs. (Plan 23.5-01)
+
+- **Hedge ensemble** — `scripts/lib/hedge-ensemble.cjs` implements parameter-free AdaNormalHedge weighted-majority over verifier + checker agents. Weights persist at `.design/telemetry/hedge-weights.json`. Update rule: `η_i = sqrt(ln(N) / max(1, cumLoss2_i))` per-agent learning rate; `w_i *= exp(-η_i * loss_i)`; renormalise. Vote semantics: weighted sum normalised by the SUM of voting agents' weights — agents in the pool that didn't vote this round don't dilute the verdict. API: `loss / vote / weights / loadWeights / saveWeights`. Default vote threshold 0.5. (Plan 23.5-02)
+
+- **MMR re-rank** — `scripts/lib/mmr-rerank.cjs` implements Maximal Marginal Relevance over scored items. Solves the "all 5 surfaced learnings are about the same thing" failure mode in the Phase 14.5 decision-injector. Greedy criterion: `next = argmax_{i ∉ selected} λ * relevance(i) − (1 − λ) * max_sim(i, selected)`. Similarity = Jaccard on word n-grams (default n=2). λ default 0.7. No external deps, no embedding API. API: `rerank / similarity / tokenize / ngrams / jaccard`. (Plan 23.5-03)
+
+- **Adaptive-mode feature flag ladder** — `scripts/lib/adaptive-mode.cjs` is the single source of truth for which Phase 23.5 components are active. Three modes:
+  - `static` (DEFAULT) — Phase 10.1 behaviour. Static `tier_overrides` applies. No posterior writes / no hedge updates / no MMR.
+  - `hedge` — Adds AdaNormalHedge consensus + MMR re-rank. Routing still static (bandit OFF). Safest intro level.
+  - `full` — Adds bandit Thompson-sampling routing + reflector confidence-interval proposals. Both posterior + hedge persist.
+  Read from `.design/budget.json.adaptive_mode` with safe fallback to `static` on missing/malformed/unknown values. API: `getMode / setMode / caps / isBanditEnabled / isHedgeEnabled / isMmrEnabled / isReflectorProposalsEnabled`. (Plan 23.5-04)
+
+### Changed
+
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.23.5`.
+- `test-fixture/baselines/phase-20/resilience-primitives.txt` regenerated alphabetically with all four new `.cjs` modules added.
+
+### Tests
+
+- `tests/bandit-router.test.cjs` — bin partitioning, prior elevation per tier, beta sampling, pull persistence, missing-input throws, update/reward/clamp, reset, decay-toward-prior, all reward branches, load+save, 60-round convergence smoke test (18 tests)
+- `tests/hedge-ensemble.test.cjs` — init uniform, high-loss penalty, normalisation, simple vs weighted vote, boolean=numeric equivalence, custom threshold, empty votes, loss clamp, NaN throw, round-trip (14)
+- `tests/mmr-rerank.test.cjs` — tokenize edges, ngram size+fallback, similarity properties, λ=1 pure relevance, λ=0 pure diversity, textOf/relevanceOf overrides, empty input, non-array throw, k>length truncation, defaults, jaccard guards, canonical "5 D-13 hits" scenario (18)
+- `tests/adaptive-mode.test.cjs` — missing-file fallback, malformed-JSON fallback, unknown-mode quiet fallback, all 3 capability matrices, all 4 predicates, setMode preserves other fields, parent-dir creation, mode rejection, exports, absolute-path support (13)
+- `tests/phase-23.5-baseline.test.cjs` — Phase 23.5 regression baseline (8)
+
+Total: 71 new tests. All Phase 20/21/22/23 tests still green.
+
+### Reflector integration
+
+The Phase 22 code-level reflector reads `posterior.json` + hedge weights at run time (under `adaptive_mode: "full"`). When `stddev(Beta(α, β)) < 0.05` for a single-arm dominant tier, it proposes `tier_overrides` updates via `/gdd:apply-reflections`. Pure-read; never auto-writes. Same proposal pattern as Plan 23-06 touches pattern miner.
+
+### Deferred (evidence-gated, per ROADMAP)
+
+- Hierarchical shared prior (revisit after 20+ cycles of single-user convergence data)
+- Dense-embedding retrieval (revisit if MMR-only miss-rate exceeds 15%)
+- Offline policy evaluation harness (bootstraps from bandit's stochastic logs once accumulated)
+- Auto changepoint detection (manual `/gdd:bandit-reset --reason "<msg>"` covers v1)
+
+### Explicitly out of scope
+
+- HDBSCAN auto-crystallization, BOCPD changepoint detection, Personalized PageRank, MinHash/LSH dedup, Borda/Kemeny rank aggregation, submodular greedy — each rejected with rationale in ROADMAP.md.
+
+---
+
+## [1.23.0] — 2026-04-25
+
+Phase 23 GDD SDK Domain Primitives milestone — lands the highest-leverage code primitives from the ROADMAP "GDD SDK Domain Primitives" entry as typed Node modules with tests. 10 atomic plans (23-01 through 23-10), additive — every Phase 20/21/22 consumer keeps working unchanged. Distribution as separate `@hegemonart/gdd-sdk` npm package and screenshot-capture orchestration are explicitly deferred to follow-up phases.
+
+### Added
+
+- **JSON output contracts** — `reference/output-contracts/planner-decision.schema.json` + `verifier-decision.schema.json` (Draft-07). `scripts/lib/parse-contract.cjs` gains `parsePlannerDecision()` and `parseVerifierDecision()` riding the same extract→parse→validate pipeline as the existing `parseMotionMap`. Lets `/gdd:synthesize` consume planner output without regex-parsing markdown headings, and lets executor↔verifier ping-pong on a typed envelope. (Plan 23-01)
+
+- **Solidify-with-rollback gate** — `scripts/lib/design-solidify.mjs` runs the typecheck/build/targeted-test triplet for a task and, on any failure, rolls the working tree back via `git stash` (configurable: `stash` | `hard` | `none`) and emits a `solidify.rollback` event onto the Phase 22 causal chain. Optional `emit()` callback for event-stream telemetry sink. Authored as `.mjs` to sidestep the Phase 22 Node 24 + Windows + .mjs↔.ts loader bug. (Plan 23-02)
+
+- **Touches: analyzer + parallelism decision engine** — `scripts/lib/touches-analyzer/index.cjs` parses `Touches:` lines from task markdown into glob lists and produces a pairwise verdict (`parallel` | `sequential`) for any two tasks. Encodes today's prompt-only heuristic into auditable code. Verdict rules (first match wins): empty → unknown-touches; literal equality → shared-glob; shared component dir → shared-component-dir; resolved-file overlap → shared-file; otherwise → disjoint. (Plan 23-03)
+
+- **Audit aggregator** — `scripts/lib/audit-aggregator/index.cjs` takes `Array<Finding>` from N audit-agents, dedups by `{file, line, rule_id}`, scores via severity-weighted formula (P0:8/P1:4/P2:2/P3:1), and returns sorted top-N + tally summary. Default merge picks higher-confidence → higher-severity → lex-earliest agent → first-seen. Confidence outside `[0, 1]` clamped with one `process.emitWarning` per call. Cross-platform path normalization. (Plan 23-04)
+
+- **Reference resolver** — `scripts/lib/reference-resolver.cjs` adds the resolution direction on top of the Phase 14.5 reference-registry. `resolve('forms')` / `resolve('type:forms')` → `{name, path, type, excerpt}` with a 200-char excerpt suitable for inlining into agent prompts. Lookup order: exact name → slug match → singularize fuzzy → type-only-when-unique. Ambiguous match throws `RangeError` with candidates. `resolveAll(keys, {ignoreMissing})` for bulk. `excerptOf(path, {maxChars})` strips frontmatter / fenced code / HTML comments / markdown headers. (Plan 23-05)
+
+- **Touches pattern miner** — `scripts/lib/touches-pattern-miner.cjs` scans `.design/archive/cycle-*/tasks/*.md` after `/gdd:complete-cycle`, canonicalizes signatures (lowercase + backslash-normalize + cycle-slug strip + dedup + sort), and proposes crystallization candidates when a signature recurs in ≥3 tasks across ≥2 cycles. Writes `.design/learnings/touches-patterns.json` atomically (`.tmp` + rename). **NEVER auto-applies** — `/gdd:apply-reflections` is the materialization gate. (Plan 23-06)
+
+- **Image diff + visual baseline manager** — `scripts/lib/visual-baseline/diff.cjs` compares two PNG buffers. With `pngjs` installed (probeOptional), decodes both and counts pixels whose R/G/B/A channels differ beyond the tolerance (default 4). Without `pngjs`, falls back to bytewise SHA-256 equality. `scripts/lib/visual-baseline/index.cjs` exposes `compareToBaseline(key, pngBuffer)` and `applyBaseline(key, pngBuffer)`; reads/writes `.design/baselines/<key>.png`; rejects path-traversal keys. `pngjs@7` declared as optional dep. Defers Playwright/Preview MCP screenshot capture orchestration to a later phase. (Plan 23-07)
+
+- **Design-token reader (multi-source)** — `scripts/lib/design-tokens/index.cjs` facades over four pure-JS readers producing the uniform `{tokens, source, format, warnings}` shape:
+  - `css-vars.cjs` — extracts `--token: value;` from CSS/SCSS, last-write-wins, strips block comments, warns on `$scss-vars`
+  - `js-const.cjs` — spawn-node harness evaluates CJS/ESM exports, recognises `{tokens: …}` / default / direct bag, flattens nested with `.` separator
+  - `tailwind.cjs` — same harness, walks `theme` + `theme.extend` per scale (extend overrides base)
+  - `figma.cjs` — parses `{variableCollections}` shape OR already-flattened bag; emits `rgb(R, G, B)` for color values, per-mode tokens for multi-mode variables
+  Auto-detection by extension + content sniff. (Plan 23-08)
+
+- **Domain primitives bundle** — three checkers sharing a single hit shape (`{rule_id, severity P0-P3, summary, evidence?, line?, file}`):
+  - `domain-primitives/nng.cjs` — runs grep-style heuristic rules loaded from `reference/heuristics.md` fenced yaml blocks; caller may inject `opts.rules` to bypass file-load
+  - `domain-primitives/anti-patterns.cjs` — same yaml extractor against `reference/anti-patterns.md`
+  - `domain-primitives/wcag.cjs` (no axe-core dep) — `contrastRatio()` (WCAG 1.4.3 luminance), `checkContrast({fg, bg, level: AA|AAA})`, `checkTapTarget({width, height, level})` (AA 24×24, AAA 44×44), `checkAriaLabels({content})` (interactive elements without text + aria-label)
+  Both NNG + anti-pattern files allow no parseable yaml today (treated as empty registry); robust to gradual rule population. (Plan 23-09)
+
+### Changed
+
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.23.0`.
+- `test-fixture/baselines/phase-20/resilience-primitives.txt` gains `reference-resolver.cjs` (alphabetical between `reference-registry.cjs` and `relevance-counter.cjs`) and `touches-pattern-miner.cjs` (alphabetical at end).
+
+### Tests
+
+- `tests/output-contracts-23-01.test.cjs` — planner + verifier contracts (14 tests)
+- `tests/design-solidify.test.cjs` — solidify gate, all rollback modes (6)
+- `tests/touches-analyzer.test.cjs` — parser + verdict + matrix (17)
+- `tests/audit-aggregator.test.cjs` — dedup + score + tallies (15)
+- `tests/reference-resolver.test.cjs` — resolution rules + excerpts (12)
+- `tests/touches-pattern-miner.test.cjs` — canonicalize + thresholds + atomic write (10)
+- `tests/visual-baseline.test.cjs` — diff modes + baseline round-trip (14, pngjs-optional path skipped when absent)
+- `tests/design-tokens.test.cjs` — 4 readers + facade auto-detect (15)
+- `tests/domain-primitives.test.cjs` — NNG + anti-pattern + WCAG checkers (18)
+- `tests/phase-23-baseline.test.cjs` — Phase 23 regression baseline (12)
+
+Total: 133 new tests. All Phase 20/21/22 tests still green.
+
+### Deferred
+
+- **`@hegemonart/gdd-sdk` separate npm package** — out of scope; build/packaging project of its own.
+- **Screenshot capture orchestration** (Playwright + Claude Preview MCP wrapper) — needs live MCP infra to validate.
+- **Spec↔code↔visual triangulation verifier** — depends on Phase 16/17 component specs being fleshed out.
+- **Knowledge-graph typed query layer** + cycle/workstream model SDK + pause/resume context serializer SDK + per-stage budget allocator SDK + git operations primitive + handoff bundle parser + intel store typed reader/writer — each is roadmap-text-sized and warrants its own phase scope.
+
+---
+
 ## [1.22.0] — 2026-04-25
 
 Phase 22 GDD SDK Observability milestone — the single-typed `BaseEvent` envelope from Phase 20 grows into a queryable, redacted, transport-able observability layer with tail/grep/WebSocket consumers and a causal event chain. 10 plans (22-01 through 22-10), additive — every Phase 20 + Phase 21 consumer keeps working unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.22.0",
+  "version": "1.23.5",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -87,6 +87,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "optionalDependencies": {
+    "pngjs": "^7.0.0",
     "ws": "^8.20.0"
   }
 }

package/reference/output-contracts/planner-decision.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "planner-decision.schema.json",
+  "title": "Planner Decision Output Contract",
+  "description": "Schema for the structured JSON block emitted by design-planner. Lets /gdd:synthesize and downstream consumers (executor, audit aggregator) read planner output without regex-parsing markdown.",
+  "type": "object",
+  "required": ["schema_version", "plan_id", "tasks", "waves"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "plan_id": {
+      "type": "string",
+      "description": "Stable identifier — e.g. '23-04' or 'PLAN.md'.",
+      "minLength": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["task_id", "summary", "touches"],
+        "additionalProperties": false,
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable per-plan task identifier (e.g. T-01, 23-04-T-1)."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 3
+          },
+          "touches": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "File globs the task is expected to read or write."
+          },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Other task_ids that must complete first.",
+            "default": []
+          },
+          "parallel_safe": {
+            "type": "boolean",
+            "description": "Hint from the planner — the parallelism decision engine confirms via Touches: analysis.",
+            "default": false
+          },
+          "estimated_minutes": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Rough wall-clock estimate; consumed by budget allocator."
+          },
+          "acceptance": {
+            "type": "string",
+            "description": "Free-form acceptance criteria copy."
+          }
+        }
+      }
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["wave", "task_ids"],
+        "additionalProperties": false,
+        "properties": {
+          "wave": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Wave label (e.g. 'A', 'B', 'C')."
+          },
+          "task_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Free-form planner-side rationale — not consumed by code."
+    }
+  }
+}

package/reference/output-contracts/verifier-decision.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "verifier-decision.schema.json",
+  "title": "Verifier Decision Output Contract",
+  "description": "Schema for the structured JSON block emitted by design-verifier. Drives executor↔verifier ping-pong with a typed envelope rather than free-form prose.",
+  "type": "object",
+  "required": ["schema_version", "verdict", "gaps", "must_fix_before_ship", "confidence"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["pass", "fail", "gap"],
+      "description": "pass = ship-ready, gap = remediable, fail = re-plan."
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "area", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": {
+            "type": "string",
+            "enum": ["P0", "P1", "P2", "P3"]
+          },
+          "area": {
+            "type": "string",
+            "description": "Free-form domain tag — e.g. 'a11y', 'motion', 'tokens'."
+          },
+          "summary": { "type": "string", "minLength": 3 },
+          "evidence": {
+            "type": "string",
+            "description": "Citation: file:line reference or audit excerpt."
+          },
+          "remediation": {
+            "type": "string",
+            "description": "One-line proposed fix."
+          }
+        }
+      }
+    },
+    "must_fix_before_ship": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Subset of gap.id values that block ship — typically the P0/P1 ones."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "med", "low"],
+      "description": "Verifier's self-rated confidence — drives whether to escalate to a second pass."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Free-form notes — not code-consumed."
+    }
+  }
+}

package/scripts/lib/adaptive-mode.cjs

@@ -0,0 +1,170 @@
+/**
+ * adaptive-mode.cjs — feature-flag ladder facade for the Phase 23.5
+ * no-regret stack (Plan 23.5-04).
+ *
+ * Three modes, ladder-shaped:
+ *
+ *   "static"  — Phase 10.1 behaviour. Static tier_overrides map applies;
+ *               no posterior writes; no hedge weight updates; no MMR.
+ *               Default for all installs.
+ *
+ *   "hedge"   — Adds AdaNormalHedge consensus thresholding to verifier
+ *               + checker pools. Routing still static. Safest intro
+ *               level — bandit routing is NOT enabled, so the model
+ *               choice for any agent is unchanged.
+ *
+ *   "full"    — Adds bandit Thompson-sampling routing on top of hedge.
+ *               Both posterior + hedge weights persist. Reflector
+ *               proposals based on confidence intervals enabled.
+ *
+ * The ladder is read from `.design/budget.json.adaptive_mode`. Fallback
+ * default = "static". Unknown values clamp to "static" with a stderr
+ * warning (silent if `quiet: true`).
+ *
+ * This module owns the SINGLE source of truth for "is bandit on / is
+ * hedge on" — every consumer (router, hedge, MMR, reflector, the
+ * Phase 22 budget-enforcer hook) reads from `getMode(opts)`.
+ *
+ * No external deps. CommonJS.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_BUDGET_PATH = '.design/budget.json';
+const VALID_MODES = Object.freeze(['static', 'hedge', 'full']);
+const DEFAULT_MODE = 'static';
+
+/** Capability matrix per mode — consumed by callers as a boolean check. */
+const MODE_CAPS = Object.freeze({
+  static: Object.freeze({ bandit: false, hedge: false, mmr: false, reflector_proposals: false }),
+  hedge: Object.freeze({ bandit: false, hedge: true, mmr: true, reflector_proposals: false }),
+  full: Object.freeze({ bandit: true, hedge: true, mmr: true, reflector_proposals: true }),
+});
+
+function resolveBudgetPath(opts = {}) {
+  if (opts.budgetPath) {
+    return path.isAbsolute(opts.budgetPath)
+      ? opts.budgetPath
+      : path.resolve(opts.baseDir ?? process.cwd(), opts.budgetPath);
+  }
+  return path.resolve(opts.baseDir ?? process.cwd(), DEFAULT_BUDGET_PATH);
+}
+
+/**
+ * Read the current adaptive_mode from .design/budget.json. Falls back
+ * to "static" when the file is absent, malformed, or holds an
+ * unrecognised value.
+ *
+ * @param {{baseDir?: string, budgetPath?: string, quiet?: boolean}} [opts]
+ * @returns {'static'|'hedge'|'full'}
+ */
+function getMode(opts = {}) {
+  const p = resolveBudgetPath(opts);
+  if (!fs.existsSync(p)) return DEFAULT_MODE;
+  /** @type {{adaptive_mode?: string}} */
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return DEFAULT_MODE;
+  }
+  const m = cfg && typeof cfg.adaptive_mode === 'string' ? cfg.adaptive_mode : null;
+  if (!m) return DEFAULT_MODE;
+  if (!VALID_MODES.includes(m)) {
+    if (!opts.quiet) {
+      try {
+        process.stderr.write(
+          `[adaptive-mode] unknown adaptive_mode "${m}" in ${p}; falling back to "static"\n`,
+        );
+      } catch {
+        /* swallow */
+      }
+    }
+    return DEFAULT_MODE;
+  }
+  return /** @type {'static'|'hedge'|'full'} */ (m);
+}
+
+/**
+ * Convenience: capability matrix for the current mode.
+ *
+ * @param {{baseDir?: string, budgetPath?: string, quiet?: boolean}} [opts]
+ * @returns {{bandit: boolean, hedge: boolean, mmr: boolean, reflector_proposals: boolean}}
+ */
+function caps(opts = {}) {
+  return MODE_CAPS[getMode(opts)];
+}
+
+/**
+ * Set the adaptive_mode on disk. Atomic write (.tmp + rename). Creates
+ * the budget.json file if missing — the rest of the budget config
+ * defaults to {} so other readers see "no caps configured".
+ *
+ * @param {'static'|'hedge'|'full'} mode
+ * @param {{baseDir?: string, budgetPath?: string}} [opts]
+ * @returns {string} absolute path written
+ */
+function setMode(mode, opts = {}) {
+  if (!VALID_MODES.includes(mode)) {
+    throw new RangeError(
+      `adaptive-mode.setMode: mode must be one of [${VALID_MODES.join('|')}], got ${JSON.stringify(mode)}`,
+    );
+  }
+  const p = resolveBudgetPath(opts);
+  /** @type {Record<string, unknown>} */
+  let cfg = {};
+  if (fs.existsSync(p)) {
+    try {
+      cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      cfg = {};
+    }
+  }
+  cfg.adaptive_mode = mode;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+/**
+ * High-level "should bandit route this agent?" predicate. Replaces ad-
+ * hoc `if (mode === 'full' || …)` checks across the codebase.
+ *
+ * @param {{baseDir?: string, budgetPath?: string}} [opts]
+ * @returns {boolean}
+ */
+function isBanditEnabled(opts = {}) {
+  return caps(opts).bandit;
+}
+
+function isHedgeEnabled(opts = {}) {
+  return caps(opts).hedge;
+}
+
+function isMmrEnabled(opts = {}) {
+  return caps(opts).mmr;
+}
+
+function isReflectorProposalsEnabled(opts = {}) {
+  return caps(opts).reflector_proposals;
+}
+
+module.exports = {
+  getMode,
+  setMode,
+  caps,
+  isBanditEnabled,
+  isHedgeEnabled,
+  isMmrEnabled,
+  isReflectorProposalsEnabled,
+  resolveBudgetPath,
+  DEFAULT_BUDGET_PATH,
+  DEFAULT_MODE,
+  VALID_MODES,
+  MODE_CAPS,
+};