@bongos/core 1.25.14 → 1.25.15

package/scripts/bongos/genesis.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// scripts/bongos/genesis.js — the founder's genesis answers from a terminal (task 1005116)
+//
+// WHY. Each genesis stage is the founder's to write, through one of three doors onto one
+// stored record (modules/onboarding/genesis-work.js): guided questions, an open page, or
+// their own AI session helping. This is how an AI session works a stage WITH the founder
+// — it reads what they have said, asks the stage's own questions, and records only the
+// answers the founder accepts — and how any session planning a goal or task reads what
+// the founder said (`context`). Every write goes to the server as the person signed in;
+// only the project owner may write, so a session can never author a stage on its own.
+//
+// Usage:
+//   npx bongos genesis show [stage]                       every stage, or one, with its answers
+//   npx bongos genesis context                            what the founder said, as markdown (for planning sessions)
+//   npx bongos genesis assist <stage>                     the brief for the founder's AI session (the assisted door)
+//   npx bongos genesis answer <stage> <question> "<words>" [--origin founder|assisted]
+//   npx bongos genesis answer <stage> <question> --not-sure ["why"]
+//   npx bongos genesis answer <stage> <question> --skip ["why"]
+//   npx bongos genesis clear <stage> <question>           un-answer: back to empty (not skipped)
+//   npx bongos genesis history <stage> <question>         what an answer used to say
+//   npx bongos genesis door <stage> guided|open|assisted  which way the founder is working now
+//   npx bongos genesis page <stage> "<words>" | --file <path> | --remove
+//   npx bongos genesis link <stage> <url> | --remove      the document the founder already has
+//
+// Also `node scripts/bongos/genesis.js …`.
+'use strict';
+
+const fs = require('node:fs');
+const { apiCall, requireSession, errCode, cliExit } = require('./cli-lib');
+
+const USAGE = 'usage: npx bongos genesis show [stage] | context | assist <stage> | answer <stage> <question> "<words>" [--origin founder|assisted] | answer <stage> <question> --not-sure|--skip ["why"] | clear <stage> <question> | history <stage> <question> | door <stage> guided|open|assisted | page <stage> "<words>"|--file <path>|--remove | link <stage> <url>|--remove';
+
+const STATE_LABEL = { answered: '', not_sure: '[not sure yet] ', skipped: '[skipped] ' };
+const ORIGIN_LABEL = { assisted: ' (with AI help)', carried_over: ' (carried over — confirm or edit)' };
+
+// Pure: one stage as the founder reads it.
+function formatStage(s) {
+  const out = [`${s.stage[0].toUpperCase()}${s.stage.slice(1)} — working ${s.door}` +
+    (s.adopted ? ` · ${s.counts.answered} answered, ${s.counts.not_sure} not sure, ${s.counts.skipped} skipped, ${s.counts.empty} empty` : '')];
+  for (const q of s.questions) {
+    out.push(`  ${q.id}: ${q.ask}`);
+    if (!q.answer) { out.push('    (empty)'); continue; }
+    const a = q.answer;
+    const words = a.text ? a.text.replace(/\n/g, '\n    ') : '';
+    out.push(`    ${STATE_LABEL[a.state] || ''}${words}${ORIGIN_LABEL[a.origin] || ''}`.trimEnd());
+  }
+  if (s.page) out.push('  Page:', `    ${s.page.replace(/\n/g, '\n    ')}`);
+  if (s.link) out.push(`  Link: ${s.link}`);
+  return out.join('\n');
+}
+
+// Pure: parse `answer` arguments into the PUT body, or { error }.
+function parseAnswer(rest) {
+  const args = [...rest];
+  const body = {};
+  const take = (flag) => {
+    const i = args.indexOf(flag);
+    if (i < 0) return undefined;
+    const next = args[i + 1];
+    const val = next != null && !String(next).startsWith('--') ? next : '';
+    args.splice(i, val === '' && (next == null || String(next).startsWith('--')) ? 1 : 2);
+    return val;
+  };
+  const origin = take('--origin');
+  const notSure = take('--not-sure');
+  const skip = take('--skip');
+  if (notSure !== undefined && skip !== undefined) return { error: 'choose one of --not-sure or --skip' };
+  if (origin !== undefined) body.origin = origin;
+  if (notSure !== undefined) { body.state = 'not_sure'; if (notSure) body.text = notSure; }
+  else if (skip !== undefined) { body.state = 'skipped'; if (skip) body.text = skip; }
+  else {
+    const words = args.join(' ').trim();
+    if (!words) return { error: 'give the answer in quotes, or --not-sure / --skip' };
+    body.state = 'answered';
+    body.text = words;
+  }
+  return { body };
+}
+
+async function call(method, path, body, what) {
+  const r = await apiCall(method, `/api/bongos${path}`, body);
+  if (!r.ok) console.error(`Could not ${what} (${r.status}${errCode(r.data) ? `: ${errCode(r.data)}` : ''}).`);
+  return r.ok ? r.data : null;
+}
+
+const enc = encodeURIComponent;
+
+async function main(argv) {
+  const [cmd, stage, ...rest] = argv;
+  if (!cmd || cmd === '--help' || cmd === '-h') { console.log(USAGE); return cmd ? 0 : 2; }
+  await requireSession();
+  if (cmd === 'show') {
+    if (stage) {
+      const d = await call('GET', `/founding/work/${enc(stage)}`, null, 'read the stage');
+      if (!d) return 1;
+      console.log(formatStage(d.work));
+      return 0;
+    }
+    const d = await call('GET', '/founding/work', null, 'read genesis');
+    if (!d) return 1;
+    console.log(d.stages.map(formatStage).join('\n\n'));
+    return 0;
+  }
+  if (cmd === 'context') {
+    const d = await call('GET', '/founding/context', null, 'read what the founder said');
+    if (!d) return 1;
+    console.log(d.markdown || 'The founder has not written anything in genesis yet.');
+    return 0;
+  }
+  if (!stage) { console.error(USAGE); return 2; }
+  if (cmd === 'assist') {
+    const d = await call('GET', `/founding/work/${enc(stage)}/assist`, null, 'build the brief');
+    if (!d) return 1;
+    console.log(d.prompt);
+    return 0;
+  }
+  if (cmd === 'answer') {
+    const [question, ...words] = rest;
+    if (!question) { console.error(USAGE); return 2; }
+    const p = parseAnswer(words);
+    if (p.error) { console.error(p.error); return 2; }
+    const d = await call('PUT', `/founding/work/${enc(stage)}/answers/${enc(question)}`, p.body, 'save the answer');
+    if (!d) return 1;
+    console.log(d.changed === false ? 'Unchanged — that is already the answer.' : 'Saved.');
+    console.log(formatStage(d.work));
+    return 0;
+  }
+  if (cmd === 'clear' || cmd === 'history') {
+    const [question] = rest;
+    if (!question) { console.error(USAGE); return 2; }
+    if (cmd === 'clear') {
+      const d = await call('DELETE', `/founding/work/${enc(stage)}/answers/${enc(question)}`, null, 'clear the answer');
+      if (!d) return 1;
+      console.log(d.cleared ? 'Cleared — the question is empty again.' : 'It was already empty.');
+      return 0;
+    }
+    const d = await call('GET', `/founding/work/${enc(stage)}/answers/${enc(question)}/history`, null, 'read the history');
+    if (!d) return 1;
+    if (!d.history.length) console.log('No answer has ever been saved here.');
+    for (const h of d.history) console.log(`${h.changed_at}  ${h.state}${h.text ? `: ${h.text}` : ''}`);
+    return 0;
+  }
+  if (cmd === 'door') {
+    const d = await call('PUT', `/founding/work/${enc(stage)}/door`, { door: String(rest[0] || '') }, 'switch the door');
+    if (!d) return 1;
+    console.log(`Now working ${d.work.door}. Nothing already written was lost.`);
+    return 0;
+  }
+  if (cmd === 'page') {
+    let page;
+    if (rest[0] === '--remove') page = '';
+    else if (rest[0] === '--file') {
+      if (!rest[1]) { console.error('give the file to read: --file <path>'); return 2; }
+      page = fs.readFileSync(rest[1], 'utf8');
+    } else page = rest.join(' ');
+    const d = await call('PUT', `/founding/work/${enc(stage)}/page`, { page }, 'save the page');
+    if (!d) return 1;
+    console.log(d.work.page ? 'Page saved.' : 'Page removed.');
+    return 0;
+  }
+  if (cmd === 'link') {
+    const url = rest[0] === '--remove' ? '' : String(rest[0] || '');
+    const d = await call('PUT', `/founding/work/${enc(stage)}/link`, { url }, 'save the link');
+    if (!d) return 1;
+    console.log(d.work.link ? `Linked: ${d.work.link}` : 'Link removed.');
+    return 0;
+  }
+  console.error(USAGE);
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2))
+    .then((code) => cliExit(code))
+    .catch((err) => { console.error('fatal:', err && err.message ? err.message : err); cliExit(1); });
+}
+
+module.exports = { main, formatStage, parseAnswer };

