@bongos/core 1.19.366 → 1.19.367

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 315 endpoints across 52 route files.
+> **Generated from the live route files** — the route file is authoritative. 318 endpoints across 52 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -205,15 +205,16 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/github/repos` | `any-builder` | — | acts only on the caller's OWN GitHub identity (the token they granted). |
 | POST | `/api/bongos/github/repos` | `any-builder` | `name` | creates a repo in the caller's OWN account. |
 
-## `goals` (26)
+## `goals` (27)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/goals` | `any-builder` | — | GET /goals?version=&status= — list goals (read). |
-| POST | `/api/bongos/goals` | `metic+archon` | `version_id`, `title`, `subtitle`, `description`, `scope_modules`, `succeeds_goal_id` | POST /goals — create a goal. |
+| POST | `/api/bongos/goals` | `metic+archon` | `version_id`, `title`, `subtitle`, `description`, `scope_modules`, `succeeds_goal_id`, `category_id` | POST /goals — create a goal. |
 | GET | `/api/bongos/goals/:id` | `any-builder` | — | GET /goals/:id — one goal with its members + linked criteria (read). |
 | PATCH | `/api/bongos/goals/:id` | `any-builder` | — | PATCH /goals/:id — correct a goal's own title/subtitle/description (tasks 1003102, 1003224). |
 | POST | `/api/bongos/goals/:id/archive` | `metic+archon` | — | POST /goals/:id/archive — retire a goal (open\|achieved → archived). |
+| PATCH | `/api/bongos/goals/:id/category` | `any-builder` | — | PATCH /goals/:id/category — body { category_id } (null clears it). |
 | GET | `/api/bongos/goals/:id/conflicts` | `any-builder` | — | GET /goals/:id/conflicts — the server-side task-conflict view (task 1736). |
 | POST | `/api/bongos/goals/:id/conflicts/resolve` | `any-builder` | `action`, `note`, `touches`, `first_task_id`, `then_task_id`, `task_id` | POST /goals/:id/conflicts/resolve — the owner/manager resolution actions for a detected conflict (task 1736; authority model ADR 0106): s… |
 | POST | `/api/bongos/goals/:id/invitations` | `any-builder` | `note`, `builder_id` | POST /goals/:id/invitations { builder_id, note? } — an owner\|manager\|Archon invites a builder (task 1952). |
@@ -577,6 +578,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/versions/close-suggestions` | `public` | — | Close-flow gate suggestions for every version still 'building'. |
 | GET | `/api/bongos/versions/progress` | `public` | — | read-only progress aggregate; mirrors /public/progress. |
 
+## `work-categories` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/work-categories` | `any-builder` | — | ---- the ADVISORY human category (task 1003275, criterion legibility-categories) ---- A category ORIENTS a person and steers Claude; it a… |
+| POST | `/api/bongos/work-categories` | `metic+archon` | — | POST /work-categories — the endpoint the "Claude could not place this goal" prompt writes into. |
+
 ---
 
 > 8 write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a `validateOrRespond` schema (`src/bongos/routes/_helpers.js`) surfaces them here automatically.

package/migrations/core_226_work_categories.sql

