@bongos/core 1.19.366 → 1.19.368

package/scripts/gds/category-advisory-guard.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// scripts/gds/category-advisory-guard.js — the fitness check that keeps a work
+// CATEGORY advisory (task 1003275, goal 1000072, criterion legibility-categories;
+// ADR 0192).
+//
+// WHY A CHECK AND NOT A COMMENT. The owner said it twice about this organisation:
+// it "has no hierarchical purpose", and these categories have "no effect on the
+// creation and agentic management of these elements". The risk is specific and
+// named in the goal's own prose: the system ALREADY has a real hierarchy
+// (Project → Version → Goal → Criteria → Task, ADR 0086) with real enforcement —
+// the scope_modules wall, per-task rank floors, goal membership — so a SECOND
+// thing that looks like a hierarchy "will be mistaken for one within a release".
+// The mistake does not arrive as a decision; it arrives as one plausible line in
+// a gate ("skip Legal goals in the feed"), and from then on work is refused
+// because of a label nobody meant as a permission. A comment cannot refuse that
+// line. This check can.
+//
+// WHAT IT ENFORCES, in two halves:
+//   1. NO GATE READS A CATEGORY. Every file that decides authority, claim
+//      eligibility, feed membership or dependency satisfaction is scanned with
+//      comments stripped; any surviving mention of a category is a hard failure.
+//      Comments are stripped rather than flagged so a gate may CITE this rule (the
+//      checkVocabularyWall precedent) — what it may not do is branch on it.
+//   2. THE FEATURE STILL EXISTS. A guard whose subject was renamed away passes
+//      silently and reads as proof (the ADR 0022 assurance-of-assurance finding
+//      that produced control-manifest.js). So the check also asserts the category
+//      surface is present; if the feature is gone, the guard must fail loudly
+//      rather than congratulate an empty repo.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Every file that DECIDES something: who may act, what may be claimed, what the
+// feed offers, when a dependency is satisfied. A category may not appear in any
+// of them. Add to this list when a new decision surface lands — that is the
+// maintenance cost, and it is the point.
+const GATE_FILES = [
+  'src/bongos/auth.js',
+  'src/bongos/auth-admission.js',
+  'src/bongos/permission-path-check.js',
+  'src/bongos/goal-scope-check.js',
+  'src/bongos/module-scope-map.js',
+  'src/bongos/stealth-gate.js',
+  'modules/lifecycle/claim-eligibility.js',
+  'modules/lifecycle/claim-feed.js',
+  'modules/lifecycle/goal-authz.js',
+  'modules/lifecycle/routes/goal-route-authz.js',
+  'modules/lifecycle/db-rank-authz.js',
+  'modules/lifecycle/db-deps-criteria.js',
+  'scripts/gds/gating.js',
+];
+
+// DELIBERATELY NOT a gate: src/bongos/route-rank-check.js. It is the pin TABLE
+// the rank fitness check reads, so it names every route including the category
+// ones by design, and it decides nothing at runtime. Scanning it would force the
+// pins out of the registry that exists to hold them.
+
+// The category surface half 2 asserts still exists. Path + a token that must
+// appear in it, so a rename or a gutting is caught rather than a bare `existsSync`.
+const FEATURE_ANCHORS = [
+  { file: 'migrations/core_226_work_categories.sql', needle: 'CREATE TABLE IF NOT EXISTS work_categories' },
+  { file: 'modules/lifecycle/goal-category.js', needle: 'decorateGoalCategory' },
+  { file: 'modules/lifecycle/routes/goals.js', needle: "router.patch('/goals/:id/category'" },
+];
+
+// Word-bounded on purpose: `subcategory_id` in some unrelated module is not this
+// feature, and a guard that cries wolf gets suppressed rather than obeyed. The
+// table name needs no boundary — nothing else is called that.
+const CATEGORY_RE = /\bcategor(y|ies|ised|ized|isation|ization)\b|\bcategory_id\b|work_categories/i;
+
+// Strip // line comments and /* */ blocks so a citation of the rule is legal and
+// only executable text is judged. Crude on purpose: it errs toward keeping text
+// (a `//` inside a string literal turns the rest of that line into a "comment"),
+// and erring toward keeping text would make the check LOUDER, not quieter — which
+// is the safe direction for a guard.
+function stripComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+function readFromDisk(rel) {
+  try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; }
+}
+
+// The scan, with its file list and its reader INJECTED. A guard tested only
+// against the live tree proves nothing about what it would refuse — the tree is
+// clean today by construction. `read(rel)` returns the source or null.
+function scanGates(files, read) {
+  const violations = [];
+  const warnings = [];
+  let scanned = 0;
+
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) {
+      // A missing gate file is a warning, not a pass: the list has drifted from
+      // the repo and someone must re-point it.
+      warnings.push(`${rel} not found — the GATE_FILES list in scripts/gds/category-advisory-guard.js has drifted; re-point it at the file that replaced it.`);
+      continue;
+    }
+    scanned += 1;
+    const code = stripComments(src);
+    const hits = code.split('\n')
+      .map((line, i) => ({ line: line.trim(), n: i + 1 }))
+      .filter(({ line }) => CATEGORY_RE.test(line));
+    for (const { line, n } of hits) {
+      violations.push(
+        `${rel}:${n} reads a work CATEGORY inside a decision surface — \`${line.slice(0, 100)}\`. `
+        + 'A category is ADVISORY: it orients a human and steers Claude, and authorises nothing (task 1003275, ADR 0192). '
+        + 'The real hierarchy with real enforcement is ADR 0086 — gate on scope_modules, rank, membership or dependencies instead. '
+        + 'If this label genuinely must gate something, that is an owner decision and needs its own ADR before this check is relaxed.'
+      );
+    }
+  }
+
+  return { violations, warnings, scanned };
+}
+
+// Half 2: the feature this guard constrains must still be there, or the guard is
+// vacuous and its green tick is a lie (the ADR 0022 assurance-of-assurance finding).
+function scanAnchors(anchors, read) {
+  const violations = [];
+  for (const { file, needle } of anchors) {
+    const src = read(file);
+    if (src == null || !src.includes(needle)) {
+      violations.push(
+        `${file} no longer carries \`${needle}\` — the category feature this guard exists to constrain has moved or been removed, so the guard is now vacuous and would pass an empty repo. `
+        + 'Re-point FEATURE_ANCHORS in scripts/gds/category-advisory-guard.js, or delete the guard along with the feature.'
+      );
+    }
+  }
+
+  return violations;
+}
+
+function checkCategoryIsAdvisory({ files = GATE_FILES, anchors = FEATURE_ANCHORS, read = readFromDisk } = {}) {
+  const { violations: gateViolations, warnings, scanned } = scanGates(files, read);
+  const violations = gateViolations.concat(scanAnchors(anchors, read));
+  return {
+    name: 'a work category is ADVISORY — no gate reads it (task 1003275 / ADR 0192)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${scanned} decision surface(s) scanned (authority, claim eligibility, claimable feed, dependency satisfaction) with comments stripped — a gate may CITE this rule, never branch on it. Plus ${anchors.length} feature anchor(s), so a renamed-away feature fails loudly instead of passing vacuously.`,
+  };
+}
+
+module.exports = { checkCategoryIsAdvisory, scanGates, scanAnchors, GATE_FILES, FEATURE_ANCHORS, stripComments };

