@bongos/core 1.19.382 → 1.19.384

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.382",
-  "core_contract": "1.19.382",
-  "source_commit": "e25777564172174924d9ee444d920a7c1b6dee44",
+  "core_version": "1.19.384",
+  "core_contract": "1.19.384",
+  "source_commit": "c17ffedef449a2cb392b9bedc87fa31f1746625a",
   "source_ref": "HEAD",
-  "built_at": "2026-08-27T16:42:17.638Z",
+  "built_at": "2026-08-27T21:02:17.519Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 336,
+    "docs_redacted": 338,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1598,
+    "functional_verbatim": 1603,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1956,
-  "tree_sha256": "0f3a95aa9c80905da7b7ec21e7cf6edfa3208ae622fe0674fcdb36cbc9319dd5",
+  "file_count": 1963,
+  "tree_sha256": "d6620f625c1c0969033c8326d7e5d9490f054072e6a6d0eecef66552c2025290",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1469,10 +1469,15 @@
       "mode": "0000644",
       "sha256": "65bd3a60b8d313af7ea69acf7fe9a522a15a144c4395b3788bd3f82cc20e8351"
     },
+    {
+      "path": "docs/adr/0195-adr-numbers-are-checked-like-migration-numbers.md",
+      "mode": "0000644",
+      "sha256": "bef44bdf75d61a0e7f076b78d384c4523cb706e5a1023768daa232feee6898aa"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "7f7354c2597bd982d92e0008595e05642c8ccc05c1e9446388c304e80b142626"
+      "sha256": "ad42cce140bb167b6702b8181d1e31ca39f537dca3f294440fcc53ece97f47d3"
     },
     {
       "path": "docs/api-reference.md",
@@ -1539,6 +1544,11 @@
       "mode": "0000644",
       "sha256": "90bed9a9f3859f7cfc6dd8a0e23e70adeda5854be0b10f8208d60a96c83403b3"
     },
+    {
+      "path": "docs/design/landing-page-direction-v2.md",
+      "mode": "0000644",
+      "sha256": "d3d921b7cbdbf929248f7c8e143241bf762d8a17c535ab0300eb1fd7ec432b0a"
+    },
     {
       "path": "docs/design/landing-page-direction.md",
       "mode": "0000644",
@@ -1564,6 +1574,26 @@
       "mode": "0000644",
       "sha256": "c277f432a0d3e23e481bae01355f5f11648ee9a6593f665a809d8f406ebbe033"
     },
+    {
+      "path": "docs/design/mocks/landing/landing-sheet.html",
+      "mode": "0000644",
+      "sha256": "052d9a62f37d52bcab8f20d01bb67b6f83cdce00d64cca9aa794f212166c2f92"
+    },
+    {
+      "path": "docs/design/mocks/landing/v1.html",
+      "mode": "0000644",
+      "sha256": "f016ed6900a72d05df49331b1a8436aba3b1ac53a65f52e7ad1c1895fb2f3a60"
+    },
+    {
+      "path": "docs/design/mocks/landing/v2.html",
+      "mode": "0000644",
+      "sha256": "4de2026c96f95739213857c2c02bb53d41f8c15854a9f59240781288e21257b6"
+    },
+    {
+      "path": "docs/design/mocks/landing/v3.html",
+      "mode": "0000644",
+      "sha256": "ad7a2cac824d592002a13cad7054bc5babfb4a3f80d5a43c325ff7a10db51b64"
+    },
     {
       "path": "docs/design/mocks/projects-hub-mock.html",
       "mode": "0000644",
@@ -5087,12 +5117,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b29fad739b5ae1c818f7974aaffa1a2c9cdcd468a96fdd5cf557e669539a26ea"
+      "sha256": "d1bb9eb4376b39eb26a2fb46d91a70556c332521be0f193633d11807248f48ca"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d0986bb5a781bc56402c86519e1c293f7672c0b52938574913356eceba838dfb"
+      "sha256": "cbb22bb9c93706c85329e51d1a67becc24d477f6c63baadadb2c6b10aa1cc59a"
     },
     {
       "path": "public-docs/index.html",
@@ -5449,6 +5479,11 @@
       "mode": "0000644",
       "sha256": "07ff338beac12979eba50e4a6fe9c2f6dbfd842fa01abe1c412b19888d10c4a0"
     },
