@bongos/core 1.19.365 → 1.19.367

package/scripts/gds/gen-sounds.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// scripts/gds/gen-sounds.js — synthesize the notification WAVs (task 1003272).
+//
+// WHY A GENERATOR RATHER THAN FOUR COMMITTED BINARIES. The 5-event sound system
+// (V3.R90, task 1000781) shipped its configuration — the prefs, the toggles, the
+// master volume, the per-event variant picker — and never shipped the audio. Only
+// chime.wav has ever existed in this repo, so four of the five events resolved to
+// a 404 and played nothing. Two prior attempts to fix "sound is broken" (tasks
+// 1001252 and 1000796) were abandoned without reaching that.
+//
+// An opaque binary nobody can regenerate is how a repo loses assets in the first
+// place (the local player itself vanished in the 1.18.0 re-seed and no commit
+// records it). These are simple synthesized tones, so the honest artifact is the
+// recipe: a few dozen lines of additive synthesis anyone can read, adjust, and
+// re-run. `node scripts/gds/gen-sounds.js` is idempotent — same bytes every time,
+// no timestamps, no randomness — so it can be a CI freshness check like the other
+// generators if that is ever wanted.
+//
+// chime.wav IS NOT TOUCHED. It predates this task and is the one asset the system
+// always had; regenerating it would replace a sound builders already know with a
+// different one for no reason. This writes only the four that were missing.
+//
+// WHERE THEY GO, and why one copy. modules/hall-ui/public/ is served at
+// /builders/<name>.wav, which is exactly what settings.js previews
+// (`new Audio('/builders/' + wavName + '.wav')`). The local player
+// (.claude/sounds/play.js) reads the SAME files from that directory rather than
+// keeping a second copy — two copies of an asset are two things to drift.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RATE = 44100;
+const OUT_DIR = path.resolve(__dirname, '..', '..', 'modules', 'hall-ui', 'public');
+
+// Equal-temperament note table, only the notes these sounds use. Named rather
+// than numeric so the voicings below read as music instead of magic numbers.
+const HZ = {
+  A5: 880.00, D6: 1174.66,
+  C5: 523.25, E5: 659.25, G5: 783.99,
+  C6: 1046.50, E6: 1318.51, G6: 1567.98,
+};
+
+// One struck note: a fundamental plus a little second and third harmonic (a bell
+// is not a sine wave), under an exponential decay with a short fade-in. The
+// fade-in matters — starting a waveform at full amplitude is an audible click.
+function note({ freq, start, dur, gain = 0.5, decay = 4.5 }) {
+  const voices = [
+    { mult: 1, amp: 1.0 },
+    { mult: 2, amp: 0.28 },
+    { mult: 3, amp: 0.10 },
+  ];
+  const attack = Math.min(0.006, dur / 8); // seconds
+  return { freq, start, dur, gain, decay, voices, attack };
+}
+
+// Render a list of notes into one mono float buffer, summed (notes may overlap).
+function render(notes) {
+  const end = notes.reduce((m, n) => Math.max(m, n.start + n.dur), 0);
+  const total = Math.ceil((end + 0.03) * RATE); // a little tail so nothing cuts
+  const buf = new Float64Array(total);
+  for (const n of notes) {
+    const from = Math.floor(n.start * RATE);
+    const len = Math.floor(n.dur * RATE);
+    for (let i = 0; i < len; i++) {
+      const t = i / RATE;
+      const env = Math.exp(-n.decay * t) * Math.min(1, t / n.attack);
+      let s = 0;
+      for (const v of n.voices) s += v.amp * Math.sin(2 * Math.PI * n.freq * v.mult * t);
+      buf[from + i] += s * env * n.gain;
+    }
+  }
+  // Normalize to a consistent peak so no sound is jarringly louder than another,
+  // then a short linear fade-out so the file never ends mid-cycle (another click).
+  let peak = 0;
+  for (let i = 0; i < total; i++) peak = Math.max(peak, Math.abs(buf[i]));
+  const scale = peak > 0 ? 0.82 / peak : 0;
+  const fade = Math.min(total, Math.floor(0.02 * RATE));
+  for (let i = 0; i < total; i++) {
+    let s = buf[i] * scale;
+    const fromEnd = total - 1 - i;
+    if (fromEnd < fade) s *= fromEnd / fade;
+    buf[i] = s;
+  }
+  return buf;
+}
+
+// 16-bit mono PCM, 44100 Hz — byte-for-byte the format of the existing chime.wav,
+// so nothing downstream has to care which file it got.
+function toWav(samples) {
+  const dataBytes = samples.length * 2;
+  const out = Buffer.alloc(44 + dataBytes);
+  out.write('RIFF', 0);
+  out.writeUInt32LE(36 + dataBytes, 4);
+  out.write('WAVE', 8);
+  out.write('fmt ', 12);
+  out.writeUInt32LE(16, 16);      // fmt chunk size
+  out.writeUInt16LE(1, 20);       // PCM
+  out.writeUInt16LE(1, 22);       // mono
+  out.writeUInt32LE(RATE, 24);
+  out.writeUInt32LE(RATE * 2, 28); // byte rate
+  out.writeUInt16LE(2, 32);        // block align
+  out.writeUInt16LE(16, 34);       // bits
+  out.write('data', 36);
+  out.writeUInt32LE(dataBytes, 40);
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    out.writeInt16LE(Math.round(clamped * 32767), 44 + i * 2);
+  }
+  return out;
+}
+
+// The four voicings. Each is written to match what the event MEANS — the labels
+// come from modules/builder-settings/sound-prefs.js.
+const SOUNDS = {
+  // "When Claude needs your input" — a two-tone ask, rising so it reads as a
+  // question. Short and unhurried: this one can fire while someone is thinking.
+  alert: [
+    note({ freq: HZ.A5, start: 0.00, dur: 0.26, gain: 0.5, decay: 7 }),
+    note({ freq: HZ.D6, start: 0.15, dur: 0.40, gain: 0.5, decay: 6 }),
+  ],
+  // "When a task ships" — a settled two-note rise, C5 to G5. A fifth, because it
+  // should sound finished rather than expectant.
+  ship: [
+    note({ freq: HZ.C5, start: 0.00, dur: 0.30, gain: 0.5, decay: 6 }),
+    note({ freq: HZ.G5, start: 0.14, dur: 0.55, gain: 0.5, decay: 4.5 }),
+  ],
+  // "When a big task ships" — the same idea carried further: a major triad
+  // arpeggio landing on the octave.
+  triumph: [
+    note({ freq: HZ.C5, start: 0.00, dur: 0.26, gain: 0.42, decay: 7 }),
+    note({ freq: HZ.E5, start: 0.11, dur: 0.26, gain: 0.42, decay: 7 }),
+    note({ freq: HZ.G5, start: 0.22, dur: 0.30, gain: 0.46, decay: 6 }),
+    note({ freq: HZ.C6, start: 0.34, dur: 0.75, gain: 0.55, decay: 3.4 }),
+  ],
+  // "When you earn a rank promotion" — the brightest of the four, a four-note
+  // fanfare that overlaps into a held top note.
+  fanfare: [
+    note({ freq: HZ.G5, start: 0.00, dur: 0.22, gain: 0.40, decay: 8 }),
+    note({ freq: HZ.C6, start: 0.10, dur: 0.22, gain: 0.44, decay: 8 }),
+    note({ freq: HZ.E6, start: 0.20, dur: 0.26, gain: 0.46, decay: 7 }),
+    note({ freq: HZ.G6, start: 0.31, dur: 0.90, gain: 0.55, decay: 3.0 }),
+  ],
+};
+
+function main() {
+  const check = process.argv.includes('--check');
+  const written = [];
+  const stale = [];
+  for (const [name, notes] of Object.entries(SOUNDS)) {
+    const file = path.join(OUT_DIR, `${name}.wav`);
+    const wav = toWav(render(notes));
+    let current = null;
+    try { current = fs.readFileSync(file); } catch { /* absent */ }
+    if (current && current.equals(wav)) continue;
+    if (check) { stale.push(path.relative(path.resolve(__dirname, '..', '..'), file)); continue; }
+    fs.writeFileSync(file, wav);
+    written.push(`${name}.wav (${wav.length} bytes)`);
+  }
+  if (check) {
+    if (stale.length) {
+      console.error(`gen-sounds --check: STALE — would rewrite ${stale.join(', ')}`);
+      console.error('  run: node scripts/gds/gen-sounds.js  (and commit the result)');
+      process.exit(1);
+    }
+    console.log('gen-sounds --check: up to date.');
+    return;
+  }
+  console.log(written.length
+    ? `gen-sounds: wrote ${written.join(', ')}`
+    : 'gen-sounds: all sounds already current — no changes.');
+}
+
+if (require.main === module) main();
+module.exports = { render, toWav, SOUNDS, RATE };

