@bongos/core 1.19.359 → 1.19.361

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 312 endpoints across 51 route files.
+> **Generated from the live route files** — the route file is authoritative. 315 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`.
@@ -143,6 +143,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/claims/batch/release` | `any-builder` | `claim_ids`, `force` | Bulk release (task 1758) — the batch twin of resolve(outcome='abandoned'). |
 | POST | `/api/bongos/claims/batch/validate` | `any-builder` | `task_ids` | Dry-run validate (task 1758) — read-only twin of claimTasksBatch's pre-flight checks. |
 
+## `closeness` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/closeness/for-me` | `any-builder` | — | , and OWN-SCOPED — your own graph, never someone else's. |
+| GET | `/api/bongos/closeness/weights` | `any-builder` | — | the MODEL is not private, and publishing it is the whole point of the weights being data. |
+| GET | `/api/bongos/closeness/with/:builderId` | `any-builder` | — | One pair — "why am I close to THEM", asked directly rather than by paging the graph. |
+
 ## `copy-desk` (4)
 
 | Method | Path | Rank | Body | Description |

package/docs/file-map.md

@@ -45,6 +45,7 @@
 │   │   └── 0001…0120-*.md       ← 133 ADR files (a handful of numbers collide — see README.md's disambiguation note; README.md has the live list)
 │   ├── architecture.md          ← §10 detail: live infra, app stack, DB schema, Bongos API (split out V3.R86)
 │   ├── canonical-permissions.md ← rank ladder + trust boundary reference (read-only mirror; DB enforces)
+│   ├── code-conventions.md      ← ADR 0095 (task 1001654): the doc-comment convention — every module a header, every public symbol a line, saying WHAT it does and WHY it exists. The findability layer agents grep. Advisory only; the nudge is scripts/gds/doc-comment-coverage.js
 │   ├── design/                  ← game design docs (V2 visual redesign cluster)
 │   │   ├── container-exterior.md ← (#641) container building exterior: two-storey stacked-container structure, glass facade, deck, rooftop
 │   │   └── container-interior.md ← (#645) container building interior: layered industrial shell + aqua wave floor + boutique display; palette reconciled to ADR 0044
@@ -180,6 +181,7 @@
 │       ├── worktree.js          ← (task 1002809) junction-safe worktree add/remove/list — outside-repo worktrees get a node_modules junction via node (no shell quoting), removed BEFORE `git worktree remove`
 │       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)
 │       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`
+│       ├── doc-comment-coverage.js ← ADR 0095 / task 1001654: the ADVISORY doc-comment nudge (fitness Check 28) — reports source files under src/·scripts/·modules/ that open with no module header. Never hard-fails: a doc-comment gate that blocks a ship buys filler prose, and making it blocking needs owner sign-off + its own ADR. CRLF-safe (unlike docs-entropy.js); an empty enumeration throws as a scan defect
 │       ├── copy-inventory.js  ← R01 of goal 1000074 (the artist's loop): the COPY REGISTRY — every user-facing string across the hall / status / landing surfaces, each row naming the render path that shows it (html-text · html-attr · js-markup · js-notice · js-text-assign) + a stable id that survives a move. Writes docs/copy-registry.json + docs/copy-inventory.md; `--check` fails on drift. Precision over recall: a JS literal with no render path is not listed
 │       ├── gen-diagrams.js      ← generates the 5 onboarding diagrams (`.mmd`/`.svg`/`.png` + `assertions.json`) from templates in this file — never hand-edit a `.mmd`/assertions.json; runs on deploy
 │       ├── gen-api-docs.js      ← ADR 0109: generates `docs/api/openapi.json` + `docs/api-reference.md` from the live route files via `route-rank-check.js` introspection, so the API reference cannot drift from what the server actually mounts

package/modules/autonomy/routes/autonomy.js

@@ -1,3 +1,22 @@
+// modules/autonomy/routes/autonomy.js — GET /autonomy/precheck: should an
+// autonomous run start at all? (ADR 0095 backfill).
+//
+// WHY. The nightly routines boot real models that spend real money, so the
+// go/no-go decision must be made BEFORE any model starts — and must itself be
+// free. This is Step 0 of the Multi-Agent System (ADR 0024, System 3): a $0
+// deterministic gate over live signals (is there claimable work, is there budget
+// left, has anything actually changed since the last `go`), exposed over HTTP so
+// an operator can ask the same question the cron asks.
+//
+// TWO SAFETY PROPERTIES worth preserving: it is INERT until `OTB_AUTONOMY_ENABLED=1`
+// (an un-armed instance always answers `go`, so nothing here can start work by
+// accident), and it is Archon-gated, because the answer decides autonomous spend.
+//
+// The decision logic is not here — it lives in the gate CLI
+// `scripts/gds/autonomy-gate.js`, deliberately OUTSIDE the module boundary, since
+// gathering signals means reading ideas/economy/lifecycle, which a modules/ file
+// may not do. This route is a thin wrapper over its `precheck`.
+
 const express = require('express');
 // The published doorway — requireBuilder / requireRank live on the doorway surface
 // (a module never reaches into core auth directly; the one-way boundary, ADR 0083).

package/modules/dev-box/app/src/config.js

@@ -1,4 +1,16 @@
-// devbox-app/src/config.js — runtime configuration resolution.
+// modules/dev-box/app/src/config.js — where the desktop app decides which server
+// it is talking to, and what version of itself it is (ADR 0095 backfill).
+//
+// WHY. The tray app ships as a built artifact to builders' machines, so it cannot
+// be configured by editing a file next to it — yet it still has to point at a dev
+// or staging API during development, and at the origin a builder actually signed
+// in to afterwards. `apiBase` resolves that in a fixed precedence (explicit env →
+// the base recorded in the session file at sign-in → the branded production
+// default) so a developer override is possible without ever overriding a real
+// builder's session.
+//
+// The production default comes from `./brand`, which is GENERATED from the
+// instance's branding at build time — this file must not hardcode an origin.
 
 const brand = require('./brand');
 

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

@@ -251,6 +251,14 @@ function createClient(opts = {}) {
       // POST /claims/batch/validate — rank: any-builder — POST /claims/batch/validate
       postClaimsBatchValidate: (args) => request("POST", "/claims/batch/validate", { hasBody: true }, args),
     },
+    "closeness": {
+      // GET /closeness/for-me — rank: any-builder — GET /closeness/for-me
+      getClosenessForMe: (args) => request("GET", "/closeness/for-me", { hasBody: false }, args),
+      // GET /closeness/weights — rank: any-builder — GET /closeness/weights
+      getClosenessWeights: (args) => request("GET", "/closeness/weights", { hasBody: false }, args),
+      // GET /closeness/with/{builderId} — rank: any-builder — GET /closeness/with/:builderId
+      getClosenessWithBuilderId: (args) => request("GET", "/closeness/with/{builderId}", { hasBody: false }, args),
+    },
     "copyDesk": {
       // POST /copy-desk/flags — rank: any-builder — POST /copy-desk/flags
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),

package/modules/economy/achievements.js

@@ -1,5 +1,26 @@
 'use strict';
 
+// modules/economy/achievements.js — what a builder has unlocked, and the reads that
+// display it (ADR 0095 backfill).
+//
+// WHY. Credits pay for work; achievements recognise SHAPES of work that a
+// per-task payout cannot see — a streak sustained, a first ship, a change that
+// removed more than it added. They are the gamification half of the economy.
+//
+// THE ONE STRUCTURAL RULE, and the reason the evaluators look the way they do:
+// an unlock must be ATOMIC with the thing that earned it. Each `evaluateAfter*`
+// therefore takes the CALLER'S transaction `client` as its first argument and runs
+// inside the lifecycle's existing `withTx` — it never opens its own. A separate
+// transaction could commit an unlock for a ship that then rolled back, or drop one
+// for a ship that succeeded. Callers reach these through the `reward` kernel port,
+// never by importing this file (core may not require a module — ADR 0093).
+//
+// The GETTER slice below (`listAchievements`, `getBuilderAchievements`,
+// `getLeaderboardWithAchievements`, `getLockedAchievementsProgress`,
+// `renderProgressText`) is the opposite posture: plain reads for the hall and the
+// public leaderboard, reaching the shared pool through the doorway rather than a
+// caller's tx.
+
 const { SUBTRACTOR_THRESHOLD } = require('./policy');
 
 // Achievement evaluation — runs inside existing DB transactions so unlocks

package/modules/economy/routes/cost.js

@@ -1,3 +1,19 @@
+// modules/economy/routes/cost.js — POST /cost: record what a session actually spent
+// (ADR 0095 backfill).
+//
+// WHY. Builder pay is cost-plus (ADR 0054: `round(true_cost_usd × 1.20)`), so the
+// cost ledger is not telemetry — it is the input to real money. A session that
+// fails to log its spend under-pays its builder and under-states the project's
+// burn; one that logs twice over-pays. That is why the write is IDEMPOTENT: a
+// retried or resumed ship must not book the same spend again.
+//
+// This route is only the doorway; `../cost.js` owns `logCost` and is the single
+// writer to `cost_log`. Keep it that way — a second writer is how two sources of
+// truth for money start.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; `../cost` is an intra-module sibling.
+
 const express = require('express');
 // Carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2): auth gates + request
 // validators reach through the published doorway; the cost_log writer is an

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/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/closeness-weights.json

@@ -0,0 +1,64 @@
+{
+  "_comment": [
+    "The closeness scoring model, as DATA (task 1003174 / C04, goal 1000075; criterion",
+    "collab-closeness-consented, ADR 0187 §2). The owner's decision was explicit that the",
+    "weights are data rather than constants buried in a function, so they can be reviewed",
+    "and changed without a code-archaeology dig. This file IS that review surface, and it",
+    "is served verbatim by GET /closeness/weights so the number can always be audited",
+    "against the model that produced it.",
+    "",
+    "HOW A SCORE IS BUILT. Each signal counts real events between two builders. That count",
+    "is divided by the signal's `saturation` and clamped to 1, so a signal is 'full' once",
+    "it has happened `saturation` times and no single runaway count can dominate. The",
+    "closeness score is the weighted sum of those clamped values, expressed 0..1.",
+    "",
+    "WEIGHTS ARE RENORMALISED OVER AVAILABLE SIGNALS. A signal with `available: false`",
+    "cannot be measured yet, and its weight is redistributed across the rest rather than",
+    "counted as zero. Counting it as zero would depress every pair's score identically and,",
+    "worse, the explanation would read as 'you never talk' when the truth is 'nothing here",
+    "can see whether you talk'. The explanation names every excluded signal for this reason.",
+    "",
+    "CHANGING A WEIGHT is a product decision about how the system describes real people to",
+    "each other. Weights should sum to 1 across ALL signals (the test asserts it); the",
+    "renormalisation handles the available subset at read time."
+  ],
+
+  "version": 1,
+  "scale": "0..1, rendered as 0..100 on any surface that shows a number",
+
+  "signals": [
+    {
+      "key": "co_claim",
+      "label": "Worked the same goal at the same time",
+      "description": "You each held an active claim on a task in the same goal, and those claims overlapped in time. This is the live version of working alongside someone: you were both holding work in the same place at once.",
+      "weight": 0.3,
+      "saturation": 5,
+      "available": true
+    },
+    {
+      "key": "co_build_session",
+      "label": "Sat down to it in the same stretch",
+      "description": "You logged work sessions on tasks in the same goal that overlapped in time. A claim can sit open for days; a session is the hours actually spent, so this is the closer measure of being present together. The owner's decision (ADR 0187 §3) is that the unit of collaboration is the GOAL, never a shared claim — nobody co-runs a claim, and this signal does not pretend they do.",
+      "weight": 0.3,
+      "saturation": 5,
+      "available": true
+    },
+    {
+      "key": "shipped_together_goal",
+      "label": "Shipped into the same goal",
+      "description": "Distinct goals where you have each shipped at least one task. Unlike the two above, this ignores timing entirely — it is the durable record that you both built the same thing, even months apart.",
+      "weight": 0.25,
+      "saturation": 3,
+      "available": true
+    },
+    {
+      "key": "comms_mention",
+      "label": "Talked to or mentioned each other",
+      "description": "Messages and mentions between you. NOT MEASURABLE YET: this needs the Discord-into-the-hall mirror, which is C06 of this goal (task 1003176) and is still an open decision. Until it lands this signal is unavailable and its weight is redistributed across the others — it is never silently counted as zero, because 'we cannot see your conversations' and 'you never speak' are different facts and only one of them is true.",
+      "weight": 0.15,
+      "saturation": 20,
+      "available": false,
+      "blocked_by": "task 1003176 (C06 — Discord chat mirrors INTO the hall)"
+    }
+  ]
+}