@bongos/core 1.19.531 → 1.19.533

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.531",
-  "core_contract": "1.19.531",
-  "source_commit": "9044e13dacbf2160d02eef08915ffa74dbc669be",
+  "core_version": "1.19.533",
+  "core_contract": "1.19.533",
+  "source_commit": "03699f66aaf653282fcbb775d32389f301c822f8",
   "source_ref": "HEAD",
-  "built_at": "2026-09-04T13:41:13.821Z",
+  "built_at": "2026-09-04T14:01:59.226Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 435,
+    "docs_redacted": 436,
     "agent_docs_stubbed": 24,
     "functional_verbatim": 1979,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2438,
-  "tree_sha256": "0d93f09e833a982f219a54f124fe11808be718651cd93d5258119ef9e50a7954",
+  "file_count": 2439,
+  "tree_sha256": "2ab0086b311db79080f1d46f9e35341d02d01ed318907fcf85a11f4dd19beb38",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1729,10 +1729,15 @@
       "mode": "0000644",
       "sha256": "17a0018cfa4f42364a1567bee6bc98f8cf84311ce8344b218d4de9eab870b496"
     },
+    {
+      "path": "docs/adr/0244-a-catalog-search-is-a-view-over-the-rows-never-an-edit-to-the-selection.md",
+      "mode": "0000644",
+      "sha256": "a115ba411ec945223b0de36514fcbfb253205b79c2125c232081f35af3ec9a45"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "fb28cbf7bb03cc69deb895b5e25956a440449c11f1fd977ee09655116e3fc3b0"
+      "sha256": "b34cab20b46a17a183ce54b2aed2bb09f03c55c47c7f6300b43fc32c86a79421"
     },
     {
       "path": "docs/api-reference.md",
@@ -1767,12 +1772,12 @@
     {
       "path": "docs/copy-inventory.md",
       "mode": "0000644",
-      "sha256": "729633c41036ec0026d3ef1ac787f68cb6fb7ab77e3eb578f855b5ec2d63280f"
+      "sha256": "b42faf85d36a5411a0a1227ca1dd52c7d1f0f741332f03f2fb66d5fa90bc3ea0"
     },
     {
       "path": "docs/copy-registry.json",
       "mode": "0000644",
-      "sha256": "344a451940b630b1f6db2f97acb45eb387616311675b243dcc4381dc604ef77d"
+      "sha256": "f1a02c1bad4249ae04fc7c0758c5e6efd2df2e647be3d89c531a3daeb5281826"
     },
     {
       "path": "docs/design/apex-pass-2-direction.md",
@@ -2617,7 +2622,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "fa1785c5b0009ea7431a5fcf3fd13dcb5b65563c481e8d417d62c2eea6050af6"
+      "sha256": "4b74bef8f5b808fa3c7990b8fd727c26be2c929d64805e071489f1ca40a7f339"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6587,7 +6592,7 @@
     {
       "path": "modules/public-landing/public/projects.html",
       "mode": "0000644",
-      "sha256": "7147ff51b2eaa3487557fff35f4fc7c3e4f6164fd8054e41c76064bcfe932e08"
+      "sha256": "16d728f41b1fc8b72fb1ac74d6b97b8bb0709f8a490e660062d21a964b52a4f1"
     },
     {
       "path": "modules/public-landing/public/projects.probes.json",
@@ -6597,7 +6602,7 @@
     {
       "path": "modules/public-landing/public/projects.states.json",
       "mode": "0000644",
-      "sha256": "16fbd27a36c9c32696539c74a815dc9b3f187f5b539b393e3bee7f7dabc4e2a6"
+      "sha256": "2cd5e5598d59e8dbf813658c950821bbb9a34b57823bdfb3be7f61d834bf7714"
     },
     {
       "path": "modules/public-landing/public/terms.html",
@@ -7332,12 +7337,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "03ecbc56365c6b70ada0bdfd2ca666962f3ed8edcf95ef52acf93f2d0b82de51"
+      "sha256": "427e2b1d9b7e871c4e28163f4acd078751e2e43c88561fcefd85083721126292"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0eaf9886acaf585da2ecc97408dcb6f879a801ff20cead40a20bac221e8ea32f"
+      "sha256": "7e9fdd8898ce17821b9724972161530d4fb126cd7ec164a02dc290be89a41ae6"
     },
     {
       "path": "public-docs/index.html",
@@ -9017,7 +9022,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a534c8a215f1f744707ef9835905ac2850c991757a76545f77a191f8c3827e7b"
+      "sha256": "12cf837247460eee2eafd0b97bcbaf4472a0dcea13cd87b116952f4b8f2b75fb"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11247,12 +11252,12 @@
     {
       "path": "tests/projects_hub.mjs",
       "mode": "0000644",
-      "sha256": "f8e557372a86d42dc0433414a1d5821a350dc545056fcc8104aa151b51e939f7"
+      "sha256": "edcc3d0cc2b9d5e5c44a33b43f98353001ff22222bf2f34c2c3dd28f04f66989"
     },
     {
       "path": "tests/projects_hub_module_picker.mjs",
       "mode": "0000644",
-      "sha256": "55b7912d1985ea1e02874b479c9d0453c25df48bfad6287ba9402df50326d6ed"
+      "sha256": "44981254fda6a07522d650210127fae6d65ed4d06e539f8a555c860c74de8c64"
     },
     {
       "path": "tests/projects_hub_pre_uat.mjs",

package/docs/adr/0244-a-catalog-search-is-a-view-over-the-rows-never-an-edit-to-the-selection.md

@@ -0,0 +1,116 @@
+# 0244 — A catalog search is a view over the rows, never an edit to the selection
+
+- **Status:** Accepted
+- **Date:** 2026-09-04
+- **Tasks:** [#1002340](https://cloudbongos.com/builders#/task/1002340) (this decision — BV1.R21)
+- **Goal:** [#1000046](https://cloudbongos.com/builders#/goal/1000046) — Project creation, criterion
+  `proj-module-select` ("during setup a default set of modules is pre-selected…")
+- **Related:** [ADR 0237](<redacted>.md)
+  (R19 — the per-type presets, and the file that already said "R21 searches the catalog"),
+  [ADR 0240](<redacted>.md)
+  (R20 — the picker, and the three-valued `modules` column whose `null` this must not disturb),
+  [ADR 0243](<redacted>.md)
+  (R22 — the tailored preselect the search now filters)
+
+## 1. The problem
+
+The picker paints one row per optional module. The catalog is three rows today
+and is meant to grow — the module system's whole point is that an instance adds
+modules — so R21 asks for a keyword search over it.
+
+A search over a list of *links* is trivial. A search over a list of **toggles**
+is not, because the list is also an answer. Two things can go wrong the moment a
+row can be hidden:
+
+1. **The filter edits the answer.** The natural implementation of "show only the
+   matching rows" is to narrow the array the panel renders *and* the array it
+   reads back — at which point typing `discord` and pressing Next files a project
+   with one module instead of three. The bug is silent: every screen looks right.
+2. **The filter lies about the answer.** Even a filter that only narrows the
+   *render* leaves a switched-on module off screen. The owner sees one row, sees
+   it unticked, and reasonably concludes nothing else is on. ADR 0237's standard
+   for the preselect — "a preselect an owner cannot see the reason for is one
+   they have to audit" — applies here in its harsher form: a preselect they
+   cannot **see at all** is one they cannot audit.
+
+## 2. Decision
+
+**The search is a view. `state.modules` is the answer. The view may not write to
+it.**
+
+Concretely, in `modules/public-landing/public/projects.html`'s picker block:
+
+- `moduleQuery` is a plain variable that holds what is typed. It is **not** part
+  of the draft — `saveDraft()` is never called from the input handler — so a
+  resumed draft never comes back mid-search, and a search can never be the thing
+  that turns an untouched picker into an answered one (ADR 0240's `null`).
+- `visibleModules()` derives, per render, the rows the current query leaves.
+  `pickedModules()`, `modulesForCreate()` and `extrasRow()` are untouched and
+  keep reading the whole catalog, so what rides the create request and what the
+  review names are both independent of what is on screen.
+- **The panel states the part the filter is hiding.** One line under the field:
+  `Showing 1 of 3. 2 extras are switched on, including any this search is
+  hiding.` It is silent with an empty query, and it counts what is *on*, not what
+  is *visible* — which is the whole point of it existing.
+- An empty query is not a search: every row shows, and the line goes quiet. So
+  does a query of nothing but spaces.
+
+## 3. What "matching" means, and what it deliberately does not
+
+`moduleMatches(mod, terms)` is a pure function over one catalog row:
+
+> lower-case the row's **label + summary + key** into one haystack; every
+> whitespace-separated term must appear in it as a **substring**.
+
+- **AND across terms.** An owner adding a word is saying the list is still too
+  long; OR would grow it, which is the opposite of what they asked for.
+- **Substring, not word-boundary.** A half-typed word must still find its module,
+  because the field filters on every keystroke and a filter that shows nothing
+  until you finish typing reads as a broken one.
+- **The key is searchable even though it is never shown.** It costs nothing and
+  it is what a returning owner (or a support answer, or our own docs) actually
+  names a module by.
+- **No ranking, no fuzziness, no synonyms.** The catalog is small enough that
+  order is the catalog's order, and a rank that reorders toggles under a typing
+  hand is a worse experience than a filter that does not.
+- **Not semantic.** "Somewhere for people to chat" finds nothing, and that is the
+  scope line: search by meaning is deferred to idea 1000552 with the rest of the
+  AI layer for project creation. A lexical filter that admits it is lexical is
+  honest; one that half-guesses is not.
+
+The whole matcher is a named function on the page precisely so the vm harness in
+`tests/projects_hub_module_picker.mjs` can run it directly — the same reason
+`bundleForAnswers` is a function and not an inline expression.
+
+## 4. Consequences
+
+- The picker scales past the point where the band is scannable, with no server
+  work: the catalog already arrives whole in the one `GET
+  /provisioning/starter-bundles` read (ADR 0237), so typing costs no round trip
+  and adds no failure mode.
+- BV1.R24's proof path — *create → bundle preselected → search + add → enabled* —
+  works because a toggle made while filtered still re-derives the answer in
+  **catalog order**, exactly as an unfiltered toggle does.
+- When the catalog fails to load the field is hidden rather than disabled: a
+  search box over a list that is not there can only disappoint.
+- A future by-meaning search replaces `moduleMatches` and nothing else. The
+  view/answer split is what makes that swap safe.
+
+## 5. Alternatives considered
+
+- **Filtering the array the panel reads back** (the "obvious" implementation) —
+  rejected: it makes the search an editor of the answer, which is failure mode 1
+  above, and it is silent.
+- **Hiding matched-out rows with CSS instead of not rendering them** — same
+  outcome for the owner, but it puts `aria-pressed` toggles in the accessibility
+  tree that a sighted owner cannot see, and the empty-result case still needs its
+  own line. Rendering fewer rows is the simpler truth.
+- **Keeping switched-on rows pinned at the top regardless of the query** — it
+  makes the count line unnecessary, but it means a search sometimes shows rows
+  that do not match, which is a filter that lies in the other direction. The
+  count says the same thing without breaking the band's one rule.
+- **Persisting the query in the draft** — a search is a way of looking, not a
+  decision. Restoring one on a resumed draft would hide most of the catalog from
+  an owner who did not ask for that.
+- **Debouncing the input** — the filter is a pass over three-to-a-few-dozen rows
+  of already-loaded data. A delay would only make the field feel slower.

package/docs/adr/README.md

@@ -331,5 +331,6 @@ This keeps the decision history honest and traceable.
 | 0241 | [**The artist gate holds the DEPLOY, not the ship, and it reads a state rather than a judgement** ([task 1003116](https://cloudbongos.com/builders#/task/1003116) · goal 1000074, criterion `artist-blocking-is-per-project` — R05, the DECISION task the goal placed before R04 so no code would be wired to an unsettled gate). Goal 1000074 carries two rules on a collision course: the owner's "blocking strictness is PER PROJECT, not global", and [ADR 0162](<redacted>.md), which retired review gates on `main` after a code-owner requirement stranded two graded-PASS ships in a day. **0162 is usually cited by a paraphrase — "a verdict is advisory, never self-executing" — and the paraphrase is wrong as a blanket claim:** 0162's own table of compensating controls marks three of four as *fails closed*, the subagent grader among them. What it actually retired was a gate GitHub could only express as ACCOUNTS — identity-pinned against [ADR 0016](<redacted>.md), and stranding with no escape hatch. So the surviving test is: **a gate is admissible when it is evaluated automatically from readable state, consistently for every builder, with a named escape hatch; inadmissible when a particular person must act and it stalls when they do not.** Decision: (1) the gate reads a **STATE** — "is there an unresolved artist review task?" — never an opinion, so the artist's judgement is what they write INTO the task and stays advisory in exactly 0162's sense, while what the system reads is ordinary GDS status; (2) strictness is a project setting `artist_gate ∈ off | advisory | strict` and at `strict` it holds the **DEPLOY, not the ship** (owner ruling) — the builder's work is graded, merged, credited and landed on CI alone exactly as today, so 0162's strand class cannot recur, and the gate attaches to the boundary the artist's ABI mandate is actually about (users see the deployed instance, not `main`; [ADR 0137](<redacted>.md) already splits land/release/deploy); (3) the escape hatch is the **project OWNER only** — not the builder, not any Metic+, not the artist — via the existing `POST /tasks/:id/override-request`, because a person can be both artist and builder and could pass their own work; a self-release is permitted but never quiet (required rationale, audit-logged as a self-override) so a solo instance cannot deadlock; (4) the default is **`strict`** (owner ruling, against the author's `advisory` recommendation), which is safe only because §2 holds the deploy — the worst case is a pin that waits, and this instance is included once R04 ships; a project with no artist must still be able to deploy, and the refusal must name what holds it and which control releases it; (5) tightening is **not retroactive** — re-gating history would strand the next deploy behind reviews for work nobody remembers and make the setting frightening to raise; R02's flag queue is the right tool for already-shipped copy. Rejected: blocking the ship (recreates 0162's incident exactly, with credits unpaid — [ADR 0120](<redacted>.md)); advisory at every level (configures nothing); any Metic+ as the hatch (makes `strict` indistinguishable from `advisory`); making the artist's VERDICT the gate (the one thing 0162 genuinely forbids); retroactive tightening; a global constant (ruled out by the owner's constraint by name).](<redacted>.md) | goal 1000074 / the artist's loop |
 | 0242 | [**A cross-role cascade is a declaration table on the event that already exists** ([task 1003549](https://cloudbongos.com/builders#/task/1003549) · goal 1000074, criterion `artist-review-task-on-ship` — the split R04 invited in its own brief and [ADR 0241](<redacted>.md)'s dependency). R04 needs "every ship with copy or visuals GENERATES one", and its brief said the infrastructure did not exist, naming the spark queue as the prototype. Reading both surfaces shows the prototype is the wrong half: the spark queue ([task 1002921](https://cloudbongos.com/builders#/task/1002921)) and the copy-desk flag queue ([task 1003113](https://cloudbongos.com/builders#/task/1003113)) are both **PULL** — filtered listings of rows another role already created — and nothing anywhere generated work on a state transition, which is the **PUSH** R04 asks for. (`cascade-dispatch.js` is model-cost routing; named only because its name has misled more than one reader.) **Decision: no new bus.** The kernel seam registry's own header uses this exact scenario as its worked example, `task.shipped` is already emitted post-commit by both ship paths and already has two consumers (discord's broadcast, sessions' deferred reward) — so a cascade is ONE MORE LISTENER on it, registered in `routes/lifecycle.js` beside the port because that mount is the one boot hook tests also run. A cascade is a frozen entry `{ key, discipline, when(task), title(task), body(task) }` — **a declaration table, not a rules engine**: no condition language, no stored rules, no per-project config, no priority ordering; adding one appends an entry and the runner does not change (the [ADR 0237](<redacted>.md)/[0239](<redacted>.md) shape, for their reason — the generalisations worth building are the ones two or three real entries have shown they share). **`CASCADES` ships EMPTY and R04 writes the first rule**, asserted so the emptiness is a decision on the record; the mechanism is proved against the tests' own declarations rather than against its first consumer's shape. Four load-bearing properties, all pinned: (1) **it can never fail the ship it reacts to** — post-commit event, isolated listeners, and a runner that catches everything and returns a report, because ADR 0241 settled that an artist may hold a DEPLOY and never a builder's SHIP and a generator that could fail a ship would smuggle that gate back in; verified against a real failure (no database reachable → one log line, resolves); (2) **idempotent on machinery that already exists** — `source: 'cascade'` + `source_ref: cascade-<key>-<taskId>` through `createTask`'s `(source, source_ref)` read, the same one a copy proposal uses ([ADR 0233](<redacted>.md)), so a reconciler re-sweep or a double emit is a no-op; (3) **it says where it came from** — inherits `goal_id`/`version_id`, carries the origin id in the ref and the prose, but NOT `parent_task_id`, which models a SUBTASK, and cascaded work is not part of the ship that triggered it; (4) **files at `backlog`, never `ready`** — generated work is a request, and auto-filing claimable work would let a rule nobody re-read mint claims. A rule key is PERMANENT (half the source_ref; renaming re-files everything it ever generated), pinned by a duplicate-key check. The mechanism is discipline-agnostic — an ideator or engineer cascade is the same entry with a different `discipline`, which is the generalisation that made this its own task. Accepted limit: cascades are declared in code, not configured per project. Rejected: extending the spark queue (a read-side filter that generates nothing), a new event or poller, a rules engine or per-project config, filing at `ready`, `parent_task_id` as the link, and running the cascade inside the ship transaction (which would make a generation failure a ship failure — the exact coupling ADR 0241 rules out).](<redacted>.md) | goal 1000074 / the artist's loop |
 | 0243 | [**A bundle adjustment belongs to the bundle, not to the advice about it** ([task 1002341](https://cloudbongos.com/builders#/task/1002341) · goal 1000046, criterion `proj-module-select`). R17 ([ADR 0239](<redacted>.md)) built a rule engine and R20 ([ADR 0240](<redacted>.md)) built a picker, and nothing connected them: the picker preselected the type's RAW preset while `GET /provisioning/recommendations` separately applied `TEAM_SHAPE_RULES` to that same preset and returned a better answer no surface rendered. Joining them the obvious way — let the picker apply the rules — breaks the property R20 was built on ([ADR 0240](<redacted>.md) §2: the preselect and the fallback are "one function, called twice"), because an owner who answers the interview, watches the panel preselect `discord`, and then SKIPS the picker would get a project without it. **Decision: `TEAM_SHAPE_RULES` moves from `recommendations.js` down to `starter-bundles.js`** (re-exported, so the public surface is unchanged), `effectiveModules` resolves through the new `bundleForAnswers(type, teamShape)`, and the picker reads the same table the fallback does. The distinction is not a preference: a bundle adjustment is not advice ABOUT the bundle — it IS the bundle once the owner has answered, and it is the only one of R17's three tables that is ever APPLIED (governance is a preview carrying `applied: false`, invites are a seam for R28), so it is the only one that has to live where the resolution happens. `effectiveModules` reads `detail.team_shape` straight off the row rather than through `normalizeProjectDetail` — importing it would point the bundle layer UP at the module that requires it ([ADR 0083](<redacted>.md)) to buy an answer it already has, since an off-vocabulary shape fires no rule and adjusts nothing. `GET /provisioning/starter-bundles` gains `byTeamShape`: every bundle re-resolved for every ruled answer, with the `adjustments` that got it there — twenty small rows, the whole preselect table in ONE read, for the reason `optional` rides the same payload (the owner flips type and team-shape on two EARLIER panels, and a refetch could land after they moved on or paint a key the panel has no row for). `PATCH /provisioning/instances/:id/detail` returns `modules: effectiveModules(updated)` beside its `publish` verdict and for the same reason — changing `team_shape` MOVES the modules of a `source: 'bundle'` project, so the effect comes back with the cause. The panel renders one reason line per adjustment that ACTUALLY fired, and only while the owner has not answered for themselves (a reason handed back for a toggle they flipped reads as the panel arguing with them). An adjusted bundle returns in CATALOG order, never append order, or the same set of modules would read as a different list depending on whether the picker was answered or skipped; a payload without `byTeamShape` degrades to the R20 answer, which is never wrong, only untailored. No new storage — the adjustment is resolved, never written. Rejected: leaving the rules up in `recommendations.js` and having the picker call `/recommendations` (two lists kept in agreement by hand, plus a round trip per keystroke); importing `normalizeProjectDetail`; storing the adjusted bundle on a skip (it writes down an answer nobody gave); moving governance and invites down too (they are never applied, so there is nothing for them to stay in agreement with); and a reason line per matched condition rather than per actual change.](<redacted>.md) | provisioning / project creation |
+| 0244 | [**A catalog search is a view over the rows, never an edit to the selection** ([task 1002340](https://cloudbongos.com/builders#/task/1002340) · goal 1000046, criterion `proj-module-select`). The creation picker ([ADR 0240](<redacted>.md)) paints one toggle per optional module, and the catalog is meant to grow — so R21 adds a keyword search over it. A search over a list of links is trivial; a search over a list of TOGGLES is not, because the list is also an answer. Two failure modes follow from letting a row be hidden: the filter **edits** the answer (narrow the rendered array and the read-back array together, and typing `discord` then pressing Next files one module instead of three — silently, with every screen looking right), or the filter **lies** about it (a switched-on module off screen reads as switched off, which is [ADR 0237](<redacted>.md)’s "a preselect they have to audit" in its harsher form — one they cannot see at all). **Decision: the search is a VIEW and `state.modules` is the answer; the view may not write to it.** `moduleQuery` is a plain variable, never part of the draft, so `saveDraft` is not called from the input handler and a search can never turn an untouched picker into an answered one (ADR 0240’s `null` survives); `visibleModules()` derives the shown rows per render while `pickedModules()`, `modulesForCreate()` and `extrasRow()` keep reading the whole catalog; and the panel STATES what the filter is hiding — one line under the field counting what is **on**, not what is visible. Matching is `moduleMatches(mod, terms)`, a pure function: lower-cased **label + summary + key** as one haystack, every whitespace-separated term an AND’d substring. AND because adding a word means the list is still too long; substring because a filter that shows nothing until you finish typing reads as broken; the key because that is what a returning owner names a module by. No ranking (reordering toggles under a typing hand is worse than not), and deliberately **not semantic** — by-meaning search is deferred with the rest of the creation AI layer (idea 1000552). Rejected: filtering the read-back array (failure mode 1), CSS-hiding non-matches (leaves invisible `aria-pressed` toggles in the a11y tree), pinning switched-on rows above the query (a filter that lies the other way), persisting the query in the draft, and debouncing a pass over already-loaded rows.](<redacted>.md) |
 
 > ⚠️ **Numbering collisions are now machine-enforced, not narrated.** Twenty numbers are shared by two ADRs each — assigned in parallel sessions before anything checked. The files keep their filenames (renumbering would break every existing citation, and a number once assigned is never reused), and this table disambiguates each pair as `NNNN-a` / `NNNN-b`. The authoritative list is `LEGACY_DUPLICATE_ADRS` in [`scripts/gds/adr-namespace.js`](../../scripts/gds/adr-namespace.js), frozen by exact filename: a **new** collision — or a third file joining a legacy number, or a rename of either half — hard-fails the `unit` CI gate, as does an index row that points at no file or an ADR with no row. The list may only shrink. This paragraph used to narrate the collisions one by one and had fallen eight behind reality; see [ADR 0195](<redacted>.md) for why the check exists and why the pairs are grandfathered rather than renumbered.