@bongos/core 1.25.13 → 1.25.15

package/tests/front_door_guide_db.mjs

@@ -25,6 +25,7 @@ const db = require('../modules/front-door-guide/db.js');
 const sql = (n) => readFileSync(new URL(`../modules/front-door-guide/migrations/${n}`, import.meta.url), 'utf8');
 const M1 = sql('front_door_guide_001_conversations.sql');
 const M2 = sql('front_door_guide_002_plan_and_account.sql');
+const M3 = sql('front_door_guide_003_starting_point.sql');
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
 try {
@@ -48,7 +49,7 @@ async function cleanup() {
 const call = (over = {}) => ({ visitorHash: V, model: 'claude-opus-5-5', inputTokens: 800, outputTokens: 200, cacheReadTokens: 0, cacheWriteTokens: 0, costMicro: 9000, stopReason: 'end_turn', ...over });
 
 try {
-  for (const m of [M1, M2, M1, M2]) await x(m); // applies, then re-applies as a no-op
+  for (const m of [M1, M2, M3, M1, M2, M3]) await x(m); // applies, then re-applies as a no-op
   await cleanup();
   await insertTestBuilders(pool, [{ id: ALICE, login: 't1005273-alice' }, { id: BOB, login: 't1005273-bob' }]);
 
@@ -99,6 +100,10 @@ try {
   assert.equal(await db.siteSpendMicro('day', x), before, 'the budgets still count the deleted chat\'s money');
   assert.ok(before >= dayBefore + 9000 + 20000 + 1 + 5 + 7000);
 
+  // The starting point (task 1005279): set, read back, and nothing else accepted.
+  assert.equal((await db.setStartingPoint(conv.id, 'existing', x)).starting_point, 'existing');
+  await assert.rejects(x(`UPDATE front_door_guide_conversations SET starting_point = 'repo' WHERE id = $1`, [conv.id]));
+
   // Refusals the schema owns.
   await assert.rejects(x(`INSERT INTO front_door_guide_calls (visitor_hash, model, cost_micro, kind) VALUES ($1, 'm', 1, 'other')`, [V]));
   await assert.rejects(x(`INSERT INTO front_door_guide_calls (visitor_hash, model, cost_micro) VALUES ($1, 'm', -1)`, [V]));

package/tests/front_door_guide_existing.mjs

@@ -0,0 +1,238 @@
+// tests/front_door_guide_existing.mjs — the guide's branch for a visitor who already has
+// something (task 1005279): the guide asks early whether they are starting fresh, asks an
+// existing-project visitor what they have and what they want next, and plans from their
+// DESCRIPTION. The owner's hard rule: nothing they have made is read on the platform's AI
+// bill — no upload, no fetch, no link reading — so the tests pin the absence too: the
+// requests carry text only and no tools, no outbound request is made besides the (mocked)
+// model call, and the guide's routes have no upload path.
+//
+// The real routers over an in-memory db and a mocked Claude client: no key, no network,
+// no spend.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const db = require('../modules/front-door-guide/db.js');
+const claude = require('../modules/front-door-guide/claude.js');
+const SP = require('../modules/front-door-guide/starting-point.js');
+require('../modules/provisioning/seams.js').registerProvisioningSeams();
+
+const ENV = 'BONGOS_FRONT_DOOR_GUIDE_';
+
+// ---- in-memory db --------------------------------------------------------------------
+
+const convs = new Map();
+let calls = [];
+let seq = 0;
+const copy = (c) => c && JSON.parse(JSON.stringify(c));
+Object.assign(db, {
+  createConversation: async (tokenHash, visitorHash) => {
+    const c = { id: String(++seq), token_hash: tokenHash, visitor_hash: visitorHash, messages: [], visitor_messages: 0, spend_micro: 0, status: 'open', end_reason: null, created_at: new Date(Date.now() - 10_000).toISOString(), plan: null, builder_id: null, starting_point: null };
+    convs.set(c.id, c);
+    return copy(c);
+  },
+  setStartingPoint: async (id, sp) => { const c = convs.get(String(id)); c.starting_point = sp; return copy(c); },
+  getConversation: async (id, tokenHash) => { const c = convs.get(String(id)); return c && c.token_hash === tokenHash ? copy(c) : null; },
+  siteSpendMicro: async () => calls.reduce((s, r) => s + r.cost_micro, 0),
+  visitorUsage: async (v) => {
+    const mine = calls.filter((r) => r.visitor_hash === v);
+    return { messages: mine.filter((r) => r.kind === 'reply').length, spendMicro: mine.reduce((s, r) => s + r.cost_micro, 0) };
+  },
+  recordTurn: async (id, { messages, status, endReason }, call) => {
+    calls.push({ visitor_hash: call.visitorHash, cost_micro: call.costMicro, kind: 'reply' });
+    const c = convs.get(String(id));
+    Object.assign(c, { messages, status, end_reason: endReason, visitor_messages: c.visitor_messages + 1 });
+    return copy(c);
+  },
+  endConversation: async (id, reason) => Object.assign(convs.get(String(id)), { status: 'ended', end_reason: reason }),
+  savePlan: async (id, plan, call) => {
+    calls.push({ visitor_hash: call.visitorHash, cost_micro: call.costMicro, kind: 'plan' });
+    const c = convs.get(String(id));
+    Object.assign(c, { plan: c.plan || plan, status: 'ended', end_reason: 'planned' });
+    return copy(c);
+  },
+  recordPlanSpend: async () => {},
+});
+
+// ---- the mocked model, and a trap for any other outbound request ----------------------------
+
+let requests = [];
+let planText = null;
+claude.createClient = () => ({ messages: { create: async (req) => {
+  requests.push(req);
+  if (req.output_config && req.output_config.format) {
+    return { model: 'claude-opus-5-5', stop_reason: 'end_turn', usage: { input_tokens: 1500, output_tokens: 500 }, content: [{ type: 'text', text: planText }] };
+  }
+  return { model: 'claude-opus-5-5', stop_reason: 'end_turn', usage: { input_tokens: 700, output_tokens: 150 }, content: [{ type: 'text', text: 'What would you like to build next?' }] };
+} } });
+
+let outbound = [];
+const realFetch = globalThis.fetch;
+globalThis.fetch = async (url) => { outbound.push(String(url)); throw new Error('no outbound requests in this test'); };
+
+// ---- the real routers over http -----------------------------------------------------------
+
+const express = require('express');
+const app = express();
+app.set('trust proxy', true);
+app.use(express.json({ limit: '64kb' }));
+const chatRouter = require('../modules/front-door-guide/routes/front-door-guide.js')();
+const planRouter = require('../modules/front-door-guide/routes/front-door-guide-plan.js')();
+app.use('/api/bongos', chatRouter);
+app.use('/api/bongos', planRouter);
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const PORT = server.address().port;
+test.after(() => { server.close(); globalThis.fetch = realFetch; });
+
+let ipSeq = 0;
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const data = body === undefined ? null : JSON.stringify(body);
+    const req = http.request({ host: '127.0.0.1', port: PORT, method, path: `/api/bongos${path}`,
+      headers: { 'content-type': 'application/json', 'user-agent': 'Mozilla/5.0 (test browser)', 'x-forwarded-for': `10.7.0.${++ipSeq}` } }, (res) => {
+      let buf = '';
+      res.on('data', (c) => { buf += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: buf ? JSON.parse(buf) : null }));
+    });
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+function reset() {
+  for (const k of Object.keys(process.env)) if (k.startsWith(ENV)) delete process.env[k];
+  Object.assign(process.env, { [`${ENV}ANTHROPIC_API_KEY`]: 'sk-ant-TEST-ONLY-0123456789abcdef', [`${ENV}MIN_FIRST_MESSAGE_MS`]: '1', [`${ENV}STARTS_PER_HOUR`]: '1000', [`${ENV}MESSAGES_PER_MINUTE`]: '1000' });
+  convs.clear(); calls = []; requests = []; outbound = []; planText = null;
+}
+
+// Every request the platform sent its AI: text only, no tools, nothing attached.
+function assertTextOnly(reqs) {
+  for (const r of reqs) {
+    assert.equal(r.tools, undefined, 'no tools: the model cannot fetch or read anything');
+    assert.equal(r.mcp_servers, undefined);
+    assert.equal(r.container, undefined);
+    assert.equal(typeof r.system, 'string');
+    for (const m of r.messages) assert.equal(typeof m.content, 'string', 'no file, image or document blocks');
+  }
+  assert.deepEqual(outbound, [], 'no other outbound request was made');
+}
+
+// ---- asking early -------------------------------------------------------------------------
+
+test('without a starting point, the greeting asks it, with two answers to offer', async () => {
+  reset();
+  const st = await call('POST', '/front-door-guide/conversations', {});
+  assert.equal(st.status, 201);
+  assert.equal(st.body.greeting, SP.GREETINGS.unknown);
+  assert.match(st.body.greeting, /already have something/);
+  assert.deepEqual(st.body.starting_point_options, [{ value: 'fresh', label: 'Starting fresh' }, { value: 'existing', label: 'I already have something' }]);
+  assert.equal(st.body.conversation.starting_point, null);
+
+  const conv = st.body.conversation;
+  await call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { token: conv.token, text: 'I want to make a recipe app.' });
+  assert.match(requests[0].system, /do not yet know whether this visitor is starting fresh/);
+  assert.match(requests[0].system, /cannot see, open or read any file, repository/);
+});
+
+test('a starting point can be given at the start, or with a message; anything else is refused', async () => {
+  reset();
+  const fresh = await call('POST', '/front-door-guide/conversations', { starting_point: 'fresh' });
+  assert.equal(fresh.body.greeting, SP.GREETINGS.fresh);
+  assert.equal(fresh.body.conversation.starting_point, 'fresh');
+
+  const bad = await call('POST', '/front-door-guide/conversations', { starting_point: 'github' });
+  assert.equal(bad.status, 400);
+
+  const st = await call('POST', '/front-door-guide/conversations', {});
+  const conv = st.body.conversation;
+  const r = await call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { token: conv.token, text: 'I already have a half-built shop.', starting_point: 'existing' });
+  assert.equal(r.body.mode, 'chat');
+  assert.equal(r.body.conversation.starting_point, 'existing');
+  assert.match(requests[0].system, /This visitor already has something/, 'the reply already follows the answer');
+  assert.equal((await call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { token: conv.token, text: 'x', starting_point: 'both' })).status, 400);
+});
+
+// ---- the existing-project branch -----------------------------------------------------------
+
+test('an existing project: the guide asks what they have and what is next, and plans from their words alone', async () => {
+  reset();
+  const st = await call('POST', '/front-door-guide/conversations', { starting_point: 'existing' });
+  assert.equal(st.body.greeting, SP.GREETINGS.existing);
+  assert.match(st.body.greeting, /cannot open files or links/);
+  const conv = st.body.conversation;
+  const say = (text) => call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { token: conv.token, text });
+
+  await say('I have a Node app for booking yoga classes, about half done, on github.com/someone/yoga-app.');
+  await say('Next I want online payments and a teacher dashboard.');
+  const system = requests[0].system;
+  assert.match(system, /ask what they have \(code, documents, artwork or something else, and how far along it is\) and what they want to build next/);
+  assert.match(system, /Never ask them to paste code, upload files or share links/);
+  assert.match(system, /If they paste a link, say you cannot open links/);
+
+  // The plan: the visitor's answer decides the starting point, even if the model said otherwise.
+  planText = JSON.stringify({
+    summary: 'Finish a yoga booking app and add payments and a teacher dashboard.',
+    starting_point: 'fresh',
+    what_you_have: ['A Node booking app, about half done', 'Code on GitHub'],
+    project_type: 'business', how_it_works: ['You decide; AI builders do small tasks.'],
+    modules: [], steps: [{ title: 'Sign up', detail: '' }, { title: 'Bring in your existing work', detail: 'Your own AI looks through it.' }],
+    needs: [{ item: 'A payments account', detail: '' }], open_questions: [],
+  });
+  const plan = await call('POST', `/front-door-guide/conversations/${conv.id}/plan`, { token: conv.token });
+  assert.equal(plan.body.mode, 'plan');
+  assert.equal(plan.body.plan.starting_point, 'existing');
+  assert.deepEqual(plan.body.plan.what_you_have, ['A Node booking app, about half done', 'Code on GitHub']);
+
+  const planReq = requests.find((r) => r.output_config.format);
+  const props = planReq.output_config.format.schema.properties;
+  assert.deepEqual(props.starting_point.enum, ['fresh', 'existing']);
+  assert.equal(props.what_you_have.type, 'array');
+  assert.match(planReq.system, /"existing" \(the visitor said so\)/);
+  assert.match(planReq.system, /Only what they described: you have seen none of it/);
+
+  // Nothing they have made reached the platform's AI: text only, no tools, no fetch of the link.
+  assertTextOnly(requests);
+  const sent = requests.flatMap((r) => r.messages.map((m) => m.content)).join('\n');
+  assert.ok(sent.includes('github.com/someone/yoga-app'), 'the link is only their words');
+  assert.equal(outbound.length, 0, 'and it was never opened');
+});
+
+test('a fresh project plans with nothing listed as already made', async () => {
+  reset();
+  const st = await call('POST', '/front-door-guide/conversations', { starting_point: 'fresh' });
+  const conv = st.body.conversation;
+  await call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { token: conv.token, text: 'A garden planner.' });
+  planText = JSON.stringify({ summary: 'A garden planner.', starting_point: 'existing', what_you_have: [], project_type: 'not-sure', how_it_works: [], modules: [], steps: [], needs: [], open_questions: [] });
+  const plan = await call('POST', `/front-door-guide/conversations/${conv.id}/plan`, { token: conv.token });
+  assert.equal(plan.body.plan.starting_point, 'fresh');
+  assert.deepEqual(plan.body.plan.what_you_have, []);
+  assert.match(requests[0].system, /starting fresh, from an idea/);
+  assertTextOnly(requests);
+});
+
+// ---- no path for reading their work ------------------------------------------------------
+
+test('the guide has no upload, fetch or link-reading path: these are all its routes', () => {
+  const routes = (r) => r.stack.filter((l) => l.route).map((l) => `${Object.keys(l.route.methods)[0].toUpperCase()} ${l.route.path}`);
+  assert.deepEqual([...routes(chatRouter), ...routes(planRouter)].sort(), [
+    'GET /front-door-guide/conversations/:id',
+    'GET /front-door-guide/mine',
+    'GET /front-door-guide/status',
+    'POST /front-door-guide/conversations',
+    'POST /front-door-guide/conversations/:id/attach',
+    'POST /front-door-guide/conversations/:id/messages',
+    'POST /front-door-guide/conversations/:id/plan',
+  ]);
+});
+
+test('every instruction version carries the no-reading rule', () => {
+  for (const sp of [null, 'fresh', 'existing']) {
+    assert.match(SP.instructionsFor(sp), /You cannot see, open or read any file, repository, code, document, image or link/);
+  }
+  assert.equal(SP.greetingFor('nonsense'), SP.GREETINGS.unknown);
+});

