@bongos/core 1.17.0

package/modules/builder-settings/routes/settings.js

@@ -0,0 +1,417 @@
+'use strict';
+
+// modules/builder-settings/routes/settings.js — the per-builder PREFERENCE
+// endpoints (BV1.R80 / ADR 0093 §1).
+//
+// Carved out of the core src/bongos/routes/me.js: the five SELF-CONTAINED pref
+// surfaces — skill-model / sound / event-sound / wandering / render — moved here
+// verbatim (the security-carve precedent that SPLIT routes/security.js: the
+// feature routes left, the aggregator stayed). They keep their exact `/me/*`
+// paths (the loader mounts this router on the same /api/bongos router, BEFORE the
+// public catch-all), so the API surface is OTB byte-identical — only the
+// require() paths changed: the auth gates + validators reach the published
+// doorway (`api.*`); the pref shapers + the db slice are intra-module requires.
+//
+// The `GET /me` AGGREGATOR stayed in core me.js as a thin facade — it resolves
+// the `builder-settings` kernel port for its wandering/render/needs slices
+// (02-module-map §2). This factory also REGISTERS that port (below), mirroring
+// modules/economy/routes/reward.js.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const settings = require('../settings');
+const db = require('../db');
+const skillPrefs = require('../skill-prefs');
+const soundPrefs = require('../sound-prefs');
+const eventSoundPrefs = require('../event-sound-prefs');
+const wanderingPrefs = require('../wandering-prefs');
+const interactionPrefs = require('../interaction-prefs');
+const modelAllocPrefs = require('../model-alloc-prefs');
+const renderPrefs = require('../render-prefs');
+const displayName = require('../display-name');
+
+// Register the `builder-settings` kernel PORT (BV1.R80 / ADR 0093 §1). The core
+// consumers (routes/me.js's GET /me aggregator + cascade-dispatch.js) resolve it
+// instead of importing the module (the boundary rule: core never requires a
+// module). Pattern mirrors modules/economy/routes/reward.js — registered from the
+// route factory (the one boot hook that runs both live AND when a test rebuilds
+// the GDS router), hasProvider-guarded so re-instantiation never trips the
+// single-provider guard.
+function registerSeams() {
+  if (!api.hasProvider('builder-settings')) {
+    api.registerProvider('builder-settings', settings);
+  }
+}
+
+module.exports = function buildBuilderSettingsRouter() {
+  registerSeams();
+  const router = express.Router();
+
+  // Per-builder skill model preferences (V3.R85 / #304, migration 037).
+  //
+  // The matrix shows every skill from skill-prefs.KNOWN_SKILLS with three
+  // columns: the system default (audit-derived in skill-prefs.js), the
+  // builder's override if any, and the effective pick (override > default).
+  // ALLOWED_MODELS + KNOWN_SKILLS are echoed back so the UI doesn't have to
+  // mirror them from a second source.
+  //
+  // rank: any-builder — own profile config; mirrors the disciplines route.
+  router.get('/me/skill-prefs', api.requireBuilder, async (req, res) => {
+    try {
+      const stored = await db.getBuilderSkillPrefs(req.builder.id);
+      res.json({
+        prefs: stored,
+        effective: skillPrefs.listEffective(stored),
+        defaults: skillPrefs.SKILL_DEFAULTS,
+        known_skills: skillPrefs.KNOWN_SKILLS,
+        allowed_models: skillPrefs.ALLOWED_MODELS,
+      });
+    } catch (err) {
+      console.error('[gds] GET /me/skill-prefs', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH a partial set of skill overrides. Body shape is
+  //   { "<skill-name>": "<model>" | null, ... }
+  // with the `null` sentinel meaning "clear this skill's override (fall
+  // back to the system default)". Unknown skill names or unknown models
+  // → 422 with an errors array naming each bad entry; nothing is written
+  // when validation fails. An empty body is a no-op (returns current).
+  //
+  // rank: any-builder — self-service profile edit; same posture as
+  // /me/disciplines.
+  router.patch('/me/skill-prefs', api.requireBuilder, async (req, res) => {
+    try {
+      const v = skillPrefs.validatePatch(req.body || {});
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderSkillPrefs(req.builder.id);
+      const next = skillPrefs.applyPatch(existing, v.patch);
+      const saved = await db.setBuilderSkillPrefs(req.builder.id, next);
+      res.json({
+        prefs: saved,
+        effective: skillPrefs.listEffective(saved),
+        defaults: skillPrefs.SKILL_DEFAULTS,
+        known_skills: skillPrefs.KNOWN_SKILLS,
+        allowed_models: skillPrefs.ALLOWED_MODELS,
+      });
+    } catch (err) {
+      console.error('[gds] PATCH /me/skill-prefs', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder per-sound on/off preferences (V3.R91 / #786, migration 075).
+  //
+  // The toggle list shows every sound from sound-prefs.KNOWN_SOUNDS with its
+  // label/description, system default (ON), the builder's override if any, and
+  // the effective enabled-state. The local player (.claude/sounds/play.js) reads
+  // a mirror of these prefs written by scripts/gds/fetch-sound-prefs.js at
+  // session start — this endpoint is the source of truth.
+  //
+  // rank: any-builder — own profile config; mirrors the skill-prefs route.
+  router.get('/me/sound-prefs', api.requireBuilder, async (req, res) => {
+    try {
+      const stored = await db.getBuilderSoundPrefs(req.builder.id);
+      res.json({
+        prefs: stored,
+        effective: soundPrefs.listEffective(stored),
+        effective_map: soundPrefs.effectiveMap(stored),
+        volume: soundPrefs.getVolume(stored),
+        defaults: soundPrefs.SOUND_DEFAULTS,
+        known_sounds: soundPrefs.KNOWN_SOUNDS,
+      });
+    } catch (err) {
+      console.error('[gds] GET /me/sound-prefs', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH a partial set of sound overrides. Body shape is
+  //   { "<sound-name>": <bool> | null, ... }
+  // with the `null` sentinel meaning "clear this sound's override (fall back to
+  // the system default ON)". Unknown sound names or non-boolean values → 422
+  // with an errors array; nothing is written when validation fails. An empty
+  // body is a no-op (returns current).
+  //
+  // rank: any-builder — self-service profile edit; same posture as
+  // /me/skill-prefs.
+  router.patch('/me/sound-prefs', api.requireBuilder, async (req, res) => {
+    try {
+      const v = soundPrefs.validatePatch(req.body || {});
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderSoundPrefs(req.builder.id);
+      const next = soundPrefs.applyPatch(existing, v.patch);
+      const saved = await db.setBuilderSoundPrefs(req.builder.id, next);
+      res.json({
+        prefs: saved,
+        effective: soundPrefs.listEffective(saved),
+        effective_map: soundPrefs.effectiveMap(saved),
+        volume: soundPrefs.getVolume(saved),
+        defaults: soundPrefs.SOUND_DEFAULTS,
+        known_sounds: soundPrefs.KNOWN_SOUNDS,
+      });
+    } catch (err) {
+      console.error('[gds] PATCH /me/sound-prefs', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder per-event sound variant selection (task 582, migration 164).
+  //
+  // Returns each of the 5 build events with their available world-themed variants,
+  // the builder's current selection (or the default), and the resolved .wav file
+  // name. The local player uses a mirror written by fetch-sound-prefs.js.
+  //
+  // rank: any-builder — own profile config; mirrors the sound-prefs route.
+  router.get('/me/event-sound-prefs', api.requireBuilder, async (req, res) => {
+    try {
+      const stored = await db.getBuilderEventSoundPrefs(req.builder.id);
+      res.json({
+        prefs:        stored,
+        effective:    eventSoundPrefs.listEffective(stored),
+        effective_wav: eventSoundPrefs.effectiveWavMap(stored),
+        events:       eventSoundPrefs.EVENTS,
+      });
+    } catch (err) {
+      console.error('[gds] GET /me/event-sound-prefs', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH a partial set of event sound overrides. Body shape:
+  //   { "<event-id>": "<variant-id>" | null, ... }
+  // null clears the override (falls back to the event's default). Unknown event
+  // IDs, non-string variants, or variants that don't belong to the event → 422.
+  //
+  // rank: any-builder — self-service profile edit; mirrors the sound-prefs route.
+  router.patch('/me/event-sound-prefs', api.requireBuilder, async (req, res) => {
+    try {
+      const v = eventSoundPrefs.validatePatch(req.body || {});
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderEventSoundPrefs(req.builder.id);
+      const next = eventSoundPrefs.applyPatch(existing, v.patch);
+      const saved = await db.setBuilderEventSoundPrefs(req.builder.id, next);
+      res.json({
+        prefs:        saved,
+        effective:    eventSoundPrefs.listEffective(saved),
+        effective_wav: eventSoundPrefs.effectiveWavMap(saved),
+        events:       eventSoundPrefs.EVENTS,
+      });
+    } catch (err) {
+      console.error('[gds] PATCH /me/event-sound-prefs', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder "wandering" level (task 1268, migration 119). Governs how
+  // readily the agent opens a NEW THREAD of work (tangent / investigation /
+  // unsolicited suggestion) vs. staying on the claimed task — off-task only,
+  // never in-task initiative. The effective level is resolved server-side: the
+  // builder's override clamped to [0, maxForRank], with the rank default when
+  // unset (wandering-prefs.js is the single source of truth). Newcomers (Xenos)
+  // are hard-clamped to Locked; Thetes capped at Focused; Metic+ free.
+  //
+  // rank: any-builder — own profile config; mirrors the skill/sound-prefs routes.
+  router.get('/me/wandering', api.requireBuilder, async (req, res) => {
+    try {
+      const builder = await api.getBuilderById(req.builder.id);
+      const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
+      res.json(wanderingPrefs.describeForApi(stored, builder?.rank));
+    } catch (err) {
+      console.error('[gds] GET /me/wandering', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH the wandering level. Body: { wandering: <0..3> | null } where null
+  // clears the override (fall back to the rank default). A level above the
+  // builder's rank ceiling → 422 above_rank_cap (the UI also hides those). Any
+  // other key → 422. Empty body is a no-op (returns current).
+  //
+  // rank: any-builder — self-service profile edit; same posture as
+  // /me/skill-prefs. The rank cap is enforced server-side, so a builder can
+  // never store a level their rank doesn't permit.
+  router.patch('/me/wandering', api.requireBuilder, async (req, res) => {
+    try {
+      const builder = await api.getBuilderById(req.builder.id);
+      const maxLevel = wanderingPrefs.maxLevelForRank(builder?.rank);
+      const v = wanderingPrefs.validatePatch(req.body || {}, { maxLevel });
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
+      const next = wanderingPrefs.applyPatch(existing, v.patch);
+      const saved = await db.setBuilderBehaviorPrefs(req.builder.id, next);
+      res.json(wanderingPrefs.describeForApi(saved, builder?.rank));
+    } catch (err) {
+      console.error('[gds] PATCH /me/wandering', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder INTERACTION PROFILE (task 2010, shares the behavior_prefs jsonb /
+  // migration 119). Tone, technical level, and local-toolchain familiarity — the
+  // old CLAUDE.md §2 "The Prompter" defaults, now a per-builder profile (there is
+  // no special "owner" entity; an owner is a builder with a profile). Resolved
+  // server-side over the portable defaults; the effective contract is injected
+  // each session (like wandering). interaction-prefs.js is the source of truth.
+  //
+  // rank: any-builder — own profile config; mirrors the wandering/render routes.
+  router.get('/me/interaction', api.requireBuilder, async (req, res) => {
+    try {
+      const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
+      res.json(interactionPrefs.describeForApi(stored));
+    } catch (err) {
+      console.error('[gds] GET /me/interaction', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH the interaction profile. Body: { <field>: <value> | null } — null
+  // clears a field back to its default. Unknown field/value → 422. Empty body is
+  // a no-op (returns current). No rank cap (pure ergonomics, not a trust gate).
+  router.patch('/me/interaction', api.requireBuilder, async (req, res) => {
+    try {
+      const v = interactionPrefs.validatePatch(req.body || {});
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
+      const nextInteraction = interactionPrefs.applyPatch(interactionPrefs.storedProfile(existing), v.patch);
+      const nextPrefs = { ...(existing || {}), [interactionPrefs.RESERVED_KEY]: nextInteraction };
+      const saved = await db.setBuilderBehaviorPrefs(req.builder.id, nextPrefs);
+      res.json(interactionPrefs.describeForApi(saved));
+    } catch (err) {
+      console.error('[gds] PATCH /me/interaction', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder / per-instance MODEL ALLOCATION (task 2011, shares the
+  // behavior_prefs jsonb). The subagent model-routing policy (main tier +
+  // subagent default/routine tiers) — the old CLAUDE.md §2 hardcoded table, now
+  // settings-driven: resolved as builder override → instance default
+  // (`branding.models`) → code default. model-alloc-prefs.js is the SSOT.
+  //
+  // rank: any-builder — own profile config; mirrors the wandering/interaction routes.
+  function instanceModels() {
+    try { return api.branding().models || {}; } catch { return {}; }
+  }
+  router.get('/me/model-allocation', api.requireBuilder, async (req, res) => {
+    try {
+      const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
+      res.json(modelAllocPrefs.describeForApi(stored, instanceModels()));
+    } catch (err) {
+      console.error('[gds] GET /me/model-allocation', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH the model allocation. Body: { <slot>: <tier> | null } — null clears the
+  // override for that slot (fall back to instance/code default). Unknown slot or
+  // bad tier → 422. Empty body is a no-op (returns current).
+  router.patch('/me/model-allocation', api.requireBuilder, async (req, res) => {
+    try {
+      const v = modelAllocPrefs.validatePatch(req.body || {});
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
+      const nextOverride = modelAllocPrefs.applyPatch(modelAllocPrefs.storedOverride(existing), v.patch);
+      const nextPrefs = { ...(existing || {}), [modelAllocPrefs.RESERVED_KEY]: nextOverride };
+      const saved = await db.setBuilderBehaviorPrefs(req.builder.id, nextPrefs);
+      res.json(modelAllocPrefs.describeForApi(saved, instanceModels()));
+    } catch (err) {
+      console.error('[gds] PATCH /me/model-allocation', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder "render widgets" knob (task 1279, shares the behavior_prefs
+  // jsonb / migration 119). Whether the deterministic session cards render as a
+  // rich in-feed HTML widget or the plain text fallback. The widget is nicer but
+  // the agent must relay its full markup verbatim into show_widget (read +
+  // re-emit) every session-start / claim / ship stage — a real token cost. This
+  // toggle turns that off; when off the CLIs emit only text (no HTML relayed).
+  // No rank cap (pure cost/taste, not a trust gate); default ON. render-prefs.js
+  // is the single source of truth.
+  //
+  // rank: any-builder — own profile config; mirrors the skill/sound/wandering routes.
+  router.get('/me/render', api.requireBuilder, async (req, res) => {
+    try {
+      const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
+      res.json(renderPrefs.describeForApi(stored));
+    } catch (err) {
+      console.error('[gds] GET /me/render', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH the render knob. Body: { widgets: <bool> | null } where null clears the
+  // override (fall back to the default ON). Any other key, or a non-boolean
+  // value → 422. Empty body is a no-op (returns current). Sibling behavior keys
+  // (e.g. wandering) are preserved by applyPatch.
+  //
+  // rank: any-builder — self-service profile edit; same posture as /me/wandering.
+  router.patch('/me/render', api.requireBuilder, async (req, res) => {
+    try {
+      const v = renderPrefs.validatePatch(req.body || {});
+      if (!v.ok) {
+        return res.fail('invalid_patch', 422, { errors: v.errors });
+      }
+      const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
+      const next = renderPrefs.applyPatch(existing, v.patch);
+      const saved = await db.setBuilderBehaviorPrefs(req.builder.id, next);
+      res.json(renderPrefs.describeForApi(saved));
+    } catch (err) {
+      console.error('[gds] PATCH /me/render', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Per-builder DISPLAY NAME (task 1669). The free label shown next to a
+  // builder's work in the hall (header, leaderboard, work feed — all already read
+  // display_name, so a DB update propagates). Seeded once from GitHub at account
+  // creation; these routes are the only way to change it afterward. Stable
+  // identity stays github_login/id — the display name is just the rendered label.
+  //
+  // rank: any-builder — own profile config; mirrors the skill/sound/render routes.
+  router.get('/me/display-name', api.requireBuilder, async (req, res) => {
+    try {
+      const current = await db.getBuilderDisplayName(req.builder.id);
+      res.json({ display_name: current, max_length: displayName.MAX_LENGTH });
+    } catch (err) {
+      console.error('[gds] GET /me/display-name', err);
+      res.fail('read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH the display name. Body: { display_name: "<new name>" }. Validated +
+  // trimmed by display-name.js: empty/whitespace-only, control chars, and names
+  // over the length ceiling → 422 with an errors array; nothing is written when
+  // validation fails. Own-scoped — only the AUTHENTICATED builder's row is
+  // touched (api.requireBuilder + req.builder.id), never another builder.
+  // Uniqueness is NOT required (display names may collide).
+  router.patch('/me/display-name', api.requireBuilder, async (req, res) => {
+    try {
+      const v = displayName.validate((req.body || {}).display_name);
+      if (!v.ok) {
+        return res.fail('invalid_display_name', 422, { errors: v.errors });
+      }
+      const saved = await db.setBuilderDisplayName(req.builder.id, v.value);
+      res.json({ display_name: saved, max_length: displayName.MAX_LENGTH });
+    } catch (err) {
+      console.error('[gds] PATCH /me/display-name', err);
+      res.fail('write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/modules/builder-settings/settings.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// modules/builder-settings/settings.js — the `builder-settings` kernel PORT
+// provider surface (BV1.R80 / ADR 0093 §1).
+//
+// builder-settings owns the per-builder preference domain (wandering · skill ·
+// sound · render) + builder-needs. Most of that surface is reached HTTP-side
+// through the module's own routes (routes/settings.js mounts the `/me/*-prefs`
+// endpoints). But two CORE files legitimately need a sliver of it and must NOT
+// `require()` a module (the one-way boundary, ADR 0083):
+//   • routes/me.js — the `GET /me` aggregator builds the `wandering` / `render` /
+//     `needs` slices of the profile payload inline (alongside the economy/discord
+//     slices it already resolves through ports). It resolves THIS port for them.
+//   • cascade-dispatch.js — the dormant System-3 cascade router clamps a spawn to
+//     the builder's configured model ceiling (`skillPrefs.getForBuilder`). It
+//     resolves THIS port's `skillCeiling`.
+//
+// So this port is the narrow read surface those two core consumers resolve via
+// `seams.resolveOptional('builder-settings')`. builder-settings is default-on, so
+// the provider is present in prod; the consumers degrade gracefully when it isn't
+// (a vanilla instance without the module): me.js's slices are best-effort and
+// cascade's ceiling falls back to 'opus' (its existing `|| 'opus'` default).
+//
+// We DELEGATE (do not spread) every method so a test that stubs a function on the
+// live db/pref module object still bites at call time (the economy reward.js
+// precedent — a spread captures the original reference at module-load).
+
+const db = require('./db');
+const skillPrefs = require('./skill-prefs');
+const wanderingPrefs = require('./wandering-prefs');
+const interactionPrefs = require('./interaction-prefs');
+const modelAllocPrefs = require('./model-alloc-prefs');
+const renderPrefs = require('./render-prefs');
+const builderNeeds = require('./builder-needs');
+
+module.exports = {
+  // --- the raw behavior_prefs blob read (GET /me resolves this once, then shapes
+  //     the wandering + render slices from the same blob — one DB round-trip).
+  getBuilderBehaviorPrefs: (...a) => db.getBuilderBehaviorPrefs(...a),
+
+  // --- effective-value shapers the GET /me aggregator renders inline (the SSOT
+  //     for each knob's API shape lives in the corresponding pref lib).
+  describeWandering: (...a) => wanderingPrefs.describeForApi(...a),
+  describeInteraction: (...a) => interactionPrefs.describeForApi(...a),
+  describeModelAllocation: (...a) => modelAllocPrefs.describeForApi(...a),
+  describeRender: (...a) => renderPrefs.describeForApi(...a),
+  computeNeeds: (...a) => builderNeeds.computeNeeds(...a),
+
+  // --- the per-builder model ceiling for a skill (cascade-dispatch clamps to it;
+  //     never exceeds it). Mirrors the former `skillPrefs.getForBuilder` call.
+  skillCeiling: (builderPrefs, skillName) => skillPrefs.getForBuilder(builderPrefs, skillName),
+};

package/modules/builder-settings/skill-prefs.js

@@ -0,0 +1,196 @@
+// src/bongos/skill-prefs.js — per-builder model preferences per skill (V3.R85
+// / #304).
+//
+// One jsonb column on `builders` (skill_model_prefs, migration 037) stores
+// each builder's overrides as { <skill-name>: <model-token> }. Missing keys
+// fall back to the system defaults in SKILL_DEFAULTS below. This module is
+// the single source of truth that the API surfaces, the /builders UI reads
+// from, and any future skill-execution-time hook resolves against.
+//
+// The audit that produced SKILL_DEFAULTS lives in ADR 0021 — each skill is
+// classified as one of:
+//
+//   - 'script'         — pure mechanism; no LLM judgment needed. Slash
+//                        command shells out to a script in scripts/gds/ and
+//                        formats the output. No model selection meaningful.
+//   - 'opus'  (default for heavy judgment) — design/strategy work the
+//                        builder really wants right.
+//   - 'sonnet'         — middle tier; judgment is involved but not load-
+//                        bearing. Cheaper than opus, more capable than
+//                        haiku.
+//   - 'haiku'          — light judgment; classification, sorting, brief
+//                        framing.
+//
+// A skill listed here as default 'script' still appears in the UI matrix so
+// a builder can deliberately upgrade it (e.g. someone using /builder-cost
+// wants Opus to suggest the right cost category) — the system default just
+// signals "no LLM judgment is structurally needed."
+
+const ALLOWED_MODELS = Object.freeze(['opus', 'sonnet', 'haiku', 'script']);
+
+// The complete set of skills the matrix exposes. Drives both the UI render
+// and the PATCH validation — any pref for a skill not in this set is
+// rejected. Add a new skill = add one line here + one line in
+// SKILL_DEFAULTS. (Keeping these in code, not in a table, so that the
+// allowlist is reviewed alongside the skill SKILL.md itself.)
+//
+// Ordered to match the /builders UI grouping: methodology + workflow
+// builders first, then otb-art at the bottom.
+const KNOWN_SKILLS = Object.freeze([
+  // Methodology / workflow
+  'builder-start',
+  'builder-claim',
+  'builder-ship',
+  'builder-release',
+  'builder-exit',
+  'builder-cost',
+  // Daily cadence (heavy judgment)
+  'idea-triage',
+  'blocker-review',
+  'merge-mode',
+  // Planning (heavy judgment)
+  'planning-session',
+  'priority-session',
+  // Setup / one-shot
+  'builder-setup',
+  // Art pipeline
+  'otb-tile-generate',
+  'otb-design-review',
+  'otb-feedback-capture',
+  'otb-figma-sync',
+]);
+
+// System default per skill. The audit's verdict — what runs when the
+// builder hasn't expressed a preference.
+const SKILL_DEFAULTS = Object.freeze({
+  // Pure mechanism — script wrappers around scripts/gds/*.js. No LLM
+  // judgment needed for the wrapped operation; the slash command just
+  // routes input → script → formatted output.
+  'builder-start': 'script',
+  'builder-claim': 'script',
+  'builder-release': 'script',
+  'builder-exit': 'script',
+  'builder-cost': 'script',
+  'otb-figma-sync': 'script',
+  // Mechanism with a small judgment moment (drafting the handoff notes
+  // and value summary). Default Sonnet — Opus is overkill for short note
+  // drafting, Haiku would weaken the value summary.
+  'builder-ship': 'sonnet',
+  // Heavy judgment — the skill IS the LLM walking through verdicts,
+  // proposals, conflict resolution, criterion design. Defaults Opus per
+  // the project-wide subagent-routing rule (CLAUDE.md §2).
+  'idea-triage': 'opus',
+  'blocker-review': 'opus',
+  'merge-mode': 'opus',
+  'planning-session': 'opus',
+  'priority-session': 'opus',
+  // One-shot setup — long-form environment walk-through, but mechanical
+  // once the steps are clear. Sonnet is enough.
+  'builder-setup': 'sonnet',
+  // Art pipeline — generation + design review + feedback capture all use
+  // an EXTERNAL model (Gemini for the image gen + review). The 'model'
+  // here refers to the orchestrating Claude subagent, not the image
+  // model. Sonnet is sufficient for orchestration.
+  'otb-tile-generate': 'sonnet',
+  'otb-design-review': 'sonnet',
+  'otb-feedback-capture': 'sonnet',
+});
+
+// Sanity assertion at module-load: every KNOWN_SKILLS entry has a default.
+// Catches drift between the two lists at deploy time, not at runtime.
+for (const s of KNOWN_SKILLS) {
+  if (!Object.prototype.hasOwnProperty.call(SKILL_DEFAULTS, s)) {
+    throw new Error(`skill-prefs: KNOWN_SKILLS lists '${s}' but SKILL_DEFAULTS has no entry`);
+  }
+}
+
+function isAllowedModel(value) {
+  return typeof value === 'string' && ALLOWED_MODELS.includes(value);
+}
+
+function isKnownSkill(value) {
+  return typeof value === 'string' && KNOWN_SKILLS.includes(value);
+}
+
+// Resolve a builder's effective preference for one skill: the override if
+// they've set one, else the system default. Returns null for unknown
+// skills (caller should treat as "not configurable").
+//
+// `builderPrefs` is the raw jsonb value off builders.skill_model_prefs.
+// We accept it as a plain object so callers can pass it in once (e.g. the
+// API endpoint resolves it once per request) rather than hitting the DB
+// per-skill.
+function getForBuilder(builderPrefs, skillName) {
+  if (!isKnownSkill(skillName)) return null;
+  const override = builderPrefs && builderPrefs[skillName];
+  if (isAllowedModel(override)) return override;
+  return SKILL_DEFAULTS[skillName];
+}
+
+// Build the per-builder effective-preference list shown in the UI matrix.
+// Each row carries the skill name, the system default, the builder's
+// override (or null if unset), and the effective pick. Ordered to match
+// KNOWN_SKILLS for stable UI rendering.
+function listEffective(builderPrefs) {
+  return KNOWN_SKILLS.map((skill) => ({
+    skill,
+    default_model: SKILL_DEFAULTS[skill],
+    override_model: isAllowedModel(builderPrefs?.[skill]) ? builderPrefs[skill] : null,
+    effective_model: getForBuilder(builderPrefs, skill),
+  }));
+}
+
+// Validate a PATCH body: { <skill>: <model>, ... } where every skill is
+// KNOWN_SKILLS and every model is ALLOWED_MODELS OR null (null = clear
+// the override and fall back to the system default).
+//
+// Returns { ok: true, patch } on success, { ok: false, errors } on
+// failure. Empty body is allowed (no-op).
+function validatePatch(body) {
+  if (body == null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, errors: [{ error: 'body_must_be_object' }] };
+  }
+  const errors = [];
+  const patch = {};
+  for (const [skill, model] of Object.entries(body)) {
+    if (!isKnownSkill(skill)) {
+      errors.push({ skill, error: 'unknown_skill' });
+      continue;
+    }
+    if (model === null) {
+      patch[skill] = null; // sentinel: clear the override
+      continue;
+    }
+    if (!isAllowedModel(model)) {
+      errors.push({ skill, error: 'unknown_model', value: model, allowed: ALLOWED_MODELS });
+      continue;
+    }
+    patch[skill] = model;
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, patch };
+}
+
+// Apply a validated patch to a builder's existing prefs. Pure — does not
+// touch the DB. Returns a new object suitable for writing back. null
+// values delete keys; defined string values overwrite.
+function applyPatch(existing, patch) {
+  const next = { ...(existing || {}) };
+  for (const [skill, model] of Object.entries(patch)) {
+    if (model === null) delete next[skill];
+    else next[skill] = model;
+  }
+  return next;
+}
+
+module.exports = {
+  ALLOWED_MODELS,
+  KNOWN_SKILLS,
+  SKILL_DEFAULTS,
+  isAllowedModel,
+  isKnownSkill,
+  getForBuilder,
+  listEffective,
+  validatePatch,
+  applyPatch,
+};