@@ -0,0 +1,100 @@
+-- core_226_work_categories.sql — a human CATEGORY for the work, that gates
+-- nothing (task 1003275, goal 1000072, criterion legibility-categories).
+--
+-- WHAT THIS IS FOR. The project is legible to Claude and illegible to a person.
+-- A human scanning 38 open goals cannot tell at a glance which are about money,
+-- which are about the walls, and which are about the hall — the goal's own words
+-- carry that, but only if you read all of them. A category is one word that
+-- answers it, and the owner named the set: Builders Hall, Context Management,
+-- Government (Decision Making), Modules, Security, Economics, Legal, and
+-- User/ABI Experience.
+--
+-- THE CONSTRAINT THAT MATTERS MORE THAN THE FEATURE — THIS IS ADVISORY ONLY.
+-- The owner said it twice: this organisation "has no hierarchical purpose" and
+-- these categories have "no effect on the creation and agentic management of
+-- these elements". 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. A second thing that LOOKS like a
+-- hierarchy will be mistaken for one within a release, and then something will
+-- be refused because of a label. So: no claim gate, no route guard, no rank
+-- check, no claimable-feed filter and no dependency rule may read a category.
+-- That is enforced in code by the fitness check
+-- `scripts/gds/category-advisory-guard.js`, not by this comment (ADR 0192).
+--
+-- WHY A TABLE AND NOT AN ENUM OR A text COLUMN. The criterion requires that when
+-- Claude cannot fit a goal into the set, "the human is prompted to create a new
+-- category — that failure is a designed prompt, not an error". A category set
+-- that a person extends at runtime cannot be a CHECK constraint or a pg enum
+-- without a migration per addition, and it must not be a free-text column or the
+-- set is not a set (two spellings of "Security" and the label has stopped
+-- orienting anyone).
+--
+-- WHY A TASK HAS NO COLUMN HERE. The criterion says "every goal (and task, BY
+-- INHERITANCE)". A task's category is its goal's, read through tasks.goal_id —
+-- storing a copy creates two answers to one question and no way to know which is
+-- right. Inheritance is literal: there is nothing to keep in sync.
+--
+-- WHY CORE AND NOT modules/lifecycle/migrations/. `goals` was created by
+-- migrations/160_goal_tier.sql and is a CORE table; the lifecycle module owns the
+-- QUERIES against it, not the table (modules/lifecycle/CLAUDE.md: "None owned").
+-- Fitness check 11 refuses an `ALTER TABLE goals` from a module migration however
+-- lifecycle-ish it feels (ADR 0083 §Decision #5) — the same trap core_224 hit.
+--
+-- Additive, replay-safe, forward-safe: nullable with no default (NULL = never
+-- categorised, which is a legal state and a prompt, never a rejection), and every
+-- existing reader SELECTs an explicit column list so old code on the new schema
+-- neither sees nor needs it (tests/migrations_forward_safe.mjs).
+
+BEGIN;
+
+-- 1. The set itself. `slug` is the stable machine key (a client filter, a skill's
+--    inference); `label` is what a person reads and may be re-worded without
+--    breaking anything that referenced it. created_by NULL = shipped with the
+--    project (the eight below); a real id = a human created it at the moment
+--    Claude could not place a goal. A migration must never hard-code a builder
+--    id, so the seeded rows are system-attributed (learning 1238).
+--    `active` retires a category without deleting it — a goal already carrying it
+--    keeps reading correctly, which a DELETE would break.
+CREATE TABLE IF NOT EXISTS work_categories (
+  id          bigserial PRIMARY KEY,
+  slug        text NOT NULL UNIQUE,
+  label       text NOT NULL,
+  sort_order  integer NOT NULL DEFAULT 0,
+  active      boolean NOT NULL DEFAULT true,
+  created_by  bigint REFERENCES builders(id),   -- NULL = shipped with the project
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE work_categories IS
+  'The human category set a project owns (task 1003275). ADVISORY ONLY: no gate, route guard, rank check, feed filter or dependency rule may read it — enforced by scripts/gds/category-advisory-guard.js. The real hierarchy is ADR 0086.';
+
+-- 2. The owner's default set. ON CONFLICT DO NOTHING so a replay is a no-op and
+--    a project that has re-worded a label does not have it reverted.
+INSERT INTO work_categories (slug, label, sort_order) VALUES
+  ('builders-hall',      'Builders Hall',                 10),
+  ('context-management', 'Context Management',            20),
+  ('government',         'Government (Decision Making)',  30),
+  ('modules',            'Modules',                       40),
+  ('security',           'Security',                      50),
+  ('economics',          'Economics',                     60),
+  ('legal',              'Legal',                         70),
+  ('user-experience',    'User/ABI Experience',           80)
+ON CONFLICT (slug) DO NOTHING;
+
+-- 3. The goal's label. ON DELETE SET NULL rather than RESTRICT: retiring a
+--    category is `active = false`, but if one is ever genuinely deleted an
+--    advisory label must not be able to block it — a goal falling back to
+--    uncategorised is exactly the designed prompt.
+ALTER TABLE goals
+  ADD COLUMN IF NOT EXISTS category_id bigint REFERENCES work_categories(id) ON DELETE SET NULL;
+
+COMMENT ON COLUMN goals.category_id IS
+  'The goal''s human category (task 1003275). ADVISORY ONLY — orients a person and steers Claude, authorises nothing. NULL = not yet categorised, a legal state that prompts rather than refuses. A task inherits this through tasks.goal_id and stores no copy.';
+
+CREATE INDEX IF NOT EXISTS idx_goals_category ON goals (category_id);
+
+COMMIT;
+
+INSERT INTO schema_migrations (version) VALUES ('core_226_work_categories')
+ON CONFLICT (version) DO NOTHING;

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -322,6 +322,8 @@ function createClient(opts = {}) {
       patchGoalsId: (args) => request("PATCH", "/goals/{id}", { hasBody: true }, args),
       // POST /goals/{id}/archive — rank: metic+archon — POST /goals/:id/archive
       postGoalsIdArchive: (args) => request("POST", "/goals/{id}/archive", { hasBody: true }, args),
+      // PATCH /goals/{id}/category — rank: any-builder — PATCH /goals/:id/category
+      patchGoalsIdCategory: (args) => request("PATCH", "/goals/{id}/category", { hasBody: true }, args),
       // GET /goals/{id}/conflicts — rank: any-builder — GET /goals/:id/conflicts
       getGoalsIdConflicts: (args) => request("GET", "/goals/{id}/conflicts", { hasBody: false }, args),
       // POST /goals/{id}/conflicts/resolve — rank: any-builder — POST /goals/:id/conflicts/resolve
@@ -815,6 +817,12 @@ function createClient(opts = {}) {
       // GET /versions/progress — rank: public — GET /versions/progress
       getVersionsProgress: (args) => request("GET", "/versions/progress", { hasBody: false }, args),
     },
+    "workCategories": {
+      // GET /work-categories — rank: any-builder — GET /work-categories
+      getWorkCategories: (args) => request("GET", "/work-categories", { hasBody: false }, args),
+      // POST /work-categories — rank: metic+archon — POST /work-categories
+      postWorkCategories: (args) => request("POST", "/work-categories", { hasBody: true }, args),
+    },
   };
 }
 

package/modules/lifecycle/db-goals.js

@@ -32,7 +32,7 @@ const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
 // Shared column list so every goal read/return shapes a row identically.
 
 const GOAL_COLS =
-  'id, version_id, title, subtitle, description, scope_modules, status, visibility, created_by, succeeded_by_goal_id, sort_order, created_at, updated_at';
+  'id, version_id, title, subtitle, description, scope_modules, status, visibility, created_by, succeeded_by_goal_id, sort_order, category_id, created_at, updated_at';
 
 // Shared column list for a goal_membership_requests row (task 1951 / ADR 0112) —
 // the invite / join-request queue behind private goals. Every helper below shapes
@@ -48,7 +48,7 @@ const MEMBERSHIP_REQUEST_COLS =
 // goals) inserts no member — those goals have no owner; Archons act as one.
 
 async function createGoal(
-  { versionId, title, subtitle = null, description = null, scopeModules = [], status = 'open', createdBy = null },
+  { versionId, title, subtitle = null, description = null, scopeModules = [], status = 'open', createdBy = null, categoryId = null },
   deps = {}
 ) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
@@ -56,15 +56,15 @@ async function createGoal(
     `WITH next_order AS (
        SELECT COALESCE(MAX(sort_order) + 1, 0) AS n FROM goals WHERE version_id = $1
      ), g AS (
-       INSERT INTO goals (version_id, title, subtitle, description, scope_modules, status, created_by, sort_order)
-            SELECT $1, $2, $7, $3, $4, $5, $6, next_order.n FROM next_order
+       INSERT INTO goals (version_id, title, subtitle, description, scope_modules, status, created_by, sort_order, category_id)
+            SELECT $1, $2, $7, $3, $4, $5, $6, next_order.n, $8 FROM next_order
        RETURNING ${GOAL_COLS}
      ), first_lead AS (
        INSERT INTO goal_members (goal_id, builder_id, membership_kind)
        SELECT g.id, $6::bigint, 'lead' FROM g WHERE $6::bigint IS NOT NULL
      )
      SELECT * FROM g`,
-    [versionId, title, description, scopeModules, status, createdBy, subtitle]
+    [versionId, title, description, scopeModules, status, createdBy, subtitle, categoryId]
   );
   return rows[0];
 }

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.366",
+  "version": "1.19.367",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.366",
+      "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.366",
+  "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",