@bongos/core 1.19.365 → 1.19.367

package/modules/lifecycle/goal-category.js

@@ -0,0 +1,273 @@
+'use strict';
+
+// modules/lifecycle/goal-category.js — the human CATEGORY on a goal, and the
+// project's category SET (task 1003275, goal 1000072, criterion
+// legibility-categories).
+//
+// WHY THIS EXISTS. A person scanning the goal board cannot tell at a glance which
+// goals are about money, which are about the walls, and which are about the hall.
+// Each goal's own words say so, but only if you read all 38 of them. A category is
+// the one word that answers it. The owner named the set; migration
+// core_226_work_categories seeds it and holds the schema reasoning.
+//
+// THE RULE THAT OUTRANKS THE FEATURE — A CATEGORY IS ADVISORY AND MUST STAY THAT
+// WAY. It orients a human and steers Claude; it authorises NOTHING. No claim gate,
+// no route guard, no rank check, no claimable-feed filter and no dependency rule
+// may read it. The reason is not tidiness: 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 — and a second
+// thing that LOOKS like a hierarchy gets mistaken for one, after which work is
+// refused because of a label nobody meant as a permission. Enforced by
+// `scripts/gds/category-advisory-guard.js` (a fitness check), because a comment is
+// not a guardrail. See ADR 0192.
+//
+// Two consequences that look like bugs and are not:
+//   - Uncategorised is LEGAL. A goal with no category is a prompt to a human, never
+//     a rejected write. The criterion is explicit: "where it cannot, the human is
+//     prompted to create a new category — that failure is a designed prompt, not
+//     an error."
+//   - A task has no category column. It INHERITS its goal's through tasks.goal_id.
+//     Storing a copy would create two answers to one question.
+//
+// Lives here rather than in routes/goals.js or db-goals.js because both are over
+// the fitness oversize threshold and the ratchet is shrink-only — the
+// goal-edits.js / goal-authz.js precedent (a cohesive slice with its own SQL and
+// its handlers as factories, so a test can drive them without a database).
+
+const api = require('../../src/module-api');
+const { pool } = api;
+
+// Shared column list so every category read/return shapes a row identically
+// (the GOAL_COLS precedent in db-goals.js).
+const CATEGORY_COLS = 'id, slug, label, sort_order, active, created_by, created_at, updated_at';
+
+// A slug is the stable machine key a client filter and a skill's inference hold
+// onto, so it is deliberately narrow: lowercase, alnum, single dashes, no edges.
+// Derived from the label when the caller does not supply one, because the human
+// creating a category at the moment Claude could not place a goal should be typing
+// "Developer Relations", not inventing a key.
+function slugify(text) {
+  return String(text == null ? '' : text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+}
+
+function isValidSlug(slug) {
+  const s = String(slug == null ? '' : slug);
+  if (s.length < 2 || s.length > 48) return false;
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(s)) return false;
+  return !s.includes('--');
+}
+
+// -------------------------------------------------------------------------
+// Reads
+// -------------------------------------------------------------------------
+
+// The project's category set, in the order a human should see it. Retired
+// categories are excluded by default but readable with includeInactive, because a
+// goal still carrying one must render correctly — that is why retiring is
+// `active = false` and not a DELETE.
+async function listCategories({ includeInactive = false } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT ${CATEGORY_COLS}
+       FROM work_categories
+      WHERE ($1::boolean OR active)
+      ORDER BY sort_order, label, id`,
+    [includeInactive]
+  );
+  return rows;
+}
+
+async function getCategory(id, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT ${CATEGORY_COLS} FROM work_categories WHERE id = $1`,
+    [id]
+  );
+  return rows[0] ?? null;
+}
+
+// -------------------------------------------------------------------------
+// Writes
+// -------------------------------------------------------------------------
+
+// Create a category. `slug` collides → returns the EXISTING row rather than
+// throwing: two people prompted to create "Developer Relations" in the same hour
+// must converge on one category, and a 409 here would strand whichever goal lost
+// the race with no label and no obvious next step.
+async function createCategory({ slug, label, createdBy = null }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `WITH next_order AS (
+       SELECT COALESCE(MAX(sort_order) + 10, 10) AS n FROM work_categories
+     ), ins AS (
+       INSERT INTO work_categories (slug, label, sort_order, created_by)
+            SELECT $1, $2, next_order.n, $3 FROM next_order
+       ON CONFLICT (slug) DO NOTHING
+       RETURNING ${CATEGORY_COLS}
+     )
+     SELECT ${CATEGORY_COLS}, true AS created FROM ins
+     UNION ALL
+     SELECT ${CATEGORY_COLS}, false AS created FROM work_categories
+      WHERE slug = $1 AND NOT EXISTS (SELECT 1 FROM ins)`,
+    [slug, label, createdBy]
+  );
+  return rows[0] ?? null;
+}
+
+// Set (or clear, with null) a goal's category. Returns the goal row, or null when
+// the goal is gone. No authorisation happens here — the route applies the SAME
+// owner|manager|Archon gate the prose edit uses; a category never widens who may
+// write to a goal, and it must never narrow it either.
+async function setGoalCategory({ goalId, categoryId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `UPDATE goals
+        SET category_id = $2, updated_at = now()
+      WHERE id = $1
+     RETURNING id, version_id, title, subtitle, category_id, status, created_by, updated_at`,
+    [goalId, categoryId]
+  );
+  return rows[0] ?? null;
+}
+
+// -------------------------------------------------------------------------
+// Decoration
+// -------------------------------------------------------------------------
+
+// Attach the readable category onto a goal row for the wire: `category` is
+// {id, slug, label} or null. A map keyed by id is passed in so listing 38 goals
+// costs ONE category query, not 38 joins — and so the goal SELECTs in db-goals.js
+// stay untouched (GOAL_COLS is used in INSERT ... RETURNING, where a join cannot
+// go). Pure, so the shape is pinned by a test.
+function decorateGoalCategory(goal, byId) {
+  if (!goal) return goal;
+  const id = goal.category_id;
+  const row = id == null ? null : (byId instanceof Map ? byId.get(String(id)) : (byId || {})[String(id)]);
+  return {
+    ...goal,
+    category: row ? { id: String(row.id), slug: row.slug, label: row.label } : null,
+  };
+}
+
+// Map of id → row, for decorateGoalCategory. Inactive categories are INCLUDED:
+// a goal carrying a retired one must still render its label rather than silently
+// reading as uncategorised.
+async function categoryIndex(deps = {}) {
+  const rows = await listCategories({ includeInactive: true }, deps);
+  return new Map(rows.map((r) => [String(r.id), r]));
+}
+
+// -------------------------------------------------------------------------
+// Handlers (factories — collaborators injected, so a test needs no database)
+// -------------------------------------------------------------------------
+
+// GET /work-categories — the set. Any signed-in builder: it is a vocabulary, and
+// a client that cannot read it hard-codes the labels instead, which is how the
+// "present in every builders hall on any project" requirement rots.
+function categoriesListHandler({ list = listCategories, log } = {}) {
+  return async function getWorkCategories(req, res) {
+    try {
+      const includeInactive = String(req.query?.include_inactive || '') === '1';
+      const categories = await list({ includeInactive });
+      return res.json({ categories });
+    } catch (err) {
+      log?.error({ err: err && err.message }, 'GET /work-categories failed');
+      return res.fail('category_list_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+// POST /work-categories — the endpoint the "Claude could not place this goal"
+// prompt writes INTO. Gated at the same rank as authoring a goal: extending the
+// project's vocabulary is a planning act, not an administrative one.
+function categoryCreateHandler({ create = createCategory, validateOrRespond, LIMITS, log } = {}) {
+  return async function postWorkCategory(req, res) {
+    if (validateOrRespond(req, res, {
+      label: { required: true, type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
+      slug: { type: 'string', maxLength: 48 },
+    })) return;
+    const label = String(req.body.label).trim();
+    if (!label) return res.fail('label_required', 400);
+    const slug = slugify(req.body.slug || label);
+    if (!isValidSlug(slug)) {
+      return res.fail('bad_slug', 400, {
+        message: 'A category slug is lowercase letters, digits and single dashes (2–48 chars). '
+          + 'Send a `slug` explicitly if the label does not reduce to one.',
+      });
+    }
+    try {
+      const row = await create({ slug, label, createdBy: req.builder.id });
+      if (!row) return res.fail('category_create_failed', { status: 500, message: 'internal error' });
+      const created = row.created !== false;
+      delete row.created;
+      return res.status(created ? 201 : 200).json({ ok: true, category: row, created });
+    } catch (err) {
+      log?.error({ err: err && err.message }, 'POST /work-categories failed');
+      return res.fail('category_create_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+// PATCH /goals/:id/category — body { category_id } (null clears it).
+//
+// A separate route from PATCH /goals/:id on purpose: that one is the PROSE edit
+// (task 1003102), which carries a write-once posture and an audit delta of the
+// before/after text. A category is a label, not prose — re-labelling is cheap and
+// reversible, and folding it into the prose handler would either subject a label
+// to the prose rules or loosen the prose rules to suit a label.
+function goalCategoryHandler({ db, authorizeGoalManagement, validateOrRespond, parseId, set = setGoalCategory, read = getCategory, index = categoryIndex, log } = {}) {
+  return async function patchGoalCategory(req, res) {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (!Object.prototype.hasOwnProperty.call(req.body || {}, 'category_id')) {
+      return res.fail('category_id_required', 400, {
+        message: 'Send { category_id: <id> } to set the goal\'s category, or { category_id: null } to clear it.',
+      });
+    }
+    const raw = req.body.category_id;
+    const categoryId = raw == null ? null : Number(raw);
+    if (categoryId !== null && (!Number.isInteger(categoryId) || categoryId <= 0)) {
+      return res.fail('bad_category_id', 400);
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const actorMembership = goal
+        ? await db.getGoalMember({ goalId: id, builderId: req.builder.id })
+        : null;
+      const decision = authorizeGoalManagement({
+        goal, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+      });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+      if (categoryId !== null) {
+        const category = await read(categoryId);
+        if (!category) return res.fail('category_not_found', 404);
+      }
+      const updated = await set({ goalId: id, categoryId });
+      if (!updated) return res.fail('goal_not_found', 404);
+      const byId = await index();
+      return res.json({ ok: true, goal: decorateGoalCategory(updated, byId) });
+    } catch (err) {
+      log?.error({ err: err && err.message }, 'PATCH /goals/:id/category failed');
+      return res.fail('goal_category_update_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+module.exports = {
+  CATEGORY_COLS,
+  slugify,
+  isValidSlug,
+  listCategories,
+  getCategory,
+  createCategory,
+  setGoalCategory,
+  decorateGoalCategory,
+  categoryIndex,
+  categoriesListHandler,
+  categoryCreateHandler,
+  goalCategoryHandler,
+};

package/modules/lifecycle/routes/goals.js

@@ -28,6 +28,7 @@ const db = require('../db');
 const hierarchy = require('../hierarchy');
 const goalSuggest = require('../goal-suggest.js'); // task 1003062 — pre-creation goal suggester
 const goalEdits = require('../goal-edits.js'); // task 1003102 — goal self-edit handlers
+const goalCategory = require('../goal-category.js'); // task 1003275 — the ADVISORY human category (gates nothing)
 const { suggestCriteria } = require('../criterion-suggest');
 const { classifyTaskKind, VALID_KINDS, VALID_DISCIPLINES, TASK_FIELD_BOUNDS } = require('../task-classifier');
 const { validateOrRespond, parseId, LIMITS } = api;
@@ -77,6 +78,9 @@ module.exports = function buildGoalsRouter() {
       subtitle: { type: 'string', maxLength: LIMITS.TITLE }, description: { type: 'string', maxLength: LIMITS.DESCRIPTION },
       scope_modules: { type: 'array', maxItems: 64, itemsType: 'string' },
       succeeds_goal_id: { type: 'integer', min: 1 },
+      // task 1003275 — the human category. ADVISORY: absent is legal (it becomes a
+      // prompt, never a refusal), and no gate below reads it.
+      category_id: { type: 'integer', min: 1 },
     })) return;
 
     const scopeModules = req.body.scope_modules || [];
@@ -107,12 +111,19 @@ module.exports = function buildGoalsRouter() {
           return res.fail('predecessor_not_found', { status: 404, message: 'No such goal to carry forward.' });
         }
       }
+      // task 1003275: an unknown category is the caller's typo, not a new
+      // category — creating one is an explicit POST /work-categories.
+      const categoryId = req.body.category_id ?? null;
+      if (categoryId !== null && !(await goalCategory.getCategory(categoryId))) {
+        return res.fail('category_not_found', 404, { message: 'No such category. List them at GET /work-categories, or create one with POST /work-categories.' });
+      }
       const goal = await db.createGoal({
         versionId: req.body.version_id,
         title: req.body.title,
         subtitle: (req.body.subtitle || '').trim() || null, description: (req.body.description || '').trim() || null,
         scopeModules,
         createdBy: req.builder.id,
+        categoryId,
       });
       // Stamp the predecessor's succeeded_by pointer at the new goal (the lineage).
       if (succeedsId != null) {
@@ -134,7 +145,10 @@ module.exports = function buildGoalsRouter() {
     }
     try {
       const goals = await db.listGoals({ versionId: version || null, status: status || null });
-      return res.json({ goals: goals.map(decorateGoalScope) });
+      // task 1003275: ONE category query decorates the whole board (never a join
+      // per goal). Purely a label for the reader — nothing downstream branches on it.
+      const byId = await goalCategory.categoryIndex();
+      return res.json({ goals: goals.map((g) => goalCategory.decorateGoalCategory(decorateGoalScope(g), byId)) });
     } catch (err) {
       log.error('[gds] GET /goals', err);
       return res.fail('list_failed', { status: 500, message: 'internal error' });
@@ -210,7 +224,8 @@ module.exports = function buildGoalsRouter() {
         db.listCriteriaForGoal(id),
         db.getGoalDependencies(id),  // task 1761 — prerequisite goals + satisfied state
       ]);
-      return res.json({ goal: decorateGoalScope(goal), members, criteria, dependencies });
+      const byId = await goalCategory.categoryIndex();
+      return res.json({ goal: goalCategory.decorateGoalCategory(decorateGoalScope(goal), byId), members, criteria, dependencies });
     } catch (err) {
       log.error('[gds] GET /goals/:id', err);
       return res.fail('fetch_failed', { status: 500, message: 'internal error' });
@@ -286,6 +301,27 @@ module.exports = function buildGoalsRouter() {
   // Pinned in route-rank-check.MODULE_EXPECTED_RANKS['lifecycle'].
   router.patch('/goals/:id/visibility', auth.requireBuilder, goalEdits.goalVisibilityHandler({ db, authorizeGoalManagement, validateOrRespond, parseId, VALID_VISIBILITIES }));
 
+  // ---- the ADVISORY human category (task 1003275, criterion legibility-categories) ----
+  // A category ORIENTS a person and steers Claude; it authorises nothing. Nothing
+  // in this file, in claim eligibility, or in the claimable feed may branch on it —
+  // scripts/gds/category-advisory-guard.js fails the build if that changes (ADR 0192).
+  //
+  // GET /work-categories — the project's set. rank: any-builder; it is a vocabulary,
+  // and a client that cannot read it hard-codes the labels instead.
+  router.get('/work-categories', auth.requireBuilder, goalCategory.categoriesListHandler({ log }));
+  // POST /work-categories — the endpoint the "Claude could not place this goal"
+  // prompt writes into. Same permission as authoring a goal: extending the project's
+  // vocabulary is a planning act. A duplicate slug returns the existing row (200),
+  // so two people prompted at once converge instead of one being stranded.
+  router.post('/work-categories', auth.requireBuilder, auth.requirePermission('goal.create'),
+    goalCategory.categoryCreateHandler({ validateOrRespond, LIMITS, log }));
+  // PATCH /goals/:id/category — body { category_id } (null clears it). Separate from
+  // PATCH /goals/:id because that route is the PROSE edit with its write-once posture
+  // and before/after audit delta; a label is neither.
+  // rank: any-builder (requireBuilder) + the in-handler owner|manager|Archon gate.
+  router.patch('/goals/:id/category', auth.requireBuilder,
+    goalCategory.goalCategoryHandler({ db, authorizeGoalManagement, validateOrRespond, parseId, log }));
+
   // POST /goals/:id/requests — a builder asks to join a (private or protected)
   // goal (task 1952 / ADR 0112). Refused on a public, non-protected goal (that's
   // open-join — just POST /goals/:id/join). Creates a pending kind='request' the

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.365",
+  "version": "1.19.367",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.365",
+      "version": "1.19.367",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.365",
+  "version": "1.19.367",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

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.