package/scripts/bongos/run-unit-tests.js

@@ -375,6 +375,9 @@ const INTEGRATION = new Set([
   // the second proves the search index never widens a caller past their rank or into
   // another builder memory. Each skipped in CI before, so none had ever been gated.
   'page_notes_db', 'howto_state_db', 'search_isolation_db',
+  // task 1005116: the genesis stage-work store on the real schema (the DB-free half,
+  // genesis_work, stays in the unit lane).
+  'genesis_work_db',
 ]);
 
 // Excluded so this gate is trustworthy in a CLEAN checkout (the CI condition):

package/scripts/gds/genesis.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// scripts/gds/genesis.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/genesis.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'genesis.js');

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.14'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.15'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/genesis_work.mjs

@@ -0,0 +1,255 @@
+// tests/genesis_work.mjs — the founder's own work on a genesis stage (task 1005116)
+//
+// The DB-free half. It drives modules/onboarding/genesis-work.js against an in-memory
+// store with the same four-method contract as the Postgres one, so the rules run
+// everywhere: three doors onto ONE record (switching loses nothing), guided is the
+// default, an answer is stored as an answer, "not sure yet" / skipped / empty are three
+// different things, un-answering goes back to empty, a revision keeps its history, a
+// carried-over answer never overwrites the founder, and the read path a planning
+// session uses says what the founder said. Plus the assisted door's brief and the CLI's
+// argument parsing.
+//
+// The SAME contract runs against Postgres in tests/genesis_work_db.mjs (integration lane),
+// which imports `contract` from here. The tests below run only when this file is the
+// entry point.
+//
+// Run:  node tests/genesis_work.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const gw = require('../modules/onboarding/genesis-work.js');
+const { parseAnswer, formatStage } = require('../scripts/bongos/genesis.js');
+
+// An in-memory store honouring the contract pgStore implements.
+export function memStore() {
+  const work = new Map();
+  const answers = new Map();
+  const history = [];
+  let clock = 0;
+  const tick = () => new Date(1.7e12 + ++clock * 1000);
+  return {
+    work, answers, history,
+    async loadAll() { return { work: [...work.values()], answers: [...answers.values()] }; },
+    async upsertWork(stage, patch, by) {
+      const cur = work.get(stage) || { stage, door: 'guided', page_md: null, link_url: null };
+      work.set(stage, { ...cur, ...patch, updated_by: by, updated_at: tick() });
+    },
+    async writeAnswer(stage, q, v, by, { ifEmpty = false } = {}) {
+      const k = `${stage}|${q}`;
+      const cur = answers.get(k);
+      if (cur && ifEmpty) return { changed: false };
+      if (cur && cur.state === v.state && cur.answer_md === v.answer_md && cur.origin === v.origin) return { changed: false };
+      answers.set(k, { stage, question_id: q, ...v, updated_by: by, updated_at: tick() });
+      history.push({ stage, question_id: q, state: v.state, answer_md: v.answer_md, origin: v.origin, changed_by: by, changed_at: tick() });
+      return { changed: true };
+    },
+    async clearAnswer(stage, q, by) {
+      const k = `${stage}|${q}`;
+      if (!answers.has(k)) return { cleared: false };
+      answers.delete(k);
+      history.push({ stage, question_id: q, state: null, answer_md: null, origin: null, changed_by: by, changed_at: tick() });
+      return { cleared: true };
+    },
+    async history(stage, q) {
+      return history.filter((h) => h.stage === stage && h.question_id === q).reverse();
+    },
+  };
+}
+
+const qOf = (r, id) => r.work.questions.find((q) => q.id === id);
+
+// The contract both stores must satisfy. `deps` carries the store; `A` is a builder id.
+export async function contract(test, label, deps, A) {
+  await test(`${label}: an untouched stage reads guided, every question empty`, async () => {
+    const r = await gw.readStage('strategize', deps);
+    assert.equal(r.ok, true);
+    assert.equal(r.work.door, 'guided', 'guided is the default door');
+    assert.equal(r.work.adopted, true);
+    assert.deepEqual(r.work.counts, { total: 4, answered: 0, not_sure: 0, skipped: 0, empty: 4 });
+    assert.ok(r.work.questions.every((q) => q.answer === null));
+  });
+
+  await test(`${label}: an answer is stored as an answer, with its words and origin`, async () => {
+    const r = await gw.setAnswer('strategize', 'big_pieces', { text: '  Ledger first, then the importer, then the view.  ' }, A, deps);
+    assert.equal(r.changed, true);
+    const a = qOf(r, 'big_pieces').answer;
+    assert.equal(a.state, 'answered');
+    assert.equal(a.text, 'Ledger first, then the importer, then the view.');
+    assert.equal(a.origin, 'founder');
+    assert.equal(a.carried_over, false);
+  });
+
+  await test(`${label}: "not sure yet", skipped and empty are three different states`, async () => {
+    await gw.setAnswer('strategize', 'risks', { state: 'not_sure', text: 'depends on the bank API' }, A, deps);
+    await gw.setAnswer('strategize', 'try_first', { state: 'skipped' }, A, deps);
+    const r = await gw.readStage('strategize', deps);
+    assert.equal(qOf(r, 'risks').answer.state, 'not_sure');
+    assert.equal(qOf(r, 'risks').answer.text, 'depends on the bank API');
+    assert.equal(qOf(r, 'try_first').answer.state, 'skipped');
+    assert.equal(qOf(r, 'change_course').answer, null, 'never touched is empty, not skipped');
+    assert.deepEqual(r.work.counts, { total: 4, answered: 1, not_sure: 1, skipped: 1, empty: 1 });
+  });
+
+  await test(`${label}: revising replaces the answer and keeps what it used to say`, async () => {
+    const r = await gw.setAnswer('strategize', 'risks', { text: 'The bank API may not allow read-only access.' }, A, deps);
+    assert.equal(qOf(r, 'risks').answer.state, 'answered');
+    const h = await gw.answerHistory('strategize', 'risks', deps);
+    assert.equal(h.ok, true);
+    assert.deepEqual(h.history.map((x) => x.state), ['answered', 'not_sure'], 'newest first');
+    assert.equal(h.history[1].text, 'depends on the bank API');
+  });
+
+  await test(`${label}: a write that changes nothing writes nothing`, async () => {
+    const r = await gw.setAnswer('strategize', 'risks', { text: 'The bank API may not allow read-only access.' }, A, deps);
+    assert.equal(r.changed, false);
+    assert.equal((await gw.answerHistory('strategize', 'risks', deps)).history.length, 2);
+  });
+
+  await test(`${label}: un-answering goes back to EMPTY (not skipped) and is recorded`, async () => {
+    const r = await gw.clearAnswer('strategize', 'try_first', A, deps);
+    assert.equal(r.cleared, true);
+    assert.equal(qOf(r, 'try_first').answer, null);
+    assert.equal(r.work.counts.skipped, 0);
+    assert.equal(r.work.counts.empty, 2);
+    const h = await gw.answerHistory('strategize', 'try_first', deps);
+    assert.equal(h.history[0].state, 'cleared');
+    const again = await gw.clearAnswer('strategize', 'try_first', A, deps);
+    assert.equal(again.cleared, false, 'clearing an empty question is a no-op');
+  });
+
+  await test(`${label}: switching doors keeps the answers, the page and the link`, async () => {
+    await gw.setDoor('strategize', 'open', A, deps);
+    await gw.setPage('strategize', 'We bet on the ledger. Everything else waits.', A, deps);
+    await gw.setLink('strategize', 'https://example.com/strategy', A, deps);
+    let r = await gw.setDoor('strategize', 'assisted', A, deps);
+    assert.equal(r.work.door, 'assisted');
+    r = await gw.setDoor('strategize', 'guided', A, deps);
+    assert.equal(r.work.page, 'We bet on the ledger. Everything else waits.');
+    assert.equal(r.work.link, 'https://example.com/strategy');
+    assert.equal(r.work.counts.answered, 2, 'answers survive every switch');
+  });
+
+  await test(`${label}: a carried-over answer fills only what is empty, and the founder's edit makes it theirs`, async () => {
+    const kept = await gw.setAnswer('strategize', 'big_pieces', { text: 'from the pre-sign-up chat', origin: 'carried_over' }, null, deps, { ifEmpty: true });
+    assert.equal(kept.changed, false);
+    assert.equal(qOf(kept, 'big_pieces').answer.origin, 'founder', 'never overwrites the founder');
+    const filled = await gw.setAnswer('strategize', 'change_course', { text: 'If nobody connects a bank in a month.', origin: 'carried_over' }, null, deps, { ifEmpty: true });
+    assert.equal(qOf(filled, 'change_course').answer.carried_over, true);
+    const mine = await gw.setAnswer('strategize', 'change_course', { text: 'If nobody connects a bank in two months.' }, A, deps);
+    assert.equal(qOf(mine, 'change_course').answer.origin, 'founder');
+  });
+
+  await test(`${label}: the read path a planning session uses says what the founder said`, async () => {
+    const { markdown, stages } = await gw.readContext(deps);
+    assert.equal(stages.length, 5);
+    assert.match(markdown, /^# What the founder has said about this project/);
+    assert.match(markdown, /## Strategize/);
+    assert.match(markdown, /Ledger first, then the importer, then the view\./);
+    assert.match(markdown, /We bet on the ledger/);
+    assert.match(markdown, /https:\/\/example\.com\/strategy/);
+    assert.doesNotMatch(markdown, /## Scope/, 'a stage with nothing in it is left out');
+  });
+}
+
+if (import.meta.url === url.pathToFileURL(process.argv[1]).href) {
+  let passed = 0;
+  let failed = 0;
+  const test = async (name, fn) => {
+    try { await fn(); passed++; console.log(`  ok  ${name}`); }
+    catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+  };
+
+  await contract(test, 'memory', { store: memStore() }, 7);
+
+  await test('refusals: unknown stage / question, bad state / origin / door / link, empty answer', async () => {
+    const deps = { store: memStore() };
+    assert.equal((await gw.readStage('decide', deps)).reason, 'unknown_stage');
+    assert.equal((await gw.setAnswer('strategize', 'nope', { text: 'x' }, 1, deps)).reason, 'unknown_question');
+    assert.equal((await gw.setAnswer('strategize', 'risks', { state: 'maybe' }, 1, deps)).reason, 'bad_state');
+    assert.equal((await gw.setAnswer('strategize', 'risks', { text: 'x', origin: 'model' }, 1, deps)).reason, 'bad_origin');
+    assert.equal((await gw.setAnswer('strategize', 'risks', { text: '   ' }, 1, deps)).reason, 'empty_answer');
+    assert.equal((await gw.setAnswer('strategize', 'risks', { text: 'x'.repeat(4001) }, 1, deps)).reason, 'answer_too_long');
+    assert.equal((await gw.setDoor('strategize', 'autopilot', 1, deps)).reason, 'bad_door');
+    assert.equal((await gw.setLink('strategize', 'javascript:alert(1)', 1, deps)).reason, 'bad_link');
+    assert.equal((await gw.clearAnswer('strategize', 'nope', 1, deps)).reason, 'unknown_question');
+    assert.equal(deps.store.answers.size, 0, 'no refusal wrote anything');
+  });
+
+  await test('"not sure yet" needs no words; a skip may carry a note', async () => {
+    const deps = { store: memStore() };
+    const r = await gw.setAnswer('strategize', 'risks', { state: 'not_sure' }, 1, deps);
+    assert.equal(qOf(r, 'risks').answer.state, 'not_sure');
+    assert.equal(qOf(r, 'risks').answer.text, null);
+  });
+
+  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);
+    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');
+  });
+
+  await test('an empty project gives the planning read path nothing to print', async () => {
+    assert.equal((await gw.readContext({ store: memStore() })).markdown, '');
+  });
+
+  await test('the read path labels not-sure, skipped, assisted and carried-over answers', async () => {
+    const deps = { store: memStore() };
+    await gw.setAnswer('strategize', 'risks', { state: 'not_sure', text: 'waiting on the bank' }, 1, deps);
+    await gw.setAnswer('strategize', 'try_first', { state: 'skipped' }, 1, deps);
+    await gw.setAnswer('strategize', 'big_pieces', { text: 'Ledger, then view.', origin: 'assisted' }, 1, deps);
+    await gw.setAnswer('strategize', 'change_course', { text: 'No users.', origin: 'carried_over' }, null, deps);
+    const md = (await gw.readContext(deps)).markdown;
+    assert.match(md, /Not sure yet — waiting on the bank/);
+    assert.match(md, /Skipped by the founder/);
+    assert.match(md, /worked out with an AI session, accepted by the founder/);
+    assert.match(md, /carried over from before sign-up, not yet confirmed/);
+  });
+
+  await test('the assisted door works the stage\'s own questions and leaves the founder the author', async () => {
+    const p = gw.assistPrompt('strategize');
+    assert.match(p, /I am the author; you are my assistant/);
+    for (const q of gw.QUESTIONS.strategize) assert.ok(p.includes(q.ask), `asks: ${q.ask}`);
+    assert.match(p, /Push back/);
+    assert.match(p, /Not sure yet/i);
+    assert.match(p, /npx bongos genesis answer strategize <question-id> "<my words>" --origin assisted/);
+    assert.equal(gw.assistPrompt('decide'), null);
+  });
+
+  await test('question ids are unique and fit the stored shape', async () => {
+    for (const [stage, qs] of Object.entries(gw.QUESTIONS)) {
+      assert.ok(gw.STAGES.includes(stage));
+      const ids = qs.map((q) => q.id);
+      assert.equal(new Set(ids).size, ids.length);
+      for (const id of ids) assert.match(id, /^[a-z][a-z0-9_]{1,39}$/);
+    }
+  });
+
+  await test('CLI: answer arguments become the right body', async () => {
+    assert.deepEqual(parseAnswer(['Ledger', 'first']).body, { state: 'answered', text: 'Ledger first' });
+    assert.deepEqual(parseAnswer(['--not-sure']).body, { state: 'not_sure' });
+    assert.deepEqual(parseAnswer(['--not-sure', 'bank API']).body, { state: 'not_sure', text: 'bank API' });
+    assert.deepEqual(parseAnswer(['--skip']).body, { state: 'skipped' });
+    assert.deepEqual(parseAnswer(['Ledger', '--origin', 'assisted']).body, { state: 'answered', text: 'Ledger', origin: 'assisted' });
+    assert.ok(parseAnswer([]).error);
+    assert.ok(parseAnswer(['--skip', '--not-sure']).error);
+  });
+
+  await test('CLI: a stage prints each answer with its state and origin', async () => {
+    const deps = { store: memStore() };
+    await gw.setAnswer('strategize', 'risks', { state: 'not_sure' }, 1, deps);
+    const r = await gw.setAnswer('strategize', 'big_pieces', { text: 'Ledger', origin: 'assisted' }, 1, deps);
+    const out = formatStage(r.work);
+    assert.match(out, /Strategize — working guided · 1 answered, 1 not sure, 0 skipped, 2 empty/);
+    assert.match(out, /\[not sure yet\]/);
+    assert.match(out, /Ledger \(with AI help\)/);
+    assert.match(out, /\(empty\)/);
+  });
+
+  console.log(`\ngenesis_work: ${passed} passed, ${failed} failed`);
+  if (failed) process.exit(1);
+}

