@bongos/core 1.25.16 → 1.25.18

package/tests/first_read.mjs

@@ -0,0 +1,479 @@
+// tests/first_read.mjs — THE FIRST READ-THROUGH of a project that already exists (task
+// 1005280, goal 1000106).
+//
+// Done-when: an adopted project's Genesis step hands the owner a prompt for their OWN AI
+// session; that session's map comes back in a defined, validated shape; the owner
+// accepts it whole or item by item into DRAFT goals and tasks; a rejection files
+// nothing; a re-run files nothing twice; the shape has room for task 1005281's
+// recommended modules.
+//
+// Everything here RUNS: the real prompt and Genesis checklist, the real validator and
+// acceptance planner, the real store over an in-memory fake pool, and the real router
+// over a socket.
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const fr = require('../modules/lifecycle/first-read.js');
+const storeModule = require('../modules/lifecycle/first-read-db.js');
+// A snapshot of the real store: the route section below re-points the module's exports
+// at its own pool, and module-level code runs before any test does.
+const store = { ...storeModule };
+const { genesisChecklist } = require('../modules/lifecycle/kickoff-checklist.js');
+
+const clone = (o) => JSON.parse(JSON.stringify(o));
+
+// ── an in-memory pool that answers exactly the store's statements ─────────────
+
+function fakePool() {
+  const s = { maps: [], filed: new Map(), goals: [], tasks: [], nextId: 1 };
+  const query = async (sql, p = []) => {
+    const q = sql.replace(/\s+/g, ' ').trim();
+    if (/^(BEGIN|COMMIT|ROLLBACK)$/.test(q) || /pg_advisory_xact_lock/.test(q)) return { rows: [] };
+    if (/^INSERT INTO lifecycle_repo_maps/.test(q)) {
+      const row = { id: String(s.nextId++), schema: p[0], map: JSON.parse(p[1]), status: 'pending', submitted_by: p[2], submitted_at: new Date() };
+      s.maps.push(row); return { rows: [row] };
+    }
+    if (/FROM lifecycle_repo_maps ORDER BY/.test(q)) return { rows: s.maps.slice(-1) };
+    if (/^SELECT .* FROM lifecycle_repo_maps WHERE id = \$1/.test(q)) return { rows: s.maps.filter((m) => m.id === String(p[0])) };
+    if (/^SELECT ref, kind, entity_id FROM lifecycle_repo_map_filed/.test(q)) {
+      return { rows: p[0].filter((r) => s.filed.has(r)).map((r) => ({ ref: r, ...s.filed.get(r) })) };
+    }
+    if (/^INSERT INTO lifecycle_repo_map_filed .*'dismissed', NULL/.test(q)) {
+      // the owner's no: ON CONFLICT DO NOTHING
+      for (const ref of p[0]) if (!s.filed.has(ref)) s.filed.set(ref, { kind: 'dismissed', entity_id: null, map_id: p[1] });
+      return { rows: [] };
+    }
+    if (/^INSERT INTO lifecycle_repo_map_filed .* unnest/.test(q)) {
+      s.filedWrites = (s.filedWrites || 0) + 1;
+      p[0].forEach((ref, i) => {
+        // ON CONFLICT ... DO UPDATE ... WHERE kind = 'dismissed': only a dismissed row is replaced
+        if (s.filed.has(ref) && s.filed.get(ref).kind !== 'dismissed') throw Object.assign(new Error('filed twice'), { code: '23505' });
+        s.filed.set(ref, { kind: p[1][i], entity_id: p[2][i], map_id: p[3] });
+      });
+      return { rows: [] };
+    }
+    if (/^SELECT id FROM versions/.test(q)) return { rows: [{ id: 'V1' }] };
+    if (/^UPDATE lifecycle_repo_maps SET status = 'accepted'/.test(q)) { s.maps.find((m) => m.id === String(p[0])).status = 'accepted'; return { rows: [] }; }
+    if (/^UPDATE lifecycle_repo_maps SET status = 'rejected'/.test(q)) {
+      const m = s.maps.find((x) => x.id === String(p[0]) && x.status === 'pending');
+      if (!m) return { rows: [] };
+      m.status = 'rejected'; return { rows: [{ id: m.id }] };
+    }
+    throw new Error('unexpected SQL: ' + q);
+  };
+  const pool = { query, connect: async () => ({ query, release() {} }), state: s };
+  const deps = {
+    pool,
+    createGoal: async (row, d) => { assert.ok(d && d.client, 'goals are created inside the accept transaction'); const g = { id: String(100 + s.goals.length), ...row }; s.goals.push(g); return g; },
+    createTask: async (row, d) => { assert.ok(d && d.client, 'tasks are created inside the accept transaction'); const t = { id: String(500 + s.tasks.length), ...row }; s.tasks.push(t); return t; },
+  };
+  return { pool, deps, s };
+}
+
+// ── the prompt ───────────────────────────────────────────────────────────────
+
+test('the prompt sends the owner\'s own session to read locally, map in the defined shape, and accept only with a yes', () => {
+  const p = fr.firstReadPrompt();
+  for (const must of [
+    'own AI session', 'Bongos itself never reads this repository', 'Do not upload, paste or send any source code',
+    fr.MAP_FILE, fr.SCHEMA, '"goals"', '"next"', '"why"', '"seen_at"', 'errors or mishaps',
+    'first-read check', 'first-read submit', 'first-read accept', 'first-read reject', 'first-read dismiss', 'Never accept or dismiss on your own',
+    'not filed twice',
+  ]) assert.ok(p.includes(must), `the prompt says: ${must}`);
+  // The example it prints is itself a valid map, so a session that copies it is on the shape.
+  assert.equal(fr.validateRepoMap(fr.exampleMap()).ok, true);
+  const from = p.indexOf('Use exactly this shape:') + 'Use exactly this shape:'.length;
+  const printed = JSON.parse(p.slice(p.indexOf('{', from), p.indexOf('\n   - Optional', from)));
+  assert.deepEqual(printed, fr.exampleMap());
+});
+
+test('an adopted project\'s Genesis step carries the prompt; a new project\'s does not', () => {
+  const existing = genesisChecklist({ existing: true }).scope;
+  assert.equal(existing[0].ref, 'genesis:scope:existing', 'the step keeps its ref, so a seeded project is not refiled');
+  assert.ok(existing[0].description.includes(fr.firstReadPrompt()), 'the hall copy-prompt hands over the whole prompt');
+  assert.ok(/own AI/.test(existing[0].title));
+  const fresh = genesisChecklist().scope;
+  assert.ok(fresh.every((t) => !t.description.includes(fr.SCHEMA)));
+});
+
+// ── validation ───────────────────────────────────────────────────────────────
+
+test('a good map validates into a flat review list with stable refs', () => {
+  const v = fr.validateRepoMap(fr.exampleMap());
+  assert.equal(v.ok, true);
+  assert.deepEqual(v.items.map((i) => [i.type, i.ref]), [
+    ['goal', 'goal:take-payments-for-bookings'],
+    ['task', 'task:take-payments-for-bookings:finish-the-checkout-page'],
+    ['task', 'task:take-payments-for-bookings:send-a-receipt-by-email'],
+    ['next', 'next:fix-the-failing-booking-test'],
+  ]);
+  assert.ok(v.items.every((i) => i.why && i.seen_at.length));
+  assert.equal(v.items[3].goal_ref, fr.NEXT_GOAL.ref, 'a next item naming no goal lands under the fix-what-was-found goal');
+});
+
+test('a section this version does not read rides along without breaking the shape', () => {
+  const raw = { ...fr.exampleMap(), later_section: [{ key: 'x', why: 'room to grow' }] };
+  const v = fr.validateRepoMap(raw);
+  assert.equal(v.ok, true);
+  assert.deepEqual(v.map.later_section, raw.later_section);
+});
+
+test('a prototype-shaped key in the map is never copied onto it', () => {
+  const raw = JSON.parse(`{"schema":"${fr.SCHEMA}","summary":"s","next":[{"title":"t","why":"w","seen_at":["a"]}],"__proto__":{"polluted":true},"constructor":{"x":1}}`);
+  const v = fr.validateRepoMap(raw);
+  assert.equal(v.ok, true);
+  assert.equal(v.map.polluted, undefined);
+  assert.equal(Object.getPrototypeOf(v.map), Object.prototype);
+  assert.ok(!Object.prototype.hasOwnProperty.call(v.map, 'constructor'));
+  assert.equal(({}).polluted, undefined);
+});
+
+test('malformed maps are refused, each error naming its field', () => {
+  const cases = [
+    [null, /JSON object/],
+    [[], /JSON object/],
+    [{ ...fr.exampleMap(), schema: 'other/1' }, /schema must be/],
+    [{ ...fr.exampleMap(), goals: 'lots' }, /goals must be a list/],
+    [{ schema: fr.SCHEMA, summary: 'x', goals: [], next: [] }, /no goals and nothing next/],
+    [(() => { const m = fr.exampleMap(); delete m.goals[0].why; return m; })(), /goals\[0\]\.why is missing/],
+    [(() => { const m = fr.exampleMap(); m.goals[0].tasks[0].seen_at = []; return m; })(), /goals\[0\]\.tasks\[0\]\.seen_at needs at least one place/],
+    [(() => { const m = fr.exampleMap(); m.goals[0].tasks[1].status = 'half'; return m; })(), /status must be one of/],
+    [(() => { const m = fr.exampleMap(); m.goals[0].tasks[1].title = m.goals[0].tasks[0].title; return m; })(), /repeats another item's title/],
+    [(() => { const m = fr.exampleMap(); m.next[0].goal = 'No such goal'; return m; })(), /not a goal in this map/],
+    [(() => { const m = fr.exampleMap(); m.next[0].kind = 'oops'; return m; })(), /kind must be one of/],
+    [(() => { const m = fr.exampleMap(); m.goals[0].why = 'x'.repeat(fr.LIMITS.WHY + 1); return m; })(), /longer than/],
+    [(() => { const m = fr.exampleMap(); m.summary = 'y'.repeat(fr.LIMITS.BYTES); return m; })(), /larger than/],
+    [(() => { const m = fr.exampleMap(); m.goals[0].title = '!!!'; return m; })(), /needs letters or numbers/],
+  ];
+  for (const [raw, re] of cases) {
+    const v = fr.validateRepoMap(raw);
+    assert.equal(v.ok, false, `refused: ${re}`);
+    assert.ok(v.errors.some((e) => re.test(e)), `${re} in ${JSON.stringify(v.errors)}`);
+  }
+});
+
+// ── the store: submit, accept, reject, re-run ────────────────────────────────
+
+test('submitting files nothing: the map waits pending', async () => {
+  const { deps, s } = fakePool();
+  const out = await store.submitMap({ raw: fr.exampleMap(), builderId: '1' }, deps);
+  assert.equal(out.ok, true);
+  assert.equal(s.maps[0].status, 'pending');
+  assert.equal(s.goals.length + s.tasks.length, 0);
+  const bad = await store.submitMap({ raw: { schema: 'nope' } }, deps);
+  assert.equal(bad.ok, false);
+  assert.equal(s.maps.length, 1, 'a malformed map is not stored');
+});
+
+test('accepting the whole map files draft goals and backlog tasks, nothing claimable', async () => {
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw: fr.exampleMap(), builderId: '1' }, deps);
+  const out = await store.acceptMap({ mapId: map_id, select: 'all', builderId: '1' }, deps);
+  assert.equal(out.ok, true);
+  assert.deepEqual(s.goals.map((g) => g.title), ['Take payments for bookings', fr.NEXT_GOAL.title]);
+  assert.equal(s.tasks.length, 3);
+  for (const t of s.tasks) {
+    assert.equal(t.status, 'backlog');
+    assert.equal(t.source, store.TASK_SOURCE);
+    assert.ok(t.goalId, 'every task has a goal home');
+    assert.ok(t.description.includes('Seen at:'));
+  }
+  assert.equal(s.tasks.find((t) => t.title === 'Fix the failing booking test').kind, 'bug');
+  assert.equal(s.tasks.find((t) => t.title === 'Fix the failing booking test').goalId, s.goals[1].id);
+  assert.equal(s.maps[0].status, 'accepted');
+  assert.equal(s.filedWrites, 1, 'every filed ref is remembered in one statement');
+  assert.equal(s.filed.size, 5);
+});
+
+test('accepting item by item files only what the owner chose (and the goal it needs)', async () => {
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw: fr.exampleMap() }, deps);
+  const out = await store.acceptMap({ mapId: map_id, select: ['task:take-payments-for-bookings:send-a-receipt-by-email'] }, deps);
+  assert.equal(out.ok, true);
+  assert.deepEqual(s.goals.map((g) => g.title), ['Take payments for bookings']);
+  assert.deepEqual(s.tasks.map((t) => t.title), ['Send a receipt by email']);
+  const unknown = await store.acceptMap({ mapId: map_id, select: ['task:nope'] }, deps);
+  assert.equal(unknown.code, 'unknown_items');
+  const none = await store.acceptMap({ mapId: map_id, select: [] }, deps);
+  assert.equal(none.code, 'nothing_selected');
+  assert.equal(s.tasks.length, 1, 'a refused accept files nothing');
+});
+
+test('a task the map says is done is shown, never filed', async () => {
+  const { deps, s } = fakePool();
+  const raw = fr.exampleMap();
+  raw.goals[0].tasks[0].status = 'done';
+  const { map_id } = await store.submitMap({ raw }, deps);
+  const out = await store.acceptMap({ mapId: map_id, select: 'all' }, deps);
+  assert.ok(out.skipped.some((x) => x.reason === 'already_done'));
+  assert.ok(!s.tasks.some((t) => t.title === 'Finish the checkout page'));
+});
+
+test('rejecting files nothing, and a rejected map cannot then be accepted', async () => {
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw: fr.exampleMap() }, deps);
+  assert.equal((await store.rejectMap({ mapId: map_id, builderId: '1' }, deps)).ok, true);
+  assert.equal(s.maps[0].status, 'rejected');
+  const again = await store.acceptMap({ mapId: map_id, select: 'all' }, deps);
+  assert.equal(again.code, 'map_rejected');
+  assert.equal(s.goals.length + s.tasks.length, 0);
+  assert.equal((await store.rejectMap({ mapId: map_id }, deps)).code, 'not_pending');
+  assert.equal((await store.rejectMap({ mapId: '99' }, deps)).code, 'not_found');
+});
+
+test('a re-run does not duplicate: the same items are skipped, only new ones are filed', async () => {
+  const { deps, s } = fakePool();
+  const first = await store.submitMap({ raw: fr.exampleMap() }, deps);
+  await store.acceptMap({ mapId: first.map_id, select: 'all' }, deps);
+  const goalsBefore = s.goals.length;
+  const tasksBefore = s.tasks.length;
+  // Accepting the same map again files nothing.
+  const twice = await store.acceptMap({ mapId: first.map_id, select: 'all' }, deps);
+  assert.equal(twice.filed.goals.length + twice.filed.tasks.length, 0);
+  // A second read-through names the same items (reordered, retitled in case) plus one new task.
+  const raw = clone(fr.exampleMap());
+  raw.goals[0].title = 'TAKE PAYMENTS FOR BOOKINGS';
+  raw.goals[0].tasks.reverse();
+  raw.goals[0].tasks.push({ title: 'Refund a booking', status: 'not_started', why: 'No refund path exists.', seen_at: ['src/payments/'] });
+  const second = await store.submitMap({ raw }, deps);
+  const review = await store.reviewMap('latest', deps);
+  assert.equal(review.map_id, second.map_id);
+  assert.equal(review.items.filter((i) => i.filed).length, 4, 'the review marks what is already in Bongos');
+  const out = await store.acceptMap({ mapId: second.map_id, select: 'all' }, deps);
+  assert.equal(s.goals.length, goalsBefore, 'no goal filed twice');
+  assert.equal(s.tasks.length, tasksBefore + 1);
+  assert.deepEqual(out.filed.tasks.map((t) => t.title), ['Refund a booking']);
+  assert.equal(out.filed.tasks[0].goal_id, s.goals[0].id, 'the new task joins the goal filed by the first run');
+  assert.equal(out.skipped.filter((x) => x.reason === 'already_filed').length, 4);
+});
+
+// ── the routes, over a real socket ───────────────────────────────────────────
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const perms = [];
+api.requireBuilder = (req, _res, next) => { req.builder = { id: '7', rank: 'archon' }; next(); };
+api.requirePermission = (...p) => { perms.push(p.join(',')); return (_req, _res, next) => next(); };
+api.requireActAlone = (area) => { perms.push('act-alone:' + area); return (_req, _res, next) => next(); };
+
+const route = fakePool();
+for (const fn of ['submitMap', 'reviewMap', 'acceptMap', 'rejectMap', 'dismissItems']) {
+  storeModule[fn] = (a) => store[fn](a, route.deps);
+}
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+  res.fail = (code, status, details) => res.status(status || 400).json({ error: code, ...(details || {}) });
+  next();
+});
+app.use('/api/bongos', require('../modules/lifecycle/routes/first-read.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+after(() => server.close());
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+const call = async (method, p, body) => {
+  const r = await fetch(base + p, { method, headers: { 'content-type': 'application/json' }, body: body ? JSON.stringify(body) : undefined });
+  return { status: r.status, body: await r.json().catch(() => null) };
+};
+
+test('the routes: filing is gated like creating a goal, and the flow runs end to end', async () => {
+  assert.ok(perms.includes('goal.create'));
+  assert.ok(perms.includes('act-alone:planning'));
+  const prompt = await call('GET', '/first-read/prompt');
+  assert.equal(prompt.status, 200);
+  // No module list is registered in this test, so the prompt says so (task 1005281).
+  assert.equal(prompt.body.prompt, fr.firstReadPrompt({ catalog: null }));
+
+  const bad = await call('POST', '/first-read/maps', { map: { schema: fr.SCHEMA, summary: 'x', goals: [{ title: 'A' }] } });
+  assert.equal(bad.status, 400);
+  assert.equal(bad.body.error, 'invalid_map');
+  assert.ok(bad.body.errors.length >= 2);
+
+  const ok = await call('POST', '/first-read/maps', { map: fr.exampleMap() });
+  assert.equal(ok.status, 201);
+  assert.equal(route.s.tasks.length, 0, 'submit files nothing');
+
+  const bogus = await call('POST', `/first-read/maps/${ok.body.map_id}/accept`, { items: ['x'], all: true });
+  assert.equal(bogus.status, 400);
+  const accepted = await call('POST', `/first-read/maps/${ok.body.map_id}/accept`, { items: ['goal:take-payments-for-bookings'] });
+  assert.equal(accepted.status, 200);
+  assert.equal(accepted.body.filed.goals.length, 1);
+  assert.equal(accepted.body.filed.tasks.length, 0);
+
+  const shown = await call('GET', '/first-read/maps/latest');
+  assert.equal(shown.status, 200);
+  assert.equal(shown.body.items.find((i) => i.ref === 'goal:take-payments-for-bookings').filed.kind, 'goal');
+  assert.equal((await call('GET', '/first-read/maps/999')).status, 404);
+  assert.equal((await call('POST', `/first-read/maps/${ok.body.map_id}/reject`)).status, 409, 'an accepted map is not then rejected');
+});
+
+// ── recommended modules (task 1005281) ───────────────────────────────────────
+//
+// The owner's own session compares what the code does with this project's live module
+// list and may recommend from it. Only keys on that list are accepted; a recommendation
+// is a suggestion the owner accepts (a draft task to switch it on) or dismisses.
+
+const fc = require('../modules/lifecycle/first-read-catalog.js');
+
+const LISTED = [
+  { key: 'lifecycle', title: 'Lifecycle', description: 'Tasks and claims.', enabled: true },
+  { key: 'billing', title: 'Billing (internal name)', description: 'Takes card payments through the processor and keeps the ledger. Engineers: see ADR.', enabled: false },
+  { key: 'raise', title: 'Raise', description: 'A fundraising page.', enabled: false },
+];
+const PICKER = { optional: [{ key: 'billing', label: 'Billing', summary: 'Take payments and send receipts.' }] };
+const CATALOG = fc.buildCatalog(LISTED, PICKER);
+
+// A repository whose billing code keeps failing: a known weak area.
+function weakBillingMap() {
+  return {
+    schema: fr.SCHEMA,
+    summary: 'A shop whose own card-payment code keeps failing.',
+    next: [{ title: 'Payments fail at checkout', kind: 'error', why: 'Half the test charges fail with a timeout.', seen_at: ['src/billing/charge.js:30'] }],
+    recommended_modules: [{
+      module: 'billing', title: 'Session-chosen words, ignored',
+      found: 'The hand-written billing code retries forever and loses receipts.',
+      why: 'The Billing module takes payments and sends receipts, so this code can go.',
+      seen_at: ['src/billing/'],
+    }],
+  };
+}
+
+test('the catalog is this project\'s modules not yet on, in the picker\'s words where it has them', () => {
+  assert.deepEqual(CATALOG.map((m) => m.key), ['billing', 'raise'], 'an enabled module is not offered');
+  assert.equal(CATALOG[0].title, 'Billing');
+  assert.equal(CATALOG[0].summary, 'Take payments and send receipts.');
+  assert.equal(CATALOG[1].summary, 'A fundraising page.', 'otherwise the module\'s own first sentence');
+  assert.equal(fc.buildCatalog(null, null).length, 0);
+});
+
+test('the catalog is read live from the kernel port, and is null when no list can be read', async () => {
+  const seams = require('../src/module-seams.js');
+  assert.equal(await fc.switchOnCatalog(), null, 'no port, no list: nothing may be recommended');
+  // Left registered: the route test below reads the same list.
+  seams.registerProvider('modules.catalog', () => LISTED);
+  assert.deepEqual((await fc.switchOnCatalog()).map((m) => m.key), ['billing', 'raise']);
+});
+
+test('the prompt carries the live list; the Genesis copy tells the session how to get it', () => {
+  const p = fr.firstReadPrompt({ catalog: CATALOG });
+  assert.ok(p.includes('- billing: Billing. Take payments and send receipts.'));
+  assert.ok(p.includes('"recommended_modules"') && p.includes('Recommend only from the list'));
+  assert.ok(p.includes('no recommendation is a good answer'));
+  assert.ok(fr.firstReadPrompt().includes('first-read catalog'), 'the fixed Genesis text names the live list');
+  assert.ok(fr.firstReadPrompt({ catalog: null }).includes('could not be read'));
+});
+
+test('a repository with a known weak area gets the matching module, with its reason', async () => {
+  const v = fr.validateRepoMap(weakBillingMap(), { catalog: CATALOG });
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const mod = v.items.find((i) => i.type === 'module');
+  assert.equal(mod.ref, 'module:billing');
+  assert.equal(mod.title, 'Billing', 'the catalog\'s words, never the session\'s');
+  assert.match(mod.found, /retries forever/);
+  assert.match(mod.why, /takes payments/);
+  assert.deepEqual(v.map.recommended_modules[0].title, 'Billing');
+
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw: weakBillingMap(), catalog: CATALOG }, deps);
+  const out = await store.acceptMap({ mapId: map_id, select: 'all' }, deps);
+  assert.equal(out.ok, true);
+  assert.ok(s.goals.some((g) => g.title === fr.MODULES_GOAL.title));
+  const task = s.tasks.find((t) => t.sourceRef === 'module:billing');
+  assert.equal(task.title, 'Switch on the Billing module');
+  assert.equal(task.status, 'backlog', 'a draft: nothing is switched on, nothing is claimable');
+  assert.match(task.description, /Found: The hand-written billing code/);
+  assert.match(task.description, /Why the Billing module/);
+  assert.match(task.description, /Seen at: src\/billing\//);
+});
+
+test('a repository with nothing to replace gets no recommendation', async () => {
+  const raw = { ...fr.exampleMap() };
+  const v = fr.validateRepoMap(raw, { catalog: CATALOG });
+  assert.equal(v.ok, true);
+  assert.equal(v.items.filter((i) => i.type === 'module').length, 0);
+  assert.equal(v.map.recommended_modules, undefined);
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw, catalog: CATALOG }, deps);
+  await store.acceptMap({ mapId: map_id, select: 'all' }, deps);
+  assert.ok(!s.goals.some((g) => g.title === fr.MODULES_GOAL.title), 'no modules goal is filed for an empty section');
+  assert.ok(!s.tasks.some((t) => /^Switch on the/.test(t.title)));
+});
+
+test('an unknown module, a repeated one, or any module when no list can be read, is refused', async () => {
+  const unknown = weakBillingMap();
+  unknown.recommended_modules[0].module = 'stripe-magic';
+  let v = fr.validateRepoMap(unknown, { catalog: CATALOG });
+  assert.equal(v.ok, false);
+  assert.ok(v.errors.some((e) => /"stripe-magic" is not a module this project can switch on/.test(e)));
+
+  const on = weakBillingMap();
+  on.recommended_modules[0].module = 'lifecycle';
+  assert.equal(fr.validateRepoMap(on, { catalog: CATALOG }).ok, false, 'a module already on is not on the list');
+
+  const twice = weakBillingMap();
+  twice.recommended_modules.push({ ...twice.recommended_modules[0] });
+  assert.ok(fr.validateRepoMap(twice, { catalog: CATALOG }).errors.some((e) => /repeats a module/.test(e)));
+
+  v = fr.validateRepoMap(weakBillingMap(), { catalog: null });
+  assert.ok(v.errors.some((e) => /could not be read here/.test(e)));
+
+  const missing = weakBillingMap();
+  delete missing.recommended_modules[0].found;
+  assert.ok(fr.validateRepoMap(missing, { catalog: CATALOG }).errors.some((e) => /recommended_modules\[0\]\.found is missing/.test(e)));
+
+  const { deps, s } = fakePool();
+  const out = await store.submitMap({ raw: unknown, catalog: CATALOG }, deps);
+  assert.equal(out.ok, false);
+  assert.equal(s.maps.length, 0, 'a refused map is not stored');
+});
+
+test('dismissing a recommendation files nothing, and a re-run does not raise it again unless named', async () => {
+  const { deps, s } = fakePool();
+  const first = await store.submitMap({ raw: weakBillingMap(), catalog: CATALOG }, deps);
+  const d = await store.dismissItems({ mapId: first.map_id, refs: ['module:billing'] }, deps);
+  assert.equal(d.ok, true);
+  assert.deepEqual(d.dismissed, ['module:billing']);
+  assert.equal(s.tasks.length, 0, 'a no files nothing');
+  assert.equal((await store.dismissItems({ mapId: first.map_id, refs: ['module:nope'] }, deps)).code, 'unknown_items');
+
+  const second = await store.submitMap({ raw: weakBillingMap(), catalog: CATALOG }, deps);
+  const review = await store.reviewMap(second.map_id, deps);
+  assert.equal(review.items.find((i) => i.ref === 'module:billing').filed.kind, 'dismissed');
+  const all = await store.acceptMap({ mapId: second.map_id, select: 'all' }, deps);
+  assert.ok(all.skipped.some((x) => x.ref === 'module:billing' && x.reason === 'dismissed'));
+  assert.ok(!s.tasks.some((t) => t.sourceRef === 'module:billing'));
+
+  const named = await store.acceptMap({ mapId: second.map_id, select: ['module:billing'] }, deps);
+  assert.equal(named.filed.tasks.length, 1, 'naming a dismissed item files it: the owner changed their mind');
+  assert.equal(s.filed.get('module:billing').kind, 'task');
+  const again = await store.dismissItems({ mapId: second.map_id, refs: ['module:billing'] }, deps);
+  assert.ok(again.skipped.some((x) => x.reason === 'already_filed'), 'a filed item is not un-filed by a dismiss');
+});
+
+test('the routes: the catalog route, a submit checked against the live list, and dismiss', async () => {
+  const seams = require('../src/module-seams.js');
+  if (!seams.hasProvider('modules.catalog')) seams.registerProvider('modules.catalog', () => LISTED);
+  const cat = await call('GET', '/first-read/catalog');
+  assert.equal(cat.status, 200);
+  assert.equal(cat.body.available, true);
+  assert.deepEqual(cat.body.modules.map((m) => m.key), ['billing', 'raise']);
+  const prompt = await call('GET', '/first-read/prompt');
+  assert.ok(prompt.body.prompt.includes('- billing: Billing (internal name). Takes card payments through the processor and keeps the ledger.'));
+
+  const bad = weakBillingMap();
+  bad.recommended_modules[0].module = 'stripe-magic';
+  const refused = await call('POST', '/first-read/maps', { map: bad });
+  assert.equal(refused.status, 400);
+  assert.ok(refused.body.errors.some((e) => /stripe-magic/.test(e)));
+
+  const ok = await call('POST', '/first-read/maps', { map: weakBillingMap() });
+  assert.equal(ok.status, 201);
+  assert.ok(ok.body.items.some((i) => i.ref === 'module:billing' && i.type === 'module'));
+  const dismissed = await call('POST', `/first-read/maps/${ok.body.map_id}/dismiss`, { items: ['module:billing'] });
+  assert.equal(dismissed.status, 200);
+  assert.equal((await call('POST', `/first-read/maps/${ok.body.map_id}/dismiss`, { items: 'all' })).status, 400);
+  assert.ok(perms.filter((x) => x === 'goal.create').length >= 4, 'dismiss is gated like the rest of the review');
+});

