@bongos/core 1.25.14 → 1.25.16

package/modules/hall-ui/public/dom-utils.js

@@ -529,6 +529,10 @@
     } catch (err) { return null; }
   }
 
+  // The hall's one completion tick (24x24, stroked, currentColor): the setup flow's step
+  // marks and the Genesis checklist both draw it, so a done thing looks done the same way.
+  const CHECK_SVG = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12.5l4.5 4.5L19 7.5" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg>';
+
   const OTB = {
     escapeHtml, sleep, $, fmtNum, num, fmtInt, fmtCompact, fmtDate, rankLabel, toast, moduleOn, disciplines,
     plainMessage, toastKind, TOAST_MS, // task 1005086 — one toast, a duration per kind, no server address
@@ -542,6 +546,7 @@
     splitCriterion,
     categoryChip, // task 1003276 — shared by the Goals page, the Tasks board and the task page
     hubOrigin, // task 1003485 — the hub account page's origin, for Settings and the profile nudge
+    CHECK_SVG, // task 1005110 — the one tick, setup-gate.js and genesis-home.js
   };
   if (typeof window !== 'undefined') window.OTB = OTB;
   // Node: the hall libs that also load under require() (hall-kit.js, task-lib.js, …)

package/modules/hall-ui/public/genesis-home.js

@@ -190,9 +190,10 @@
 
   // task 1005109: Copy prompt on each task still to do, so the founder pastes it into
   // Claude without leaving Genesis. The Tasks board's own button (work.js), and only that
-  // one verb: the owner declined a Claim button here. A finished task offers nothing.
+  // one verb: the owner declined a Claim button here. Only an OPEN task offers it: a done
+  // one has nothing left, and a locked one cannot be claimed yet (task 1005110).
   function copyButtonHtml(t) {
-    if (t.finished) return '';
+    if (t.state !== 'open') return '';
     return '<button class="task__copy" type="button" data-genesis-copy="' + esc(t.id) + '"'
       + ' title="Copy the task prompt to your clipboard" aria-label="Copy prompt for task ' + esc(t.id) + '">'
       + '<span class="task__copy-icon" aria-hidden="true">📋</span></button>';
@@ -212,16 +213,30 @@
     return lib.copyTaskPrompt(t, btn, toast);
   }
 
