@bongos/core 1.19.360 → 1.19.361

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.360",
-  "core_contract": "1.19.360",
-  "source_commit": "5bf79048217d490a0d571e749290b110875a0bc8",
+  "core_version": "1.19.361",
+  "core_contract": "1.19.361",
+  "source_commit": "52986b2ce513fb2d4550b8ad303333c6f02daafb",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T17:58:51.325Z",
+  "built_at": "2026-08-25T18:21:25.463Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 330,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1523,
+    "functional_verbatim": 1525,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1875,
-  "tree_sha256": "15871fd570e735b51bbfd212b53fcc55faa1479569e51e6d2c7179f407bb58d3",
+  "file_count": 1877,
+  "tree_sha256": "ec6c330506400cf439253a53651300f6be6176f28375130cc28ba0949823736c",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1597,7 +1597,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "74102dbb050a3e9df3ade05ef25d8704319e7b1fac801b784f1ed8c3ea1b7566"
+      "sha256": "1cda168698104ff12fbe75a28a5f76fd11a2d7311c8ba32ba985874dbff65570"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2537,7 +2537,7 @@
     {
       "path": "modules/autonomy/routes/autonomy.js",
       "mode": "0000644",
-      "sha256": "aa0c84ab532bbc946d80cf625d130b9ef2ba8e2e54cd320945aa1dda6b210488"
+      "sha256": "ae9aff3f47f2b5801f9839493549b912424e8b22c153e91afcf3376a1cc4fb4d"
     },
     {
       "path": "modules/builder-settings/CLAUDE.md",
@@ -2827,7 +2827,7 @@
     {
       "path": "modules/dev-box/app/src/config.js",
       "mode": "0000644",
-      "sha256": "a29e9b2ac8353ec20e572597a288078c1e31339651cfdf396f71f3ae47495209"
+      "sha256": "689935bb1901be4f31877207e7885be21630b9eafa6afe5fa025b1ff1dce4f83"
     },
     {
       "path": "modules/dev-box/app/src/gds-client.js",
@@ -3032,7 +3032,7 @@
     {
       "path": "modules/economy/achievements.js",
       "mode": "0000644",
-      "sha256": "fc270efbe9439442d2f51490a8a292313e3f66c7b5d33c28cd9e7f929f56b307"
+      "sha256": "000cb76c8bfd4a7a6f3544f4fae923691a7596b6caed0af3b324df91ff72dfcb"
     },
     {
       "path": "modules/economy/cost-classify.js",
@@ -3077,12 +3077,12 @@
     {
       "path": "modules/economy/routes/cost.js",
       "mode": "0000644",
-      "sha256": "7b85120b73500c91e98e8a580709d7f6a0fddad784d19d4ea75b2828cff508c7"
+      "sha256": "4113b736359f09d6869795800d52394603823b570263dd1852281b35e6bb2485"
     },
     {
       "path": "modules/economy/routes/leaderboard.js",
       "mode": "0000644",
-      "sha256": "36d91233de89844b129f08a5fe2e6f5510b0811a1e2ebc99b9d2e12d878bad65"
+      "sha256": "e8c6baf3e5bbd54c9dc79f74a9a562a6c550e75952bbd1010a11bd26dec17833"
     },
     {
       "path": "modules/economy/routes/reward.js",
@@ -3902,12 +3902,12 @@
     {
       "path": "modules/ideas/routes/blockers.js",
       "mode": "0000644",
-      "sha256": "2247bb4499e6296fca8ccde3614b6726a50435786fc3cf634eaacd35982ef3f4"
+      "sha256": "61c7692449f16ce103762d703f2eb5b0412cf1ba393d9a4d3724a14830747ab5"
     },
     {
       "path": "modules/ideas/routes/inbox.js",
       "mode": "0000644",
-      "sha256": "0215d0eadab112c023af4e67a1fa81060b0844334d29e3943f8c388f64cda533"
+      "sha256": "cfe139439ef93d42718354fd10781e0aa11f5f8a730d64dbf09c7232305daaaf"
     },
     {
       "path": "modules/ideas/routing.js",
@@ -4127,7 +4127,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "fb5dda00e0c378e2fb8b3190fdeaf4562be65097895bd67b68e67428a14c8297"
+      "sha256": "6bc32c6ae4029748d6099701f25fc17d5875b2ff005de5ad2cacbc023092c32c"
     },
     {
       "path": "modules/lifecycle/routes/closeness.js",
@@ -4187,12 +4187,12 @@
     {
       "path": "modules/lifecycle/routes/tasks.js",
       "mode": "0000644",
-      "sha256": "b29d9bffce9c81e0f5e02ea2da387e15dc6f0bf8d96820931c29275861eeaf66"
+      "sha256": "e27a8ce945d8d7e68d618e60b3cac72af9722588affb876fa22df0f525ec3dc5"
     },
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "044ca86e5605c19dd8e523da9eb061b4a90ed0af199ec1288c3c5f1b1bb8f46b"
+      "sha256": "77183a22af7bd1f506f2b3d2cba176e89af578ce5aa2da6abe0ee353e3ec8cbd"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -4267,7 +4267,7 @@
     {
       "path": "modules/memory/routes/learnings.js",
       "mode": "0000644",
-      "sha256": "1772c54a56e3ceb4fe10b96d036c4b51ea102f5a5c989db0ad188bbf2adc25d6"
+      "sha256": "c205d67b5fe840af28cd7f6b9a02fa2f8a8287a992bd009bbcd6f7bcf733043b"
     },
     {
       "path": "modules/memory/routes/memory.js",
@@ -4847,12 +4847,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "26d9ebcd21d9fa6f7634d877e028131c6beb6e144d3055645e159d81e94c64a3"
+      "sha256": "f1a896b55fbf77414ebf57311585f596768d6278a3543e0e3cc2b3b29e9ddc5e"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2f3161d67426337fc350354987df123ccc867ebbb15ae4bf28e3082f80edbdcd"
+      "sha256": "dd516fa3534fbadfa1dc22fabae2226206d88e1857b5a346dad8cbfa45c89ca9"
     },
     {
       "path": "public-docs/index.html",
@@ -5352,7 +5352,7 @@
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "81c4f4795291f9daef800dcc17b65aec8b82f6281434b0f3e52655789a481072"
+      "sha256": "68f2c65ac9297328f44927ccb9a40a0fa536b91d9056aaa980a92149a64ce47c"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -5479,6 +5479,11 @@
       "mode": "0000644",
       "sha256": "9cf6c8ead8129799d17a18eadedf0423828cb457fa07fd317dcf2853254861e9"
     },
+    {
+      "path": "scripts/gds/doc-comment-coverage.js",
+      "mode": "0000644",
+      "sha256": "17d0fbc570b6dea3dfcf2425058510cd70b23f066fdf1ed751072852713284a3"
+    },
     {
       "path": "scripts/gds/docs-entropy.js",
       "mode": "0000644",
@@ -5537,7 +5542,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "91b125de588406e6b93f8cc29d4d53891932a52744a6e92824459c734f747f16"
+      "sha256": "e38069a6eee1072438d745634cdae405c57c20b8261f133d4afa0440b1d3d545"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -5732,7 +5737,7 @@
     {
       "path": "scripts/gds/me.js",
       "mode": "0000644",
-      "sha256": "f7246b3d527692913b164c07b6040013e9152302da9c7bff7274de8cb1295da5"
+      "sha256": "e2591cd7a867120cbf5bda0ba7460508ab0342c3dfcdaecec88a29290fec1566"
     },
     {
       "path": "scripts/gds/memory-map.js",
@@ -6602,7 +6607,7 @@
     {
       "path": "src/bongos/routes/auth.js",
       "mode": "0000644",
-      "sha256": "be7b68b01d82fb3ac714d92f22b6adbc1788fb47b9ce8345d4cf14bd1fb92e94"
+      "sha256": "39392e56faf8fb7efb52686a006d3dd5dbb4b965dd81402d6a4d7a7c173923bb"
     },
     {
       "path": "src/bongos/routes/backup.js",
@@ -6612,7 +6617,7 @@
     {
       "path": "src/bongos/routes/builders.js",
       "mode": "0000644",
-      "sha256": "afc0f563da646c6a2d7c3b1adeaeaaf19cf2db48251005f6f003511d2dba65e9"
+      "sha256": "38760c782a379b7a977b9ed4e0af00726d4080ebedf9ea071cefe8d90ceb69b1"
     },
     {
       "path": "src/bongos/routes/github.js",
@@ -6622,7 +6627,7 @@
     {
       "path": "src/bongos/routes/healthz.js",
       "mode": "0000644",
-      "sha256": "26f4992c484d2fc5882131c695c4173db950e4c815424fad68385bfa64fa7ab8"
+      "sha256": "5d22031a1acd21a9a244d9f68809450e811fe6a6c98a2f4e2330452515757c37"
     },
     {
       "path": "src/bongos/routes/instance.js",
@@ -6642,7 +6647,7 @@
     {
       "path": "src/bongos/routes/me.js",
       "mode": "0000644",
-      "sha256": "1d9e11f3ca4d08033bc116e79ccf66e901ec4e8c48b61d969eeeceface1f9da1"
+      "sha256": "0006bf8ec2430532a72c194bcc7517b4008d00b8fa4a73e9a77bc2c6a10c6d26"
     },
     {
       "path": "src/bongos/routes/modules.js",
@@ -6652,12 +6657,12 @@
     {
       "path": "src/bongos/routes/optimizer.js",
       "mode": "0000644",
-      "sha256": "6021253819fcd629e1a14e2027bdf80a2006d9fcb83cf90dbd891d6e542a94ec"
+      "sha256": "22cc9a90dd67c358ec6f23aed86a3053548fbd5f0dfdce09eefc48e215b63a06"
     },
     {
       "path": "src/bongos/routes/public.js",
       "mode": "0000644",
-      "sha256": "b4f0f1d10bebd66259b48bb72af121ae9ef94e774c8b840456aa7c2e0aabdf52"
+      "sha256": "0127967b6e345e93cb576702f472534d7985d7f2d8a0d7031a865c5c1d815576"
     },
     {
       "path": "src/bongos/routes/security.js",
@@ -6712,7 +6717,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "4cb8b8e962fd1891d9fbbb446048dba025754a73b1a3c313e2e586f14f843b13"
+      "sha256": "71ef74c90f0f0d5d092a1c3fa586f564a4fec242da73acf1d310a7323e960cce"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7519,6 +7524,11 @@
       "mode": "0000644",
       "sha256": "4e68c67489daa51167b8d738a36f7c0187016b342e8a57731d14241563262878"
     },
+    {
+      "path": "tests/doc_comment_coverage.mjs",
+      "mode": "0000644",
+      "sha256": "f51d3c747fbb3201ed3388abb1386d0547c3a3be70d7ad7237b9a0f5fdd2347b"
+    },
     {
       "path": "tests/docs_entropy.mjs",
       "mode": "0000644",

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

@@ -1150,8 +1150,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.360'; // 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');

package/tests/doc_comment_coverage.mjs

@@ -0,0 +1,87 @@
+// tests/doc_comment_coverage.mjs — the ADR 0095 doc-comment nudge detects real
+// gaps, stays advisory, and survives CRLF (task 1001654).
+//
+// Three things are pinned here, each a way this check could quietly become useless:
+//   1. It must stay ADVISORY. The ADR says a doc-comment gate must not block a ship
+//      without owner sign-off, because a blocking gate buys filler prose. A future
+//      edit that flips hardFail should fail this test and force that decision.
+//   2. It must be CRLF-safe. The sibling scanner docs-entropy.js finds ZERO
+//      markdown headings on a Windows checkout because its regex breaks on a
+//      trailing \r; this check reads source files the same way and must not
+//      repeat it.
+//   3. An empty enumeration is a scan defect, not a clean pass (the task 1002526
+//      lesson: a lint that scans nothing reports success forever).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { checkDocCommentCoverage, scanHeaders, leadingComment, wordCount, MIN_WORDS } =
+  require(path.join(ROOT, 'scripts', 'gds', 'doc-comment-coverage.js'));
+
+const FILES = {
+  'src/no-header.js': "const x = require('y');\nmodule.exports = x;\n",
+  'src/code-first.js': 'const a = 1;\n// a comment AFTER code is not a header\n',
+  'src/thin.js': '// config.js — config.\nconst a = 1;\n',
+  'src/good.js': '// src/good.js — does the thing.\n//\n// WHY. It exists because the other thing could not do it safely.\nconst a = 1;\n',
+  'src/prologue.js': "#!/usr/bin/env node\n'use strict';\n// src/prologue.js — a real header stating what this does and why it exists.\nconst a = 1;\n",
+  'src/block.js': '/*\n * src/block.js — a block-comment header that explains what this file does\n * and the reason it exists at all.\n */\nconst a = 1;\n',
+};
+const read = (rel) => FILES[rel];
+
+test('a file with no leading comment is reported missing', () => {
+  const { missing } = scanHeaders(Object.keys(FILES), read);
+  assert.ok(missing.includes('src/no-header.js'));
+});
+
+test('a comment that follows code is NOT a header', () => {
+  // Otherwise any stray inline note anywhere in the file would count as coverage.
+  assert.equal(leadingComment(FILES['src/code-first.js']), '');
+  const { missing } = scanHeaders(Object.keys(FILES), read);
+  assert.ok(missing.includes('src/code-first.js'));
+});
+
+test('a header that only restates the filename is flagged thin, not missing', () => {
+  const { thin, missing } = scanHeaders(Object.keys(FILES), read);
+  assert.ok(!missing.includes('src/thin.js'));
+  assert.ok(thin.some((t) => t.file === 'src/thin.js' && t.words < MIN_WORDS));
+});
+
+test('a shebang + use-strict prologue may precede the header', () => {
+  const { missing, thin } = scanHeaders(['src/prologue.js'], read);
+  assert.deepEqual(missing, [], 'a CLI opening with #! still has a header');
+  assert.deepEqual(thin, []);
+});
+
+test('block-comment headers count too', () => {
+  const { missing, thin } = scanHeaders(['src/block.js'], read);
+  assert.deepEqual(missing, []);
+  assert.deepEqual(thin, []);
+});
+
+test('CRLF files are parsed identically to LF — the docs-entropy trap', () => {
+  // docs-entropy.js finds zero headings on a CRLF checkout because `.` does not
+  // match \r and `$` (no /m) only matches end-of-input. Reading source the same
+  // naive way would make this check report full coverage on Windows regardless of
+  // the truth, so LF and CRLF must agree exactly.
+  const lf = '// src/x.js — states what this file does and the reason it exists.\nconst a = 1;\n';
+  const crlf = lf.replace(/\n/g, '\r\n');
+  assert.equal(wordCount(leadingComment(crlf)), wordCount(leadingComment(lf)));
+  assert.ok(wordCount(leadingComment(crlf)) >= MIN_WORDS, 'a real CRLF header must not read as thin');
+});
+
+test('the check is ADVISORY — it never fails the build (ADR 0095)', () => {
+  const r = checkDocCommentCoverage();
+  assert.equal(r.hardFail, false, 'promoting this to blocking needs owner sign-off + its own ADR');
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.violations, [], 'findings surface as warnings, never violations');
+});
+
+test('the live repo scan actually reads files (never a silent empty scan)', () => {
+  const r = checkDocCommentCoverage();
+  const scanned = Number(/^(\d+)\/(\d+)/.exec(r.note)?.[2] ?? 0);
+  assert.ok(scanned > 100, `expected hundreds of scanned files, got ${scanned} — an empty scan proves nothing`);
+});