@bongos/core 1.19.360 → 1.19.362

package/modules/economy/routes/leaderboard.js

@@ -1,3 +1,15 @@
+// modules/economy/routes/leaderboard.js — GET /leaderboard: who has earned what
+// (ADR 0095 backfill).
+//
+// WHY. The instance publishes its build openly, and the leaderboard is the
+// human-readable face of the credit ledger — it is read by the PUBLIC status
+// dashboard, so it carries no auth gate. Kept deliberately tiny: the ordering and
+// the join live in `../credits.js` beside the ledger they describe, so the ranking
+// shown here can never drift from the balances it claims to rank.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; `../credits` is an intra-module sibling.
+
 const express = require('express');
 // Carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2): the leaderboard query
 // is an intra-module require — a module never requires a core internal. The

package/modules/hall-ui/public/government.js

@@ -25,14 +25,21 @@
 // gated server-side on the `government.manage` atom (archon floor). On 401 →
 // web sign-in.
 //
-// SINCE R15 (goal 1000069, ADR 0175) this page carries the three-section IA —
-// Constitution · Board Room · Ranks & Permissions — because Government is the
-// page that answers "how is this project governed", and administration is only
-// the third part of that answer. Tabs are OTBKit.makeTabs with hash deep links
-// (#constitution / #board-room / #ranks). The first two sections are FRAMES
-// until their build-out lands: R18 fills Constitution with the live values +
-// change history, R19 adds the charter library, R16/R17 fill the Board Room
-// with open items and the vote. Until then each frame states what belongs there
+// SINCE R15 (goal 1000069, ADR 0175) this page carries a three-section IA,
+// because Government is the page that answers "how is this project governed"
+// and administration is only one part of that answer. Task 1003269 reordered
+// the tabs to Permissions · Board Room · Constitution (the administering Archon
+// works from the first of those, and it used to sit last) and shortened the
+// "Ranks & Permissions" label to "Permissions". Tabs are OTBKit.makeTabs with
+// hash deep links, and the HASH IDS DID NOT CHANGE with that reorder
+// (#constitution / #board-room / #ranks) — they are linked from Discord and
+// docs.
+//
+// The Constitution and Board Room sections began as FRAMES (named here by
+// section, not by position, so a reorder like 1003269's cannot make this
+// comment lie): R18 filled Constitution with the live values + change history,
+// R19 added the charter library, and R16/R17 filled the Board Room with open
+// items and the vote. Until a frame is filled it states what belongs there
 // and shows an honest kit empty state — never a fake or a hardcoded value that
 // could drift from the real config.
 
@@ -412,19 +419,29 @@
 
   // ---- the three-section IA (R15) -------------------------------------------
 
-  // Tab order is the spec's — Constitution · Board Room · Ranks & Permissions.
-  // A non-archon lands on the Constitution (the page's IA claim: this is the
-  // page that answers "how is this project governed"); the Archon still lands
-  // on Ranks, their working surface.
+  // Tab order puts Permissions FIRST (task 1003269, owner request): it is the
+  // surface an administering Archon actually works from, and it sat last. The
+  // label is "Permissions" — the words the owner uses for it — not the compound
+  // "Ranks & Permissions"; ranks are still what the panel lists, but permissions
+  // are the atom (ADR 0151) and the shorter label is the clearer one.
+  //
+  // THE HASH IDS ARE LOAD-BEARING AND MUST NOT CHANGE: the Discord board
+  // announcement deep-links ?item=<id>#board-room (board-broadcast.js, and the
+  // reader in loadBoard below), and #constitution/#ranks are linked from docs.
+  // Reorder and relabel freely; the ids are the contract.
+  //
+  // A non-archon still lands on the Constitution (the page's IA claim: this is
+  // the page that answers "how is this project governed"); the Archon still
+  // lands on their working surface, which is now also the first tab.
   function wireTabs({ isArchon }) {
     window.OTBKit.makeTabs({
       mount: document.getElementById('gov-tabs'),
       hash: true,
       initial: isArchon ? 'ranks' : 'constitution',
       tabs: [
-        { id: 'constitution', label: 'Constitution', panel: 'gov-panel-constitution' },
+        { id: 'ranks', label: 'Permissions', panel: 'gov-panel-ranks' },
         { id: 'board-room', label: 'Board Room', panel: 'gov-panel-board' },
-        { id: 'ranks', label: 'Ranks & Permissions', panel: 'gov-panel-ranks' },
+        { id: 'constitution', label: 'Constitution', panel: 'gov-panel-constitution' },
       ],
     });
   }