package/scripts/gds/ship-io.js

@@ -14,8 +14,7 @@ const { playSound } = require('./ship-state.js');
 function playShipBell() {
   let shipWav = 'ship';
   try {
-    const prefsPath = require('path').join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
-    const raw = require('fs').readFileSync(prefsPath, 'utf8');
+    const raw = require('fs').readFileSync(shipPrefsPath(), 'utf8');
     const parsed = JSON.parse(raw);
     const ev = parsed && parsed.event_sounds && parsed.event_sounds['task-shipped'];
     if (typeof ev === 'string') shipWav = ev;
@@ -23,6 +22,20 @@ function playShipBell() {
   playSound(shipWav);
 }
 
+// task 1003272: this used to hardcode ~/.config/otb/, the PRE-RENAME location,
+// while fetch-sound-prefs.js writes the mirror through
+// instance-config.configPath() — today ~/.config/cloudbongos/. Reader and writer
+// were looking at different files, so a builder's chosen ship sound was never
+// found and this always fell through to the 'ship' default. Resolve the SAME way
+// the writer does, with the legacy path as a fallback for an older box.
+function shipPrefsPath() {
+  try {
+    const p = require('../../src/instance-config').configPath('sound-prefs.json');
+    if (require('fs').existsSync(p)) return p;
+  } catch (_) { /* fall through to the legacy location */ }
+  return require('path').join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
+}
+
 // task 1002809: normalize an API error body across BOTH wire shapes — the live
 // ADR 0116 (R01) envelope `{ error: { code, message } }` and the legacy flat
 // `{ error: 'code' }`. Same normalization as claim.js:formatClaimFailure and
@@ -93,6 +106,7 @@ function postLandShipOutcome({ code, liveStatus }) {
 // the early returns are control flow only.
 
 module.exports = {
+  shipPrefsPath,
   apiErrorLine,
   normalizeApiError,
   playShipBell,

package/scripts/gds/turn-end-sound.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// scripts/gds/turn-end-sound.js — the Stop hook that rings when a turn ends
+// (task 1003272).
+//
+// THE TRIGGER THAT NEVER EXISTED. scripts/gds/fetch-sound-prefs.js has always
+// described "a LOCAL Stop hook + ship.js via .claude/sounds/play.js", and
+// sound-prefs.js has always labelled `chime` as "When Claude finishes a turn" —
+// but .claude/settings.json had no Stop hook at all. So the single most
+// noticeable sound in the system had nothing to fire it, on top of the player
+// being absent and four of the five WAVs never having been committed. Three
+// independent gaps, one symptom: "all sound seems bugged".
+//
+// WHY A SCRIPT RATHER THAN AN INLINE HOOK COMMAND. The variant resolution below
+// is the same logic ship-io.js's playShipBell() already uses (read the mirrored
+// prefs, take the event's chosen wav, fall back to a base sound). That is a
+// couple of lines too many for a JSON string, and a hook that cannot be read is
+// a hook nobody will fix.
+//
+// IT MUST ALWAYS EXIT 0 AND FAST. This runs at the end of every turn. It resolves
+// a name, hands it to a fire-and-forget player that spawns detached, and returns;
+// every failure path is a silent no-op. A Stop hook that threw, or that blocked
+// on audio, would make a cosmetic feature everyone's problem.
+
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// `user-input` is the event whose meaning matches a turn ending — Claude has
+// paused and it is the builder's move. Falls back to `chime`, which is the base
+// sound sound-prefs.js labels "When Claude finishes a turn".
+const EVENT_ID = 'user-input';
+const FALLBACK_WAV = 'chime';
+
+// Resolve the mirror the SAME way fetch-sound-prefs.js writes it
+// (instance-config.configPath — today ~/.config/cloudbongos/), with the
+// pre-rename ~/.config/otb/ as a fallback for an older box. Hardcoding the
+// legacy path is the bug this task found in two other readers; it is not going
+// to be re-introduced here.
+function prefsPath() {
+  try {
+    const p = require('../../src/instance-config').configPath('sound-prefs.json');
+    if (fs.existsSync(p)) return p;
+  } catch (_) { /* fall through */ }
+  return path.join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
+}
+
+function resolveWav() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(prefsPath(), 'utf8'));
+    const chosen = parsed && parsed.event_sounds && parsed.event_sounds[EVENT_ID];
+    if (typeof chosen === 'string' && chosen) return chosen;
+  } catch (_) { /* no mirror yet — the fallback is the honest default */ }
+  return FALLBACK_WAV;
+}
+
+function main() {
+  try {
+    // Guarded exactly like ship-state.js's: on a checkout without the player
+    // (or mid-re-seed) this is a no-op, never a failed turn.
+    let playSound;
+    try {
+      ({ playSound } = require(path.resolve(__dirname, '..', '..', '.claude', 'sounds', 'play.js')));
+    } catch (_) { return; }
+    if (typeof playSound === 'function') playSound(resolveWav());
+  } catch (_) { /* cosmetic, always */ }
+}
+
+if (require.main === module) {
+  main();
+  process.exit(0); // never let a stray handle hold the turn open
+}
+module.exports = { resolveWav, prefsPath, EVENT_ID, FALLBACK_WAV };

package/src/bongos/route-rank-check.js

@@ -370,6 +370,17 @@ const MODULE_EXPECTED_RANKS = {
     // authorizeGoalManagement) corrects its own title/description — same shape
     // and same gate as the visibility route above.
     'PATCH /goals/:id': 'any-builder',
+    // task 1003275 (goal 1000072, legibility-categories): the ADVISORY human
+    // category. The set is a VOCABULARY, so reading it is any-builder — a client
+    // that cannot read it hard-codes the labels. Creating one is a planning act,
+    // pinned to the same permission as authoring a goal. Setting a goal's category
+    // rides the same owner|manager|Archon in-handler gate as the prose edit above.
+    // These pins are also the tripwire for the rule that outranks the feature: a
+    // category must never GATE anything, so if one of these ever needs a WIDER
+    // gate than its neighbours, the label has grown into a permission.
+    'GET /work-categories': 'any-builder',
+    'POST /work-categories': 'perm:goal.create',
+    'PATCH /goals/:id/category': 'any-builder',
     'POST /goals/:id/requests': 'any-builder',
     'POST /goals/:id/requests/:reqId/respond': 'any-builder',
     'POST /goals/:id/invitations': 'any-builder',

package/src/module-api.js

@@ -1160,8 +1160,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.363 with no explicit bump. run 32890225073. (task 1002620)
 //   1.19.365 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.364 with no explicit bump. run 32893443215. (task 1002620)
+//   1.19.366 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.365 with no explicit bump. run 32895705036. (task 1002620)
+//   1.19.367 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.366 with no explicit bump. run 32902059088. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.365'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.367'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/category_advisory_guard.mjs

@@ -0,0 +1,135 @@
+// tests/category_advisory_guard.mjs — the guard that keeps a work CATEGORY from
+// becoming a permission (task 1003275, goal 1000072, criterion legibility-categories).
+//
+// The whole point of that criterion's load-bearing constraint is that the failure
+// arrives as ONE plausible line inside a gate, not as a decision anyone announces.
+// So the guard has to be tested on synthetic sources: a scan that passes because
+// today's tree happens to be clean proves nothing about what it would REFUSE
+// tomorrow (the client_baseurl_guard.mjs precedent).
+//
+// Run:  node tests/category_advisory_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { checkCategoryIsAdvisory, scanGates, scanAnchors, GATE_FILES, FEATURE_ANCHORS, stripComments } =
+  require('../scripts/gds/category-advisory-guard.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const from = (map) => (rel) => (rel in map ? map[rel] : null);
+
+// --- THE FAILURE THE GUARD EXISTS FOR --------------------------------------
+
+test('a claimable feed that hides a category is refused', () => {
+  const { violations } = scanGates(['modules/lifecycle/claim-feed.js'], from({
+    'modules/lifecycle/claim-feed.js':
+      "const rows = await pool.query('SELECT * FROM tasks');\n"
+      + "return rows.filter((t) => t.category_id !== LEGAL_CATEGORY);\n",
+  }));
+  assert.equal(violations.length, 1);
+  assert.match(violations[0], /claim-feed\.js:2/);
+  assert.match(violations[0], /ADVISORY/, 'the message states the rule');
+  assert.match(violations[0], /ADR 0086/, 'and points at the hierarchy that DOES enforce');
+  assert.match(violations[0], /owner decision/, 'and names the only legitimate way to change it');
+});
+
+test('an authorisation branch on a category is refused', () => {
+  const { violations } = scanGates(['modules/lifecycle/goal-authz.js'], from({
+    'modules/lifecycle/goal-authz.js':
+      'function authorizeGoalManagement({ goal, actorRank }) {\n'
+      + "  if (goal.category === 'security' && actorRank !== 'archon') return { ok: false };\n"
+      + '  return { ok: true };\n}\n',
+  }));
+  assert.equal(violations.length, 1);
+  assert.match(violations[0], /goal-authz\.js:2/);
+});
+
+test('the plural, the past tense and the raw table name are all caught', () => {
+  for (const line of [
+    'const c = row.categories;',
+    'if (!goal.categorised) return refuse();',
+    "await pool.query('SELECT slug FROM work_categories');",
+  ]) {
+    const { violations } = scanGates(['scripts/gds/gating.js'], from({ 'scripts/gds/gating.js': `${line}\n` }));
+    assert.equal(violations.length, 1, `not caught: ${line}`);
+  }
+});
+
+// --- WHAT IT MUST NOT REFUSE ----------------------------------------------
+
+test('a gate may CITE the rule in a comment', () => {
+  const { violations } = scanGates(['modules/lifecycle/claim-eligibility.js'], from({
+    'modules/lifecycle/claim-eligibility.js':
+      '// A work category is advisory and is deliberately NOT read here (task 1003275).\n'
+      + '/* Not even the category set — see ADR 0192. */\n'
+      + 'return { ok: true };\n',
+  }));
+  assert.deepEqual(violations, [], 'citing the rule is the whole reason comments are stripped');
+});
+
+test('a gate that reads scope, rank or membership is untouched', () => {
+  const { violations } = scanGates(['src/bongos/goal-scope-check.js'], from({
+    'src/bongos/goal-scope-check.js':
+      "if (scopeIncludesProtected(goal.scope_modules) && rank !== 'archon') return refuse();\n",
+  }));
+  assert.deepEqual(violations, []);
+});
+
+test('a word that merely CONTAINS the letters is not a category', () => {
+  const { violations } = scanGates(['src/bongos/auth.js'], from({
+    'src/bongos/auth.js': 'const c = categorizeNothing;\nconst d = subcategory_id_like;\n',
+  }));
+  assert.deepEqual(violations, [], 'the word boundary matters — `categorize` alone is not `category`');
+});
+
+// --- THE GUARD MUST NOT BE ABLE TO PASS VACUOUSLY -------------------------
+
+test('a renamed-away feature fails the guard instead of passing it silently', () => {
+  const violations = scanAnchors(
+    [{ file: 'modules/lifecycle/goal-category.js', needle: 'decorateGoalCategory' }],
+    from({ 'modules/lifecycle/goal-category.js': '// gutted\n' })
+  );
+  assert.equal(violations.length, 1);
+  assert.match(violations[0], /vacuous/, 'it says WHY a green tick here would be a lie');
+});
+
+test('a deleted feature file fails the guard', () => {
+  const violations = scanAnchors(FEATURE_ANCHORS.slice(0, 1), from({}));
+  assert.equal(violations.length, 1);
+});
+
+// --- A DRIFTED LIST WARNS, IT DOES NOT PASS -------------------------------
+
+test('a gate file that has moved warns rather than silently shrinking the scan', () => {
+  const { violations, warnings, scanned } = scanGates(['modules/lifecycle/gone.js'], from({}));
+  assert.deepEqual(violations, []);
+  assert.equal(scanned, 0);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /drifted/);
+});
+
+// --- COMMENT STRIPPING KEEPS TEXT WHEN UNSURE ----------------------------
+
+test('stripComments errs toward KEEPING text (a guard should fail loud, not quiet)', () => {
+  assert.match(stripComments("const url = 'http://x/category';\n"), /category/,
+    'a `//` inside a string must not be able to hide a real read from the scan');
+});
+
+// --- THE LIVE TREE -------------------------------------------------------
+
+test('the live tree passes, and the gate list is not empty', () => {
+  assert.ok(GATE_FILES.length >= 10, 'a decision-surface list this short would not be covering the gates');
+  const r = checkCategoryIsAdvisory();
+  assert.deepEqual(r.violations, [], r.violations.join('\n'));
+  assert.equal(r.hardFail, false);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/goal_category.mjs

@@ -0,0 +1,199 @@
+// tests/goal_category.mjs — the human CATEGORY on a goal, and the rule that
+// outranks it (task 1003275, goal 1000072, criterion legibility-categories).
+//
+// Two things are pinned here, and the second matters more than the first.
+//
+// 1. The feature works: the set is readable, a category can be created at the
+//    moment Claude could not place a goal, a goal can be labelled and unlabelled,
+//    and a board of goals costs ONE category query rather than a join per goal.
+//
+// 2. UNCATEGORISED IS LEGAL. The criterion is explicit that Claude failing to
+//    place a goal is "a designed prompt, not an error". The moment a missing
+//    category can refuse a write, the label has become a gate — which is the exact
+//    failure the goal's own prose predicts ("a second thing that LOOKS like a
+//    hierarchy will be mistaken for one within a release"). The
+//    scripts/gds/category-advisory-guard.js check covers the gates; these cover
+//    the write paths.
+//
+// Run:  node --test tests/goal_category.mjs   (or: node tests/goal_category.mjs)
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const gc = require(path.join(ROOT, 'modules', 'lifecycle', 'goal-category.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const fakeRes = () => ({
+  code: null, statusCode: null, payload: null,
+  fail(code, status, extra) { this.code = code; this.statusCode = typeof status === 'number' ? status : status?.status ?? 400; this.payload = { error: code, ...(extra || {}) }; return this; },
+  status(c) { this.statusCode = c; return this; },
+  json(p) { this.payload = p; return this; },
+});
+
+// ---- slugs -----------------------------------------------------------------
+
+test('a label a human types reduces to a usable slug', () => {
+  assert.equal(gc.slugify('Government (Decision Making)'), 'government-decision-making');
+  assert.equal(gc.slugify('User/ABI Experience'), 'user-abi-experience');
+  assert.equal(gc.slugify('  Developer   Relations  '), 'developer-relations');
+});
+
+test('a slug that could break a client filter is refused, not silently mangled', () => {
+  assert.equal(gc.isValidSlug('security'), true);
+  assert.equal(gc.isValidSlug('user-experience'), true);
+  assert.equal(gc.isValidSlug('a'), false, 'one char is not a key');
+  assert.equal(gc.isValidSlug('-legal'), false);
+  assert.equal(gc.isValidSlug('legal-'), false);
+  assert.equal(gc.isValidSlug('a--b'), false);
+  assert.equal(gc.isValidSlug('Legal'), false, 'case matters — two spellings of one category is not a set');
+});
+
+test('a label of pure punctuation yields no slug, and the route says so', async () => {
+  // slugify('***') is '' — isValidSlug rejects it, so the caller gets a message
+  // telling them to send an explicit slug rather than a mystery 400.
+  const handler = gc.categoryCreateHandler({ create: async () => { throw new Error('must not reach the DB'); }, validateOrRespond: () => false, LIMITS: { TITLE: 200 } });
+  const res = fakeRes();
+  await handler({ body: { label: '***' }, builder: { id: 1 } }, res);
+  assert.equal(res.code, 'bad_slug');
+  assert.match(res.payload.message, /send a `slug` explicitly/i);
+});
+
+// ---- creating one at the moment Claude could not place a goal ---------------
+
+test('creating a category returns 201 and attributes it to the human who made it', async () => {
+  let seen = null;
+  const handler = gc.categoryCreateHandler({
+    create: async (args) => { seen = args; return { id: 9, slug: args.slug, label: args.label, created: true }; },
+    validateOrRespond: () => false, LIMITS: { TITLE: 200 },
+  });
+  const res = fakeRes();
+  await handler({ body: { label: 'Developer Relations' }, builder: { id: 42 } }, res);
+  assert.equal(res.statusCode, 201);
+  assert.equal(res.payload.created, true);
+  assert.deepEqual(seen, { slug: 'developer-relations', label: 'Developer Relations', createdBy: 42 });
+  assert.equal('created' in res.payload.category, false, 'the internal created flag does not leak onto the row');
+});
+
+test('a duplicate converges on the existing category instead of stranding a goal', async () => {
+  // Two people prompted to create "Developer Relations" in the same hour must end
+  // up with ONE category. A 409 here would leave whichever lost the race with no
+  // label and no obvious next step — the opposite of a designed prompt.
+  const handler = gc.categoryCreateHandler({
+    create: async ({ slug }) => ({ id: 9, slug, label: 'Developer Relations', created: false }),
+    validateOrRespond: () => false, LIMITS: { TITLE: 200 },
+  });
+  const res = fakeRes();
+  await handler({ body: { label: 'developer relations' }, builder: { id: 7 } }, res);
+  assert.equal(res.statusCode, 200, 'not a 201, and not an error');
+  assert.equal(res.payload.created, false);
+  assert.equal(res.payload.category.id, 9);
+});
+
+// ---- labelling a goal ------------------------------------------------------
+
+const setDeps = {
+  db: { getGoal: async () => ({ id: 7, status: 'open', created_by: 1 }), getGoalMember: async () => null },
+  authorizeGoalManagement: () => ({ ok: true }),
+  validateOrRespond: () => false,
+  parseId: () => 7,
+  index: async () => new Map(),
+};
+
+test('setting a goal\'s category rides the SAME gate as editing its prose', async () => {
+  // Not a wider gate and not a narrower one: a label must never change who may
+  // write to a goal. Pinning the refusal is how a future widening gets noticed.
+  let asked = null;
+  const handler = gc.goalCategoryHandler({
+    ...setDeps,
+    authorizeGoalManagement: (args) => { asked = args; return { ok: false, status: 403, body: { error: 'not_yours' } }; },
+    set: async () => { throw new Error('must not write when refused'); },
+    read: async () => ({ id: 3 }),
+  });
+  const res = fakeRes();
+  await handler({ params: { id: '7' }, body: { category_id: 3 }, builder: { id: 99, rank: 'thetes' } }, res);
+  assert.equal(res.statusCode, 403);
+  assert.equal(asked.actorId, 99, 'the same authorizeGoalManagement decision the prose edit uses');
+});
+
+test('clearing a category is an explicit null, not an omission', async () => {
+  let wrote;
+  const handler = gc.goalCategoryHandler({ ...setDeps, set: async (a) => { wrote = a; return { id: 7, category_id: null }; }, read: async () => ({ id: 1 }) });
+  const res = fakeRes();
+  await handler({ params: { id: '7' }, body: { category_id: null }, builder: { id: 1, rank: 'archon' } }, res);
+  assert.equal(res.code, null, `must not fail — got ${res.code}`);
+  assert.deepEqual(wrote, { goalId: 7, categoryId: null });
+});
+
+test('an omitted category_id is a 400 that says what to send', async () => {
+  const handler = gc.goalCategoryHandler({ ...setDeps, set: async () => { throw new Error('must not write'); } });
+  const res = fakeRes();
+  await handler({ params: { id: '7' }, body: {}, builder: { id: 1, rank: 'archon' } }, res);
+  assert.equal(res.code, 'category_id_required');
+  assert.match(res.payload.message, /category_id: null/, 'the message shows how to clear it too');
+});
+
+test('an unknown category is a 404, not a silently-created one', async () => {
+  const handler = gc.goalCategoryHandler({ ...setDeps, read: async () => null, set: async () => { throw new Error('must not write'); } });
+  const res = fakeRes();
+  await handler({ params: { id: '7' }, body: { category_id: 4242 }, builder: { id: 1, rank: 'archon' } }, res);
+  assert.equal(res.code, 'category_not_found');
+  assert.equal(res.statusCode, 404);
+});
+
+// ---- decoration ------------------------------------------------------------
+
+test('a goal carries a readable category, and an uncategorised one carries null', () => {
+  const byId = new Map([['3', { id: 3, slug: 'security', label: 'Security' }]]);
+  assert.deepEqual(gc.decorateGoalCategory({ id: 1, category_id: 3 }, byId).category,
+    { id: '3', slug: 'security', label: 'Security' });
+  assert.equal(gc.decorateGoalCategory({ id: 2, category_id: null }, byId).category, null,
+    'uncategorised reads as null — a prompt, never an omission the client has to guess at');
+});
+
+test('a goal carrying a RETIRED category still renders its label', () => {
+  // Retiring is `active = false`, never a DELETE, and categoryIndex reads inactive
+  // rows for exactly this reason: a goal must not silently become uncategorised
+  // because someone tidied the set.
+  const byId = new Map([['5', { id: 5, slug: 'legal', label: 'Legal', active: false }]]);
+  assert.equal(gc.decorateGoalCategory({ id: 1, category_id: 5 }, byId).category.label, 'Legal');
+});
+
+test('decoration never mutates the goal it was handed', () => {
+  const goal = { id: 1, category_id: 3 };
+  gc.decorateGoalCategory(goal, new Map());
+  assert.equal('category' in goal, false);
+});
+
+// ---- the rule that outranks the feature ------------------------------------
+
+test('a task has no category column — inheritance is literal', () => {
+  const migration = read('migrations', 'core_226_work_categories.sql');
+  assert.match(migration, /ALTER TABLE goals/);
+  assert.equal(/ALTER TABLE tasks/.test(migration), false,
+    'a task INHERITS its goal\'s category (criterion wording). A stored copy would be a second answer to one question.');
+});
+
+test('the category is nullable with no default, so uncategorised stays a legal state', () => {
+  const migration = read('migrations', 'core_226_work_categories.sql');
+  assert.match(migration, /ADD COLUMN IF NOT EXISTS category_id bigint REFERENCES work_categories\(id\)/);
+  assert.equal(/category_id[^\n]*NOT NULL/.test(migration), false, 'NOT NULL would turn the designed prompt into a refused write');
+});
+
+test('the eight defaults the owner named all ship', () => {
+  const migration = read('migrations', 'core_226_work_categories.sql');
+  for (const label of ['Builders Hall', 'Context Management', 'Government (Decision Making)',
+    'Modules', 'Security', 'Economics', 'Legal', 'User/ABI Experience']) {
+    assert.ok(migration.includes(label), `missing default category: ${label}`);
+  }
+});
+
+test('POST /goals accepts a category but never requires one', () => {
+  const routes = read('modules', 'lifecycle', 'routes', 'goals.js');
+  assert.match(routes, /category_id: \{ type: 'integer', min: 1 \}/, 'accepted on create');
+  assert.equal(/category_id: \{ required: true/.test(routes), false, 'never required — that would make the prompt a refusal');
+});