+    {
+      "path": "scripts/gds/adr-namespace.js",
+      "mode": "0000644",
+      "sha256": "9c7ef61b64e41ee5dd6d913883e16dfed6d44bd6eefa4960b8dde566a63b5621"
+    },
     {
       "path": "scripts/gds/api.js",
       "mode": "0000644",
@@ -5802,7 +5837,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "4dec7f6bee219ca3c11dbf5b9c3380de286264a66830fd8e2d37018a989eb83e"
+      "sha256": "2fcc7dfa75a6fcf1ebc0fb75d0e4343dc54b9d75b88fb798f8b16674b919c1b8"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -6997,7 +7032,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9a9f751f0b8da59f2e74a6ee3ea8f57c3ddbd0be971b97d5c654d7ef02d6b322"
+      "sha256": "62c5f68383474bfeb692ea38e926c689615320d644d8d83fe7c35b3dd51e23bb"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7887,7 +7922,7 @@
     {
       "path": "tests/fitness.mjs",
       "mode": "0000644",
-      "sha256": "465c7ef58342b6e03947858fe34649f5a13a5bcf3658478601baed1e8b2420ef"
+      "sha256": "e247bd7ab5ea26493186d9c308a7774bd6ef65fe057613da887ec94fe8b2b5b5"
     },
     {
       "path": "tests/fitness_ratchets.mjs",

package/docs/adr/0195-adr-numbers-are-checked-like-migration-numbers.md

@@ -0,0 +1,46 @@
+# 0195 — ADR numbers are checked like migration numbers, and the twenty existing collisions are grandfathered by name
+
+- **Status:** Accepted
+- **Date:** 2026-08-27
+- **Deciders:** the builder on [task 1003164](https://cloudbongos.com/builders#/task/1003164)
+
+## Context
+
+Two ADRs could carry the same number and nothing flagged it. It happened for real on 2026-08-22: [task 1002483](https://cloudbongos.com/builders#/task/1002483)'s branch authored `<redacted>.md` while, three days into that branch sitting stranded at `completed`, [task 1003042](https://cloudbongos.com/builders#/task/1003042) landed `0181-teardown-state-gate-and-address-retention.md` on `main`. Merging `main` into the branch produced both files side by side.
+
+**Git cannot see this.** The filenames differ, so there is no path collision and no merge conflict — git adds both cleanly. `docs/adr/README.md` auto-merges too, ending up with two `| 0181 |` rows, the incoming one placed out of the ascending order the index reads in. The `unit` gate, fitness, docs-entropy and the grader all passed. A human reading `ls docs/adr/` found it.
+
+**The asymmetry that made this a bug rather than a gap.** Migrations already have exactly this protection. `migration-namespace.js` exports `stemCollisions()`, and `fitness.js` runs `checkMigrationNamespacing` as a hard failure — because a re-used migration number silently *skips* a migration, which the team correctly treated as unacceptable. ADRs got `next-number.js`, which computes the next free number for a claim card from a possibly-stale tree, best-effort, at claim time — and then nothing enforced it afterwards. Same shared, monotonic, human-allocated number line; one guarded, one not.
+
+**Why it matters past tidiness.** An ADR number is a *citation target*. [Task 1000900](https://cloudbongos.com/builders#/task/1000900)'s close-rationale cited "ADR 0180" and, because of this collision, `0180` on `main` is *Dependency intake & drift policy* — an unrelated document. A reader following that citation lands nowhere near the ship gate it meant. ADRs cite each other by number throughout, and `docs/adr/README.md` is the index every agent is told to consult, so a duplicated number makes a citation ambiguous **forever**.
+
+**What building the check revealed.** The bug report described one collision. The live tree held **twenty**, plus fourteen index defects the same merge class had produced: two ADRs listed twice (`0116`, `0117` — a merge duplicated the rows verbatim) and twelve ADRs with no index row at all. Ten of those twelve were the *second file of a colliding pair* — which is the mechanism by which a collision hides, since the file that never gets indexed is the one nobody sees. The hand-written "known collision" paragraph under the index narrated eight collisions and had fallen twelve behind reality: a record nobody checked, the shape [ADR 0184](<redacted>.md) was written about.
+
+## Decision
+
+**We will check ADR numbers the way we check migration numbers — a hard CI failure — and grandfather the twenty existing collisions by exact filename rather than renumbering them.**
+
+1. **`scripts/gds/adr-namespace.js`** is the ADR sibling of `migration-namespace.js`: pure functions over a file list and the index text, no disk, unit-testable. It exports `checkAdrNumbering()`, registered in `fitness.js` (Check 31) and therefore inside the required `unit` CI check — no new workflow.
+
+2. **A number claimed by two files is a hard failure naming both paths**, unless that number's file set is *exactly* the frozen pair in `LEGACY_DUPLICATE_ADRS`.
+
+3. **The index is checked by link target, not by number**: every ADR file has exactly one row, and every row points at a file that exists. This is one invariant covering all three real defects — the dangling row, the duplicated row, and the unindexed file.
+
+4. **Row ordering warns, never blocks.** Ten legacy rows sit out of ascending order. Blocking would fail every PR for a mess nobody's diff created — the split [ADR 0189](<redacted>.md) draws between declaration rot (hard) and inherited drift (warn).
+
+## Alternatives considered
+
+- **Renumber the nineteen newer halves so the tree is genuinely unique.** Rejected: renumbering breaks every existing citation to those numbers, which is precisely the harm this check exists to prevent, and `README.md` states the rule outright — a number, once assigned, is never reused. It would also rewrite nineteen files' git history for a cosmetic property no reader depends on, since each pair's two files are unambiguous by *name*.
+- **Grandfather by number instead of by exact filename** (`0181` is simply exempt). Rejected: that permanently un-guards twenty numbers. A third ADR joining `0181`, or a rename of either half, would pass silently. Set-equality on filenames keeps the exemption exactly as wide as the history that earned it, and the list can only shrink.
+- **A numeric cutoff, mirroring `LEGACY_BARE_CORE_MAX`.** Rejected: migrations could use a cutoff because the new namespace makes collision *structurally* impossible above it. Here a new ADR takes a number above the current max, so a cutoff would exempt every historical number while catching nothing that hasn't already happened — and a new file deliberately numbered `0050` would sail through.
+- **Enforce "exactly one index row per ADR *number*"**, as the bug report proposed. Rejected: it cannot express a grandfathered pair, which legitimately has two rows. Keying on the link target says what we actually mean and catches strictly more.
+- **Fix it in `next-number.js` instead** — make the allocator authoritative. Rejected: the allocator already exists and already tries. It runs at *claim* time against a tree that may be days stale, which is exactly how the `0181` pair happened; only a check at merge time sees both files.
+- **Leave the check advisory** (warn, like the doc-comment gate). Rejected: this is the failure the migration check treats as unacceptable, one layer up, and a warning is what the situation already effectively had.
+
+## Consequences
+
+- A new ADR number collision now fails the `unit` gate, naming both paths and the remedy. The failure arrives on the PR that creates it rather than months later via a wrong citation.
+- The index and the tree can no longer drift apart unnoticed: 214 files, 214 rows, checked on every PR. Adding an ADR without indexing it is now a build failure — a small new obligation on every ADR author, and the point.
+- The twenty legacy pairs keep their filenames and their citations. They are listed once, in code, in a list that may only shrink; the prose paragraph that used to narrate them (and lagged twelve behind) now points at that list instead of restating it.
+- Ten index rows sit out of order and stay that way, as warnings. Anyone reordering them is welcome to; nothing forces it.
+- `docs/adr/README.md`'s `#` column now uses `NNNN-a` / `NNNN-b` for all twenty pairs, extending a convention that previously covered five of them.