@@ -843,15 +860,16 @@
   }
 
   // Since R16 the page shell admits page.view.government (metic+), and only the
-  // RANKS tab is the archon admin surface — so the seal narrowed from the whole
-  // page to that one panel. Cosmetic defence-in-depth as ever: every
+  // Permissions tab (panel id gov-panel-ranks) is the archon admin surface — so
+  // the seal narrowed from the whole page to that one panel. Cosmetic
+  // defence-in-depth as ever: every
   // /government/* CRUD endpoint still gates on government.manage server-side,
   // and the board read carries its own atom.
   function sealRanksPanel() {
     const panel = document.getElementById('gov-panel-ranks');
     const body = document.getElementById('gov-body');
     // Replace the admin surface with the sealed note, inside its own tab only.
-    panel.innerHTML = '<p class="gov-sealed">Ranks & Permissions is the Archon administration surface. The Constitution and the Board Room are yours to read.</p>';
+    panel.innerHTML = '<p class="gov-sealed">Permissions is the Archon administration surface. The Constitution and the Board Room are yours to read.</p>';
     body.hidden = false;
   }
 

package/modules/ideas/routes/blockers.js

@@ -1,7 +1,28 @@
+// modules/ideas/routes/blockers.js — the queue of things stuck on a human
+// (ADR 0095 backfill).
+//
+// WHY. An AI agent can build almost anything in this repo except the things only
+// the owner can decide or provide — a credential, a purchase, a product call. Those
+// used to stall silently inside a session nobody re-read. A blocker makes that
+// stall a first-class, reviewable record (`/blocker-review`), linked to the tasks
+// it holds up.
+//
+// THE PAYOFF IS IN `/resolve`: `blockers.resolveBlocker` leans on a DB TRIGGER on
+// `blockers.status` to auto-promote every linked `blocked` task back to ready. So
+// answering the owner's question un-sticks the work automatically — nobody has to
+// remember which tasks were waiting on it. Do not reimplement that promotion here;
+// the trigger is the single writer.
+//
+// `GET /blockers` is PUBLIC (the status dashboard renders it — being open about
+// what the project is stuck on is the point). Filing is open to any builder;
+// resolving and linking are Metic+.
+//
+// MODULE BOUNDARY (carved into modules/ideas/ — BV1.R78 / ADR 0093 §1): auth gates
+// + request validators reach through the published doorway `src/module-api.js`;
+// `blockers` is an intra-module sibling. Never a core internal, never another
+// module.
+
 const express = require('express');
-// Carved into modules/ideas/ (BV1.R78 / ADR 0093 §1): auth gates + request
-// validators reach through the published doorway; `blockers` is an intra-module
-// sibling — a module never requires a core internal.
 const api = require('../../../src/module-api');
 const blockers = require('../blockers');
 const { validateOrRespond, LIMITS, parseId } = api;

package/modules/ideas/routes/inbox.js

