@bongos/core 1.19.365 → 1.19.367

package/docs/api/openapi.json

@@ -224,6 +224,10 @@
     {
       "name": "versions",
       "description": "Endpoints under `/api/bongos/versions`."
+    },
+    {
+      "name": "work-categories",
+      "description": "Endpoints under `/api/bongos/work-categories`."
     }
   ],
   "paths": {
@@ -4553,6 +4557,51 @@
         ]
       }
     },
+    "/goals/{id}/category": {
+      "patch": {
+        "operationId": "patch_goals_id_category",
+        "tags": [
+          "goals"
+        ],
+        "summary": "PATCH /goals/:id/category",
+        "description": "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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/goals.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/goals/{id}/conflicts": {
       "get": {
         "operationId": "get_goals_id_conflicts",
@@ -14324,6 +14373,69 @@
         },
         "security": []
       }
+    },
+    "/work-categories": {
+      "get": {
+        "operationId": "get_work_categories",
+        "tags": [
+          "work-categories"
+        ],
+        "summary": "GET /work-categories",
+        "description": "---- 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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/goals.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_work_categories",
+        "tags": [
+          "work-categories"
+        ],
+        "summary": "POST /work-categories",
+        "description": "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.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.create` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/goals.js",
+        "x-permissions": [
+          "goal.create"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
     }
   },
   "components": {
@@ -17888,6 +18000,10 @@
           "succeeds_goal_id": {
             "type": "integer",
             "minimum": 1
+          },
+          "category_id": {
+            "type": "integer",
+            "minimum": 1
           }
         },
         "required": [
@@ -19961,7 +20077,7 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 315,
+  "x-endpoint-count": 318,
   "x-schema-count": 353,
   "x-undocumented-bodies": 8,
   "x-response-schemas": 237,

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/docs/file-map.md

@@ -412,12 +412,24 @@ To install on a new machine, symlink each routine's directory under `~/.claude/s
 ├── lifecycle-card.js         ← PostToolUse: deterministic delivery of MUTATING lifecycle cards (claim/ship/release) — the write-side mirror of session-cards.js (task 1288)
 ├── pre-compact.js            ← PreCompact: thin reader around eviction-policy.js — emits an eviction directive (blocks to drop + one-line recovery stubs) at the compaction seam (task 1349)
 ├── eviction-policy.js        ← pure deterministic in-session compaction classifier (transcript turns → eviction set + replacement stubs); no I/O, unit-tested in tests/eviction_policy.mjs; consumed by pre-compact.js (task 1348)
-├── stop-sound.js             ← Stop: completion sound on macOS (afplay; Glass / Hero on /tmp/otb-celebrate); silent no-op on other OSes
+├── stop-sound.js             ← ⚠ ABSENT from this repo (see the note below). Superseded anyway: the turn-end sound is now `scripts/gds/turn-end-sound.js`, wired as the Stop hook in `.claude/settings.json` and cross-platform rather than macOS-only (task 1003272)
 └── stop-refcheck.js          ← Stop: deterministic backstop that catches a bare `#NNN` Bongos ref in live session text (autolinks to a 404 GitHub issue) and asks for the clickable form (follow-on to task 929)
 ```
 
+> **⚠ THIS TREE IS STALE: 12 of the 13 files listed above are NOT in this repo** — only `secret-gate.js` exists on disk, and `.claude/settings.json` wires just `SessionStart` (three `scripts/gds/*` probes + the sound-prefs mirror), `PreToolUse` (secret-gate) and `Stop` (`scripts/gds/turn-end-sound.js`). The hook tree went the same way as `.claude/sounds/` — absent from every commit, lost when core was re-seeded to 1.18.0 (task 1003272 found and fixed the sound half of that). Do not assume a hook named here runs; check `.claude/settings.json`. Auditing and either restoring or deleting the other twelve is its own task, not a doc edit.
+
 (Before [#671](https://example.com/builders#/task/671) these ran via `bash` shims — `sync-env-local.sh`, `conductor.sh`, `onboarding-ship-logs.sh`, `rank-change-greeting.sh`, `pull-memory.sh` — which failed on Windows without Git Bash. The Node entries above replaced them.)
 
+**Notification sounds** at `.claude/sounds/` + `modules/hall-ui/public/*.wav` (task 1003272 — the local half of the 5-event sound system, which had never been committed):
+
+```
+.claude/sounds/
+└── play.js                   ← the local player. playSound(<wavName>) — fire-and-forget, never throws, spawns the platform player detached (afplay / paplay / aplay / ffplay / PowerShell SoundPlayer); scales the WAV itself for the master volume because aplay and SoundPlayer have no volume flag. Reads the prefs mirror at instance-config.configPath('sound-prefs.json') with the pre-rename ~/.config/otb/ as fallback. Required (guarded) by scripts/gds/ship-state.js; runnable directly: `node .claude/sounds/play.js ship`
+```
+
+The five base assets live ONCE, in `modules/hall-ui/public/` — served at `/builders/<name>.wav` for the Settings previews and read from the same directory by the player:
+`chime.wav` (pre-existing) plus `alert.wav`, `ship.wav`, `triumph.wav`, `fanfare.wav`, all generated by [`scripts/gds/gen-sounds.js`](../scripts/gds/gen-sounds.js) (`--check` verifies freshness; it never touches `chime.wav`).
+
 **On the droplet (`REDACTED_IP`):**
 
 ```

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/builder-settings/event-sound-prefs.js

@@ -2,12 +2,22 @@
 // src/bongos/event-sound-prefs.js — per-builder per-event sound variant selection
 // (task 582). Extends the mute-toggle system (sound-prefs.js) with variant
 // picking: for each of 5 build events a builder can choose which world-themed
-// sound variant plays. Each variant maps to an EXISTING .wav in .claude/sounds/;
-// the dedicated world-themed audio assets (lyre-pluck.wav etc.) ship separately.
+// sound variant plays. Each variant maps to an EXISTING base .wav; the dedicated
+// per-variant audio (lyre-pluck.wav etc.) would ship separately.
+//
+// WHERE THE BASE WAVS ACTUALLY LIVE (corrected, task 1003272): modules/hall-ui/
+// public/, served at /builders/<name>.wav and read from that same directory by
+// .claude/sounds/play.js. This comment used to say .claude/sounds/, which was
+// true of no commit in this repo's history — for months FOUR of the five base
+// wavs did not exist anywhere, so every variant below except the two backed by
+// `chime` resolved to a 404 and played nothing. All five exist now, and
+// tests/sound_player.mjs asserts that every `wav` named here has a real file.
 
 // 5 build events, ordered for the UI. Each has a world-themed default variant
-// plus alternates. `wav` is the existing .claude/sounds/<name>.wav that backs
-// the variant until dedicated audio ships.
+// plus alternates. `wav` is the existing base sound that backs the variant until
+// dedicated audio ships. Each event's two variants deliberately name DIFFERENT
+// base wavs, so switching the picker audibly changes something — a picker whose
+// options all sounded identical would be a worse lie than no picker.
 const EVENTS = Object.freeze([
   {
     id:    'user-input',

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];
 }