package/tests/genesis_home.mjs

@@ -73,6 +73,23 @@ test('the board read groups genesis tasks by the stage their ref names', async (
   assert.deepEqual(out.scope.map((t) => t.id), ['1', '2']);
 });
 
+test('the board read carries each genesis task\'s description, for its Copy prompt (task 1005109)', async () => {
+  let seen = '';
+  const pool = { query: async (sql) => {
+    seen = sql;
+    return { rows: [
+      { id: 7, title: 'Write the scope', status: 'ready', description: 'Answer the five scope questions.', source_ref: 'genesis:scope' },
+      { id: 8, title: 'Old row', status: 'ready', description: null, source_ref: 'genesis:charter' },
+    ] };
+  } };
+  const out = await seed.genesisStageTasks({ pool });
+  assert.match(seen, /\bdescription\b/, 'the SELECT reads the description');
+  assert.equal(out.scope[0].description, 'Answer the five scope questions.');
+  assert.equal(out.charter[0].description, '', 'a null description is an empty string, never "null"');
+  const g = gh.shapeGenesis({ mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 }, plan: gh.parsePlan({}).plan, tasks: out });
+  assert.equal(g.stages[0].tasks[0].description, 'Answer the five scope questions.', 'the genesis view passes it through');
+});
+
 // ── the plan ─────────────────────────────────────────────────────────────────
 
 test('an empty plan is the recommended defaults: the solo fast-track is one click', () => {
@@ -361,25 +378,60 @@ test('every genesis write is the project owner\'s; the read is any signed-in bui
 
 const CARD = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'genesis-home.js'), 'utf8');
 
+const TASK_LIB = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'task-lib.js'), 'utf8');
+
 function bootCard({ founding, data = { genesis: null } }) {
   const calls = [];
+  const copied = [];
+  const toasts = [];
   let widget = null;
   let observer = null;
   const attrs = founding ? { 'data-founding': 'on' } : {};
   const sandbox = {
     window: {
-      OTB: { escapeHtml: (s) => String(s), statusPill: (s) => `<span>${s}</span>`, contributeHallWidget: (w) => { widget = w; } },
+      OTB: { escapeHtml: (s) => String(s), statusPill: (s) => `<span>${s}</span>`, contributeHallWidget: (w) => { widget = w; }, toast: (m) => toasts.push(m) },
       BongosClient: { createClient: () => ({ request: async (m, p) => { calls.push(`${m} ${p}`); return { ok: true, status: 200, data }; } }) },
     },
+    navigator: { clipboard: { writeText: async (t) => { copied.push(t); } } },
+    location: { hostname: 'builders.example.test', origin: 'https://builders.example.test' },
     document: { documentElement: { getAttribute: (k) => attrs[k] || null } },
     MutationObserver: class { constructor(fn) { observer = fn; } observe() {} disconnect() {} },
+    setTimeout: () => 0,
     Promise,
   };
   vm.createContext(sandbox);
+  // The hall's real prompt builder, loaded as index.html loads it (before the card).
+  vm.runInContext(TASK_LIB, sandbox, { filename: 'task-lib.js' });
   vm.runInContext(CARD, sandbox, { filename: 'genesis-home.js' });
   const host = { hidden: true, innerHTML: '', addEventListener() {}, querySelector: () => null, querySelectorAll: () => [] };
   widget.mount(host);
-  return { widget, host, calls, attrs, fire: () => observer && observer() };
+  return { widget, host, calls, copied, toasts, attrs, fire: () => observer && observer() };
+}
+
+// Re-mount a booted card so its click handler is captured; returns a click(btn) driver.
+async function mountClickable(b) {
+  let onClick = null;
+  b.host.addEventListener = (type, fn) => { if (type === 'click') onClick = fn; };
+  b.host.contains = () => true;
+  b.widget.mount(b.host);
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setImmediate(r));
+  return async (btn) => {
+    onClick({ target: { closest: () => btn } });
+    for (let i = 0; i < 4; i++) await new Promise((r) => setImmediate(r));
+  };
+}
+
+// A fake button carrying one data attribute, as the click handler reads it.
+function fakeButton(attr, value) {
+  const set = {};
+  return {
+    set,
+    hasAttribute: (k) => k === attr,
+    getAttribute: (k) => (k === attr ? value : null),
+    setAttribute: (k, v) => { set[k] = v; },
+    querySelector: () => null,
+  };
 }
 
 test('the card registers in the Home banner, ahead of the welcome, hidden by default', () => {
@@ -459,6 +511,32 @@ test('the card lists every stage vote waiting on the viewer, and votes yes on al
   ], 'one yes per stage, earliest first');
 });
 
