@bongos/core 1.19.512 → 1.19.513

package/tests/helpers.mjs

@@ -188,3 +188,164 @@ export function taskRoutesSource(modulesDir = path.join(ROOT, 'modules')) {
   return familySource(path.join(modulesDir, 'lifecycle', 'routes'),
     (f) => f === 'tasks.js' || (f.startsWith('task-') && f.endsWith('.js')));
 }
+
+// ===========================================================================
+// A minimal DOM that actually PARSES what a page script writes into innerHTML
+// (task 1003516, extracted here by task 1002332 when the access-requests queue
+// needed the same harness). querySelector resolves only if the element is
+// genuinely there, form fields carry the values the file rendered (escaping
+// included), and handlers captured by addEventListener run for real — which is
+// what makes a hall page testable at all: there is no jsdom in this repo.
+// ===========================================================================
+const VOID_TAGS = new Set(['input', 'br', 'img', 'hr', 'meta', 'link']);
+
+function decodeEntities(s) {
+  return String(s)
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function parseAttrs(text) {
+  const out = {};
+  const re = /([\w:-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+  let m;
+  while ((m = re.exec(text))) {
+    const raw = m[2] !== undefined ? m[2] : m[3] !== undefined ? m[3] : m[4] !== undefined ? m[4] : '';
+    out[m[1].toLowerCase()] = decodeEntities(raw);
+  }
+  return out;
+}
+
+// Compound selectors only (tag / .class / #id / [attr] / [attr="v"], comma lists)
+// — that is every selector task-detail.js uses, and refusing anything richer
+// keeps the stub honest about what it can prove.
+function matchesOne(el, sel) {
+  let ok = true;
+  const re = /([a-zA-Z][\w-]*)|\.([\w-]+)|#([\w-]+)|\[([\w:-]+)(?:=["']([^"']*)["'])?\]/g;
+  let m;
+  while ((m = re.exec(sel))) {
+    if (m[1]) ok = ok && el.tagName === m[1].toLowerCase();
+    else if (m[2]) ok = ok && String(el.className || '').split(/\s+/).includes(m[2]);
+    else if (m[3]) ok = ok && el.id === m[3];
+    else if (m[4]) {
+      const have = el.attrs[m[4].toLowerCase()];
+      ok = ok && (m[5] === undefined ? have !== undefined : have === m[5]);
+    }
+  }
+  return ok;
+}
+export const matches = (el, sel) => String(sel).split(',').map((s) => s.trim()).filter(Boolean).some((s) => matchesOne(el, s));
+
+export function walk(el, fn) {
+  for (const child of el.children) {
+    const hit = fn(child);
+    if (hit) return hit;
+    const deeper = walk(child, fn);
+    if (deeper) return deeper;
+  }
+  return null;
+}
+
+export function makeEl(tagName, attrs = {}) {
+  const el = {
+    tagName: String(tagName).toLowerCase(),
+    attrs,
+    children: [],
+    parentNode: null,
+    className: attrs.class || '',
+    id: attrs.id || '',
+    name: attrs.name,
+    dataset: {},
+    disabled: 'disabled' in attrs,
+    style: {},
+    listeners: {},
+    _text: '',
+    _html: null,
+    _value: null,
+
+    get value() {
+      if (this._value !== null) return this._value;
+      if (this.tagName === 'select') {
+        const opts = this.querySelectorAll('option');
+        const chosen = opts.find((o) => 'selected' in o.attrs) || opts[0];
+        return chosen ? (chosen.attrs.value !== undefined ? chosen.attrs.value : chosen.textContent) : '';
+      }
+      return this.attrs.value !== undefined ? this.attrs.value : '';
+    },
+    set value(v) { this._value = String(v); },
+
+    get textContent() { return this._text + this.children.map((c) => c.textContent).join(''); },
+    set textContent(v) { this._text = String(v == null ? '' : v); this.children = []; this._html = null; },
+
+    get innerHTML() { return this._html === null ? '' : this._html; },
+    set innerHTML(v) { this._html = String(v); this._value = null; parseInto(this, this._html); },
+
+    setAttribute(k, v) { this.attrs[String(k).toLowerCase()] = String(v); },
+    getAttribute(k) { const v = this.attrs[String(k).toLowerCase()]; return v === undefined ? null : v; },
+    removeAttribute(k) { delete this.attrs[String(k).toLowerCase()]; },
+    appendChild(child) { child.parentNode = this; this.children.push(child); return child; },
+    remove() {
+      const p = this.parentNode;
+      if (!p) return;
+      p.children = p.children.filter((c) => c !== this);
+      this.parentNode = null;
+    },
+    querySelector(sel) { return walk(this, (c) => (matches(c, sel) ? c : null)); },
+    querySelectorAll(sel) {
+      const out = [];
+      walk(this, (c) => { if (matches(c, sel)) out.push(c); return null; });
+      return out;
+    },
+    closest(sel) {
+      let node = this;
+      while (node) { if (matches(node, sel)) return node; node = node.parentNode; }
+      return null;
+    },
+    addEventListener(type, fn) { (this.listeners[type] = this.listeners[type] || []).push(fn); },
+    focus() {},
+    fire(type, event) { (this.listeners[type] || []).forEach((fn) => fn(event)); },
+  };
+  for (const [k, v] of Object.entries(attrs)) {
+    if (!k.startsWith('data-')) continue;
+    el.dataset[k.slice(5).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = v;
+  }
+  return el;
+}
+
+// The reserved names a <form>'s named-field shorthand (form.title.value) must
+// never shadow — everything else on the element is fair game, same as the DOM.
+const FORM_FIELD_RESERVED = new Set(['tagName', 'attrs', 'children', 'parentNode', 'className', 'id', 'dataset',
+  'disabled', 'style', 'listeners', 'value', 'textContent', 'innerHTML', 'name']);
+
+export function parseInto(host, html) {
+  host.children = [];
+  host._text = '';
+  const stack = [host];
+  const re = /<(\/?)([a-zA-Z][\w-]*)([^>]*?)(\/?)>/g;
+  let last = 0;
+  let m;
+  const addText = (raw) => { if (raw) stack[stack.length - 1]._text += decodeEntities(raw); };
+  while ((m = re.exec(html))) {
+    addText(html.slice(last, m.index));
+    last = re.lastIndex;
+    const tag = m[2].toLowerCase();
+    if (m[1]) {
+      for (let i = stack.length - 1; i > 0; i--) if (stack[i].tagName === tag) { stack.length = i; break; }
+      continue;
+    }
+    const el = makeEl(tag, parseAttrs(m[3]));
+    stack[stack.length - 1].appendChild(el);
+    if (!m[4] && !VOID_TAGS.has(tag)) stack.push(el);
+  }
+  addText(html.slice(last));
+  // Named-field access on every form the markup just produced.
+  walk(host, (el) => {
+    if (el.tagName !== 'form') return null;
+    for (const field of el.querySelectorAll('input, select, textarea')) {
+      if (!field.name || FORM_FIELD_RESERVED.has(field.name) || field.name in el) continue;
+      el[field.name] = field;
+    }
+    return null;
+  });
+}

package/tests/joinability_invite_only.mjs

@@ -187,6 +187,14 @@ test('the Watch page offers the Archon an invite by username — the way in when
   assert.match(watch, /nobody can apply, so this is how people get in/);
   const gate = (watch.match(/function renderGate\(data, target\) \{[\s\S]*?\n  \}\n/) || [''])[0];
   assert.ok(gate, 'renderGate() must exist');
-  assert.equal((gate.match(/wireInviteForm\(target\)/g) || []).length, 2, 'the form is wired in BOTH branches — an empty queue and a listed one');
-  assert.equal((gate.match(/inviteFormHtml\(\)/g) || []).length, 2, 'and rendered in both');
+  // The form used to be rendered and wired once per branch, and this counted the
+  // pair. Task 1002332 unified the empty and listed branches onto one `head`, so
+  // the count is now 1 and the invariant it stood for is STRONGER: the form is
+  // rendered and wired UNCONDITIONALLY, outside the split, so neither branch can
+  // drop it. tests/watch_applications_queue.mjs EXECUTES both cases ("an empty
+  // view still offers the invite form and the switch out of it") — the proof a
+  // source read like this one can only ever approximate.
+  assert.equal((gate.match(/inviteFormHtml\(\)/g) || []).length, 1, 'rendered once');
+  assert.match(gate, /const head = inviteFormHtml\(\)/, 'into the head BOTH branches are built from');
+  assert.match(gate, /\n {4}wireInviteForm\(target\);\n/, 'and wired at renderGate top level, never inside a branch');
 });

package/tests/provisioning_recommendations.mjs

@@ -0,0 +1,448 @@
+// tests/provisioning_recommendations.mjs — the rule-based recommendation engine
+// (BV1.R17, task 1002336; goal 1000046 criteria `proj-module-select`,
+// `proj-governance-reco`, `proj-invite-builders`). Decision record: ADR 0239.
+//
+// Four things are pinned here:
+//
+//   1. Each rule fires on its condition and NOT otherwise — the whole claim of a
+//      rule engine, and the thing a table quietly breaks when a fourth row lands.
+//   2. Skipping the interview yields the stated defaults, and an off-vocabulary
+//      answer is read as no answer. Criterion `proj-detail-interview` splits on
+//      exactly this ("completing it produces tailored recommendations; skipping
+//      produces sensible defaults"), and R18 (task 1002337) proves it live.
+//   3. Table integrity — every module a rule names is a real OPT-IN module on
+//      disk, every governance rule names a preset that exists, and every team
+//      shape in the interview's own vocabulary has a rule. The ADR 0237 idiom: a
+//      pure file declares, and this test is the link back to the live catalog.
+//   4. The read surface — GET /provisioning/recommendations is public, needs no
+//      database, and hands back the same bundle shape the starter-bundles route
+//      serves, so a recommendation and a preselect can never name different
+//      modules.
+//
+// DB-free: the route is a pure read, so nothing here touches Postgres or the
+// network beyond a loopback listener on port 0.
+//
+// Run:  node --test --test-reporter=tap tests/provisioning_recommendations.mjs
+
+import { test, before, after } from 'node:test';
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+// ESM named imports off the CJS module on purpose: knip cannot trace a
+// createRequire() import, so a test-only export would read as dead code and move
+// the knip ratchet (see the repo's knip learning).
+import {
+  TEAM_SHAPE_RULES,
+  GOVERNANCE_PRESETS,
+  GOVERNANCE_RULES,
+  GOVERNANCE_DEFAULT,
+  INVITE_RULES,
+  INVITE_DEFAULT,
+  recommendationsForDetails,
+} from '../modules/provisioning/recommendations.js';
+import {
+  ALWAYS_ON_CORE,
+  HUB_ONLY_MODULES,
+  bundleForProjectType,
+} from '../modules/provisioning/starter-bundles.js';
+
+const require = createRequire(import.meta.url);
+
+// Stub the doorway in require.cache BEFORE the route file loads (the
+// access_requests_invite pattern): the route destructures `pool` at require time,
+// and a real pg pool would hold the event loop open long after the assertions
+// pass. Nothing here needs a database — the route under test is a pure read, and
+// this stub is also the assertion that proves it.
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool: { async query() { throw new Error('the recommendations route must not touch the database'); } },
+};
+
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+const MODULES_DIR = fileURLToPath(new URL('../modules', import.meta.url));
+
+// Every module key on disk, with the manifest's `default` — the live catalog as
+// the loader discovers it (src/module-loader/loader.js scans exactly this).
+function manifestsOnDisk() {
+  const out = new Map();
+  for (const ent of fs.readdirSync(MODULES_DIR, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    const manifestPath = path.join(MODULES_DIR, ent.name, 'module.json');
+    if (!fs.existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    out.set(manifest.key, manifest);
+  }
+  return out;
+}
+
+// ── the rules fire on their condition, and not otherwise ────────────────────
+
+test('an open community adds somewhere to gather to a bundle that lacks one', () => {
+  // Arrange — the research bundle is `agents` alone (ADR 0237 §4), so the rule
+  // has something to actually change.
+  const answers = { type: 'research', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['agents', 'discord']);
+  assert.equal(recs.bundle.adjustments.length, 1);
+  assert.equal(recs.bundle.adjustments[0].module, 'discord');
+  assert.equal(recs.bundle.adjustments[0].effect, 'add');
+  assert.equal(recs.bundle.adjustments[0].rule, 'a-community-needs-somewhere-to-gather');
+  assert.ok(recs.bundle.adjustments[0].reason.length > 0, 'an adjustment always says why');
+});
+
+test('a small team adds the shared build environment', () => {
+  // Arrange
+  const answers = { type: 'research', team_shape: 'small-team' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['agents', 'dev-box']);
+  assert.deepEqual(recs.bundle.adjustments.map((a) => a.module), ['dev-box']);
+});
+
+test('a solo builder drops the shared build environment from the bundle', () => {
+  // Arrange — the business bundle is `agents` + `dev-box`, so the removal bites.
+  const answers = { type: 'business', team_shape: 'solo' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['agents']);
+  assert.equal(recs.bundle.adjustments.length, 1);
+  assert.equal(recs.bundle.adjustments[0].effect, 'remove');
+  assert.equal(recs.bundle.adjustments[0].module, 'dev-box');
+});
+
+test('a rule does not fire for a team shape it does not name', () => {
+  // Arrange — `solo` removes dev-box; `community` must leave it exactly alone.
+  const answers = { type: 'business', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.ok(recs.bundle.bundle.includes('dev-box'), 'the solo removal did not leak onto another shape');
+  assert.deepEqual(recs.bundle.adjustments.map((a) => a.rule), ['a-community-needs-somewhere-to-gather']);
+});
+
+test('a rule whose module the bundle already carries records no adjustment', () => {
+  // The game bundle already contains `discord`, so the community rule has nothing
+  // to change. An adjustment list is a DELTA — claiming a change that did not
+  // happen is a reason the owner cannot check against the picker in front of them.
+  // Arrange
+  const answers = { type: 'game', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, [...bundleForProjectType('game').bundle], 'the bundle is untouched');
+  assert.deepEqual(recs.bundle.adjustments, [], 'and nothing is claimed');
+});
+
+test('a removal rule whose module is absent records no adjustment', () => {
+  // Arrange — `non-profit` is `discord` alone, so solo\'s dev-box removal is a no-op.
+  const answers = { type: 'non-profit', team_shape: 'solo' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.bundle.bundle, ['discord']);
+  assert.deepEqual(recs.bundle.adjustments, []);
+});
+
+test('each team shape maps to its own governance preset and invite seek', () => {
+  // Arrange
+  const expected = {
+    solo: { preset: 'owner-only', seeking: null },
+    'small-team': { preset: 'trusted-team', seeking: { kind: 'top-builders', limit: 3 } },
+    community: { preset: 'open-contribution', seeking: { kind: 'top-builders', limit: 5 } },
+  };
+
+  // Act + Assert
+  for (const [shape, want] of Object.entries(expected)) {
+    const recs = recommendationsForDetails({ type: 'not-sure', team_shape: shape });
+    assert.equal(recs.governance.preset, want.preset, `${shape} → ${want.preset}`);
+    assert.deepEqual(recs.invites.seeking, want.seeking, `${shape} → its own invite seek`);
+    assert.ok(recs.governance.reason.length > 0, 'the preset always says why it was picked');
+  }
+});
+
+// ── skipping the interview, and answers that are not answers ────────────────
+
+test('skipping the interview returns the type bundle unchanged, the narrowest governance and no invites', () => {
+  // Arrange — a declared type but no interview answer at all: the supported path
+  // (ADR 0182 D4), not a gap.
+  const answers = { type: 'game' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.equal(recs.teamShape, null);
+  assert.equal(recs.tailored, false, 'nothing here came from an answer the owner gave');
+  assert.deepEqual(recs.bundle.bundle, [...bundleForProjectType('game').bundle]);
+  assert.deepEqual(recs.bundle.adjustments, []);
+  assert.equal(recs.governance.preset, GOVERNANCE_DEFAULT.preset);
+  assert.equal(recs.governance.reason, GOVERNANCE_DEFAULT.reason);
+  assert.deepEqual(recs.invites.suggested, []);
+  assert.equal(recs.invites.seeking, null);
+  assert.equal(recs.invites.reason, INVITE_DEFAULT.reason);
+});
+
+test('answering the interview marks the recommendation tailored', () => {
+  // Arrange + Act
+  const answered = recommendationsForDetails({ type: 'game', team_shape: 'solo' });
+  const skipped = recommendationsForDetails({ type: 'game' });
+
+  // Assert — the machine-readable half of criterion `proj-detail-interview`.
+  assert.equal(answered.tailored, true);
+  assert.equal(skipped.tailored, false);
+});
+
+test('an off-vocabulary team shape is read as no answer, not as a new rule', () => {
+  // A value that was never in the vocabulary — or has since left it — must land
+  // on the defaults, exactly as normalizeProjectDetail drops it on the way in.
+  // Inventing an answer nobody gave is the failure this file exists to prevent.
+  for (const shape of [null, undefined, '', 'guild', 'SOLO', 'small team', 42, {}, ['solo']]) {
+    // Act
+    const recs = recommendationsForDetails({ type: 'business', team_shape: shape });
+
+    // Assert
+    assert.equal(recs.teamShape, null, `${JSON.stringify(shape)} → no answer`);
+    assert.equal(recs.tailored, false);
+    assert.deepEqual(recs.bundle.adjustments, [], 'no rule fires on a value nobody chose');
+    assert.equal(recs.governance.preset, GOVERNANCE_DEFAULT.preset);
+  }
+});
+
+test('a call with no answers at all recommends the always-on core and nothing else', () => {
+  // Act — the signed-out wizard's very first ask, before any question is answered.
+  for (const input of [undefined, null, {}, 'nonsense', []]) {
+    const recs = recommendationsForDetails(input);
+
+    // Assert
+    assert.equal(recs.type, null, 'never guesses a type');
+    assert.deepEqual(recs.bundle.bundle, [], 'nothing is preselected on a guess');
+    assert.deepEqual(recs.bundle.modules, [...ALWAYS_ON_CORE]);
+    assert.equal(recs.governance.preset, GOVERNANCE_DEFAULT.preset);
+    assert.equal(recs.invites.seeking, null);
+  }
+});
+
+test('an unknown project type recommends the core, even when the interview was answered', () => {
+  // Arrange — the stale seeded vocabulary (ADR 0237 §2) is the realistic caller.
+  const answers = { type: 'saas-tool', team_shape: 'community' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert — the type is refused, but the ANSWER the owner actually gave still counts.
+  assert.equal(recs.type, null);
+  assert.equal(recs.teamShape, 'community');
+  assert.deepEqual(recs.bundle.bundle, ['discord'], 'the community rule applies to an empty bundle');
+  assert.equal(recs.governance.preset, 'open-contribution');
+});
+
+// ── the recommendation is a preview, and the invites are a seam ─────────────
+
+test('governance is a named preview and is never applied', () => {
+  // The governance module is planned and unbuilt (goal 1000030), which criterion
+  // `proj-governance-reco` states outright. Flip this pin when R25 (task 1002344)
+  // fits the presets to the real module.
+  for (const shape of [...provisioning.PROJECT_DETAIL_VOCAB.team_shape, null]) {
+    // Act
+    const recs = recommendationsForDetails({ type: 'game', team_shape: shape });
+
+    // Assert
+    assert.equal(recs.governance.applied, false, 'a recommendation, never a setting');
+    assert.ok(recs.governance.label, 'carries owner-facing copy');
+    assert.ok(recs.governance.preview, 'and one sentence of what it feels like');
+  }
+});
+
+test('invites are a seam: the suggested list is empty and the seek says what to look for', () => {
+  // Ranking builders means querying the leaderboard, which lives in the `economy`
+  // module this pure file may not import (the one-way rule, ADR 0083). R28 (task
+  // 1002347) owns the lookup; the engine only states what it should look for.
+  // Arrange
+  const answers = { type: 'business', team_shape: 'small-team' };
+
+  // Act
+  const recs = recommendationsForDetails(answers);
+
+  // Assert
+  assert.deepEqual(recs.invites.suggested, []);
+  assert.equal(recs.invites.seeking.kind, 'top-builders');
+  assert.equal(typeof recs.invites.seeking.limit, 'number');
+  assert.ok(recs.invites.reason.length > 0);
+});
+
+test('a caller may mutate the result without corrupting the declaration', () => {
+  // Arrange
+  const first = recommendationsForDetails({ type: 'game', team_shape: 'small-team' });
+
+  // Act — the picker sorts and splices what it is handed.
+  first.bundle.bundle.push('not-a-module');
+  first.bundle.modules.length = 0;
+  first.invites.seeking.limit = 999;
+
+  // Assert
+  const second = recommendationsForDetails({ type: 'game', team_shape: 'small-team' });
+  assert.deepEqual(second.bundle.bundle, ['dev-box', 'discord']);
+  assert.deepEqual(second.bundle.modules, [...ALWAYS_ON_CORE, 'dev-box', 'discord']);
+  assert.equal(second.invites.seeking.limit, 3);
+});
+
+// ── table integrity ─────────────────────────────────────────────────────────
+
+test('every module a rule names is a real opt-in module in the catalog', () => {
+  // Arrange
+  const manifests = manifestsOnDisk();
+
+  // Act + Assert
+  for (const rule of TEAM_SHAPE_RULES) {
+    const manifest = manifests.get(rule.module);
+    assert.ok(manifest, `rule ${rule.id} names '${rule.module}', which is not a module on disk`);
+    assert.notEqual(manifest.default, true, `rule ${rule.id} names always-on '${rule.module}' — a toggle that toggles nothing`);
+    assert.ok(!ALWAYS_ON_CORE.includes(rule.module), `rule ${rule.id} names a core module`);
+    assert.ok(!HUB_ONLY_MODULES.includes(rule.module), `rule ${rule.id} names hub-only '${rule.module}'`);
+  }
+});
+
+test('every team shape the interview can return has a governance rule and an invite rule', () => {
+  // Arrange — the interview's own vocabulary is the source of truth. A fourth
+  // answer added there must not be silently unhandled here.
+  const vocab = provisioning.PROJECT_DETAIL_VOCAB.team_shape;
+
+  // Act + Assert
+  for (const shape of vocab) {
+    assert.ok(GOVERNANCE_RULES.some((r) => r.teamShape === shape), `no governance rule for '${shape}'`);
+    assert.ok(INVITE_RULES.some((r) => r.teamShape === shape), `no invite rule for '${shape}'`);
+  }
+  for (const rule of [...TEAM_SHAPE_RULES, ...GOVERNANCE_RULES, ...INVITE_RULES]) {
+    assert.ok(vocab.includes(rule.teamShape), `a rule names '${rule.teamShape}', which the interview cannot return`);
+  }
+});
+
+test('every governance rule names a preset that exists, and the default does too', () => {
+  // Act + Assert
+  for (const rule of [...GOVERNANCE_RULES, GOVERNANCE_DEFAULT]) {
+    const preset = GOVERNANCE_PRESETS[rule.preset];
+    assert.ok(preset, `no preset '${rule.preset}'`);
+    assert.ok(preset.label && preset.preview, `preset '${rule.preset}' is missing owner-facing copy`);
+  }
+});
+
+test('the rule tables carry exactly one row per shape, so no rule can shadow another', () => {
+  // Act + Assert — GOVERNANCE_RULES and INVITE_RULES are resolved by `find`, so a
+  // duplicate row would be dead code that reads as live.
+  for (const [name, table] of [['governance', GOVERNANCE_RULES], ['invite', INVITE_RULES]]) {
+    const shapes = table.map((r) => r.teamShape);
+    assert.equal(new Set(shapes).size, shapes.length, `duplicate team shape in the ${name} table`);
+  }
+  const ruleIds = TEAM_SHAPE_RULES.map((r) => r.id);
+  assert.equal(new Set(ruleIds).size, ruleIds.length, 'duplicate bundle rule id');
+});
+
+// ── the read surface ────────────────────────────────────────────────────────
+
+// Mount the real router. The route under test is a pure read, so it needs no
+// session gate and no res.fail helper — which is itself the point of the
+// assertions below.
+const express = require('express');
+const buildProvisioningRouter = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use('/api/bongos', buildProvisioningRouter());
+
+let server;
+let port;
+before(async () => {
+  server = http.createServer(app);
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+after(async () => { await new Promise((resolve) => server.close(resolve)); });
+
+function get(pathname) {
+  return new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port, path: pathname }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        let parsed = null;
+        try { parsed = JSON.parse(body); } catch { /* non-JSON */ }
+        resolve({ status: res.statusCode, body: parsed, raw: body });
+      });
+    }).on('error', reject);
+  });
+}
+
+test('GET /provisioning/recommendations is public and answers with no session', async () => {
+  // Act
+  const res = await get('/api/bongos/provisioning/recommendations?type=game&team_shape=community');
+
+  // Assert
+  assert.equal(res.status, 200, `readable with no session (got ${res.status} ${res.raw})`);
+  const recs = res.body.recommendations;
+  assert.equal(recs.type, 'game');
+  assert.equal(recs.teamShape, 'community');
+  assert.equal(recs.tailored, true);
+  assert.ok(Array.isArray(recs.bundle.modules));
+  assert.ok(recs.governance.preset);
+  assert.ok(Array.isArray(recs.invites.suggested));
+});
+
+test('the route serves exactly what the engine returns', async () => {
+  // Arrange
+  const expected = recommendationsForDetails({ type: 'business', team_shape: 'solo' });
+
+  // Act
+  const res = await get('/api/bongos/provisioning/recommendations?type=business&team_shape=solo');
+
+  // Assert
+  assert.deepEqual(res.body.recommendations, expected, 'a script and the wizard read one answer');
+});
+
+test('the route reads the same bundle shape the starter-bundles route serves', async () => {
+  // ADR 0237 §5's promise: a recommendation and a preselect can never name
+  // different modules, because both resolve through bundleForProjectType.
+  // Act
+  const [bundles, recs] = await Promise.all([
+    get('/api/bongos/provisioning/starter-bundles'),
+    get('/api/bongos/provisioning/recommendations?type=research'),
+  ]);
+
+  // Assert — no interview answer, so the recommendation IS the preselect.
+  const preset = bundles.body.bundles.find((b) => b.type === 'research');
+  const recommended = recs.body.recommendations.bundle;
+  assert.deepEqual(recommended.core, preset.core);
+  assert.deepEqual(recommended.bundle, preset.bundle);
+  assert.deepEqual(recommended.modules, preset.modules);
+  assert.equal(recommended.label, preset.label);
+});
+
+test('the route answers the defaults for missing or unusable query values', async () => {
+  // Act + Assert — an owner who skipped the step must get a 200 with the
+  // defaults, never a 400: skipping is a supported answer (ADR 0182 D4).
+  for (const query of ['', '?type=', '?team_shape=guild', '?type=saas-tool', '?type[]=game&team_shape[]=solo']) {
+    const res = await get(`/api/bongos/provisioning/recommendations${query}`);
+    assert.equal(res.status, 200, `${query || '(no query)'} → 200, got ${res.status} ${res.raw}`);
+    assert.ok(res.body.recommendations, 'and a recommendation, not an error envelope');
+  }
+});