+  // task 1005110: one checklist row in one of three states, as the server decided them
+  // (shapeGenesis taskState): done (a filled circle with the tick), open (an empty
+  // circle, its status and Copy prompt) or locked (a dashed circle and what it waits on,
+  // no Copy prompt: the claim would be refused).
+  function taskRowHtml(t) {
+    var state = t.state === 'done' || t.state === 'locked' ? t.state : 'open';
+    var check = window.OTB.CHECK_SVG || '';
+    var mark = '<span class="genesis__mark" aria-hidden="true">' + (state === 'done' ? check : '') + '</span>';
+    var said = { done: 'Done', open: 'To do', locked: 'Locked' }[state];
+    var after = (t.waits_on || []).map(function (w) { return w.title; }).filter(Boolean);
+    var tail = state === 'locked'
+      ? '<span class="genesis__task-wait">' + esc(after.length ? 'after ' + after.join(', ') : 'after an earlier task') + '</span>'
+      : window.OTB.statusPill(t.status, { small: true, extraClass: 'genesis__task-st' }) + copyButtonHtml(t);
+    return '<li class="genesis__task is-' + state + '">' + mark
+      + '<span class="sr-only">' + said + ': </span>'
+      + '<a class="genesis__task-t" href="/task/' + encodeURIComponent(t.id) + '">' + esc(t.title) + '</a>'
+      + tail + '</li>';
+  }
+
   function nowHtml(g, viewerId) {
     var s = g.stages.find(function (x) { return x.state === 'now'; });
     if (!s) return '';
     var tasks = s.tasks.length
-      ? '<ul class="genesis__tasks">' + s.tasks.map(function (t) {
-        return '<li class="genesis__task' + (t.finished ? ' is-finished' : '') + '">'
-          + '<a class="genesis__task-t" href="/task/' + encodeURIComponent(t.id) + '">' + esc(t.title) + '</a>'
-          + window.OTB.statusPill(t.status, { small: true, extraClass: 'genesis__task-st' })
-          + copyButtonHtml(t) + '</li>';
-      }).join('') + '</ul>'
+      ? '<ul class="genesis__tasks">' + s.tasks.map(taskRowHtml).join('') + '</ul>'
       : '<p class="genesis__note">No tasks for this stage yet.</p>';
     return '<section class="genesis__now" aria-labelledby="genesis-now-h">'
       + '<h3 id="genesis-now-h" class="genesis__now-h">This stage’s work · ' + esc(s.label) + '</h3>'

package/modules/hall-ui/public/setup-gate.js

@@ -20,7 +20,7 @@
 
   function esc(s) { return window.OTB.escapeHtml(s); }
 
-  var CHECK = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12.5l4.5 4.5L19 7.5" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg>';
+  var CHECK = window.OTB.CHECK_SVG; // the hall's one tick (dom-utils.js), shared with the Genesis checklist
 
   function stepDetail(step) {
     if (step.id === 'cli_setup') {

package/modules/hall-ui/public/style.css

@@ -1054,7 +1054,27 @@ html[data-theme="dark"] .gplate__light { display: none; }
 .genesis__stage.is-later { opacity: 0.6; }
 .genesis__now-h { margin: 0 0 4px; font-size: 15px; font-weight: 500; }
 .genesis__task-t { flex: 1; min-width: 0; padding: 3px 0; }
-.genesis__task.is-finished .genesis__task-t { color: var(--ink-faint); text-decoration: line-through; }
+/* task 1005110: the stage's work reads as a checklist. Done is a filled circle with the
+   hall's tick (the setup flow's mark), open an empty circle, locked a dashed one with
+   what it waits on. Never struck through: a finished task was earned, not cancelled. */
+.genesis__mark {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border-radius: var(--ds-radius-pill); /* round on purpose: the owner asked for a check filling a circle */
+  border: 1.5px solid var(--rule);
+  color: var(--ok);
+}
+.genesis__mark svg { width: 14px; height: 14px; }
+.genesis__task.is-done .genesis__mark { border-color: transparent; background: var(--ok-weak); }
+.genesis__task.is-done .genesis__task-t { color: var(--ink-soft); }
+.genesis__task.is-open .genesis__mark { border-color: var(--accent); }
+.genesis__task.is-locked .genesis__mark { border-style: dashed; }
+.genesis__task.is-locked .genesis__task-t { color: var(--ink-faint); }
+.genesis__task-wait { flex: none; max-width: 40%; font-size: var(--ds-text-xs); color: var(--ink-soft); text-align: right; }
 .genesis__alive { display: grid; justify-items: center; text-align: center; gap: 10px; padding: 12px 0; }
 .genesis__alive-plates { display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; }
 .genesis__alive-h { margin: 6px 0 0; font-size: 28px; font-weight: 400; }

package/modules/lifecycle/kickoff-checklist.js

@@ -144,11 +144,11 @@ function kickoffChecklist(spec = {}, { provisioned = false, firstSignIn = false
 const GENESIS_STEPS = Object.freeze({
   scope: [
     { title: 'Write the project scope: what we are making, for whom, and what is out of scope',
-      description: 'Genesis stage 1 (scope). One page the whole team can read: the thing being made, who it is for, what done looks like for the first version, and what is deliberately left out. When it is written, Goals and the Roadmap wake.' },
+      description: 'Genesis stage 1 (scope). The project interview: what you are creating and why, who it is for and who you want building it with you, what success looks like in two years, and what everyone else in this area is getting wrong. Every future goal and task is planned from your answers, and "not sure yet" is a fine answer you can come back to. You are the author and you choose how to work: be guided through the questions, write it yourself with the questions beside you, or have your own AI session walk you through them (it asks and pushes back; you decide) — switch any time, nothing is lost. The one-page scope is then drafted from your answers. Run `npx bongos genesis show scope` to see the questions and your answers, or `npx bongos genesis assist scope` for the brief to give your AI session. When it is written, Goals and the Roadmap wake.' },
   ],
   strategize: [
     { title: 'Write out the strategy, or link the one you already have',
-      description: 'Genesis stage 2 (strategize). How the project gets from here to its first version: the order of the big pieces, the risks, and what gets tried first. A strategy that already exists can be linked instead. When it is done, Tasks wake.' },
+      description: 'Genesis stage 2 (strategize). How the project gets from here to its first version: the order of the big pieces, the risks, and what gets tried first. You are the author, and you choose how to work: be guided through the questions, write it yourself on a blank page, or have your own AI session help (it asks the same questions and pushes back, and you decide) — switch any time, nothing is lost. A strategy that already exists can be linked instead. Run `npx bongos genesis show strategize` to see the questions and your answers, or `npx bongos genesis assist strategize` for the brief to give your AI session. When it is done, Tasks wake.' },
   ],
   charter: [
     { title: 'Choose the starting government and write the bylaws',
@@ -168,9 +168,19 @@ const GENESIS_EXISTING_FIRST = {
   description: 'Genesis stage 1 (scope), for a project that already exists. Before writing anything new, link what is already there, so the scope is written from it rather than beside it.',
 };
 
-// genesisChecklist({ existing }) → { stageKey: [{ title, description, kind, discipline, ref }] }
+// GENESIS_AFTER — "this step follows that one", by ref (task 1005110). A step listed
+// here is filed with a real dependency edge on the step it names, so it cannot be
+// claimed (DEPS_NOT_SHIPPED) and the genesis home draws it locked until that one
+// ships. Only where the order is real: a stage with no entry here is all open at once.
+// Today that is brownfield scope alone — the scope is written FROM what was gathered.
+const GENESIS_AFTER = Object.freeze({
+  'genesis:scope': 'genesis:scope:existing',
+});
+
+// genesisChecklist({ existing }) → { stageKey: [{ title, description, kind, discipline, ref, after }] }
 // in genesis order. `ref` is the stable per-task key the seeder dedups on, so filing
-// twice files nothing new. Pure — no I/O.
+// twice files nothing new. `after` is the ref of the step this one waits for, set only
+// when that step is in the same list (GENESIS_AFTER), else null. Pure — no I/O.
 function genesisChecklist({ existing = false } = {}) {
   const out = {};
   for (const [stage, steps] of Object.entries(GENESIS_STEPS)) {
@@ -181,6 +191,10 @@ function genesisChecklist({ existing = false } = {}) {
       ...t, kind: 'decision', discipline: 'artist', ref: t === GENESIS_EXISTING_FIRST ? 'genesis:scope:existing' : `genesis:${stage}`,
     }));
   }
+  for (const list of Object.values(out)) {
+    const refs = new Set(list.map((t) => t.ref));
+    for (const t of list) t.after = refs.has(GENESIS_AFTER[t.ref]) ? GENESIS_AFTER[t.ref] : null;
+  }
   return out;
 }
 

package/modules/lifecycle/kickoff-seed.js

@@ -85,6 +85,7 @@ async function seedGenesisStages({ builderId = null, existing = false } = {}, de
   const pool = deps.pool || api.pool;
   const insert = deps.createTask || ((row) => db.createTask(row));
   const find = deps.findTaskBySourceRef || ((q) => db.findTaskBySourceRef(q));
+  const addDep = deps.addTaskDependency || ((id, dep) => db.addTaskDependency(id, dep));
   const { rows: versions } = await pool.query(FIRST_VERSION_SQL);
   if (!versions.length) return { seeded: 0, skipped: 'no_version' };
   const versionId = versions[0].id;
@@ -109,18 +110,39 @@ async function seedGenesisStages({ builderId = null, existing = false } = {}, de
       seeded += 1;
     }
   }
+  // task 1005110: the order genesisChecklist declares becomes a real edge, so the claim
+  // gate refuses the later step (DEPS_NOT_SHIPPED) until the earlier one ships. Written
+  // for steps already filed too (ON CONFLICT DO NOTHING), so a re-run repairs a missing edge.
+  for (const steps of Object.values(genesisChecklist({ existing }))) {
+    for (const t of steps) {
+      if (!t.after) continue;
+      const [me, before] = await Promise.all([
+        find({ source: GENESIS_SOURCE, sourceRef: t.ref }),
+        find({ source: GENESIS_SOURCE, sourceRef: t.after }),
+      ]);
+      if (me && before) await addDep(me.id, before.id);
+    }
+  }
   return { seeded, versionId };
 }
 
-// genesisStageTasks(deps) → { stageKey: [{ id, title, status, description }] } for every
-// genesis task on the board, grouped by the stage its source_ref names. The genesis home
-// lists them, and a stage close hands their ids to the Board Room's finished-tasks gate.
+// genesisStageTasks(deps) → { stageKey: [{ id, title, status, description, waits_on }] } for
+// every genesis task on the board, grouped by the stage its source_ref names. The genesis
+// home lists them, and a stage close hands their ids to the Board Room's finished-tasks gate.
+// `waits_on` is [{ id, title }] of the tasks it depends on that have not shipped: the claim
+// gate's own rule (unsatisfiedDeps, abandoned still blocks), so a row drawn locked is one
+// POST /claims would refuse (task 1005110).
 // The description rides along so each row's Copy prompt carries the task's own words
 // (task 1005109); the read stays bounded, it is only the few seeded genesis tasks.
 async function genesisStageTasks(deps = {}) {
   const pool = deps.pool || api.pool;
   const { rows } = await pool.query(
-    `SELECT id, title, status, description, source_ref FROM tasks WHERE source = $1 ORDER BY id ASC`,
+    `SELECT t.id, t.title, t.status, t.description, t.source_ref,
+            COALESCE((SELECT json_agg(json_build_object('id', x.id, 'title', x.title) ORDER BY x.id)
+                        FROM dependencies d JOIN tasks x ON x.id = d.to_id
+                       WHERE d.from_kind = 'task' AND d.from_id = t.id
+                         AND d.to_kind = 'task' AND x.status <> 'shipped'), '[]'::json) AS waits_on
+       FROM tasks t WHERE t.source = $1 ORDER BY t.id ASC`,
     [GENESIS_SOURCE],
   );
   const out = {};
@@ -129,6 +151,7 @@ async function genesisStageTasks(deps = {}) {
     if (!stage) continue;
     (out[stage] = out[stage] || []).push({
       id: String(r.id), title: r.title, status: r.status, description: r.description || '',
+      waits_on: (Array.isArray(r.waits_on) ? r.waits_on : []).map((w) => ({ id: String(w.id), title: w.title })),
     });
   }
   return out;

package/modules/onboarding/genesis-home.js

@@ -143,10 +143,19 @@ function readPlanValue(raw) {
 
 const FINISHED = Object.freeze(['shipped', 'abandoned']); // the Board Room's own gate, mirrored for display
 
+// taskState(t) — one stage task as the checklist draws it (task 1005110).
+function taskState(t) {
+  const finished = FINISHED.includes(t.status);
+  const waits = finished ? [] : (Array.isArray(t.waits_on) ? t.waits_on : []);
+  return { ...t, finished, waits_on: waits, state: finished ? 'done' : waits.length ? 'locked' : 'open' };
+}
+
 // shapeGenesis({ mode, plan, tasks, board, stageAt }) — PURE. The genesis home's view.
 //   mode    foundingModeFor's shape (non-null)
 //   plan    the saved plan or null (deciding)
-//   tasks   { stage: [{ id, title, status, description }] }
+//   tasks   { stage: [{ id, title, status, description, waits_on }] }
+// Each task comes back with `state`: 'done' (finished), 'locked' (waits on an unshipped
+// task, named in `waits_on`) or 'open' — decided here, never re-derived in a browser.
 //   board   { stage: genesisStageStatus row } or {}
 //   stageAt { stage: ISO } — when each stage began, for its due date
 function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
@@ -154,7 +163,7 @@ function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
   const stages = PROPER.map((key) => {
     const info = STAGE_INFO[key];
     const idx = fm.STAGES.indexOf(key);
-    const list = (tasks[key] || []).map((t) => ({ ...t, finished: FINISHED.includes(t.status) }));
+    const list = (tasks[key] || []).map((t) => taskState(t));
     const b = board[key] || null;
     const allFinished = list.length > 0 && list.every((t) => t.finished);
     const onBoard = !!(b && (b.state === 'sitting' || b.state === 'passed'));

package/modules/onboarding/genesis-work.js

@@ -0,0 +1,387 @@
+'use strict';
+
+// modules/onboarding/genesis-work.js — THE FOUNDER'S OWN WORK ON A GENESIS STAGE: one
+// stored record per stage that three ways of working all read and write (task 1005116,
+// goal 1000106; owner ruling 2026-11-07).
+//
+// WHY. A genesis stage is a decision only the founder can make. It used to have one
+// route through it: an AI session drafted the stage's answer, and the project's strategy
+// (or scope) became the model's. The owner's rule: Bongos may structure the thinking
+// and may help with the words, but THE FOUNDER IS THE AUTHOR. So every stage offers
+// three DOORS onto the same work, and the founder picks and switches freely:
+//
+//   guided    the platform asks the stage's questions one at a time; the founder
+//             answers every one. The DEFAULT, offered first: a blank page is how a
+//             stage comes back thin.
+//   open      a blank page and the stage's done-when line. The questions still show
+//             beside it, as the shape of a good answer, never as fields to fill.
+//   assisted  the founder's own AI session helps (assistPrompt): it works the SAME
+//             questions, pushes back and offers options, and records only what the
+//             founder decides.
+//
+// Plus the fourth way that already existed: link the document you already have.
+//
+// ONE ARTIFACT, NOT THREE FLOWS. The door is only how the founder is working right now.
+// The answers, the free page and the link are one record per stage, kept whatever the
+// door, so switching loses nothing: start guided, finish on the page, ask the session
+// to poke holes in it.
+//
+// AN ANSWER IS STORED AS AN ANSWER, never as prose inside a task description, so every
+// later goal and task can read it (contextMarkdown, `GET /founding/context`). Each has
+// a STATE, and the three are deliberately distinct from one another and from "empty":
+//   answered   the founder's words
+//   not_sure   "not sure yet" — an answer, not a gap (an optional note says why)
+//   skipped    the founder chose to pass on it
+//   (no row)   never touched
+// Un-answering deletes the row, back to empty. Each answer carries its ORIGIN —
+// `founder` (typed by them), `assisted` (worked out with their session and accepted by
+// them) or `carried_over` (brought in from before sign-up, task 1005274; shown as
+// editable, and any edit by the founder makes it theirs). Every write and every
+// un-answer appends a history row, so the founder can see what an answer used to say.
+//
+// WHICH STAGES. A stage adopts the pattern by declaring its questions in QUESTIONS.
+// Strategize does (task 1005116); scope's guided door is its project interview (task 1005114);
+// charter, legalize and legislation adopt it when they are next touched. A stage with
+// no questions still takes a free page and a link.
+//
+// THE BOUNDARY. Pure apart from the store. The store is injected (tests) or the
+// Postgres one below, over the doorway's pool; tables in
+// migrations/onboarding_002_genesis_work.sql.
+
+const fm = require('./founding-mode');
+
+const STAGES = Object.freeze(fm.STAGES.slice(1)); // scope … legislation
+const DOORS = Object.freeze(['guided', 'open', 'assisted']);
+const DEFAULT_DOOR = 'guided';
+const STATES = Object.freeze(['answered', 'not_sure', 'skipped']);
+const ORIGINS = Object.freeze(['founder', 'assisted', 'carried_over']);
+const LIMITS = Object.freeze({ answer: 4000, page: 20000, link: 500 });
+
+// Each adopted stage's questions, in the order the guided door asks them. `id` is
+// stable: a stored answer names it, so never rename or reuse one. `hint` is the shape
+// of a good answer, shown under the question in every door. `group` (optional) is a
+// heading the guided door shows above the questions that share it.
+//
+// SCOPE IS THE PROJECT INTERVIEW (task 1005114): the questions every later goal and task
+// should be planned inside — what this is for, who it is for, and the bet — rather than
+// V1's edges, which is what came back thin before. The owner's starter set, as written;
+// the list is "not final" and the owner invited more. These are prose questions; the
+// closed-vocabulary ones (team shape, geography, entity, rewards) are the hub's project
+// detail and are not repeated here.
+const QUESTIONS = Object.freeze({
+  scope: Object.freeze([
+    Object.freeze({ id: 'what_creating', group: 'What and why', ask: 'In a few sentences, what are you creating with this project?',
+      hint: 'Say it the way you would to a friend. What exists when this is done that does not exist now?' }),
+    Object.freeze({ id: 'goal_impact', group: 'What and why', ask: 'What is your goal with it? What impact do you want it to have?',
+      hint: 'Why this is worth doing at all, and for whom it changes something.' }),
+    Object.freeze({ id: 'success_two_years', group: 'What and why', ask: 'In two years, what does success look like?',
+      hint: 'Something you could point at: who is using it, what they do with it, what it has become.' }),
+    Object.freeze({ id: 'reach_who', group: 'Who', ask: 'Who do you want to reach with this project?',
+      hint: 'The people it is ultimately for, not only the first ones. Be as specific as you can.' }),
+    Object.freeze({ id: 'work_with_who', group: 'Who', ask: 'Who do you want working on it with you?',
+      hint: 'The kind of people you hope join: their skills, how they work, what they care about.' }),
+    Object.freeze({ id: 'others_wrong', group: 'The bet', ask: 'What is everyone else in this area getting wrong?',
+      hint: 'The thing you believe that others in this space do not. This is the bet the project makes.' }),
+  ]),
+  strategize: Object.freeze([
+    Object.freeze({ id: 'big_pieces', ask: 'What are the big pieces, and in what order do they get built?',
+      hint: 'Three to six pieces is plenty. Say why that order: what has to exist before what.' }),
+    Object.freeze({ id: 'risks', ask: 'What are the biggest risks, the things that could sink this?',
+      hint: 'Name what you are least sure of: a technical unknown, whether anyone wants it, time, money.' }),
+    Object.freeze({ id: 'try_first', ask: 'What gets tried first, and why that?',
+      hint: 'Usually the cheapest test of the biggest risk.' }),
+    Object.freeze({ id: 'change_course', ask: 'What would make you change course?',
+      hint: 'The signal that would tell you this plan is wrong, so you notice it when it comes.' }),
+  ]),
+});
+
+const isStage = (s) => STAGES.includes(s);
+const questionsFor = (stage) => QUESTIONS[stage] || [];
+const questionFor = (stage, id) => questionsFor(stage).find((q) => q.id === id) || null;
+const text = (v) => (v == null ? '' : String(v)).trim();
+
+// ── pure: checking a write ────────────────────────────────────────────────────
+
+// checkAnswer(stage, questionId, body) → { ok, value } or { ok:false, reason }.
+//   body: { state, text?, origin? }. `answered` needs words; `not_sure` and `skipped`
+//   may carry a short note. The origin defaults to `founder`.
+function checkAnswer(stage, questionId, body = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  if (!questionFor(stage, questionId)) return { ok: false, reason: 'unknown_question' };
+  const b = body && typeof body === 'object' ? body : {};
+  const state = b.state == null ? 'answered' : String(b.state);
+  if (!STATES.includes(state)) return { ok: false, reason: 'bad_state' };
+  const origin = b.origin == null ? 'founder' : String(b.origin);
+  if (!ORIGINS.includes(origin)) return { ok: false, reason: 'bad_origin' };
+  const words = text(b.text);
+  if (words.length > LIMITS.answer) return { ok: false, reason: 'answer_too_long' };
+  if (state === 'answered' && !words) return { ok: false, reason: 'empty_answer' };
+  return { ok: true, value: { state, answer_md: words || null, origin } };
+}
+
+// checkLink(url) → { ok, value } — an http(s) address, or '' / null to remove it.
+function checkLink(url) {
+  const u = text(url);
+  if (!u) return { ok: true, value: null };
+  if (u.length > LIMITS.link) return { ok: false, reason: 'link_too_long' };
+  if (!/^https?:\/\/[^\s]+$/i.test(u)) return { ok: false, reason: 'bad_link' };
+  return { ok: true, value: u };
+}
+
+// ── pure: the view ────────────────────────────────────────────────────────────
+
+const iso = (v) => (v ? new Date(v).toISOString() : null);
+
+// shapeStage(stage, work, answers) → one stage's record as every door sees it.
+//   work     the stage row ({ door, page_md, link_url, updated_at }) or null
+//   answers  the stage's answer rows
+function shapeStage(stage, work, answers = []) {
+  const byId = new Map(answers.filter((a) => a.stage === stage).map((a) => [a.question_id, a]));
+  const questions = questionsFor(stage).map((q) => {
+    const a = byId.get(q.id);
+    return {
+      id: q.id, ask: q.ask, hint: q.hint, group: q.group || null,
+      answer: a ? {
+        state: a.state, text: a.answer_md || null, origin: a.origin,
+        // A carried-over answer is shown as such until the founder makes it theirs.
+        carried_over: a.origin === 'carried_over',
+        updated_at: iso(a.updated_at),
+      } : null,
+    };
+  });
+  const count = (st) => questions.filter((q) => q.answer && q.answer.state === st).length;
+  return {
+    stage,
+    adopted: questionsFor(stage).length > 0,
+    door: (work && DOORS.includes(work.door)) ? work.door : DEFAULT_DOOR,
+    doors: DOORS,
+    questions,
+    page: work && work.page_md ? work.page_md : null,
+    link: work && work.link_url ? work.link_url : null,
+    counts: {
+      total: questions.length,
+      answered: count('answered'),
+      not_sure: count('not_sure'),
+      skipped: count('skipped'),
+      empty: questions.filter((q) => !q.answer).length,
+    },
+    updated_at: iso(work && work.updated_at),
+  };
+}
+
+// shapeAll({ work, answers }) → every stage, in genesis order.
+function shapeAll({ work = [], answers = [] } = {}) {
+  const byStage = new Map(work.map((w) => [w.stage, w]));
+  return STAGES.map((s) => shapeStage(s, byStage.get(s) || null, answers));
+}
+
+const STATE_WORDS = { not_sure: 'Not sure yet', skipped: 'Skipped by the founder' };
+const ORIGIN_WORDS = { assisted: ' (worked out with an AI session, accepted by the founder)', carried_over: ' (carried over from before sign-up, not yet confirmed by the founder)' };
+
+// contextMarkdown(stages) → THE READ PATH for an AI session planning a goal or task:
+// what the founder has said about the project, stage by stage, as plain markdown. Only
+// stages with something in them appear; an empty project returns an empty string so a
+// caller can say nothing rather than print an empty heading.
+function contextMarkdown(stages) {
+  const out = [];
+  for (const s of stages || []) {
+    const said = s.questions.filter((q) => q.answer);
+    if (!said.length && !s.page && !s.link) continue;
+    out.push(`## ${s.stage[0].toUpperCase()}${s.stage.slice(1)}`);
+    for (const q of said) {
+      const a = q.answer;
+      const body = a.state === 'answered' ? a.text : `${STATE_WORDS[a.state]}${a.text ? ` — ${a.text}` : ''}`;
+      out.push(`- **${q.ask}**${ORIGIN_WORDS[a.origin] || ''}\n  ${String(body).replace(/\n/g, '\n  ')}`);
+    }
+    if (s.page) out.push('', '**In the founder\'s own words:**', '', s.page);
+    if (s.link) out.push('', `**The founder's existing document:** ${s.link}`);
+    out.push('');
+  }
+  if (!out.length) return '';
+  return ['# What the founder has said about this project', '',
+    'Written by the founder during genesis. Treat it as the project\'s own direction: plan inside it, and say so when a goal or task would go against it. "Not sure yet" is an honest answer, not a gap to fill in for them.', '',
+    ...out].join('\n').trimEnd() + '\n';
+}
+
+// assistPrompt(stage) → the brief the founder hands their own AI session for the
+// assisted door. It works the stage's own questions (never a shape of its own),
+// argues rather than authors, and records only what the founder decides.
+function assistPrompt(stage) {
+  if (!isStage(stage)) return null;
+  const qs = questionsFor(stage);
+  const lines = [
+    `Help me work through the ${stage} stage of my project's genesis. I am the author; you are my assistant.`,
+    '',
+    'How to help:',
+    '- Work these questions, one at a time, in this order. Do not invent a different structure.',
+    '- Ask what I am assuming. Push back when an answer is vague or I seem too sure.',
+    '- Offer two or three options when I am stuck, never one confident answer.',
+    '- "Not sure yet" is a fine answer. Record it as that rather than filling the gap for me.',
+    '- Record an answer only after I say it is mine, in my words (you may tidy the wording; read it back first).',
+    '- Once I have answered, you may offer a draft page built only from my answers. I edit it; save it only when I say it is mine.',
+    '',
+  ];
+  if (qs.length) {
+    lines.push('The questions (the id in brackets is what you record the answer under):');
+    qs.forEach((q, i) => lines.push(`${i + 1}. [${q.id}] ${q.ask} (${q.hint})`));
+    lines.push('');
+  }
+  lines.push('To see what I have already said:  npx bongos genesis show ' + stage);
+  if (qs.length) {
+    lines.push(`To record an answer I accepted:    npx bongos genesis answer ${stage} <question-id> "<my words>" --origin assisted`);
+    lines.push(`To record "not sure yet":          npx bongos genesis answer ${stage} <question-id> --not-sure ["why"]`);
+  }
+  lines.push(`To save a page I wrote:            npx bongos genesis page ${stage} --file <path>`);
+  return lines.join('\n');
+}
+
+// ── the store (Postgres) ──────────────────────────────────────────────────────
+
+function pgStore(pool) {
+  const db = () => pool || require('../../src/module-api').pool;
+  return {
+    async loadAll() {
+      const [w, a] = await Promise.all([
+        db().query('SELECT stage, door, page_md, link_url, updated_at FROM onboarding_genesis_work'),
+        db().query('SELECT stage, question_id, state, answer_md, origin, updated_at FROM onboarding_genesis_answers'),
+      ]);
+      return { work: w.rows, answers: a.rows };
+    },
+    // patch: any of { door, page_md, link_url }; an absent key keeps what is stored.
+    async upsertWork(stage, patch, by) {
+      const has = (k) => Object.prototype.hasOwnProperty.call(patch, k);
+      await db().query(
+        `INSERT INTO onboarding_genesis_work (stage, door, page_md, link_url, updated_by)
+         VALUES ($1, COALESCE($2, '${DEFAULT_DOOR}'), $4, $6, $8)
+         ON CONFLICT (stage) DO UPDATE SET
+           door     = CASE WHEN $3 THEN EXCLUDED.door ELSE onboarding_genesis_work.door END,
+           page_md  = CASE WHEN $5 THEN EXCLUDED.page_md ELSE onboarding_genesis_work.page_md END,
+           link_url = CASE WHEN $7 THEN EXCLUDED.link_url ELSE onboarding_genesis_work.link_url END,
+           updated_by = EXCLUDED.updated_by, updated_at = now()`,
+        [stage, has('door') ? patch.door : null, has('door'), has('page_md') ? patch.page_md : null,
+          has('page_md'), has('link_url') ? patch.link_url : null, has('link_url'), by == null ? null : by],
+      );
+    },
+    // One statement: the answer and its history row land together, and a write that
+    // changes nothing writes neither. ifEmpty never touches an answer already there.
+    async writeAnswer(stage, questionId, v, by, { ifEmpty = false } = {}) {
+      const { rows } = await db().query(
+        `WITH up AS (
+           INSERT INTO onboarding_genesis_answers (stage, question_id, state, answer_md, origin, updated_by)
+           VALUES ($1, $2, $3, $4, $5, $6)
+           ON CONFLICT (stage, question_id) DO ${ifEmpty ? 'NOTHING' : `UPDATE SET
+             state = EXCLUDED.state, answer_md = EXCLUDED.answer_md, origin = EXCLUDED.origin,
+             updated_by = EXCLUDED.updated_by, updated_at = now()
+           WHERE (onboarding_genesis_answers.state, onboarding_genesis_answers.answer_md, onboarding_genesis_answers.origin)
+             IS DISTINCT FROM (EXCLUDED.state, EXCLUDED.answer_md, EXCLUDED.origin)`}
+           RETURNING stage, question_id, state, answer_md, origin, updated_by)
+         INSERT INTO onboarding_genesis_answer_history (stage, question_id, state, answer_md, origin, changed_by)
+         SELECT stage, question_id, state, answer_md, origin, updated_by FROM up
+         RETURNING id`,
+        [stage, questionId, v.state, v.answer_md, v.origin, by == null ? null : by],
+      );
+      return { changed: rows.length > 0 };
+    },
+    async clearAnswer(stage, questionId, by) {
+      const { rows } = await db().query(
+        `WITH del AS (
+           DELETE FROM onboarding_genesis_answers WHERE stage = $1 AND question_id = $2
+           RETURNING stage, question_id)
+         INSERT INTO onboarding_genesis_answer_history (stage, question_id, state, answer_md, origin, changed_by)
+         SELECT stage, question_id, NULL, NULL, NULL, $3 FROM del
+         RETURNING id`,
+        [stage, questionId, by == null ? null : by],
+      );
+      return { cleared: rows.length > 0 };
+    },
+    async history(stage, questionId) {
+      const { rows } = await db().query(
+        `SELECT state, answer_md, origin, changed_by, changed_at FROM onboarding_genesis_answer_history
+          WHERE stage = $1 AND question_id = $2 ORDER BY changed_at DESC, id DESC LIMIT 50`,
+        [stage, questionId],
+      );
+      return rows;
+    },
+  };
+}
+
+// ── the operations the routes call ────────────────────────────────────────────
+
+const storeOf = (deps = {}) => deps.store || pgStore(deps.pool);
+
+async function readAll(deps = {}) {
+  return shapeAll(await storeOf(deps).loadAll());
+}
+
+async function readStage(stage, deps = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  const all = await readAll(deps);
+  return { ok: true, work: all.find((s) => s.stage === stage) };
+}
+
+async function setDoor(stage, door, by, deps = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  if (!DOORS.includes(door)) return { ok: false, reason: 'bad_door' };
+  await storeOf(deps).upsertWork(stage, { door }, by);
+  return readStage(stage, deps);
+}
+
+async function setPage(stage, page, by, deps = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  const words = text(page);
+  if (words.length > LIMITS.page) return { ok: false, reason: 'page_too_long' };
+  await storeOf(deps).upsertWork(stage, { page_md: words || null }, by);
+  return readStage(stage, deps);
+}
+
+async function setLink(stage, url, by, deps = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  const c = checkLink(url);
+  if (!c.ok) return c;
+  await storeOf(deps).upsertWork(stage, { link_url: c.value }, by);
+  return readStage(stage, deps);
+}
+
+// setAnswer — store or revise one answer. opts.ifEmpty (for carrying answers over,
+// task 1005274) writes only where the founder has said nothing yet.
+async function setAnswer(stage, questionId, body, by, deps = {}, opts = {}) {
+  const c = checkAnswer(stage, questionId, body);
+  if (!c.ok) return c;
+  const { changed } = await storeOf(deps).writeAnswer(stage, questionId, c.value, by, opts);
+  const r = await readStage(stage, deps);
+  return { ...r, changed };
+}
+
+// clearAnswer — un-answer: the question goes back to empty (not to "skipped").
+async function clearAnswer(stage, questionId, by, deps = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  if (!questionFor(stage, questionId)) return { ok: false, reason: 'unknown_question' };
+  const { cleared } = await storeOf(deps).clearAnswer(stage, questionId, by);
+  const r = await readStage(stage, deps);
+  return { ...r, cleared };
+}
+
+async function answerHistory(stage, questionId, deps = {}) {
+  if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
+  if (!questionFor(stage, questionId)) return { ok: false, reason: 'unknown_question' };
+  const rows = await storeOf(deps).history(stage, questionId);
+  return {
+    ok: true,
+    history: rows.map((r) => ({
+      state: r.state || 'cleared', text: r.answer_md || null, origin: r.origin || null,
+      changed_by: r.changed_by == null ? null : String(r.changed_by), changed_at: iso(r.changed_at),
+    })),
+  };
+}
+
+async function readContext(deps = {}) {
+  const stages = await readAll(deps);
+  return { markdown: contextMarkdown(stages), stages };
+}
+
+// Only what a caller uses is exported; the checks and the view shaping stay private
+// and are exercised through the operations (tests/genesis_work.mjs).
+module.exports = {
+  STAGES, LIMITS, QUESTIONS, assistPrompt,
+  pgStore, readAll, readStage, setDoor, setPage, setLink, setAnswer, clearAnswer, answerHistory, readContext,
+};