@bongos/core 1.19.514 → 1.19.516

package/tests/government_seed.mjs

@@ -182,3 +182,38 @@ test('migration objects are all governance_-namespaced (ADR 0083 §5)', () => {
     }
   }
 });
+
+// THE GAP THE DRIFT GUARD ABOVE CANNOT SEE (found by the task 1003177 grader).
+//
+// The union model is a regex over `SELECT '<rank>', unnest(ARRAY[…])`. It reads
+// the KEYS and never looks at the table those keys are inserted INTO — so a new
+// grant migration copied from a `governance_*` sibling passes it while writing to
+// `governance_role_permissions (role_key, …)`, the PRE-rename names.
+//
+// government_001_rename_from_governance renamed that table to
+// `government_rank_permissions` and its `role_key` column to `rank_key`, with no
+// compatibility shim. Migrations apply in filename order, so on any database —
+// a fresh install included — a `government_*`-prefixed file writes AFTER the
+// rename and must use the new names or error at apply time. The permission would
+// then never resolve, and its routes would 403 for every rank, Archon included.
+//
+// Scoped to the `government_`-prefixed files on purpose: the historical
+// `governance_*` migrations legitimately name the pre-rename tables (they ran
+// before the rename, and renaming an applied migration re-runs it — the standing
+// rule in modules/government/CLAUDE.md).
+test('a post-rename grant migration writes to the RENAMED table, not the old one', () => {
+  const postRename = grantSqlByFile.filter(([f]) => f.startsWith('government_'));
+  assert.ok(postRename.length > 0, 'there is at least one government_-prefixed grant migration');
+
+  for (const [file, sql] of postRename) {
+    const ddl = sql.replace(/^\s*--.*$/gm, '');   // a comment may CITE the old name
+    assert.ok(!/governance_role_permissions/.test(ddl),
+      `${file}: writes to governance_role_permissions — renamed to government_rank_permissions by government_001`);
+    assert.ok(!/\brole_key\b/.test(ddl),
+      `${file}: names the role_key column — renamed to rank_key by government_001`);
+    if (/INSERT INTO/.test(ddl)) {
+      assert.match(ddl, /INSERT INTO government_rank_permissions \(rank_key, permission_key\)/,
+        `${file}: a grant insert must target government_rank_permissions (rank_key, permission_key)`);
+    }
+  }
+});

package/tests/mingle.mjs