@@ -1,7 +1,38 @@
+// modules/ideas/routes/inbox.js — where a thought enters the system and becomes
+// work, or doesn't (ADR 0095 backfill).
+//
+// WHY. Ideas arrive mid-session, from Discord, from anyone — and an idea that has
+// to wait for the right moment to be filed is an idea that gets lost. So capture is
+// cheap and open to every rank, and JUDGEMENT happens later at triage
+// (`/idea-triage`: promote → task, discard, merge, defer). This file is the whole
+// of that intake surface. Its factory also REGISTERS the `ideas.capture` kernel
+// port — the codebase's first module→module port, which is how the Discord inbound
+// files an idea without importing this module.
+//
+// The three grades are the spine (see ../../CLAUDE.md for the full rules):
+//   quick — a title and a description; turning a thought into a task fast.
+//   spark — a quick idea whose AUTHOR marked it as wanting development. That mark
+//           is consent, which is why `/:id/spark` is author-gated and `/:id/develop`
+//           (picking one up) is open to ANY builder — gating pickup would make the
+//           queue unpickable.
+//   full  — carries the template's five fields and a deterministic completeness
+//           score, which feeds credit and the ratification board.
+//
+// TWO THINGS THAT BITE, both proven by tests:
+//   - ROUTE ORDER IS LOAD-BEARING. Express matches in declaration order, so every
+//     literal path (`/inbox/sparks`, `/inbox/template`, `/inbox/awaiting-nod`) MUST
+//     be declared before `GET /inbox/:id` — otherwise `:id` swallows it, `parseId`
+//     400s, and an entire feature disappears with no error that names it.
+//   - `/inbox/template` and `/inbox/score` are PURE (no DB, no idea id). They exist
+//     so the hall's composer renders and scores from the REAL declaration and the
+//     REAL scorer rather than a second copy of the rules in the browser.
+//
+// MODULE BOUNDARY (carved into modules/ideas/ — BV1.R78 / ADR 0093 §1+§5): auth
+// gates + request validators reach through the published doorway
+// `src/module-api.js`; `inbox` is an intra-module sibling. Never a core internal,
+// never another module.
+
 const express = require('express');
-// Carved into modules/ideas/ (BV1.R78 / ADR 0093 §1+§5): auth gates + request
-// validators reach through the published doorway; `inbox` is an intra-module
-// sibling — a module never requires a core internal.
 const api = require('../../../src/module-api');
 const inbox = require('../inbox');
 // Full Idea capture (task 1002919 / BV1.R143): the template validator (R141)

package/modules/lifecycle/routes/claims.js

@@ -1,3 +1,25 @@
+// modules/lifecycle/routes/claims.js — locking a task to one builder's session,
+// and letting go of it again (ADR 0095 backfill).
+//
+// WHY. The claim is what makes PARALLEL builder sessions safe. Several agents work
+// this repo at once; without an atomic lock two of them pick the same task, write
+// the same files, and one loses the work at merge. `POST /claims` is that lock, and
+// it must stay atomic — it refuses with a typed reason rather than racing: already
+// claimed, task not ready, touches conflict, or 409 `DEPS_NOT_SHIPPED` when the
+// dependency graph has not opened the task yet.
+//
+// Every claim ends deliberately, never by drifting: `/claims/:id/resolve` carries
+// both the ship path (credits land) and the release path (no credits, task returns
+// to `ready`). `release-on-behalf` is the privileged escape hatch for a claim whose
+// builder is gone — a crashed session must not strand a task forever.
+//
+// The batch routes serve the multi-claim session flow; `batch/validate` is a DRY
+// RUN, so a builder can see which of several tasks would be refused before locking
+// any of them.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; never a core internal, never another module.
+
 const express = require('express');
 // Intra-module + the published doorway — a module never requires a core internal.
 const api = require('../../../src/module-api');

package/modules/lifecycle/routes/tasks.js