package/scripts/gds/fitness.js

@@ -1307,7 +1307,12 @@ const CHECKS = [
   require('./control-manifest.js').checkControlsExist, // Check 21 — task 1003131: goal-1000076 controls assert their own existence (the ADR 0022 assurance-of-assurance)
   require('./routine-schedule.js').checkRoutineCadencesScheduled, // Check 25 — task 1003209: a routine that declares a cadence must have a scheduler firing it AT that period (ADR 0188)
   require('./baseline-staleness.js').checkBaselineFloors, // Check 26 — task 1003210: a shrink-only baseline that never shrinks is unmanaged debt; a floor exempting one must say why
-  require('./client-baseurl-guard.js').checkClientBaseUrl, // Check 27 — task 1003263: a page must not combine baseUrl:'' with a generated namespaced call (that pairing 404s every request; three pages shipped it, two of them dead in prod)
+  require('./client-baseurl-guard.js').checkClientBaseUrl,
+  // Check 29 — task 1003275 / ADR 0189: a work category ORIENTS a human and steers
+  // Claude; it authorises nothing. The owner said so twice, and the goal's own prose
+  // predicts the failure: a second thing that looks like a hierarchy gets mistaken
+  // for one within a release. A comment cannot refuse the line that does it.
+  require('./category-advisory-guard.js').checkCategoryIsAdvisory, // Check 27 — task 1003263: a page must not combine baseUrl:'' with a generated namespaced call (that pairing 404s every request; three pages shipped it, two of them dead in prod)
   // Check 28 — task 1001654 / ADR 0095: does each source file open with a module
   // header saying what it does and why. ADVISORY ONLY (never hardFail) — a
   // doc-comment gate that blocks a ship buys filler prose, not understanding.

package/scripts/gds/redteam-patrol.js

@@ -134,6 +134,43 @@ function lockedVersion(lock, name) {
   return entry && entry.version;
 }
 
+// Pure: what to say about ONE `overrides` entry. Extracted so the rule is a table
+// a test can enumerate — the networked half (npm view) stays outside.
+//
+// THE BUG THIS REPLACES (task 1003283, report 1000025). The old rule compared the
+// pinned MAJOR against `dist-tags.latest` and filed a medium whenever latest was
+// higher. That flags every override which deliberately holds a major line — which
+// is the normal reason an override exists at all. It fired on `undici ^6.28.0`
+// "while latest is 8.10.0", when 6.28.0 is the newest 6.x, `discord.js` (the only
+// consumer) requires the 6.x line, and `npm audit` finds nothing. Acting on it
+// would have BROKEN the dependent; ignoring it weekly is the alert-fatigue failure
+// ADR 0188 §2.4 exists to prevent — here inside the patrol itself.
+//
+// The real signal is narrower: a pin whose LOCKED version has fallen behind what
+// its own range already allows. That is rot nobody chose. Trailing the latest
+// major is reported as a NOTE instead, because only a human can say whether a
+// dependent still constrains the line.
+//
+// `satisfying` is every published version matching `range`, ASCENDING (npm's own
+// order), so the newest in-range version is simply the last element — no semver
+// comparator needed, and no dependency added to do it.
+function overrideVerdict({ name, range, locked, satisfying = [], latest = null } = {}) {
+  const newestInRange = satisfying.length ? satisfying[satisfying.length - 1] : null;
+  if (newestInRange && locked && newestInRange !== locked && satisfying.includes(locked)) {
+    return {
+      finding: { severity: 'medium', item: `stale override: ${name} is locked at ${locked} but its own pin "${range}" already allows ${newestInRange} — refresh the lockfile` },
+    };
+  }
+  const pinnedMajor = parseInt(String(range).replace(/^[^0-9]*/, ''), 10);
+  const latestMajor = parseInt(String(latest), 10);
+  if (Number.isFinite(pinnedMajor) && Number.isFinite(latestMajor) && latestMajor > pinnedMajor) {
+    return {
+      note: `override ${name} "${range}" trails the latest major (${latest}) — expected when a dependent requires that line; verify before lifting, do NOT bump blind`,
+    };
+  }
+  return {};
+}
+
 function dependencyReview() {
   const findings = [];
   const notes = [];
@@ -175,16 +212,19 @@ function dependencyReview() {
     }
   }
 
-  // 2c — override staleness (the undici lesson: a pin nobody watches rots).
+  // 2c — override staleness (the undici lesson: a pin nobody watches rots) —
+  // measured INSIDE the pinned range, see overrideVerdict above.
   for (const [name, range] of Object.entries(pkg.overrides || {})) {
     if (typeof range !== 'string') continue;
     const latest = npmViewJson(`${name} dist-tags.latest`);
-    if (!latest) continue;
-    const pinnedMajor = parseInt(String(range).replace(/^[^0-9]*/, ''), 10);
-    const latestMajor = parseInt(String(latest), 10);
-    if (Number.isFinite(pinnedMajor) && Number.isFinite(latestMajor) && latestMajor > pinnedMajor) {
-      findings.push({ severity: 'medium', item: `stale override: ${name} pinned "${range}" while latest is ${latest} — re-justify or lift the pin` });
-    }
+    // Every published version matching the range, ascending. npm returns a bare
+    // string when exactly one matches, so normalise to an array.
+    const matched = npmViewJson(`"${name}@${range}" version`);
+    const satisfying = matched == null ? [] : (Array.isArray(matched) ? matched : [matched]);
+    if (!latest && !satisfying.length) { notes.push(`npm view failed for override ${name} — staleness check skipped`); continue; }
+    const v = overrideVerdict({ name, range, locked: lockedVersion(lock, name), satisfying, latest });
+    if (v.finding) findings.push(v.finding);
+    if (v.note) notes.push(v.note);
   }
   return { findings, notes };
 }