package/tests/genesis_work.mjs

@@ -222,10 +222,81 @@ if (import.meta.url === url.pathToFileURL(process.argv[1]).href) {
 
   await test('a stage that has not adopted questions still takes a page and a link', async () => {
     const deps = { store: memStore() };
-    const r = await gw.setPage('charter', 'Monarchy to start.', 1, deps);
+    const r = await gw.setPage('legalize', 'Credits only to start.', 1, deps);
     assert.equal(r.work.adopted, false);
-    assert.equal(r.work.page, 'Monarchy to start.');
-    assert.equal((await gw.setAnswer('charter', 'anything', { text: 'x' }, 1, deps)).reason, 'unknown_question');
+    assert.equal(r.work.page, 'Credits only to start.');
+    assert.equal((await gw.setAnswer('legalize', 'anything', { text: 'x' }, 1, deps)).reason, 'unknown_question');
+  });
+
+  // ── the charter stage (task 1005119) ──────────────────────────────────────
+  // A stand-in government port that records what it was handed, so the test sees
+  // exactly which answers reach the recommender.
+  const fakeGov = () => {
+    const calls = [];
+    return { calls, async charterAdvice(input) { calls.push(input); return { charter: { key: 'monarchy' }, input }; } };
+  };
+  const charterDeps = (extra = {}) => ({ store: memStore(), government: fakeGov(), getSetting: async () => null, ...extra });
+
+  await test('charter: a closed answer must be one of its choices, and a label reads back as its key', async () => {
+    const deps = charterDeps();
+    const bad = await gw.setAnswer('charter', 'final_say', { text: 'my cat' }, 1, deps);
+    assert.equal(bad.reason, 'not_a_choice');
+    assert.deepEqual(bad.expected, ['founder', 'trusted', 'everyone', 'council']);
+    const r = await gw.setAnswer('charter', 'final_say', { text: 'Everyone on the project' }, 1, deps);
+    const q = qOf(r, 'final_say');
+    assert.equal(q.answer.text, 'everyone', 'stored as the key');
+    assert.equal(q.answer.choice_label, 'Everyone on the project');
+    assert.ok(q.choices.some((c) => c.key === 'council'), 'the choices ride the view');
+    // prose questions take any words
+    const p = await gw.setAnswer('charter', 'feel', { text: 'Calm and careful.' }, 1, deps);
+    assert.equal(qOf(p, 'feel').answer.text, 'Calm and careful.');
+  });
+
+  await test('charter: every question is skippable and answerable "not sure yet"', async () => {
+    const deps = charterDeps();
+    for (const q of gw.QUESTIONS.charter) {
+      assert.equal((await gw.setAnswer('charter', q.id, { state: 'not_sure' }, 1, deps)).ok, true, q.id);
+      assert.equal((await gw.setAnswer('charter', q.id, { state: 'skipped' }, 1, deps)).ok, true, q.id);
+    }
+  });
+
+  await test('charter: only given answers reach the recommender, closed as keys and prose as words', async () => {
+    const gov = fakeGov();
+    const deps = charterDeps({ government: gov, getSetting: async () => ({ value: JSON.stringify({ expected_builders: 6 }) }) });
+    await gw.setAnswer('charter', 'final_say', { text: 'trusted' }, 1, deps);
+    await gw.setAnswer('charter', 'agreement', { state: 'not_sure' }, 1, deps);
+    await gw.setAnswer('charter', 'speed', { state: 'skipped' }, 1, deps);
+    await gw.setAnswer('charter', 'leave_behaviour', { text: 'Lying about shipped work.' }, 1, deps);
+    const r = await gw.readStage('charter', deps);
+    const last = gov.calls[gov.calls.length - 1];
+    assert.deepEqual(last.answers, { final_say: 'trusted' }, 'not sure yet and skipped are not sent');
+    assert.deepEqual(last.prose, { leave_behaviour: 'Lying about shipped work.' });
+    assert.equal(last.headcount, 6, "the founder's expected headcount from the plan");
+    assert.equal(r.work.advice.charter.key, 'monarchy', 'the advice rides the stage');
+  });
+
+  await test('charter: no government module, or a failing one, still reads the stage (advice null)', async () => {
+    const none = await gw.readStage('charter', charterDeps({ government: null }));
+    assert.equal(none.ok, true);
+    assert.equal(none.work.advice, null);
+    const broken = await gw.readStage('charter', charterDeps({ government: { charterAdvice: async () => { throw new Error('db down'); } } }));
+    assert.equal(broken.work.advice, null);
+    const other = await gw.readStage('strategize', charterDeps());
+    assert.equal(other.work.advice, undefined, 'only the charter stage carries advice');
+  });
+
+  await test('charter: the assisted brief lists the keys to record for each closed question', async () => {
+    const p = gw.assistPrompt('charter');
+    assert.match(p, /\[final_say\]/);
+    assert.match(p, /Record one of: founder \(Me, the founder\) · trusted/);
+    assert.match(p, /\[leave_behaviour\]/);
+  });
+
+  await test('charter: the planning read path shows a closed answer in words, not its key', async () => {
+    const deps = charterDeps();
+    await gw.setAnswer('charter', 'agreement', { text: 'consent' }, 1, deps);
+    const { markdown } = await gw.readContext(deps);
+    assert.match(markdown, /How much agreement should a decision need\?\*\*\n  It passes unless someone objects/);
   });
 
   await test('an empty project gives the planning read path nothing to print', async () => {

package/tests/government_act_alone_buildings.mjs

@@ -216,6 +216,7 @@ for (const rel of [
   'modules/lifecycle/routes/goals.js',
   'modules/lifecycle/routes/versions.js',
   'modules/lifecycle/routes/project-settings.js',
+  'modules/lifecycle/routes/first-read.js',
   'modules/render-deploy/routes/act.js',
   'modules/npm-release/routes/release.js',
   'modules/provisioning/routes/core-upgrade.js',
@@ -262,6 +263,7 @@ const REQUESTS = {
   'POST /goals/reorder': ['POST', '/goals/reorder', {}],
   'POST /work-categories': ['POST', '/work-categories', {}],
   'PUT /versions/focus': ['PUT', '/versions/focus', { version_id: '   ' }],
+  'POST /first-read/maps/:id/accept': ['POST', `/first-read/maps/${BAD}/accept`, { all: true }], // task 1005280
   'POST /autonomy/fence': ['POST', '/autonomy/fence', { enabled: 'yes' }],
   'POST /autonomy/fence/goals': ['POST', '/autonomy/fence/goals', { goal_id: 0 }],
   'DELETE /autonomy/fence/goals/:goalId': ['DELETE', `/autonomy/fence/goals/${BAD}`],