package/tests/genesis_work_db.mjs

@@ -0,0 +1,73 @@
+// tests/genesis_work_db.mjs — the genesis stage-work contract against a REAL Postgres
+// (task 1005116).
+//
+// tests/genesis_work.mjs runs the contract against an in-memory store in the DB-free
+// unit lane. This runs the SAME contract (imported, not copied) through the real
+// Postgres store (genesis-work.js pgStore) over the real migration, so the one-statement
+// answer-plus-history writes, the no-op guard, the if-empty carry-over and the CHECK
+// constraints are proven where they live. Integration lane (run-unit-tests.js).
+//
+// Needs a MIGRATED database (scripts/migrate.sh). SKIPS (exit 0) with no reachable
+// Postgres, like every *_db test.
+//
+// Run:  DATABASE_URL=postgres://... node tests/genesis_work_db.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { contract } from './genesis_work.mjs';
+import { insertTestBuilders } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+const { Pool } = require('pg');
+const gw = require('../modules/onboarding/genesis-work.js');
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`genesis_work_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const MIGRATION = fs.readFileSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_002_genesis_work.sql'), 'utf8');
+const wipe = () => pool.query('DELETE FROM onboarding_genesis_answers; DELETE FROM onboarding_genesis_answer_history; DELETE FROM onboarding_genesis_work;');
+
+await test('postgres: the migration re-applies cleanly over the migrated schema (idempotent)', async () => {
+  await pool.query(MIGRATION);
+  await pool.query(MIGRATION);
+});
+
+const A = 910000201;
+await insertTestBuilders(pool, [{ id: A, login: 'genesis-a' }]);
+await wipe();
+try {
+  await contract(test, 'postgres', { store: gw.pgStore(pool) }, A);
+  await test('postgres: the CHECKs refuse a wordless answer, a bad state, origin, door and link', async () => {
+    const bad = (sql, params) => assert.rejects(pool.query(sql, params), (e) => e.code === '23514');
+    await bad("INSERT INTO onboarding_genesis_answers (stage, question_id, state, answer_md) VALUES ('scope', 'what', 'answered', '  ')");
+    await bad("INSERT INTO onboarding_genesis_answers (stage, question_id, state) VALUES ('scope', 'what', 'maybe')");
+    await bad("INSERT INTO onboarding_genesis_answers (stage, question_id, state, origin) VALUES ('scope', 'what', 'skipped', 'model')");
+    await bad("INSERT INTO onboarding_genesis_answers (stage, question_id, state) VALUES ('decide', 'what', 'skipped')");
+    await bad("INSERT INTO onboarding_genesis_work (stage, door) VALUES ('charter', 'autopilot')");
+    await bad("INSERT INTO onboarding_genesis_work (stage, link_url) VALUES ('charter', 'javascript:alert(1)')");
+  });
+} finally {
+  await wipe().catch(() => {});
+  await pool.query('DELETE FROM builders WHERE id = $1', [A]).catch(() => {});
+  await pool.end().catch(() => {});
+}
+
+console.log(`\ngenesis_work_db: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);