@bongos/core 1.19.585 → 1.19.586

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.585",
-  "core_contract": "1.19.585",
-  "source_commit": "9352691bb382c387bdccba87b372194ba8c689b0",
+  "core_version": "1.19.586",
+  "core_contract": "1.19.586",
+  "source_commit": "ac6f287b895b1259c7b9fcc6b3a13e4fe178fbc0",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T22:05:13.505Z",
+  "built_at": "2026-09-07T22:34:04.491Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 453,
+    "docs_redacted": 454,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2057,
+    "functional_verbatim": 2058,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2534,
-  "tree_sha256": "afd5fa885788c749e7a91e2ae3761266dc7c5ebe26278185542576129ecf7dd2",
+  "file_count": 2536,
+  "tree_sha256": "7986b516ffada3b257352c5ecedda7fbc33f7e216f58f11fd2cd8edf23920cae",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1819,10 +1819,15 @@
       "mode": "0000644",
       "sha256": "fa04f8d71fff8186ae975a949c045ca7481bd0f22f395cb8c7397bbe03ddd449"
     },
+    {
+      "path": "docs/adr/0261-a-preselect-always-carries-a-reason-the-bundle-summary-is-the-floor.md",
+      "mode": "0000644",
+      "sha256": "04382d76f04c9317b565fb72951b36503e67acc95981a388d5c45efc80faaa26"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "1fa7dcf1456d26896e5cec77026ace0f08db8bed65527dee563cd7fdd2d07525"
+      "sha256": "6d2df0c7c0e6cfd3381935d14a703f8cfa7854d107a6add03bc743e631823ada"
     },
     {
       "path": "docs/api-reference.md",
@@ -2707,7 +2712,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0aaa401d7dc70186f6b739772f0411eb9458e93e3266d1d4301e212ee7d9473b"
+      "sha256": "3474ae19a143b381a4da0091daa41c301338dac6ffd97e7ef396079803589160"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6832,7 +6837,7 @@
     {
       "path": "modules/public-landing/public/projects.html",
       "mode": "0000644",
-      "sha256": "9c3a537d8c0ae0e5d8ddcdf2c69a859e1c72647203c8b177cc282dcad0c97e7f"
+      "sha256": "eca7a7b580db8a794f5e0e17c8bfbb106529f14bf43c6e627d8f32e1dc9d6a53"
     },
     {
       "path": "modules/public-landing/public/projects.probes.json",
@@ -7577,12 +7582,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "995314658da0abc7f33ea3719d38b99ee78336573d89c5af94b6a752bb840ea4"
+      "sha256": "d60a7d4e330cfd6154a5dea888aa9062d7571dee2d62aafc73cadb19b4afa604"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d48fe5ff721c79f7f5673e1c1a9fa8aff96c5bc0bb86af3795ec5b6bb15f0fe9"
+      "sha256": "14e7286fe47165dabdc74cb24b6bb5afdc1e7b949ae612b2f72c7a56107a246b"
     },
     {
       "path": "public-docs/index.html",
@@ -9292,7 +9297,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "1f7f432992c33dfa9ab9c06722b952fd6f4ae1239b3ddb591be5f1c72ae77319"
+      "sha256": "b3b115c1a4652247daebb85a6c393400361c2269cb047e691121193c45a63648"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11702,7 +11707,7 @@
     {
       "path": "tests/projects_hub_module_picker.mjs",
       "mode": "0000644",
-      "sha256": "44981254fda6a07522d650210127fae6d65ed4d06e539f8a555c860c74de8c64"
+      "sha256": "bae4d97b96d9aa747e70ee3a62f40bb7ef16c3702f4c2be362b12fe814a60aa6"
     },
     {
       "path": "tests/projects_hub_pre_uat.mjs",
@@ -12654,6 +12659,11 @@
       "mode": "0000644",
       "sha256": "74ffbc7e4585e651d00ab879ece6f3d23089d7c9ae7acb15483d3752b47bbdc0"
     },
+    {
+      "path": "tests/wizard_preselect_why.mjs",
+      "mode": "0000644",
+      "sha256": "2dc90311d8a4f31b543ed7ef711b4d3fc8b387a241bf0bbe797ab360107eac38"
+    },
     {
       "path": "tests/workflow_exec_paths.mjs",
       "mode": "0000644",

package/docs/adr/0261-a-preselect-always-carries-a-reason-the-bundle-summary-is-the-floor.md

@@ -0,0 +1,78 @@
+# ADR 0261 — A preselect always carries a reason; the bundle's summary is the floor
+
+**Status:** Accepted · 2026-09-07 · task 1003684
+**Supersedes nothing. Resolves a tension between [ADR 0237](<redacted>.md) and [ADR 0243](<redacted>.md).**
+
+## Context
+
+Two rules were each right on their own and wrong together.
+
+**ADR 0243** made `bundle.adjustments` a **delta**: a team-shape rule that fires without moving
+anything claims nothing. That is correct — a sentence explaining a change that did not happen is
+a claim the owner cannot check, and the module contract states it plainly ("a rule that changed
+nothing claims nothing").
+
+**ADR 0237** says a preselect the owner cannot see a reason for is one they have to audit, which
+is worse than no preselect at all. The wizard's own paint site quotes this.
+
+The two collide whenever a type's bundle **already contains** what a rule would add. The live
+case: `game` is `['dev-box','discord']` and the `small-team` rule adds `dev-box`. The rule fires,
+moves nothing, and correctly reports `adjustments: []`. Confirmed against live core 1.19.580:
+
+```
+GET /provisioning/starter-bundles → bundles[type=game].byTeamShape['small-team']
+  {"bundle":["dev-box","discord"],"adjustments":[]}
+```
+
+The owner then reached step 4 of the create wizard and saw **two extras switched on and no reason
+beside them** — `#modWhy` rendered as an empty, hidden div. Exactly the state ADR 0237 exists to
+prevent, produced by ADR 0243 behaving correctly.
+
+This was originally filed as a bug against the recommendation engine (a "dropped adjustment").
+It was not: the engine is right. The gap is that the panel had only one voice — the rule's — and
+fell silent when the rule had nothing to say.
+
+## Decision
+
+**The why-line has two voices, and the type's is the floor.**
+
+1. When one or more rules **moved** something, their sentences are shown, unchanged. A real
+   adjustment still speaks for itself and is never displaced.
+2. When no rule moved anything, the **type's own curated `summary`** explains the preselect.
+3. When the owner has answered the picker for themselves (`state.modules !== null`), the panel
+   says nothing at all — unchanged. Handing back a reason for a toggle they just flipped reads
+   as the panel arguing with them.
+4. A bundle carrying no summary still says nothing. The floor is a floor, not an invention.
+
+The summary was already authored for this job (`STARTER_BUNDLES[type].summary` in
+`modules/provisioning/starter-bundles.js`), already served on every row of
+`GET /provisioning/starter-bundles`, and — until this change — **rendered nowhere in the
+product**.
+
+## Consequences
+
+- No new copy, no new endpoint, no new field. The change is which existing sentence is rendered
+  when the delta is empty.
+- `adjustments` keeps its meaning exactly. Nothing about ADR 0243 is weakened: the delta is still
+  a delta, and no rule is credited with a change it did not make. What changed is that the
+  panel's silence is no longer the *only* alternative to a rule sentence.
+- The pin `tests/projects_hub_module_picker.mjs` had a fixture with **no `summary` field**, which
+  made four "no adjustment, no sentence" cases pass for the wrong reason. The fixture now carries
+  the real summaries and those cases assert the new contract — including, explicitly, that no
+  *rule* sentence is invented for a change that did not happen.
+- `tests/wizard_preselect_why.mjs` pins the resolver directly across every combination.
+
+## Alternatives rejected
+
+**Make the rule claim a no-op change.** Report `a-team-shares-one-environment` as an adjustment
+even when `dev-box` was already in the bundle. Rejected: it re-introduces exactly the unverifiable
+claim ADR 0243 removed, and the owner would read "a small team gets one shared environment" beside
+a module that was on before they answered.
+
+**Widen the bundles so no rule is ever redundant.** Rejected: it contorts curated per-type presets
+to serve an unrelated rendering concern, and the redundancy would return the moment a rule or a
+bundle changed.
+
+**Leave it silent.** Rejected by the owner on 2026-09-07 after the trade-off was put to them
+directly. The preselect is the wizard's most consequential default, and shipping it unexplained
+for the most common answer combination is the failure ADR 0237 names.

package/docs/adr/README.md

@@ -352,3 +352,4 @@ This keeps the decision history honest and traceable.
 | 0258 | [**The public CLI is a generated client-only package, and its file list is proven by running it** ([task 1003679](https://cloudbongos.com/builders#/task/1003679) · goal 1000054 — *A newcomer can build without the UI*). The core ships private as `@bongos/core` ([ADR 0108](<redacted>.md)), so a newcomer with no credential can install NOTHING and the web hall is the only way in — the owner's words: "how am I supposed to easily take on tasks as a new builder? I should be able to do everything without the UI." Open task 1002025 proposed publishing the core, which ships the SERVER and bypasses [ADR 0099](<redacted>.md)'s redaction pipeline (dormant until ~2026-11). **Decision: generate a separate public `@cloudbongos/cli` from the core and do not publish the core.** Four load-bearing parts. (1) SCOPED NAME, because npm shares one namespace between org names and unscoped packages — the bare `cloudbongos` is unpublishable *precisely because the owner owns that org*, which npm reports as "invalid" and reads like the name is taken; and a package name cannot be created on the npm website at all (it exists on first publish, which is why "Add Existing Package" answered `Forbidden`). (2) THE FILE LIST IS DECLARED AND PROVEN BY BEHAVIOUR, never computed — a static require-closure CANNOT answer this, because `src/module-api.js` is the doorway a module may only import ([ADR 0083](<redacted>.md)) and it *names* every kernel capability, so a static walk sees 33 `src/` files from `start.js` alone where runtime resolves **one** (`api-prefix.js`, which imports nothing) — the same trap as task 1003677's unsatisfiable done-when. So the test packs the tarball, installs it into an empty dir with NO repo, and runs every verb: it may fail for want of a session, never for a missing file. That caught two real holes on its first strengthened run — `clients/bongos-client/index.mjs`, reached by a dynamic `import()` no `require()` walk can see, and a hand-listed `files` array that dropped `clients/` and produced a tarball which installed cleanly then died on first use; both are now build-time refusals, and the `files` array is derived from the manifest. (3) `claim`/`ship`/`dev`/`serve`/`module`/`upgrade`/`onboard`/`doctor`/`exec`/`package-core` are ABSENT and the CLI says WHY plus the next step (`bongos shell` → a cloud box with the full CLI) — a bare `unknown command` teaches nothing, which is the exact failure being fixed. The supported journey is `login` → `start` → `shell`. (4) A REDACTION GATE fails the build closed on non-loopback IPv4 (RFC 5737 doc ranges exempt), token/key shapes, and every domain + owner login readable from the instance's own `config/branding.json` — needles come from host config so the core carries no instance identity ([ADR 0062 §7](<redacted>.md)); `cloudbongos.com` is allowlisted as public by design. No `repository` field while the core repo is private (it would 404 for every user and publish the owner's login for nothing). 31 files, one dependency (`undici`), version independent of the core's ([ADR 0161](<redacted>.md)). `@bongos/client` is VENDORED, not depended on — a public package depending on a private one is uninstallable. **The owner runs `npm publish`; a builder must not.** Task 1002025 is superseded. Rejected: publishing the core; deriving from a static closure (structurally impossible past the doorway); waiting for the mirror (dormant, and this is a build product not a source release); an unscoped name; depending on `@bongos/client`; a degraded `claim`; shipping all of `src/` to make lazy getters safe.](<redacted>.md) | cli / distribution / public surface |
 | 0259 | [**A project’s departure from the public list is public, and the copy says so** ([task 1003672](https://cloudbongos.com/builders#/task/1003672) · goal 1000046 — *Project creation*). Decides the leak [ADR 0255](<redacted>.md) §6.2 deliberately filed rather than implied fixed. The public projects feed publishes a named list plus a count of anonymous rows, so when a project flips to stealth its named row LEAVES the identified block while the count RISES BY ONE — *“Mercury is gone, and there is one more black hole”* names it, and the moment, from a single diff of two snapshots. **Everything [ADR 0182](<redacted>.md) D2a does is defeated by it**, because the identity was never carried ON the anonymous row (`STEALTH_ANONYMOUS_KEEPS` is an allow-list precisely so a column added next year is anonymous by default) — it is carried by the ABSENCE of the named row that used to sit beside it. **Larger than the channel 0255 closed**, which needed repeated sampling and correlation; this one is exact and needs two reads. No `ORDER BY` change touches it: it is inherent in publishing a named list at all, so every fix is a product decision with a visible cost and the owner’s call, not a builder’s. **Decision: accept it, and make the copy say so.** Two reasons it is the right end of the trade and not merely the cheapest — (1) it is ALREADY the honest reading of the existing promise, since D2a made existence and count public *by design*, and a count that is public and truthful is a count whose CHANGES are public; (2) both alternatives damage the control they defend. A **delay window** means the owner clicks the privacy setting and is not private yet *without knowing it*, converting an information leak into a false belief — strictly worse, and the wrong direction for a privacy control. **Decoys** spend the count’s truthfulness (it is truthful today) on a guarantee that is still only probabilistic, and a decoy scheme needs some way to tell padding from real rows — the exact stable per-project key D2a forbids. The promise stealth actually keeps is about the project’s CONTENTS, not the TRANSITION: an anonymous row stays anonymous (no name, tagline, art, origin, or key surviving to the next snapshot); what is not private is stepping off a published list readers may keep copies of. So the copy — which read *“its name, and everything else about it, stay yours”*, every clause true and the paragraph as a whole overselling, because a reader takes it to cover the switch — now names the boundary in BOTH places an owner meets the setting (the choice’s blurb and the what-changes fold), in the plain register 0182’s interview fixed for this card. **A privacy control that oversells is worse than one that admits a limit**, the same standard 0255 §6 set for itself. **No behaviour changes** in `projects-feed.js` — the feed, the redaction allow-list and the keyed rotating permutation are decided FINISHED, not insufficient. `tests/projects_hub.mjs` pins the sentence in both surfaces (the copy IS the fix, so a future edit tightening the blurb must not quietly drop it) and re-applies the no-space-metaphor ban to it. Carries 0255 §6.3’s smaller residual so both live in one place: within one 24h epoch the permutation is stable, so same-day snapshots tell black holes apart (not name them) — accepted on the same reasoning, since the fix is a per-request permutation, which breaks pagination exactly as `ORDER BY random()` was rejected for. Guards recorded for any future attempt: no stable per-project key on an anonymous row, and no anonymous ordering an observer can predict or correlate. Rejected: the delay; decoys; dropping the named list (protects a privacy nobody asked for at the cost of the feature); and saying nothing, which is the failure mode this closes.](<redacted>.md) | platform-identity / privacy boundary / copy honesty |
 | 0260 | [**An application IS the consent, and the hub’s own echo is the gate** ([task 1002972](https://cloudbongos.com/builders#/task/1002972) · goal 1000045, criterion C4). Privacy spec **D7** asks that a reviewer see what the applicant’s OWN profile rules would already show, evaluated LIVE at review time. The rule is ONE port composing the two EXISTING views — `getPublicProfileExtras` for a public account, `recruiter-sliver`’s own `sliverShapeFor` for a private one — because a third five-key lookalike **is** the new disclosure class D7 forbids. **The one deliberate difference from the D3 sliver:** `getRecruiterSliver` floors on recruiting REACH, and reusing it verbatim would be wrong in the direction that looks safe — `recruiter_discoverable` defaults to FALSE for a private account, so a private builder who deliberately applied would show their reviewer NOTHING and C4 would be satisfied by an empty box. D7 settles it: *“applying is an explicit act”*. The swap relaxes REACH only; `accountActiveSql` (active **and** terms accepted) and `hide_stats` still floor it, and the proof asserts both directions on the same account so the tempting refactor cannot pass quietly. **The federated route’s gate is the whole security story** ([ADR 0205](<redacted>.md) / security report 1000027): client credentials name a PROJECT and never a person, so `POST /sso/applicant-profile` authenticated alone is a bulk disclosure oracle over every account on the platform, private ones included. `applicationBacksProfileRead` demands a HUB-WRITTEN echo for exactly (this account, this client) inside the same 30-day window — a row only the hub’s own join relay creates — refusing **404, never 403**, and BEFORE any account is read (asserted on the statement log, because a gate that refuses after reading has already done the disclosure work). LIVE means nothing is stored at either end; the queue keys on the VOUCH and never on `github_login` (the one PUBLIC unauthenticated write makes an unvouched login an impersonation surface); and the hub client secret stays in core behind a narrow doorway port. **The path is complete but DORMANT until R09 ([task 1002285](https://cloudbongos.com/builders#/task/1002285)) ships the vouch writer** — nothing writes `applicant_github_id` today, and that dependency was missing from 1002972’s graph. Rejected: routing the port through `getRecruiterSliver`, a snapshot at apply time, resolving by `github_login`, and putting `loadIdpConfig` on the doorway.](<redacted>.md) | platform identity / privacy |
+| 0261 | [**A preselect always carries a reason; the bundle’s summary is the floor** ([task 1003684](https://cloudbongos.com/builders#/task/1003684) · goal 1000046 — *Project creation*). Resolves a collision between two rules that were each right alone. [ADR 0243](<redacted>.md) made `adjustments` a **delta** — a team-shape rule that fires without moving anything claims nothing, because a sentence explaining a change that did not happen is a claim the owner cannot check. [ADR 0237](<redacted>.md) says a preselect the owner cannot see a reason for is one they must audit, which is worse than no preselect at all. The two collide whenever a type’s bundle **already contains** what a rule would add: `game` is `[dev-box, discord]` and the `small-team` rule adds `dev-box`, so the rule fires, moves nothing, and correctly reports `adjustments: []`. Confirmed on live core 1.19.580 — `byTeamShape[small-team]` = `{"bundle":["dev-box","discord"],"adjustments":[]}`. The owner then reached step 4 and saw **two extras switched on with no reason beside them**, `#modWhy` an empty hidden div: exactly what 0237 exists to prevent, produced by 0243 behaving correctly. Filed as a dropped adjustment; it was not — the engine is right, and the panel simply had ONE voice and fell silent when the rule had nothing to say. **Decision: the why-line has two voices and the type’s is the floor.** A real adjustment still speaks for itself and is never displaced; when none moved, the type’s own curated `summary` explains the preselect; when the owner has answered the picker themselves the panel stays silent (unchanged — a reason handed back for a toggle they just flipped reads as the panel arguing with them); a bundle with no summary still says nothing, because a floor is not an invention. **No new copy, endpoint or field** — the summary was authored for this job in `starter-bundles.js`, served on every row of `GET /provisioning/starter-bundles`, and rendered NOWHERE in the product until now. 0243 is not weakened: the delta stays a delta and no rule is credited with a change it did not make. The pin `tests/projects_hub_module_picker.mjs` carried a fixture with **no `summary` field**, which made four “no adjustment, no sentence” cases pass for the wrong reason; the fixture now carries the real summaries and those cases assert the new contract, including explicitly that no RULE sentence is invented for a change that did not happen. Rejected: making the rule claim a no-op change (re-introduces the unverifiable claim 0243 removed); widening the bundles so no rule is ever redundant (contorts curated presets for a rendering concern, and the redundancy returns on the next edit); and leaving it silent, declined by the owner once the trade-off was put to them directly.](<redacted>.md) | provisioning / starter bundles / owner-facing copy |

package/docs/module-api-changelog.md

@@ -1619,5 +1619,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.583 with no explicit bump. run 34164936809. (task 1002620)
   1.19.585 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.584 with no explicit bump. run 34165392436. (task 1002620)
+  1.19.586 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.585 with no explicit bump. run 34167072966. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/public-landing/public/projects.html

@@ -3408,13 +3408,29 @@ summary{min-height:24px;padding:3px 0;}
       return row ? row.bundle.slice() : [];
     }
     /* Why the preselect is what it is, in the owner's own words — one sentence per
-       rule that ACTUALLY moved something. Empty when nothing did, and empty once
-       the owner has answered for themselves: a reason given back for a toggle they
-       flipped reads as the panel arguing with them. */
+       rule that ACTUALLY moved something, and failing that the type's own summary.
+       Returns SENTENCES, not rule rows.
+
+       The fallback is the point (task 1003684). `adjustments` is a DELTA: a rule that
+       fires without changing anything claims nothing (ADR 0243). So for a type whose
+       bundle ALREADY contains what the rule would add — game is [dev-box, discord] and
+       the small-team rule adds dev-box — the delta is empty and the owner was shown a
+       tailored preselect with no reason beside it at all. That is the state ADR 0237
+       calls worse than no preselect: one the owner has to audit. Each bundle carries a
+       curated summary authored for exactly this, served on every row, and until now
+       never rendered anywhere (ADR 0261). It is the floor, not a replacement — an adjustment
+       still speaks for itself and wins.
+
+       Still empty once the owner has answered for themselves: a reason given back for
+       a toggle they flipped reads as the panel arguing with them. */
     function preselectReasons() {
       if (state.modules !== null) return [];
       var row = tailoredRow();
-      return row ? (row.adjustments || []) : [];
+      if (!row) return [];
+      var moved = (row.adjustments || []).map(function (a) { return a.reason; });
+      if (moved.length) return moved;
+      var b = bundleRow();
+      return b && b.summary ? [b.summary] : [];
     }
     /* What the panel paints and the review names: the owner's answer if they
        gave one, otherwise the type's preselect. */
@@ -3507,7 +3523,7 @@ summary{min-height:24px;padding:3px 0;}
       var why = $('modWhy');
       var reasons = preselectReasons();
       why.innerHTML = reasons.length
-        ? reasons.map(function (a) { return '<span>' + esc(a.reason) + '</span>'; }).join('')
+        ? reasons.map(function (r) { return '<span>' + esc(r) + '</span>'; }).join('')
         : '';
       why.classList.toggle('on', reasons.length > 0);
       var core = (starterBundles.core || []).length;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.585",
+  "version": "1.19.586",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.585",
+      "version": "1.19.586",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.585",
+  "version": "1.19.586",
   "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/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.585'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.586'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/projects_hub_module_picker.mjs

@@ -56,12 +56,16 @@ const PAYLOAD = {
   core: ['autonomy', 'builder-settings', 'copy-desk', 'economy', 'government', 'grading',
     'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'public-landing',
     'security', 'sessions', 'status-ui', 'ui-design'],
+  // `summary` is part of every real bundle row and is the why-line's FLOOR since task
+  // 1003684 — the sentence shown when no rule moved anything. The fixture carried none
+  // before that, which quietly made every "no adjustment, no sentence" case pass for the
+  // wrong reason. These are the real strings from starter-bundles.js.
   bundles: [
-    { type: 'game', bundle: ['dev-box', 'discord'] },
-    { type: 'research', bundle: ['agents'] },
-    { type: 'business', bundle: ['agents', 'dev-box'] },
-    { type: 'non-profit', bundle: ['discord'] },
-    { type: 'not-sure', bundle: [] },
+    { type: 'game', bundle: ['dev-box', 'discord'], summary: 'Somewhere for players to gather, and a place to walk a change through before anyone plays it.' },
+    { type: 'research', bundle: ['agents'], summary: 'Extra agents to run the reading and the experiments the question needs.' },
+    { type: 'business', bundle: ['agents', 'dev-box'], summary: 'A place to try a change before customers see it, and agents to look it over first.' },
+    { type: 'non-profit', bundle: ['discord'], summary: 'Somewhere the community around the cause can gather and be heard.' },
+    { type: 'not-sure', bundle: [], summary: 'Just the core, and nothing else to decide today. Add modules whenever you know what you need.' },
   ],
   optional: [
     { key: 'agents', label: 'Extra agents', summary: 'More AI agents alongside the ones every project gets.' },
@@ -460,8 +464,14 @@ test('a rule that changed nothing claims nothing', async () => {
   await h.open();
 
   assert.deepEqual(h.rows().filter((r) => r.pressed).map((r) => r.key), ['dev-box', 'discord']);
-  assert.deepEqual(h.why(), [], 'no adjustment, no sentence');
-  assert.equal(h.whyShown(), false, 'and no empty block sitting on the panel');
+  // No adjustment, so no adjustment-sentence — the rule still claims nothing. But the
+  // panel is not silent: the TYPE explains its own preselect (task 1003684), because two
+  // extras switched on with no reason beside them is the state ADR 0237 calls worse than
+  // no preselect at all. The rule's voice and the type's voice are different things.
+  assert.deepEqual(h.why(), ['Somewhere for players to gather, and a place to walk a change through before anyone plays it.']);
+  assert.ok(!h.why().some((s) => /shared cloud environment|somewhere for it to gather is switched on/.test(s)),
+    'and no RULE sentence is invented for a change that did not happen');
+  assert.equal(h.whyShown(), true, 'the block carries the type\'s reason');
 });
 
 test('an added module is preselected and explained', async () => {
@@ -520,7 +530,9 @@ test('a payload with no byTeamShape degrades to the untailored bundle, never to
   await h.open();
 
   assert.deepEqual(h.rows().filter((r) => r.pressed).map((r) => r.key), ['dev-box', 'discord']);
-  assert.deepEqual(h.why(), []);
+  // Degraded, but still explained: with no byTeamShape there is no adjustment to report,
+  // and the type's own summary is exactly the untailored reason (task 1003684).
+  assert.deepEqual(h.why(), ['Somewhere for players to gather, and a place to walk a change through before anyone plays it.']);
 });
 
 test('an off-vocabulary team shape adjusts nothing', async () => {
@@ -530,7 +542,9 @@ test('an off-vocabulary team shape adjusts nothing', async () => {
   await h.open();
 
   assert.deepEqual(h.rows().filter((r) => r.pressed).map((r) => r.key), ['dev-box', 'discord']);
-  assert.deepEqual(h.why(), []);
+  // No rule fires, so nothing is CLAIMED about the unknown shape — the sentence shown is
+  // the type's, which is true regardless of who is building it (task 1003684).
+  assert.deepEqual(h.why(), ['Somewhere for players to gather, and a place to walk a change through before anyone plays it.']);
 });
 
 test('a couldn\'t-load read clears any reasons it had already painted', async () => {
@@ -582,8 +596,12 @@ test('the picker and the server resolve the same set for every answer an owner c
         `type=${preset.type} team_shape=${teamShape}: the panel preselects what the server resolves`);
       assert.deepEqual(h.rows().filter((r) => r.pressed).map((r) => r.key), server.selected,
         `type=${preset.type} team_shape=${teamShape}: and the toggles show it`);
-      assert.deepEqual(h.why().length, server.adjustments.length,
-        `type=${preset.type} team_shape=${teamShape}: one sentence per adjustment the server made`);
+      // One sentence per adjustment the server made — and when it made none, the single
+      // floor sentence the type carries, so no combination leaves a preselect unexplained
+      // (task 1003684). A preset with no summary of its own still says nothing.
+      const expectedWhy = server.adjustments.length || (preset.summary ? 1 : 0);
+      assert.equal(h.why().length, expectedWhy,
+        `type=${preset.type} team_shape=${teamShape}: a sentence per adjustment, or the type's own when none moved`);
     }
   }
 });

package/tests/wizard_preselect_why.mjs

@@ -0,0 +1,137 @@
+// tests/wizard_preselect_why.mjs — the module picker always says WHY the preselect is on
+// (task 1003684).
+//
+// The bug as filed said the starter-bundle "why" sentence was being dropped for
+// Game + small-team. It was not: `adjustments` is a DELTA, and a rule that fires without
+// changing anything claims nothing (ADR 0243). The game bundle is already
+// ['dev-box','discord'] and the small-team rule ADDS dev-box, so the rule fires, moves
+// nothing, and correctly reports []. Verified against live core 1.19.580:
+//   byTeamShape['small-team'] => {"bundle":["dev-box","discord"],"adjustments":[]}
+//
+// The real defect is what the owner then saw: two extras pre-switched-on with no reason
+// beside them — precisely the state the paint site's own comment calls out, "a preselect an
+// owner cannot see the reason for is one they have to audit, which is the thing ADR 0237
+// says is worse than no preselect at all". Each bundle carries a curated `summary` authored
+// for this, served on every row of GET /provisioning/starter-bundles, and never rendered
+// anywhere in the wizard. It is now the floor beneath the adjustment sentences.
+//
+// Harness: the vm-slice idiom (tests/project_door_ui.mjs), since the wizard's script is
+// inline in the page and there is no jsdom here.
+//
+// Run:  node --test --test-reporter=tap tests/wizard_preselect_why.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8');
+
+const SLICE_RE = /function bundleRow\(\)[\s\S]*?function preselectReasons\(\)[\s\S]*?\n {4}\}/;
+const slice = (HUB.match(SLICE_RE) || [null])[0];
+
+test('the preselect-reason slice is still findable', () => {
+  assert.ok(slice, 'bundleRow/tailoredRow/preselectReasons were not found in projects.html');
+  assert.match(slice, /function tailoredRow\(\)/, 'the slice spans the tailoring lookup too');
+});
+
+// Faithful to the real payload shape (confirmed against live): every bundle row carries
+// label/summary/bundle, and byTeamShape holds the resolved answer per team shape.
+const BUNDLES = {
+  bundles: [
+    {
+      type: 'game',
+      label: 'Game starter',
+      summary: 'Somewhere for players to gather, and a place to walk a change through before anyone plays it.',
+      bundle: ['dev-box', 'discord'],
+      byTeamShape: {
+        // the live case: the rule fires, moves nothing, reports nothing
+        'small-team': { bundle: ['dev-box', 'discord'], adjustments: [] },
+        solo: {
+          bundle: ['discord'],
+          adjustments: [{ reason: 'You are building this alone, so the shared cloud environment is off — your own machine is the setup.' }],
+        },
+      },
+    },
+    {
+      type: 'research',
+      label: 'Research starter',
+      summary: 'Extra agents to run the reading and the experiments the question needs.',
+      bundle: ['agents'],
+      byTeamShape: {
+        'small-team': {
+          bundle: ['agents', 'dev-box'],
+          adjustments: [{ reason: 'A small team gets one shared environment to build in, so nobody is debugging their own laptop.' }],
+        },
+      },
+    },
+    { type: 'not-sure', label: 'Not sure', summary: '', bundle: [], byTeamShape: {} },
+  ],
+};
+
+function why({ projType, teamShape, modules = null, bundles = BUNDLES }) {
+  const sandbox = { starterBundles: bundles, state: { projType, teamShape, modules } };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(slice + '\nvar __out = preselectReasons();', sandbox);
+  // Copy out of the vm realm: its Array has a different prototype, and assert/strict's
+  // deepEqual compares prototypes — so a correct result would otherwise fail as
+  // "same structure but not reference-equal".
+  return Array.from(sandbox.__out);
+}
+
+test('game + small-team: no delta, so the type\'s own summary is the reason', () => {
+  // This is the exact combination from the live walk that surfaced the bug.
+  const out = why({ projType: 'game', teamShape: 'small-team' });
+  assert.deepEqual(out, ['Somewhere for players to gather, and a place to walk a change through before anyone plays it.']);
+});
+
+test('a REAL adjustment still speaks for itself — the summary does not displace it', () => {
+  const out = why({ projType: 'research', teamShape: 'small-team' });
+  assert.equal(out.length, 1);
+  assert.match(out[0], /shared environment/);
+  assert.doesNotMatch(out[0], /reading and the experiments/, 'the rule\'s sentence wins, not the summary');
+});
+
+test('a removal adjustment is reported the same way', () => {
+  const out = why({ projType: 'game', teamShape: 'solo' });
+  assert.equal(out.length, 1);
+  assert.match(out[0], /building this alone/);
+});
+
+test('no team shape answered: falls through to the bundle, still explained', () => {
+  // tailoredRow() returns the unadjusted bundle with adjustments: [] when no shape is set,
+  // which before this change also produced an unexplained preselect.
+  const out = why({ projType: 'game', teamShape: null });
+  assert.deepEqual(out, ['Somewhere for players to gather, and a place to walk a change through before anyone plays it.']);
+});
+
+test('once the owner has answered for themselves, the panel says nothing', () => {
+  // The pre-existing rule, and the one a careless fallback would have broken: handing back
+  // a reason for a toggle they just flipped reads as the panel arguing with them.
+  assert.deepEqual(why({ projType: 'game', teamShape: 'small-team', modules: [] }), []);
+  assert.deepEqual(why({ projType: 'game', teamShape: 'small-team', modules: ['agents'] }), []);
+});
+
+test('an unknown type, or a bundle with no summary, says nothing rather than crashing', () => {
+  assert.deepEqual(why({ projType: 'no-such-type', teamShape: 'small-team' }), []);
+  assert.deepEqual(why({ projType: null, teamShape: 'small-team' }), []);
+  assert.deepEqual(why({ projType: 'not-sure', teamShape: 'small-team' }), [], 'empty summary is not a sentence');
+});
+
+test('before the bundles read lands, nothing is claimed', () => {
+  assert.deepEqual(why({ projType: 'game', teamShape: 'small-team', bundles: null }), []);
+});
+
+test('every sentence returned is a plain string, so the paint site can escape it directly', () => {
+  for (const t of ['game', 'research']) {
+    for (const s of ['small-team', 'solo', null]) {
+      for (const line of why({ projType: t, teamShape: s })) {
+        assert.equal(typeof line, 'string', `${t}/${s} yielded a non-string`);
+      }
+    }
+  }
+});