@@ -393,5 +433,5 @@ if (require.main === module) {
 module.exports = {
   parseGitleaksReport, unpinnedUses, ageDays, mapSeverity, maxSeverity,
   buildClassReport, lockedVersion, COOLDOWN_DAYS, YOUNG_PKG_DAYS,
-  stepSummary, filingBlocker, disposition,
+  stepSummary, filingBlocker, disposition, overrideVerdict,
 };

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

@@ -1162,8 +1162,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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)
+//   1.19.368 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.367 with no explicit bump. run 32902864988. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.366'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.368'; // 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');
+});

package/tests/goal_tier.mjs

@@ -66,9 +66,11 @@ await test('createGoal: INSERT binds all six fields in order and returns the row
   assert.deepEqual(out, GOAL_ROW, 'returns the inserted row');
   const ins = find(pool.queries, /INSERT INTO goals/);
   // task 1003224 appended `subtitle` as $7 rather than inserting it next to
-  // title, so $1–$6 keep the positions this test has always pinned.
-  assert.deepEqual(ins.params, ['BONGOS-V1', 'Goal hierarchy', 'desc', ['gds-core'], 'open', 42, null],
-    'version_id, title, description, scope_modules, status, created_by, then subtitle — in that order');
+  // title, and task 1003275 appended `category_id` as $8 the same way, so $1–$6
+  // keep the positions this test has always pinned. New goal fields go on the
+  // END of the bind list for exactly this reason.
+  assert.deepEqual(ins.params, ['BONGOS-V1', 'Goal hierarchy', 'desc', ['gds-core'], 'open', 42, null, null],
+    'version_id, title, description, scope_modules, status, created_by, then subtitle, then category_id — in that order');
   assert.match(ins.sql, /RETURNING/, 'returns the row, not just inserts');
 });
 
@@ -89,8 +91,8 @@ await test('createGoal: defaults — null description/createdBy, empty scope, op
   const pool = fakePool((s) => (/INSERT INTO goals/.test(s) ? { rows: [GOAL_ROW] } : null));
   await createGoal({ versionId: 'V1', title: 'general' }, { pool });
   const ins = find(pool.queries, /INSERT INTO goals/);
-  assert.deepEqual(ins.params, ['V1', 'general', null, [], 'open', null, null],
-    'unspecified fields fall back to null / [] / open — subtitle ($7) defaults to null too');
+  assert.deepEqual(ins.params, ['V1', 'general', null, [], 'open', null, null, null],
+    'unspecified fields fall back to null / [] / open — subtitle ($7) and category_id ($8) default to null too');
 });
 
 // =========================================================================