@@ -1,3 +1,25 @@
+// modules/lifecycle/routes/tasks.js — the HTTP surface of the task itself: what
+// work exists, what is claimable, and how a task moves through its statuses
+// (ADR 0095 backfill).
+//
+// WHY. A task is the unit the whole methodology rests on — "every change is backed
+// by a claimed task" only means something if the task's shape and its status
+// transitions are enforced in ONE place. This is that place. It owns the
+// backlog→ready→active→completed→confirmed→shipped walk (`/promote`, `/demote`,
+// `/ship`, `/confirm`, `/abandon`), the DEPENDENCY graph that gates claimability,
+// and the done-when criteria a version's progress rolls up from.
+//
+// Two invariants that are easy to break from here:
+//   - `/tasks/claimable` computes parallel-safety against everyone's ACTIVE claims.
+//     It is what makes concurrent builder sessions safe; a filter loosened here
+//     hands two builders the same work.
+//   - Dependencies are load-bearing; the `V##.R##` rank prefix is decorative.
+//     Shipping a task auto-promotes its now-unblocked dependents backlog→ready
+//     (ADR 0015), so the graph — not a human — decides what opens up next.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; never a core internal, never another module.
+
 const express = require('express');
 const fs = require('node:fs');
 const os = require('node:os');

package/modules/lifecycle/routes/versions.js

@@ -1,3 +1,21 @@
+// modules/lifecycle/routes/versions.js — the version as a container of scope, and
+// the question "is it done yet?" (ADR 0095 backfill).
+//
+// WHY. The project ships version-by-version, so a version is not a label — it is
+// the unit scope is committed to and closed against. These routes answer the two
+// things anyone asks about one: what is IN it (`GET /versions`, `POST /versions`)
+// and how far along it is (`/progress`, `/:id/progress` — the roll-up `/status`
+// renders: each done-when criterion → its gating tasks → what remains, ADR 0025).
+//
+// `/versions/close-suggestions` exists because a version that is *actually*
+// finished rarely announces itself — work drifts, criteria get met out of order,
+// and a version can sit open long after its last real task shipped. Delegated to
+// `../version-close.js`, it surfaces the candidates so closing is a decision
+// someone makes rather than one nobody remembers to make.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; never a core internal, never another module.
+
 const express = require('express');
 // Intra-module + the published doorway — a module never requires a core internal.
 const api = require('../../../src/module-api');

package/modules/memory/routes/learnings.js

@@ -1,3 +1,24 @@
+// modules/memory/routes/learnings.js — GET/POST /learnings: pay for a discovery
+// once (ADR 0095 backfill).
+//
+// WHY. A hard-won diagnosis — the kind that costs half an hour of a session — is
+// worth exactly nothing if the next agent has to rediscover it. Learnings are the
+// short-form half of that cure (the long-form half is a recipe under
+// `docs/recipes/`): one durable, searchable rule per finding, captured via
+// `node scripts/gds/learning-capture.js` and surfaced again through `/recall`.
+//
+// Capture is open to any signed-in builder on purpose. The agent that just paid
+// for the discovery is the one holding it, and a rank gate on writing down what
+// you learned would simply mean it never gets written down.
+//
+// PRIVACY: bodies pass through `stripPrivate()` before persisting, so anything
+// fenced in `<private>…</private>` never enters the store or the recall index
+// (ADR 0095 C4). The fence is fail-closed — an unbalanced marker strips to the end
+// rather than leaking what it was meant to hide.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; `../learnings` is an intra-module sibling.
+
 const express = require('express');
 // Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): auth + the shared request
 // validators (validateOrRespond/LIMITS) via the doorway; the learnings lib is an

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.360",
+  "version": "1.19.362",
   "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/claude-md-template.js

