@bongos/core 1.19.511 → 1.19.513

package/docs/adr/0239-a-recommendation-is-a-table-that-carries-its-own-reason.md

@@ -0,0 +1,177 @@
+# 0239 — A recommendation is a table that carries its own reason; governance is a preview and invites are a seam
+
+- **Status:** Accepted
+- **Date:** 2026-09-03
+- **Tasks:** [#1002336](https://cloudbongos.com/builders#/task/1002336) (this decision — BV1.R17)
+- **Goal:** [#1000046](https://cloudbongos.com/builders#/goal/1000046) — Project creation: visibility and
+  customization; criteria `proj-module-select` ("additional modules are recommended (rule-based) from the
+  project's details"), `proj-governance-reco` ("a recommended governance setup … derived from its details"),
+  `proj-invite-builders` ("the owner can optionally invite guilds or top builders")
+- **Related:** [ADR 0237](<redacted>.md)
+  (R19, the per-type preset this adjusts), [ADR 0182](<redacted>.md) D4 (skipping the
+  interview is a supported answer), [ADR 0083](<redacted>.md) (the
+  one-way import rule that makes the invite lookup a seam),
+  task [#1002334](https://cloudbongos.com/builders#/task/1002334) (R15, the interview whose answer this reads),
+  task [#1002772](https://cloudbongos.com/builders#/task/1002772) (the declared project type),
+  task [#1003500](https://cloudbongos.com/builders#/task/1003500) / idea 1000552 (the deferred AI layer)
+
+## 1. The problem
+
+Three of goal 1000046's criteria ask the same question in three places: after an
+owner answers the optional project-detail interview, what do we *recommend* — which
+modules, which governance setup, which builders to invite. The goal's own text pins
+the near term: "near-term recommendations are rule-based and module search is
+lexical; the AI/embeddings layer … is a deferred follow-up captured in the idea
+inbox."
+
+R19 ([ADR 0237](<redacted>.md))
+already answered the type half — a starter bundle per declared project type — and
+said explicitly that it is "a declaration and not a rule engine … R17/R22 own the
+layer that reasons." This is that layer.
+
+## 2. Two inputs, and the description is not one of them
+
+The engine reads exactly two things, and they arrive separately because they are
+stored separately: `type` is a column (the closed set task 1002772 fixed —
+`game · research · business · non-profit · not-sure`) and `team_shape` is the one
+closed-answer key the R15 interview collects (`PROJECT_DETAIL_VOCAB.team_shape ∈
+solo | small-team | community`). The interview deliberately does not re-ask the type
+(ADR 0237 §2), so `recommendationsForDetails({ type, team_shape })` is the file that
+puts the two back together, and a caller holding a row passes
+`{ type: row.type, ...projectDetail(row) }`.
+
+The interview's *third* answer — the free-text `description` — is deliberately
+**not** read. Inferring a bundle from prose is the deferred semantic layer
+([#1003500](https://cloudbongos.com/builders#/task/1003500), idea 1000552), and ADR
+0237 §7 already rejected it once for the same reason.
+
+## 3. A table, and every row carries the sentence that explains it
+
+The engine is three frozen tables and a resolver over them — not a scorer, not a
+weighting, not a model:
+
+| table | keyed on | effect |
+|---|---|---|
+| `TEAM_SHAPE_RULES` | `team_shape` | add/remove ONE opt-in module from the type's bundle |
+| `GOVERNANCE_RULES` | `team_shape` | a named preset out of `GOVERNANCE_PRESETS` |
+| `INVITE_RULES` | `team_shape` | a `seeking` descriptor, or `null` for "suggest nobody" |
+
+Every row carries a `reason` — one sentence in the owner's own words, shipped
+alongside the effect rather than reconstructed by whichever surface renders it. That
+is the constraint that makes the whole thing auditable: a recommendation an owner
+cannot be told the reason for is one they cannot disagree with, and a reason written
+separately from the rule drifts from it the first time either changes.
+
+The three bundle rules today: `community` **adds** `discord` (somewhere for it to
+gather); `small-team` **adds** `dev-box` (one shared environment); `solo` **removes**
+`dev-box` (your own machine is the setup). They are few for the reason ADR 0237 §4
+gave — today's opt-in catalog is three modules wide, and a preselect an owner must
+audit is worse than none. The rules' job is to correct a preset the owner's answer
+contradicts, not to re-derive it.
+
+## 4. `adjustments` is a delta — a rule that changes nothing claims nothing
+
+`bundle.adjustments` lists only the rules that ACTUALLY moved the module list. The
+game bundle already carries `discord`, so a `community` answer records no adjustment
+even though its condition matched; the non-profit bundle has no `dev-box`, so a
+`solo` answer removes nothing and says nothing.
+
+The alternative — record the reason whenever the condition matches — was rejected
+because it conflates two different sentences: "discord is on because your project is
+a game" (the bundle, R19's opinion) and "we switched discord on because you said
+community" (the rule). A picker rendering the second over a module the owner would
+have had anyway is telling them something they can check and find false.
+
+## 5. Governance is a named preview, never an applied setting
+
+Criterion `proj-governance-reco` says it out loud: the recommendation "depends on the
+governance module (goal 1000030), which is planned but not yet built." So a preset
+here is a **name plus one sentence of what living under it feels like** — `owner-only`
+/ `trusted-team` / `open-contribution` — and never a set of roles or permissions,
+because there is nowhere to put them.
+
+Every recommendation carries `governance.applied: false`. A constant field looks
+redundant until you count the surfaces that otherwise hardcode the same fact: R25's
+preview step ([#1002344](https://cloudbongos.com/builders#/task/1002344)), R18's proof
+([#1002337](https://cloudbongos.com/builders#/task/1002337)), the wizard and the
+project page. One flag flips when goal 1000030 lands; a test pins it false until then.
+
+## 6. Invites are a seam, because the leaderboard is a sibling module
+
+`invites.suggested` is **always empty**, and that is a decision rather than an
+unfinished edge. Ranking builders means querying the leaderboard, which lives in
+`economy` — a sibling module `provisioning` may not import (the one-way rule, ADR
+0083). Making the route do it instead would cost the engine's purity, put a database
+read behind a public endpoint, and duplicate work
+[#1002347](https://cloudbongos.com/builders#/task/1002347) (R28) already owns and
+whose dependency is R27, not R17.
+
+So the engine emits what to look for — `invites.seeking = { kind: 'top-builders',
+limit }`, or `null` for "suggest nobody" — and R28 turns it into names. `null` is a
+real answer here: a solo builder is suggested nobody on purpose, which is a different
+statement from an empty list nobody has filled yet.
+
+## 7. Skipping is an answer, and every default is the narrowest one
+
+The interview is optional (ADR 0182 D4), so every table has a stated default for
+"nobody said" and each is deliberately the narrowest option: the type's own bundle
+unadjusted, `owner-only` governance, and no invites. Widening later costs one
+setting; a project that quietly granted strangers a role it was never asked to grant
+is not recovered by setting it back.
+
+An **off-vocabulary** `team_shape` — absent, misspelled, or a value that has since
+left the vocabulary — reads as *no answer*, exactly as `normalizeProjectDetail` drops
+it on the way in. The route follows the same rule: a missing or unusable query value
+returns 200 with the defaults, never a 400, because refusing the request would make
+the supported path an error.
+
+`tailored: boolean` is the machine-readable half of criterion
+`proj-detail-interview`'s split ("completing it produces tailored recommendations;
+skipping produces sensible defaults") — false exactly when no detail answer shaped
+anything. R18 is the live proof of that line.
+
+## 8. The read surface
+
+`GET /provisioning/recommendations?type=&team_shape=` returns
+`{ recommendations: { type, teamShape, tailored, bundle, governance, invites } }`.
+`bundle` is ADR 0237 §5's shape with `adjustments` added, so R20's picker
+([#1002339](https://cloudbongos.com/builders#/task/1002339)) and this engine resolve
+through the same `bundleForProjectType` and can never name different modules — a test
+asserts that against the live `starter-bundles` route.
+
+`rank: public`, the same absent gate as `starter-bundles` and `onboard-plan`: the
+signed-out wizard asks while the owner is still answering, *before* any row exists to
+be own-scoped against, and the answer is a declaration that names nothing private.
+The route touches no database, and the test proves it by stubbing `pool` to throw.
+
+## 9. Consequences
+
+- **The UI is not wired here.** R20 renders the picker, R22
+  ([#1002341](https://cloudbongos.com/builders#/task/1002341)) surfaces these
+  recommendations inside it, and R18 proves the details→recs / skip→defaults split.
+  The creation wizard currently hardcodes a `TEAM_META` copy table in
+  `modules/public-landing/public/projects.html` that says roughly what
+  `governance.preview` now says — R22 should collapse that duplicate into this route
+  rather than leave one sentence written twice.
+- **Adding a fourth team-shape answer is a two-file change.** The interview vocabulary
+  and this file, and `tests/provisioning_recommendations.mjs` fails the build if a
+  vocabulary value has no governance rule and no invite rule.
+- **A recommendation is still never a publish precondition** (ADR 0182 D4 — the bar is
+  name + description alone), and taking or declining one cannot move a project's
+  dark-matter state.
+
+## 10. Rejected
+
+- **Reading the free-text description** — that is the deferred AI/semantic layer
+  ([#1003500](https://cloudbongos.com/builders#/task/1003500)), and the goal pins the
+  near term as rule-based.
+- **Filling `invites.suggested` from `GET /public/leaderboard`** — the route exists and
+  is public, but reaching it means importing a sibling module, and R28 owns that work
+  behind a different dependency.
+- **A scoring function over weighted signals** — with two inputs and three opt-in
+  modules there is nothing to weigh, and a score cannot be shown to an owner as a
+  sentence they can disagree with.
+- **Recording a reason for every matched condition** — see §4; it makes a claim the
+  owner can check and find false.
+- **Refusing an unknown `team_shape` with a 400** — skipping is the supported path, so
+  the shape of a skipped answer must not be an error.

package/docs/adr/README.md

@@ -324,6 +324,8 @@ This keeps the decision history honest and traceable.
 | 0234 | [**Idea routing: capture-time promotion, the landing matrix, and the homeless-only inbox** ([task 1003064](https://cloudbongos.com/builders#/task/1003064) · goal 1000071, "Idea routing"). Idea 1000771 named the failure: Discord `#bugs` created tasks DIRECTLY against a hardcoded, already-shipped version — no `captured_by`, no lineage, so the ideator-credit lane had nothing to pay against — while every other open idea sat waiting for a human triage pass that dropped its promotion into a version catch-all, because nothing in capture ever named a goal. Records what R01/R02/R05/R07/R13 shipped. `captureIdea` (`modules/ideas/inbox.js`) stays the ONE capture chokepoint — routing is one optional `goalId` argument, never a second creation door — and when the matrix routes, `routeIdeaToGoal` writes the idea row, the task (via the `lifecycle.createTask` port) and an `ideas_task_lineage` row (`origin='route'`) in ONE transaction, so a route can never mint attribution-free work the way `#bugs` did. `modules/ideas/routing.js`'s `decideLanding` is PURE and fail-closed: a bug from a Metic+ filer hard-lands `ready`, a sub-Metic bug or any other kind with a goal soft-lands `backlog`, a Full Idea or `criterion-proposal`/`decision` never routes, no goal named stays the pre-routing inbox path. `authorizeRoutedLanding` is the BINDING gate underneath the matrix's decision — a goal reaching protected scope raises the task's rank floor to Metic and REFUSES a sub-Metic filer outright, while membership is deliberately NOT required (reporting isn't authoring). `core_222`'s `suggested_goal_id` is an advisory hint only — the real home is `tasks.goal_id`, set by construction — and `/idea-triage` (`scripts/gds/triage.js`) now sends `goal_id` on promotion, so the inbox is homeless-only. Divergence recorded: R11 (Discord `#bugs`) hard-lands a linked Metic+ builder's bug immediately through the SAME shared matrix rather than the spec's "always soft-land, pending queue" design, because a local copy of the rank split would only drift from the one definition; and R12 (Discord `#ideas` hints) is NOT YET SHIPPED, so `#ideas` carries no goal hint today despite the interview decision that it should, hint-only, never route.](<redacted>.md) | ideas / lifecycle |
 | 0235 | [**A fix category is `kind='bug'` under a goal, not a new column** ([task 1003215](https://cloudbongos.com/builders#/task/1003215) · goal 1000071, "Idea routing" — the structural half of idea 1000828; task 1003214 shipped the advisory's first quiet case, task 1003157 extended it). A fix for something that should already work needs a home under an existing goal WITHOUT a new goal being born and WITHOUT a stored column restating what `tasks.kind` already says. Not a global "Bugs" goal either: a goal spanning every module makes the [ADR 0086](<redacted>.md) scope wall either everything or nothing, and a goal that can never reach `achieved` (a bug container never finishes) pollutes the exact signal [ADR 0183](<redacted>.md)'s auto-satisfy depends on. Not [ADR 0192 "a category orients and authorises nothing"](<redacted>.md) either, despite the structural resemblance: that decision forbids any gate from branching on a goal's category, while THIS decision is two decision surfaces deliberately branching on `kind='bug'` — `adviseGoal()` (`modules/lifecycle/goal-advisory.js`) goes silent for a bug under all three of its reasons (`no_goal`, `catch_all`, `no_criterion_link` — "a fix is the goal's 'fix category', not a delivery against one of its stated outcomes," its own doc comment) and `countTasksWithoutCriterionLink()` (`modules/lifecycle/db-deps-criteria.js`, surfaced on the hall's goal detail view) excludes `kind='bug'` from its count for the same reason. No hall/status change was needed for GROUPING bugs under a goal: every task card already renders its `kind` as a visible tag and the goal detail view's Filters already offer a `Kind` lens with `bug` as a value — verified against the live code, not built new. Rejected: a `tasks.category`/`fix_category` column or enum, a global cross-module "Bugs" goal, a bug-specific grouping widget beside the general-purpose kind facility that already works.](<redacted>.md) | ideas / lifecycle |
 | 0236 | [**Many ideas → one task: the lineage key is the pair** ([task 1003515](https://cloudbongos.com/builders#/task/1003515) · goal 1000071, "Idea routing" — promoted from idea 1000815; the table was built by [task 1002997](https://cloudbongos.com/builders#/task/1002997)). `ideas_task_lineage.task_id` was the PRIMARY KEY on the reasoning that "a task descends from at most one idea", and `linkIdeaTask` wrote `ON CONFLICT (task_id) DO UPDATE SET idea_id = EXCLUDED.idea_id` — so promoting a SECOND idea into a task that already had a link **silently replaced the first idea's lineage**: no error, no warning, no log line. Two ordinary triage promotes at one task were enough, and it happened on prod on 2026-08-21 (ideas 1000811 + 1000812 → task 1003150). Because this table is the rail [ADR 0172](<redacted>.md) stream 1 pays against, an overwritten row is an **ideator not paid** for work their idea produced, with nothing recording it — and it makes merging duplicate reports into one task a LOSSY move, which is the triage the inbox exists to encourage. The R01 grader named this shape and was told it was unreachable; it was unreachable on the ROUTING path examined and fully reachable on the ordinary PROMOTE path. **Decision: many ideas → one task is a real relation, so the key is the pair** — `ideas_006` re-adds `ideas_task_lineage_pkey` as `PRIMARY KEY (task_id, idea_id)` and both INSERT sites `DO UPDATE SET origin`, never `idea_id`. Refusing the second link would turn a legitimate merge into an error; logging the replacement keeps a lossy ledger. **Where one row is still required the EARLIEST link wins** (`ORDER BY created_at, idea_id`, stated in SQL rather than left to the planner): `sourceIdeaForTask`, `credits.awardIdeaTaskShipCredit`, and the nod queue's one-row-per-task predicate — one constant shared by the list and its count, so the pill can never disagree with the rows. Consequences: a task subsumed from N ideas **counts once toward each idea's** shipped-task credit (and cannot double-count within one — the pair is unique); the per-ship payout still names one idea, the earliest, because paying every co-source ideator is a decision about total worth, not a bug fix; the migration **backfills** from `idea_inbox.promoted_to_task_id`, the weaker pointer that survived each overwrite, labelling restored rows `origin='promote'`; and `updateIdea` still swallows a lineage failure but now reports it as a `LINEAGE GAP` through `api.logger` — a silent swallow on top of a silent overwrite was two layers of one mistake.](<redacted>.md) | ideas / economy |
+| 0238 | [**The join door is a provisioning SETTINGS key, and the hub column stays the cache** ([task 1002324](https://cloudbongos.com/builders#/task/1002324) · goal 1000046, criterion `proj-visibility-states` — R05). [ADR 0182](<redacted>.md) D5 says R05 "moves host — an instance surface, not a hub one", and on the tree both halves of that sentence pointed at nothing: `platform_identity_projects.visibility` (which R04 shipped) is written by **no route** — every write on `routes/projects.js` is the `project.curate` CURATION gate with no ownership check, `upsertProject` deliberately omits the column, and `owner_github_id` there is documented "advisory attribution (not an authority)" — while "the project's own hall settings" is a page that does not exist (`settings.html` is per-BUILDER; the hall's my-projects page was deleted by task 1003308). **Decision: the door is a key in `provisioning.SETTINGS_VOCAB`** (`visibility ∈ public|private|stealth`, default `public`), set through the existing own-scoped `PATCH /provisioning/instances/:id/settings` and rendered as one more `.mSec` section on the manage view an owner already uses. One line in the vocabulary buys the whole task from machinery already proven: `instanceAccessDenied` (own-scoped, Archon override, **404** not 403 — no existence leak), a validator that IS the vocabulary (so an off-list value 400s and a key can never drift out of the schema), a `provisioning_events` audit row, the `<PREFIX>_VISIBILITY` env the runner patches into `web.env`, and `src/branding.js` mapping it onto `project.visibility` in the public manifest. It is a **POLICY** key, not a platform-drawn one like the planet, for two reasons that outlive today: ADR 0182 D6 makes the door the CEILING `joinability` may only narrow and D1/D5 put admission authority on the instance — a door the instance cannot read cannot be a ceiling — and a key with a DEFAULT belongs in the defaulted vocabulary (`PLANET_VOCAB` keys are nullable because null means "the platform picks", and there is no such thing as the platform picking your join door). Nothing here writes the hub column: it stays ADR 0182 D5's cache, and R08 is the report that will feed it — so today an owner's pick is stored, validated, audited and delivered to their instance, and does not yet move the orb (that gap is R06/R08's, named so the next builder does not hunt a bug). The section deliberately ships **no "what your project runs" read-back line**, unlike its two siblings: a deployed project reports no door until it takes a release carrying the field, and a line that could only ever say "this project's server doesn't report this yet" is worse than none. Rejected: a new owner-scoped write route on the hub catalog (D5 forbids the hub authorising the change); a new instance-side settings page on its own (right long-run home, but today a control with no consumer while R08 is unshipped); a `visibility` COLUMN beside `description` (that one earned a column as half the publish gate and is read by SQL — a closed-vocabulary knob is what the jsonb store exists for); and `PLANET_VOCAB` to dodge the restart (a quieter save today, the ceiling rule lost tomorrow).](<redacted>.md) | provisioning / public-landing |
 | 0237 | [**A starter bundle is a preset over the always-on core, keyed by the declared project type** ([task 1002338](https://cloudbongos.com/builders#/task/1002338) · goal 1000046, criterion `proj-module-select`). "During setup a default set of modules is pre-selected" can only mean the OPT-IN modules, since every instance already boots with the same sixteen `default: true` core-domain ones — so a bundle is a short list of opt-in module keys layered on that floor, preselected and freely toggled off by R20's picker ([task 1002339](https://cloudbongos.com/builders#/task/1002339)). **The key is the DECLARED type, and the seeded vocabulary is stale:** the task text (2026-07-17) names *Game / SaaS-Tool / Community*, but task [1002772](https://cloudbongos.com/builders#/task/1002772)'s owner decision (2026-08-13) fixed the live closed set as `game · research · business · non-profit · not-sure` — two CHECK constraints, two `PROJECT_TYPES` constants and five wizard buttons — and "community" survives only as a `team_shape`. Two constraints ride the key: the arrow runs **type → modules, never back** (1002772 rejected inferring type from module flags, which flip all through setup), and the R15 interview must **not re-ask** what `type` declares, so R19 adds no `PROJECT_DETAIL_VOCAB` key and no migration. `not-sure` and *undeclared* resolve to the same modules but are deliberately different answers — `type` is nullable precisely so "nobody said" is never back-filled with a guess, and the resolver returns `type: null` with its own copy. **The declaration is pinned by a test, not a runtime catalog read:** a module may not import `src/module-loader/catalog.js` (the one-way rule, [ADR 0083](<redacted>.md)), so `modules/provisioning/starter-bundles.js` stays PURE like `onboard-plan.js` beside it and `tests/provisioning_starter_bundles.mjs` reads every `modules/*/module.json` off disk — failing the build if a bundle names a module that does not exist, if `ALWAYS_ON_CORE` drifts from the manifests' `default: true` set, if a bundle names an always-on module (a preselect that toggles nothing), or if it names one of the two hub-only modules. The bundles are `game → dev-box, discord`; `research → agents`; `business → agents, dev-box`; `non-profit → discord`; `not-sure → —`, and they are SHORT because today's opt-in catalog is three modules wide and a preselect an owner must audit is worse than none. Served whole at public `GET /provisioning/starter-bundles` (`{ core, bundles }`, same absent gate as `onboard-plan`) so the picker re-preselects without a refetch and R17's recommendations read the same shape. A bundle is **never a publish precondition** — [ADR 0182](<redacted>.md) D4 fixes that bar at name + description alone. Rejected: a runtime catalog read, a `bundle` key in the interview vocabulary, inferring the bundle from the description (the deferred AI layer, [task 1003500](https://cloudbongos.com/builders#/task/1003500)), and keeping the seeded Game/SaaS-Tool/Community triple.](<redacted>.md) | provisioning / project creation |
+| 0239 | [**A recommendation is a table that carries its own reason; governance is a preview and invites are a seam** ([task 1002336](https://cloudbongos.com/builders#/task/1002336) · goal 1000046, criteria `proj-module-select` / `proj-governance-reco` / `proj-invite-builders`). R19 ([ADR 0237](<redacted>.md)) declared the per-type starter bundle and said outright it is "a declaration and not a rule engine — R17/R22 own the layer that reasons"; this is that layer, and the goal pins it **rule-based**, with the AI/embeddings pass deferred ([task 1003500](https://cloudbongos.com/builders#/task/1003500), idea 1000552). **Two inputs, and the free-text description is not one of them:** the DECLARED `type` (a column) and `team_shape` (the one closed-answer key the R15 interview collects, [task 1002334](https://cloudbongos.com/builders#/task/1002334)) — inferring from prose is the deferred layer ADR 0237 §7 already rejected once. The engine is three frozen tables (`TEAM_SHAPE_RULES` add/remove ONE opt-in module; `GOVERNANCE_RULES` name a preset; `INVITE_RULES` emit a seek) and **every row carries its own `reason` sentence**, shipped with the effect rather than reconstructed by whichever surface renders it — a recommendation an owner cannot be told the reason for is one they cannot disagree with. `bundle.adjustments` is a **DELTA**: a rule whose condition matched but whose module the bundle already carried records NOTHING, because "we switched discord on because you said community" over a module a game would have had anyway is a claim the owner can check and find false. **Governance is a named preview, never a setting** — the governance module is planned and unbuilt (goal 1000030), so a preset is a name plus one sentence of what it feels like (`owner-only` / `trusted-team` / `open-contribution`) and every result carries `applied: false`, one flag instead of the same fact hardcoded in R25, R18, the wizard and the project page. **Invites are a SEAM**: `suggested` is always `[]` because ranking builders means querying the leaderboard in the sibling `economy` module, which the one-way rule ([ADR 0083](<redacted>.md)) forbids importing — the engine emits `seeking: { kind: 'top-builders', limit }` (or `null` = suggest nobody, a real answer) and R28 ([task 1002347](https://cloudbongos.com/builders#/task/1002347)) turns it into names. **Skipping is an answer:** every table states a default and each is the NARROWEST option (widening later costs one setting; a role granted to strangers is not recovered by setting it back), an off-vocabulary `team_shape` reads as no answer exactly as `normalizeProjectDetail` drops it, and the route answers 200-with-defaults rather than 400 — refusing would make the supported path ([ADR 0182](<redacted>.md) D4) an error. `tailored: boolean` is the machine-readable half of `proj-detail-interview`'s details-vs-skip split that R18 ([task 1002337](https://cloudbongos.com/builders#/task/1002337)) proves. Served at public `GET /provisioning/recommendations?type=&team_shape=` (same absent gate as `starter-bundles`; no database, pinned by a `pool`-throws stub), returning ADR 0237 §5's bundle shape plus `adjustments` so a recommendation and R20's preselect can never name different modules. Rejected: reading the description, filling `suggested` from `GET /public/leaderboard`, a weighted scoring function, a reason per matched condition, and a 400 on an unknown shape.](<redacted>.md) | provisioning / project creation |
 
 > ⚠️ **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.

package/docs/api/openapi.json

@@ -11690,6 +11690,34 @@
         "security": []
       }
     },
+    "/provisioning/recommendations": {
+      "get": {
+        "operationId": "get_provisioning_recommendations",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/recommendations",
+        "description": "GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer> — the RULE-BASED recommendation for one set of creation answers (BV1.R17, task 1002336; goal 1000046 criteria `proj-module-select`, `proj-governance-reco`, `proj-invite-builders`). Returns `{ recommendations: { type, teamShape, tailored, bundle, governance, invites } }` — the starter bundle adjusted by the interview answer with a `reason` per adjustment, a named governance preset with its preview (`applied: false` until the governance module ships, goal 1000030), and the invite SEEK that R28 (task 1002347) turns into names. The two answers arrive separately because they are stored separately: `type` is a column and `team_shape` a key of the `detail` jsonb, so a caller passes back exactly what it holds. Both are optional and neither is validated by rejection — an absent or off-vocabulary value reads as NO ANSWER and yields the stated defaults, which is the supported path (ADR 0182 D4: skipping the interview is a real answer), never a 400. A pure read over modules/provisioning/recommendations.js — no database, no per-request state. rank: public — the same absent gate as `starter-bundles` and `onboard-plan` above: the signed-out hub wizard (/projects?view=new) asks while the owner is still answering, before any row exists to be own-scoped against, and the answer is a declaration that names nothing private.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningRecommendationsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/slug-available": {
       "get": {
         "operationId": "get_provisioning_slug_available",
@@ -16997,6 +17025,15 @@
           "steps"
         ]
       },
+      "GetProvisioningRecommendationsResponse": {
+        "type": "object",
+        "properties": {
+          "recommendations": {}
+        },
+        "required": [
+          "recommendations"
+        ]
+      },
       "GetProvisioningSlugAvailableResponse": {
         "type": "object",
         "properties": {
@@ -21797,9 +21834,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 346,
-  "x-schema-count": 378,
+  "x-endpoint-count": 347,
+  "x-schema-count": 379,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 258,
+  "x-response-schemas": 259,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 346 endpoints across 56 route files.
+> **Generated from the live route files** — the route file is authoritative. 347 endpoints across 56 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -442,7 +442,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |
 
-## `provisioning` (20)
+## `provisioning` (21)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -463,6 +463,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | PATCH | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | validated | PATCH /provisioning/instances/:id/settings — change a project's settings. |
 | POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
 | GET | `/api/bongos/provisioning/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
+| GET | `/api/bongos/provisioning/recommendations` | `public` | — | GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer> — the RULE-BASED recommendation for one set of creati… |
 | GET | `/api/bongos/provisioning/slug-available` | `any-builder` | — | GET /provisioning/slug-available?slug=<handle> — is this handle free to create under? rank: any authenticated builder (same gate as the c… |
 | GET | `/api/bongos/provisioning/starter-bundles` | `public` | — | GET /provisioning/starter-bundles — the curated module preset for each declared project type (BV1.R19, task 1002338; goal 1000046 criteri… |
 | GET | `/api/bongos/provisioning/tls-check` | `public` | — | GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST (ADR 0111 §4, task P4 task 1945). |