+test('each open stage task has Copy prompt, and it copies the task\'s own words (task 1005109)', async () => {
+  const genesis = gh.shapeGenesis({
+    mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 },
+    plan: gh.parsePlan({}).plan,
+    tasks: { scope: [
+      { id: '201', title: 'Gather what already exists', status: 'shipped', description: 'Link the documents.' },
+      { id: '202', title: 'Write the scope', status: 'ready', description: 'Answer the five scope questions in your own words.' },
+    ] },
+  });
+  const b = bootCard({ founding: true, data: { genesis, viewer_id: '1' } });
+  const click = await mountClickable(b);
+  const html = b.host.innerHTML;
+  assert.match(html, /data-genesis-copy="202"/, 'the open task offers Copy prompt');
+  assert.doesNotMatch(html, /data-genesis-copy="201"/, 'a shipped task offers nothing');
+  assert.doesNotMatch(html, /task__claim|>Claim</, 'Copy prompt only: no Claim button (owner, 2026-11-07)');
+  const btn = fakeButton('data-genesis-copy', '202');
+  await click(btn);
+  assert.equal(b.copied.length, 1, 'one click, one copy');
+  const text = b.copied[0];
+  assert.doesNotMatch(text, /\(no description\)/, 'the copied prompt is never the empty fallback');
+  assert.match(text, /Answer the five scope questions in your own words\./, 'it carries the task\'s description');
+  assert.match(text, /Bongos task 202 \(Write the scope\)/, 'built by the hall\'s one prompt builder');
+  assert.equal(btn.set['data-copied'], '1');
+  assert.match(b.toasts.join(' '), /copied/i);
+});
+
 test('the hall carries the five life plates byte-identical to the world\'s', () => {
   const world = path.join(ROOT, 'modules', 'public-landing', 'public', 'assets', 'world');
   const hall = path.join(ROOT, 'modules', 'hall-ui', 'public', 'genesis');

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);
+}