@@ -60,6 +60,7 @@ ${ident}
 - **\`bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
 - **\`bongos ship\`** runs the smoke + grade, then merges and deploys; **\`bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
 - **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
+- **Code you write or touch carries a doc-comment** — each module a header, each public function/class a line or two, saying *what* it does and *why* it exists (never how), in the words someone would search for. Agents find code by searching text, so meaning written into the source is what makes it findable.
 
 ## Where things live
 

package/scripts/gds/doc-comment-coverage.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/doc-comment-coverage.js — the ADVISORY nudge behind the ADR 0095
+// doc-comment convention (task 1001654).
+//
+// WHY. ADR 0095 ratified one convention: every module and public symbol carries a
+// short doc-comment saying WHAT it does and WHY it exists, because agents navigate
+// this repo by literal text search and meaning written into the source is the only
+// findability layer with no index to keep fresh. A convention nobody measures decays
+// silently, so this reports the one part of it a machine can honestly check — does a
+// source file open with a module header at all.
+//
+// IT WARNS; IT NEVER FAILS. That ceiling is deliberate and is stated in the ADR: a
+// doc-comment gate that blocks a ship trains builders to write a filler line to get
+// past it, which is worse than no comment because it LOOKS like documentation.
+// Promoting this to hard-fail is an owner decision and needs its own ADR.
+//
+// What it cannot check: whether the prose is any good. Presence is a proxy. The
+// convention itself — what to write, and the worked examples — lives in
+// docs/code-conventions.md.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// First-party server/CLI/module source. Deliberately NOT scanned:
+//   *.test.js            — a test's subject is named by its filename and its cases
+//   **/public/**         — browser assets; a worthwhile but separate sweep
+//   vendor / node_modules / *.min.js / *.generated.js — not ours to annotate
+const INCLUDE_RE = /^(src|scripts|modules)\//;
+const EXCLUDE_RE = /(^|\/)(node_modules|vendor|public|public-docs)\/|\.test\.js$|\.min\.js$|\.generated\.js$/;
+
+// A header is prose that appears BEFORE any code. A shebang and a 'use strict'
+// prologue are allowed to precede it — they are not code a reader learns from.
+const SKIP_PROLOGUE_RE = /^(#!.*|['"]use strict['"];?)?$/;
+
+// Minimum words for a header to count as saying something. A bare
+// `// config.js — config` restates the filename and teaches nobody anything;
+// the threshold is low on purpose so the check stays about ABSENCE, not style.
+const MIN_WORDS = 12;
+
+// Enumerate the files to scan. The glob goes to git as an argv ARRAY, never a
+// shell string — quoting a glob as `'*.js'` is literal on cmd.exe and matches
+// nothing, which is exactly how docs-entropy.js once "passed" on every Windows
+// checkout by scanning zero files (task 1002526).
+//
+// A zero-file result is therefore treated as a SCAN DEFECT and thrown, not
+// returned: this repo tracks hundreds of source files, so an empty enumeration is
+// never real, and a lint that silently proves nothing is worse than no lint.
+function trackedSourceFiles({ run } = {}) {
+  const exec = run || ((args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }));
+  const out = exec(['ls-files', '*.js']);
+  const all = String(out).split('\n').map((s) => s.trim()).filter(Boolean);
+  if (!all.length) {
+    throw new Error('doc-comment-coverage scan defect: git ls-files returned no tracked .js files — the enumeration is broken, not the repo.');
+  }
+  return all.filter((f) => INCLUDE_RE.test(f) && !EXCLUDE_RE.test(f));
+}
+
+// Extract the leading comment block of a file, or '' when the first real token is
+// code. Handles both `//` runs and a `/* … */` block, and is CRLF-safe (every line
+// is trimmed before it is classified).
+function leadingComment(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  let i = 0;
+  while (i < lines.length && SKIP_PROLOGUE_RE.test(lines[i].trim())) i++;
+
+  const block = [];
+  if (lines[i] && lines[i].trim().startsWith('/*')) {
+    for (; i < lines.length; i++) {
+      block.push(lines[i]);
+      if (lines[i].includes('*/')) break;
+    }
+  } else {
+    for (; i < lines.length && lines[i].trim().startsWith('//'); i++) block.push(lines[i]);
+  }
+  return block.join('\n');
+}
+
+function wordCount(comment) {
+  return comment.replace(/[/*]/g, ' ').trim().split(/\s+/).filter(Boolean).length;
+}
+
+// Returns { scanned, missing:[rel], thin:[{file,words}] }.
+function scanHeaders(files = trackedSourceFiles(), read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8')) {
+  const missing = [];
+  const thin = [];
+  for (const f of files) {
+    let words;
+    try {
+      words = wordCount(leadingComment(read(f)));
+    } catch (_) {
+      continue; // a file listed by git but unreadable here is not this check's problem
+    }
+    if (words === 0) missing.push(f);
+    else if (words < MIN_WORDS) thin.push({ file: f, words });
+  }
+  return { scanned: files.length, missing, thin };
+}
+
+const MAX_LISTED = 15; // keep the warning readable; the count carries the rest
+
+// Fitness-check entry point. ALWAYS returns ok:true / hardFail:false — see the
+// header. Findings surface as warnings so a red board still means something real.
+function checkDocCommentCoverage() {
+  const { scanned, missing, thin } = scanHeaders();
+  const warnings = [];
+
+  if (missing.length) {
+    const shown = missing.slice(0, MAX_LISTED).join(', ');
+    const more = missing.length > MAX_LISTED ? ` (+${missing.length - MAX_LISTED} more)` : '';
+    warnings.push(`${missing.length} source file(s) open with no module header — give each a line saying what it does and WHY it exists (docs/code-conventions.md, ADR 0095): ${shown}${more}`);
+  }
+  if (thin.length) {
+    const shown = thin.slice(0, MAX_LISTED).map((t) => `${t.file} (${t.words}w)`).join(', ');
+    const more = thin.length > MAX_LISTED ? ` (+${thin.length - MAX_LISTED} more)` : '';
+    warnings.push(`${thin.length} header(s) under ${MIN_WORDS} words — likely a restatement of the filename rather than the reason the file exists: ${shown}${more}`);
+  }
+
+  const covered = scanned - missing.length;
+  return {
+    name: 'module header doc-comments (ADR 0095)',
+    ok: true,
+    hardFail: false, // ADVISORY BY DECISION — promoting this to blocking needs owner sign-off (ADR 0095)
+    violations: [],
+    warnings,
+    note: `${covered}/${scanned} first-party source file(s) under src/·scripts/·modules/ open with a module header saying what they do and why (ADR 0095, task 1001654). ADVISORY — this check never fails the build; tests, browser assets and vendored code are out of scope.`,
+  };
+}
+
+if (require.main === module) {
+  const r = checkDocCommentCoverage();
+  process.stdout.write(`${r.note}\n`);
+  for (const w of r.warnings) process.stdout.write(`! ${w}\n`);
+}
+
+module.exports = { checkDocCommentCoverage, scanHeaders, leadingComment, wordCount, MIN_WORDS };

package/scripts/gds/fitness.js

@@ -1308,6 +1308,11 @@ const CHECKS = [
   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)
+  // 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.
+  // Making it blocking is an owner decision and needs its own ADR.
+  require('./doc-comment-coverage.js').checkDocCommentCoverage,
 ];
 
 function runAll() {

package/scripts/gds/me.js

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
-// Show the current builder profile, leaderboard top 10, and active claim.
+// scripts/gds/me.js — "who am I, and what am I holding?" from the terminal
+// (ADR 0095 backfill).
+//
+// WHY. A builder's identity lives on the SERVER (rank is read fresh from the DB on
+// every request — ADR 0016), so a local file can never answer this honestly. This
+// CLI asks the API instead: profile + rank, the leaderboard top 10, and — the part
+// that actually matters mid-session — the ACTIVE CLAIM, so an agent resuming work
+// can confirm what it is allowed to be changing before it changes anything.
+//
+// Read-only. It prints; it never mutates a claim (that is `claim.js`/`ship.js`).
 
 const { cliClient, requireSession } = require('./cli-lib');
 

package/src/bongos/routes/auth.js

@@ -1,3 +1,31 @@
+// src/bongos/routes/auth.js — every way a builder or a device proves who they are
+// (ADR 0095 backfill).
+//
+// WHY. This is the front door to the trust boundary (ADR 0016): authority lives in
+// `builders.rank` on the DB and is checked server-side per request, but a request
+// can only be checked once it carries an identity — minting that identity is this
+// file's whole job. Four flows land here, and they exist separately because the
+// caller's shape differs each time:
+//
+//   - /auth/device/*      the CLI on a builder's machine (GitHub Device Flow, plus
+//                         the IdP `exchange` variant) — no browser to redirect.
+//   - /auth/web/*         the builders' hall in a browser (OAuth redirect + cookie).
+//   - /auth/discord/*     LINKING an existing builder to a Discord id for role sync.
+//                         It is NOT a way to sign in — Discord sits OUTSIDE the trust
+//                         boundary (ADR 0032), so it can never mint a session.
+//   - /auth/app-pair/*    the Dev Box desktop app pairing to its builder (ADR 0045).
+//
+// TWO INVARIANTS worth keeping in view before editing:
+//   - `/auth/cli-token/issue` mints a CLI bearer from a browser COOKIE, never from a
+//     bearer. A leaked CLI token must not be able to extend its own life.
+//   - Logout/revoke are session-destroying and must stay synchronous with rank
+//     changes: a demotion calls `revokeAllSessionsForBuilder` so a stale token
+//     cannot outlive the authority it was issued under.
+//
+// `escapeHtml` + `renderAuthErrorPage` below render the OAuth failure branches as a
+// small standalone page (no template engine, no runtime deps) so a visitor who
+// fails auth sees something coherent instead of a text/plain stack trace.
+
 const express = require('express');
 const crypto = require('node:crypto');
 

package/src/bongos/routes/builders.js

@@ -1,3 +1,27 @@
+// src/bongos/routes/builders.js — the roster, the public profile, and the rank
+// mutations (ADR 0095 backfill).
+//
+// WHY. Two very different things share this file because they share a subject —
+// the builder as an IDENTITY, distinct from the work they do:
+//
+//   - READS  — /builders/roster · /builders/directory · /builders/:id/profile ·
+//              per-builder claims, grades and onboarding. Who is here, what have
+//              they shipped, how are they doing.
+//   - WRITES — PATCH /builders/:id/rank · /status · /budget. These are the
+//              highest-authority mutations in the platform: rank IS permission
+//              (ADR 0016), so a bug here is a privilege-escalation bug, not a
+//              display bug. They stay in CORE db (`setBuilderRank`,
+//              `deactivateBuilder`) precisely because identity and authority are
+//              kernel concerns and must not be reachable through a module.
+//
+// Promotion is deliberately single-rung (`singleRungPromotionError`) and every
+// change writes an audit row — a builder cannot be walked from newcomer to Archon
+// in one call, and no rank change is untraceable.
+//
+// The work-shaped reads (claims, grade breakdown, shipped counts) belong to the
+// lifecycle module (BV1.R86) and are resolved through the `lifecycle` kernel port
+// (`lc()`), never a direct module require — the core↔module boundary rule.
+
 const path = require('node:path');
 const { execFile } = require('node:child_process');
 const express = require('express');

package/src/bongos/routes/healthz.js

@@ -1,3 +1,13 @@
+// src/bongos/routes/healthz.js — the unauthenticated liveness probe (ADR 0095 backfill).
+//
+// WHY. Every uptime checker, the status dashboard, and the deploy smoke need one
+// endpoint they can hit with no credential to answer "is the process up, and did
+// it come up with auth wired?". It is deliberately the thinnest router in the
+// tree: no DB call, no rank gate, no branding read — anything it touches becomes
+// a new way for the health check itself to go down. `auth_configured` is the one
+// piece of state it reports, because a process that boots WITHOUT working auth
+// (missing IdP creds) is live but useless, and that failure is otherwise silent.
+
 const express = require('express');
 const auth = require('../auth');
 

package/src/bongos/routes/me.js

@@ -1,3 +1,24 @@
+// src/bongos/routes/me.js — GET /me, the one call that tells a builder everything
+// about themselves (ADR 0095 backfill).
+//
+// WHY. The hall's first paint needs identity, rank, credits, streak, achievements,
+// onboarding checklist, active claims, grade trend and preferences all at once.
+// Fetching those as eight round-trips made the hall slow and the client
+// order-dependent, so `/me` is a deliberate AGGREGATOR — one request, one shape.
+//
+// THE COST OF THAT CHOICE, and the thing to respect when editing: most of the
+// slices it returns are no longer core. They live in modules carved out per ADR
+// 0093 (`reward` → economy, `builder-settings` → prefs/needs, `onboarding` →
+// checklist, `lifecycle` → claims/estimation/grades), and core may never require a
+// module file directly. Every slice therefore resolves a kernel PORT through
+// `module-seams`, per call. Use `resolveOptional` and degrade gracefully: an
+// instance running without that module must still render `/me`, just without the
+// slice — which is why a missing provider yields the unset/default shape rather
+// than a 500.
+//
+// The per-builder `/me/*-prefs` write routes are NOT here — they moved into
+// modules/builder-settings/ (BV1.R80). This file kept only the read aggregation.
+
 const express = require('express');
 const auth = require('../auth');
 const db = require('../db');

package/src/bongos/routes/optimizer.js

@@ -1,3 +1,15 @@
+// src/bongos/routes/optimizer.js — POST /session/optimize: recommend a session's
+// worth of work to one builder (ADR 0095 backfill).
+//
+// WHY. A builder asking "what should I do with the next two hours?" would
+// otherwise read the whole claimable list and guess. This hands the question to
+// `../optimizer.js`, which picks a parallel-safe set against a time budget.
+//
+// READ-ONLY BY DESIGN: it recommends, it never claims. Claiming stays an explicit
+// builder act through the lifecycle (`/builder-claim`), so a recommendation can
+// never quietly lock work to someone. That is why the gate here is only
+// `requireBuilder` — suggesting work to yourself needs no rank.
+
 const express = require('express');
 const auth = require('../auth');
 const optimizer = require('../optimizer');

package/src/bongos/routes/public.js

@@ -1,4 +1,22 @@
-// Read-only public surface for status.amazonprimea.com. No auth.
+// src/bongos/routes/public.js — the anonymous, read-only surface that powers the
+// status dashboard (ADR 0095 backfill).
+//
+// WHY. The instance publishes its build progress to the world — versions, shipped
+// work, cost, leaderboard, grades, repo health — and that audience has no account.
+// So this router carries NO auth gate at all, which makes it the one place where a
+// projection bug leaks private work state to the public internet.
+//
+// THE RULE THAT KEEPS IT SAFE: nothing here returns a raw DB row. Every response
+// goes through an explicit `projectPublic*` allowlist (`projectPublicTask`,
+// `projectPublicBlocker`, `projectPublicIdea`) that names the fields it will
+// disclose, so a column added to `tasks` later is private by default rather than
+// silently published. A task/idea/blocker is only visible when its own `public`
+// flag is set. Rate-limited (`publicReadRateLimitMiddleware`) and CORS-scoped
+// (`corsPublicGet`) because an unauthenticated surface is also the cheapest one to
+// scrape.
+//
+// The host it serves is NOT hardcoded — the dashboard origin comes from branding
+// (`domains.statusOrigin`); this file must stay brand-neutral (ADR 0062 §3).
 
 const express = require('express');
 const db = require('../db');