@bongos/core 1.19.359 → 1.19.361

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.359",
+  "version": "1.19.361",
   "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');

package/src/module-api.js

@@ -1148,8 +1148,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.357 with no explicit bump. run 32872551850. (task 1002620)
 //   1.19.359 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.358 with no explicit bump. run 32877754251. (task 1002620)
+//   1.19.360 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.359 with no explicit bump. run 32881040669. (task 1002620)
+//   1.19.361 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.360 with no explicit bump. run 32883230235. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.359'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.361'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');