@@ -0,0 +1,370 @@
+// tests/mingle.mjs — mingle is two switches, cross-craft, and a decline that
+// costs nothing (task 1003177 / C07, goal 1000075; criterion
+// collab-mingle-two-switches, ADR 0187 §5).
+//
+// The criterion names three testable things, and the owner attached the third as
+// a condition of the feature rather than a follow-up:
+//   1. a pair is only ever CROSS-CRAFT;
+//   2. disabling EITHER switch prevents pairing;
+//   3. a decline carries NO PENALTY — "and that has to be verifiable, not just
+//      stated, or 'without penalty' is a claim rather than a property".
+//
+// (3) is the reason this file drives the REAL functions against a RECORDING pool
+// rather than asserting over prose. "No penalty" is a claim about what the code
+// does NOT do, and the only honest way to test an absence is to capture every
+// statement the code issues and assert on the whole set.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const mingle = require(path.join(ROOT, 'modules', 'lifecycle', 'mingle.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SRC = read('modules', 'lifecycle', 'mingle.js');
+const ROUTES = read('modules', 'lifecycle', 'routes', 'mingle.js');
+const MIGRATION = read('modules', 'lifecycle', 'migrations', 'lifecycle_007_mingle.sql');
+
+// A pool that answers the module's real queries and RECORDS every one of them.
+// The record is what makes the no-penalty test possible: it is an assertion about
+// the complete set of statements a decline issues, not about the one we expected.
+function recordingPool({ eligible = [], openPairs = [], pairRow = null } = {}) {
+  const queries = [];
+  return {
+    queries,
+    async query(sql, params) {
+      queries.push({ sql, params });
+      if (/FROM lifecycle_mingle_optin o/.test(sql)) {
+        return { rows: eligible.map((b) => ({ builder_id: b.builder_id, crafts: b.crafts })) };
+      }
+      if (/SELECT opted_in, updated_at FROM lifecycle_mingle_optin/.test(sql)) {
+        return { rows: [{ opted_in: true, updated_at: '2026-09-03T00:00:00Z' }] };
+      }
+      if (/INSERT INTO lifecycle_mingle_optin/.test(sql)) {
+        return { rows: [{ builder_id: params[0], opted_in: params[1], updated_at: 'now' }] };
+      }
+      if (/SELECT builder_lo::text AS lo/.test(sql)) {
+        return { rows: openPairs.map(([lo, hi]) => ({ lo, hi })) };
+      }
+      if (/INSERT INTO lifecycle_mingle_pairs/.test(sql)) {
+        // The round writes ONE bulk insert via unnest(), so the params are four
+        // parallel arrays rather than four scalars.
+        const [los, his, cl, ch] = params;
+        return {
+          rows: los.map((lo, i) => ({
+            id: i + 1, builder_lo: lo, builder_hi: his[i], craft_lo: cl[i], craft_hi: ch[i],
+            status: 'proposed', created_at: 'now',
+          })),
+        };
+      }
+      if (/UPDATE lifecycle_mingle_pairs/.test(sql)) {
+        return { rows: pairRow ? [pairRow] : [] };
+      }
+      if (/FROM lifecycle_mingle_pairs p/.test(sql)) return { rows: [] };
+      throw new Error(`unexpected query: ${sql.slice(0, 70)}`);
+    },
+  };
+}
+
+const on = () => async () => ({ value: 'true' });
+const off = () => async () => null;
+
+// ── 1. A PAIR IS ONLY EVER CROSS-CRAFT ──────────────────────────────────────
+
+test('THE RULE: crafts must be DISJOINT, not merely different', () => {
+  assert.equal(mingle.isCrossCraft(['builder'], ['artist']), true);
+  assert.equal(mingle.isCrossCraft(['builder'], ['builder']), false);
+  // The case a "different primary craft" rule would get wrong: someone who is
+  // both shares a craft with a pure engineer, so pairing them puts two of the
+  // same in a room and calls it cross-craft.
+  assert.equal(mingle.isCrossCraft(['artist', 'builder'], ['builder']), false);
+  assert.equal(mingle.isCrossCraft(['artist', 'builder'], ['ideator']), true);
+});
+
+test('a builder with NO craft is never pairable', () => {
+  // Belonging to a craft is a claim about yourself the system must not assume —
+  // the same fail-closed answer help-requests gives.
+  assert.equal(mingle.isCrossCraft([], ['artist']), false);
+  assert.equal(mingle.isCrossCraft(['artist'], []), false);
+  const pairs = mingle.planPairs([
+    { builder_id: '1', crafts: [] },
+    { builder_id: '2', crafts: ['artist'] },
+  ]);
+  assert.deepEqual(pairs, []);
+});
+
+test('EVERY pair the planner emits is cross-craft', () => {
+  const eligible = [
+    { builder_id: '10', crafts: ['builder'] },
+    { builder_id: '20', crafts: ['builder'] },
+    { builder_id: '30', crafts: ['artist'] },
+    { builder_id: '40', crafts: ['ideator'] },
+    { builder_id: '50', crafts: ['artist', 'builder'] },
+  ];
+  const byId = new Map(eligible.map((b) => [b.builder_id, b.crafts]));
+  const pairs = mingle.planPairs(eligible);
+  assert.ok(pairs.length > 0, 'the planner found pairs at all');
+  for (const p of pairs) {
+    assert.equal(mingle.isCrossCraft(byId.get(p.builder_lo), byId.get(p.builder_hi)), true,
+      `${p.builder_lo}/${p.builder_hi} share a craft`);
+    assert.notEqual(p.craft_lo, p.craft_hi, 'the recorded crafts differ');
+  }
+});
+
+test('nobody is put in two pairs in one round', () => {
+  const pairs = mingle.planPairs([
+    { builder_id: '1', crafts: ['builder'] },
+    { builder_id: '2', crafts: ['artist'] },
+    { builder_id: '3', crafts: ['ideator'] },
+    { builder_id: '4', crafts: ['ui'] },
+  ]);
+  const seen = new Set();
+  for (const p of pairs) {
+    for (const id of [p.builder_lo, p.builder_hi]) {
+      assert.ok(!seen.has(id), `${id} appears twice`);
+      seen.add(id);
+    }
+  }
+});
+
+test('CROSS-CRAFT IS ALSO A DATABASE CONSTRAINT, not only a matcher rule', () => {
+  // Enforcing it solely in the matcher leaves any future writer — a backfill, a
+  // second caller, a fixture — free to violate the property the feature is named
+  // for.
+  assert.match(MIGRATION, /CHECK \(craft_lo <> craft_hi\)/);
+  assert.match(MIGRATION, /CHECK \(builder_lo <> builder_hi\)/);
+});
+
+test('the matching rule is RECORDED, and the route serves it verbatim', () => {
+  // "chosen deliberately and recorded" — a reader can fetch the rule rather than
+  // infer it from SQL.
+  const m = mingle.matchingModel();
+  assert.equal(m.rule, 'cross_craft');
+  assert.equal(m.overlap, 'none');
+  assert.ok(m.description && m.consent && m.decline);
+  assert.match(m.rejected, /same_craft/, 'the road not taken is recorded too');
+  assert.match(ROUTES, /matching: mingle\.matchingModel\(\)/);
+});
+
+// ── 2. DISABLING EITHER SWITCH PREVENTS PAIRING ─────────────────────────────
+
+test('SWITCH 1 OFF: the project disabled means no pairing, and no write at all', async () => {
+  const pool = recordingPool({ eligible: [
+    { builder_id: '1', crafts: ['builder'] },
+    { builder_id: '2', crafts: ['artist'] },
+  ] });
+  const out = await mingle.runMingleRound({}, { pool, getSetting: off() });
+  assert.deepEqual(out.paired, []);
+  assert.equal(out.skipped, 'project_disabled');
+  // Not "paired then discarded" — it never got as far as reading who is eligible.
+  assert.equal(pool.queries.length, 0, 'a disabled project issues no query');
+});
+
+test('SWITCH 2 OFF: eligibility is opted-in only, enforced in SQL', async () => {
+  const pool = recordingPool({ eligible: [] });
+  await mingle.eligibleBuilders({ pool });
+  const sql = pool.queries[0].sql;
+  assert.match(sql, /o\.opted_in = true/, 'only people who opted in');
+  assert.match(sql, /b\.status = 'active'/, 'and only active builders');
+});
+
+test('BOTH ON is the only state that pairs', async () => {
+  const pool = recordingPool({ eligible: [
+    { builder_id: '1', crafts: ['builder'] },
+    { builder_id: '2', crafts: ['artist'] },
+  ] });
+  const out = await mingle.runMingleRound({}, { pool, getSetting: on() });
+  assert.equal(out.skipped, null);
+  assert.equal(out.paired.length, 1);
+  assert.equal(out.paired[0].builder_lo, '1');
+});
+
+test('a round is ONE insert, so a partial round cannot be written', () => {
+  const pool = recordingPool({ eligible: [
+    { builder_id: '1', crafts: ['builder'] },
+    { builder_id: '2', crafts: ['artist'] },
+    { builder_id: '3', crafts: ['ideator'] },
+    { builder_id: '4', crafts: ['ui'] },
+  ] });
+  return mingle.runMingleRound({}, { pool, getSetting: on() }).then((out) => {
+    assert.equal(out.paired.length, 2, 'two pairs from four builders');
+    const inserts = pool.queries.filter((q) => /INSERT INTO lifecycle_mingle_pairs/.test(q.sql));
+    assert.equal(inserts.length, 1, 'one statement for the whole round, not one per pair');
+    assert.match(inserts[0].sql, /unnest\(\$1::bigint\[\]/);
+  });
+});
+
+test('an empty plan writes nothing at all', async () => {
+  // Two builders of the SAME craft are not a pair, so there is nothing to insert
+  // — and no empty INSERT should be issued to discover that.
+  const pool = recordingPool({ eligible: [
+    { builder_id: '1', crafts: ['builder'] },
+    { builder_id: '2', crafts: ['builder'] },
+  ] });
+  const out = await mingle.runMingleRound({}, { pool, getSetting: on() });
+  assert.deepEqual(out.paired, []);
+  assert.equal(pool.queries.filter((q) => /INSERT/.test(q.sql)).length, 0);
+});
+
+test('FAIL CLOSED: the project switch opens only on an explicit yes', () => {
+  for (const yes of ['true', 'TRUE', ' on ', '1', 'yes']) {
+    assert.equal(mingle.parseEnabled(yes), true, `${yes} is a yes`);
+  }
+  // Absent, blank, garbage, and a value that was valid before someone tightened
+  // this are all NO. A consent gate that opens on an unreadable value is not a gate.
+  for (const no of [null, undefined, '', 'false', 'maybe', 'enabled', '2', 'off']) {
+    assert.equal(mingle.parseEnabled(no), false, `${String(no)} is not a yes`);
+  }
+});
+
+test('FAIL CLOSED: an unreadable project switch is not permission', async () => {
+  const enabled = await mingle.projectEnabled({ getSetting: async () => { throw new Error('db down'); } });
+  assert.equal(enabled, false);
+});
+
+test('the two switches are reported SEPARATELY, so a builder can see which is off', async () => {
+  // "You cannot mingle" with no reason is a dead end for the person who could fix
+  // half of it.
+  const pool = recordingPool();
+  const state = await mingle.mingleStateFor(7, { pool, getSetting: off() });
+  assert.equal(state.enabled, false);
+  assert.equal(state.project_enabled, false);
+  assert.equal(state.opted_in, true, 'my half is still reported as mine');
+});
+
+// ── 3. A DECLINE CARRIES NO PENALTY ─────────────────────────────────────────
+
+// Anything that would make declining cost something. Matched against the SQL a
+// decline actually issues AND against the module source.
+const PENALTY_SURFACES = /credit|karma|rank|streak|achievement|reward|score|penalt|cooldown|strike/i;
+
+test('THE NO-PENALTY PROPERTY: a decline writes ONE row in ONE table', async () => {
+  const pool = recordingPool({ pairRow: { id: 5, builder_lo: '1', builder_hi: '2', craft_lo: 'builder', craft_hi: 'artist', status: 'declined', decided_by: '1', decided_at: 'now' } });
+  const out = await mingle.decidePair(5, 1, 'declined', { pool });
+  assert.equal(out.pair.status, 'declined');
+
+  assert.equal(pool.queries.length, 1, 'exactly one statement');
+  const { sql } = pool.queries[0];
+  assert.match(sql, /UPDATE lifecycle_mingle_pairs/);
+  // The whole point: nothing else was touched. This is an assertion about the
+  // COMPLETE set of statements, which is the only honest way to test an absence.
+  assert.ok(!PENALTY_SURFACES.test(sql), `a decline touched a penalty surface: ${sql}`);
+});
+
+test('NO FUTURE MATCHING WEIGHT: the eligibility read cannot see pair history', async () => {
+  // This is the structural half, and it is what makes "no penalty" a property
+  // rather than a promise: the read that decides who may be paired has no way to
+  // learn that someone declined, so a decline cannot lower their odds.
+  const pool = recordingPool({ eligible: [] });
+  await mingle.eligibleBuilders({ pool });
+  const sql = pool.queries[0].sql;
+  assert.ok(!/lifecycle_mingle_pairs/.test(sql),
+    'eligibleBuilders must never join the pairs table');
+  assert.ok(!PENALTY_SURFACES.test(sql), 'eligibility reads no penalty surface either');
+});
+
+test('a declined pair may be introduced again — a decline is not a permanent split', () => {
+  // The only thing pair history gates is a second OPEN proposal for the same two
+  // people (the unique index's job). A settled pair is absent from that set, so
+  // it can come back. A permanent exclusion would be a consequence, and declining
+  // is free.
+  assert.match(MIGRATION, /CREATE UNIQUE INDEX[\s\S]{0,200}lifecycle_mingle_pairs_open_uniq[\s\S]{0,120}WHERE status = 'proposed'/);
+  const eligible = [
+    { builder_id: '1', crafts: ['builder'] },
+    { builder_id: '2', crafts: ['artist'] },
+  ];
+  // With the pair already OPEN, it is skipped...
+  assert.deepEqual(mingle.planPairs(eligible, { excludePairs: new Set(['1:2']) }), []);
+  // ...and once settled it is not in the exclude set at all, so it returns.
+  assert.equal(mingle.planPairs(eligible, { excludePairs: new Set() }).length, 1);
+});
+
+test('the exclude set is built from OPEN pairs only, never from declines', async () => {
+  const pool = recordingPool({ openPairs: [['1', '2']] });
+  await mingle.openPairKeys({ pool });
+  assert.match(pool.queries[0].sql, /WHERE status = 'proposed'/);
+  assert.ok(!/declined/.test(pool.queries[0].sql), 'declines are not read back');
+});
+
+test('NOTHING in the module reaches a penalty surface', () => {
+  // The source-level backstop for the two behavioural tests above: a future
+  // "small" addition — bump a counter, dock some karma — fails here even if it
+  // never runs in a test.
+  //
+  // TWO EXEMPTIONS, AND THEY ARE THE SAME ONE. Comments discuss penalties, and so
+  // does the MATCHING literal — its whole job is to record, in words a surface can
+  // render, WHICH standing a decline does not touch. Naming a surface in order to
+  // disclaim it is the opposite of reaching for it, so both are stripped before
+  // the scan. This is the codebase's standing convention: a line that CITES a rule
+  // is the only thing exempt from it (scripts/gds/fitness.js says so of the
+  // category-advisory guard). Everything else — every identifier, every line of
+  // SQL — is scanned.
+  const code = SRC
+    .replace(/^\s*\/\/.*$/gm, '')
+    .replace(/const MATCHING = Object\.freeze\(\{[\s\S]*?\n\}\);/, '');
+  assert.ok(!/MATCHING = Object\.freeze/.test(code), 'the MATCHING literal was actually stripped');
+  assert.ok(!/credits|karma|streak|achievement/i.test(code),
+    'mingle.js must not touch a credit/karma/streak/achievement surface');
+});
+
+test('the schema carries no penalty column', () => {
+  // A table that recorded a decline anywhere but in its own status column would be
+  // the penalty the criterion forbids — the same posture lifecycle_005 takes.
+  const ddl = MIGRATION.replace(/^\s*--.*$/gm, '');
+  assert.ok(!/credit|karma|streak|cooldown|penalt|count/i.test(ddl),
+    'no counter, cooldown or penalty column');
+});
+
+// ── the routes ──────────────────────────────────────────────────────────────
+
+test('consent is keyed by the SESSION, never a body field', () => {
+  // Consent you can give on someone else's behalf is not consent.
+  assert.match(ROUTES, /mingle\.setOptIn\(req\.builder\.id/);
+  assert.ok(!/setOptIn\(\s*req\.body/.test(ROUTES));
+});
+
+test('the operator routes gate on the ATOM; my own switch gates on nothing', () => {
+  // BV1.R105: a modules/*/routes gate is a permission atom, never a rank —
+  // tests/government_require_permission fails the build on a new requireRank, and
+  // the two files still spelling it that way are documented holdouts.
+  const projectRoute = ROUTES.slice(ROUTES.indexOf("router.put('/mingle/project'"));
+  assert.match(projectRoute.slice(0, 220), /requirePermission\('mingle\.manage'\)/);
+  const roundRoute = ROUTES.slice(ROUTES.indexOf("router.post('/mingle/round'"));
+  assert.match(roundRoute.slice(0, 220), /requirePermission\('mingle\.manage'\)/);
+
+  const optIn = ROUTES.slice(ROUTES.indexOf("router.put('/mingle/opt-in'"), ROUTES.indexOf("router.put('/mingle/project'"));
+  assert.ok(!/requirePermission|requireRank/.test(optIn),
+    'opting YOURSELF in is not a privileged act');
+});
+
+test('the atom is declared in the catalog, and a permission no route consumes does not exist', () => {
+  const catalog = read('modules', 'government', 'catalog.js');
+  assert.match(catalog, /key: 'mingle\.manage'/, 'the atom is declared');
+  assert.match(catalog, /key: 'mingle\.manage'[^\n]*floor: 'metic'/, 'at the discord.channels.manage floor');
+  assert.match(catalog, /key: 'mingle\.manage'[^\n]*guards: '[^']*\/mingle\/project/, 'and it names the routes it guards');
+});
+
+test('you can only answer an introduction you are in, and the check is in SQL', () => {
+  const fn = SRC.slice(SRC.indexOf('async function decidePair'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /builder_lo = \$2 OR builder_hi = \$2/,
+    'membership is enforced by the UPDATE, not by a check a later caller could skip');
+  assert.match(body, /status = 'proposed'/, 'and a settled pair cannot be re-decided');
+});
+
+test('the route is registered in the module manifest', () => {
+  const manifest = JSON.parse(read('modules', 'lifecycle', 'module.json'));
+  assert.ok(manifest.contributes.routes.includes('mingle'));
+});
+
+test('the craft vocabulary is CONSUMED from help-requests, never redefined', () => {
+  // Two spellings of the same craft ('builder' the craft is 'engineer' the
+  // discipline) would silently match nobody.
+  assert.match(SRC, /require\('\.\/help-requests'\)/);
+  assert.ok(!/CRAFT_TO_DISCIPLINE\s*=|DISCIPLINE_TO_CRAFT\s*=/.test(SRC),
+    'mingle must not declare its own craft map');
+});

package/tests/projects_hub.mjs

@@ -706,14 +706,15 @@ test('the About answers travel on the create request, and an empty one is OMITTE
 });
 
 test('a renumbering of the wizard invalidates old drafts — the key carries the version', () => {
-  // task 1002772 renumbered once and bumped to -v2; task 1002334 renumbered again.
-  // A draft replayed under a different numbering lands on the wrong panel with the
-  // rail already marking the skipped steps done.
+  // task 1002772 renumbered once and bumped to -v2; task 1002334 renumbered again;
+  // task 1002339 (the module picker) is the third. A draft replayed under a
+  // different numbering lands on the wrong panel with the rail already marking
+  // the skipped steps done.
   const key = (SCRIPT.match(/var DRAFT_KEY = '([^']+)'/) || [, ''])[1];
   assert.match(key, /-v\d+$/, 'the draft key is versioned');
   const panels = (SCRIPT.match(/var panels = \{([^}]*)\}/) || [, ''])[1];
   const count = [...panels.matchAll(/\d+:\s*'panel-/g)].length;
-  assert.equal(count, 8, 'gate + six numbered steps + done — bump DRAFT_KEY when this changes');
+  assert.equal(count, 9, 'gate + seven numbered steps + done — bump DRAFT_KEY when this changes');
 });
 
 test('every row lays the same five parts — the ledger has no ragged row', () => {
@@ -2058,7 +2059,9 @@ test('the wizard takes the world by scope: no card ground, the six-step strip as
   assert.ok(at > -1, 'the #view-new block exists in cosmos.css');
   const block = COSMOS.slice(at);
   assert.match(block, /#view-new \.card\{background:none;border-radius:0;box-shadow:none;/, 'no card ground');
-  assert.match(block, /#view-new \.steps\{display:grid;grid-template-columns:repeat\(6,1fr\);/, 'the strip lays its six steps on six tracks');
+  // seven tracks since task 1002339 added the Modules step; the count is the
+  // rail's own, so it moves with the panels map rather than being a magic number
+  assert.match(block, /#view-new \.steps\{display:grid;grid-template-columns:repeat\(7,1fr\);/, 'the strip lays a track per numbered step');
   assert.match(block, /#view-new \.steps li::before\{content:"";position:absolute;top:-4px;left:0;right:auto;width:7px;height:7px;/, 'the connector becomes the 7px dot');
   assert.match(block, /#view-new \.steps li\.now::before\{background:var\(--accent\);border-color:var\(--accent\);outline:4px solid/, 'the lit step carries the accent and an outline halo');
   assert.match(block, /#view-new \.panel h1\{font-weight:300;[^}]*text-transform:lowercase;/, 'the step title in the display voice, lowercase');
@@ -2105,7 +2108,7 @@ test('the wizard\'s own structures wear the world: hairline fields, cells of one
   assert.match(block, /\.addrBig code\{display:block;font-family:var\(--font-display\);/, 'the address stands in the display voice');
   assert.doesNotMatch(block, /linear-gradient/, 'no tinted plates');
   assert.doesNotMatch(block, /box-shadow:(?!none)/, 'no box shadow in the wizard block');
-  assert.match(HUB, /<div class="nav">\s*<button type="button" class="btn ghost" data-back="5">← Back<\/button>\s*<button type="button" class="btn big" id="doCreate">Create my project<\/button>/, 'the review\'s doors sit on one row, back then the primary');
+  assert.match(HUB, /<div class="nav">\s*<button type="button" class="btn ghost" data-back="6">← Back<\/button>\s*<button type="button" class="btn big" id="doCreate">Create my project<\/button>/, 'the review\'s doors sit on one row, back then the primary');
   assert.match(HUB, /<h2 class="stepsHead">Your steps — the parts only you can play<\/h2>/, 'the steps heading is the label face by class, not an inline style');
   // what is enqueued is unchanged (ADR 0111): the filing body the control plane reads
   assert.match(SCRIPT, /body: JSON\.stringify\(\{\s*slug: state\.slug,/, 'the filing still carries the slug first');
@@ -2114,7 +2117,69 @@ test('the wizard\'s own structures wear the world: hairline fields, cells of one
   assert.match(SCRIPT, /onboard_mode: state\.mode === 'adopt' \? 'adopt' : 'greenfield'/, 'the onboard mode is unchanged');
   // the kit walks every step and files against the stub
   const states = JSON.parse(fs.readFileSync(path.join(LANDING, 'projects.states.json'), 'utf8')).states;
-  for (const s of ['type', 'about', 'home', 'address', 'review', 'done']) assert.ok(states['in-new-' + s], `the ${s} step has a kit state`);
+  for (const s of ['type', 'about', 'modules', 'home', 'address', 'review', 'done']) assert.ok(states['in-new-' + s], `the ${s} step has a kit state`);
   const probes = JSON.parse(fs.readFileSync(path.join(LANDING, 'projects.probes.json'), 'utf8')).probes;
   assert.ok(probes.some((p) => /the wizard driver \(task 1003346\)/.test(p.name) && p.steps.some((st) => st[1] === '#doCreate')), 'the wizard driver files a project end to end');
 });
+
+test('the Modules step ships as real markup and is skippable like About (task 1002339)', () => {
+  const panel = (HUB.match(/<section class="panel" id="panel-modules"[\s\S]*?<\/section>/) || [''])[0];
+  assert.ok(panel, '#panel-modules ships as real markup, not built by script');
+  assert.match(panel, /id="modCards"/, 'the band the picker paints its rows into');
+  assert.match(panel, /class="typeCards"/, 'and it is the SAME band the type and team questions use — no new grammar');
+  assert.match(panel, /id="modCoreNote"/, 'the always-on core is stated on the panel');
+  // the skip must be its own control, not "leave it and press Next" — the rule
+  // task 1002334 wrote for the one other optional step
+  assert.match(panel, /id="skipModules"/, 'the skip is a control, not an inference');
+  assert.match(panel, /Optional/, 'and the panel says so before it asks');
+  // nothing in validateStep may gate it
+  const validate = SCRIPT.slice(SCRIPT.indexOf('function validateStep('));
+  const map = SCRIPT.match(/var panels = \{([^}]*)\}/)[1];
+  const modStep = Number((map.match(/(\d+):\s*'panel-modules'/) || [, 0])[1]);
+  assert.ok(modStep > 0, 'the Modules panel is in the map');
+  assert.ok(!validate.slice(0, validate.indexOf('function ', 1)).includes(`if (step === ${modStep}) {`),
+    'the optional step has no validation clause — Next past an untouched picker is the point');
+});
+
+test('the picker reads ONE public declaration, and it is the one the bundles come from (task 1002339)', () => {
+  // A second source for "what may be chosen" is exactly what would let a
+  // preselect name a module the panel has no row for (ADR 0237 §5).
+  assert.match(SCRIPT, /fetch\(API \+ '\/provisioning\/starter-bundles'/, 'the picker reads the starter-bundles route');
+  assert.equal((SCRIPT.match(/'\/provisioning\/starter-bundles'/g) || []).length, 1, 'exactly once');
+  // and it is a public read — no other module-catalog call joins it
+  assert.doesNotMatch(SCRIPT, /fetch\(API \+ '\/modules'/, 'no signed-in catalog read from a signed-out wizard');
+});
+
+test('the picker\'s answer rides the create request, and an untouched picker sends nothing (task 1002339)', () => {
+  // absent means SKIPPED, and the server then applies the same starter bundle
+  // the panel preselected — the same contract `description` and `detail` carry
+  const body = SCRIPT.slice(SCRIPT.indexOf('body: JSON.stringify({'));
+  assert.ok(body.includes('modules: modulesForCreate(),'), 'the create body carries the picker\'s ids');
+  assert.match(SCRIPT, /function modulesForCreate\(\) \{\s*return state\.modules === null \? undefined : state\.modules\.slice\(\);/,
+    'and modulesForCreate() omits the key while nothing has been said');
+});
+
+test('the review names what the project will actually come with (task 1002339)', () => {
+  // The picker is optional, so the last screen before Create must show the set
+  // the owner is about to get — their picks, or the preselect they walked past.
+  const render = SCRIPT.slice(SCRIPT.indexOf('function renderReview()'));
+  const rows = render.slice(0, render.indexOf('$(\'reviewList\').innerHTML'));
+  assert.match(rows, /\['Extras', extrasRow\(\)\]/, 'the ledger carries an Extras row');
+  // What that row SAYS has three cases (picked / preselect / catalog not loaded)
+  // and they live with the picker's own rules, executed by
+  // tests/projects_hub_module_picker.mjs. This pins that the review defers to them.
+  assert.match(SCRIPT, /function extrasRow\(\) \{/, 'and it is the picker that decides what it says');
+  assert.match(SCRIPT, /'None — just the core'/, 'an empty selection reads as a fact, not a blank');
+});
+
+test('the kit stub answers the picker\'s read, so the panel renders in the design kit (task 1002339)', () => {
+  // The stub is not the server (this module's CLAUDE.md trap): it serves
+  // fixtures. A 404 here would have rendered the couldn't-load clause in every
+  // state and probe, and nobody would have seen the picker at all.
+  const stub = fs.readFileSync(path.join(ROOT, 'modules', 'ui-design', 'kit', 'serve.js'), 'utf8');
+  assert.match(stub, /rest === '\/provisioning\/starter-bundles'/, 'the stub serves the picker\'s read');
+  const probes = JSON.parse(fs.readFileSync(path.join(LANDING, 'projects.probes.json'), 'utf8')).probes;
+  assert.ok(probes.some((p) => /the wizard driver \(task 1003346\)/.test(p.name)
+    && p.steps.some((st) => st[1] === '#panel-modules button[type=submit]')),
+  'and the end-to-end driver walks the new step rather than stopping at it');
+});