@bongos/core 1.25.15 → 1.25.17

package/modules/government/decision-rules.js

@@ -94,6 +94,7 @@ const AREAS = Object.freeze([
       'POST /goals/reorder',
       'POST /work-categories',
       'PUT /versions/focus',
+      'POST /first-read/maps/:id/accept', // task 1005280: accepting a repository map files goals
     ]) }),
   Object.freeze({ key: 'automation', name: 'Automation', gate: 'autonomy.fence.manage',
     today: 'whoever may switch unattended building on and off', acts: Object.freeze([

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/first-read-db.js

@@ -0,0 +1,152 @@
+// modules/lifecycle/first-read-db.js — the store behind the first read-through (task
+// 1005280): keep a submitted repository map, show it for review with what is already
+// filed, and file the owner's accepted items as DRAFT goals and tasks.
+//
+// The rules live in first-read.js (pure); this file only runs them against Postgres.
+// Two properties an edit must keep:
+//   - SUBMIT FILES NOTHING. A map is stored `pending`; only acceptMap creates goals or
+//     tasks, and only for the refs the owner named (or 'all').
+//   - A RE-RUN NEVER DUPLICATES. Every filed ref is a row in lifecycle_repo_map_filed
+//     (PRIMARY KEY), read under an advisory lock inside the accept transaction, so two
+//     accepts — or a second map naming the same item — file it once.
+// Nothing here calls an AI: the map arrives already written by the owner's own session.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const db = require('./db');
+const fr = require('./first-read');
+const { FIRST_VERSION_SQL } = require('./kickoff-seed');
+
+const TASK_SOURCE = 'repo-map';
+const ACCEPT_LOCK = "pg_advisory_xact_lock(hashtext('first-read/accept'))";
+
+const poolOf = (deps) => deps.pool || api.pool;
+
+// submitMap({ raw, builderId }) → { ok: true, map_id, items } | { ok: false, errors }
+// Validates, then stores the NORMALISED map (unknown sections kept). Files nothing.
+async function submitMap({ raw, builderId = null }, deps = {}) {
+  const v = fr.validateRepoMap(raw);
+  if (!v.ok) return v;
+  const { rows: [row] } = await poolOf(deps).query(
+    `INSERT INTO lifecycle_repo_maps (schema, map, submitted_by) VALUES ($1, $2::jsonb, $3) RETURNING id, status, submitted_at`,
+    [fr.SCHEMA, JSON.stringify(v.map), builderId],
+  );
+  return { ok: true, map_id: String(row.id), status: row.status, items: v.items };
+}
+
+// filedRefs(refs) → Map(ref → { kind, entity_id }) for the refs already filed.
+async function filedRefs(refs, exec) {
+  if (!refs.length) return new Map();
+  const { rows } = await exec.query(
+    'SELECT ref, kind, entity_id FROM lifecycle_repo_map_filed WHERE ref = ANY($1::text[])', [refs],
+  );
+  return new Map(rows.map((r) => [r.ref, { kind: r.kind, entity_id: String(r.entity_id) }]));
+}
+
+// reviewMap(id | 'latest') → { map_id, status, summary, items: [{ ...item, filed }], extra } | null
+// What the owner reads before deciding: every item with whether it is already in Bongos.
+async function reviewMap(id, deps = {}) {
+  const pool = poolOf(deps);
+  const { rows: [row] } = id === 'latest'
+    ? await pool.query('SELECT id, status, map, submitted_at FROM lifecycle_repo_maps ORDER BY submitted_at DESC, id DESC LIMIT 1')
+    : await pool.query('SELECT id, status, map, submitted_at FROM lifecycle_repo_maps WHERE id = $1', [id]);
+  if (!row) return null;
+  const v = fr.validateRepoMap(row.map);
+  const items = v.ok ? v.items : [];
+  const filed = await filedRefs(items.map((i) => i.ref), pool);
+  const extra = {};
+  for (const [k, val] of Object.entries(row.map || {})) if (!['schema', 'summary', 'goals', 'next'].includes(k)) extra[k] = val;
+  return {
+    map_id: String(row.id), status: row.status, submitted_at: row.submitted_at,
+    summary: (row.map && row.map.summary) || '',
+    items: items.map((i) => ({ ...i, filed: filed.has(i.ref) ? filed.get(i.ref) : null })),
+    extra,
+  };
+}
+
+// acceptMap({ mapId, select, builderId }) → { ok, filed: { goals, tasks }, skipped } | { ok: false, code, status, ... }
+// ONE transaction: lock the map, lock the accept path, plan against what is already
+// filed, create the drafts, remember their refs, mark the map accepted. A refusal files
+// nothing. Goals are created open; tasks at `backlog` (drafts nobody can claim yet).
+async function acceptMap({ mapId, select, builderId = null }, deps = {}) {
+  if (select !== 'all' && (!Array.isArray(select) || select.length === 0)) {
+    return { ok: false, code: 'nothing_selected', status: 400 };
+  }
+  const createGoal = deps.createGoal || ((row, d) => db.createGoal(row, d));
+  const createTask = deps.createTask || ((row, d) => db.createTask(row, d));
+  const client = await poolOf(deps).connect();
+  try {
+    await client.query('BEGIN');
+    const { rows: [row] } = await client.query('SELECT id, status, map FROM lifecycle_repo_maps WHERE id = $1 FOR UPDATE', [mapId]);
+    if (!row) { await client.query('ROLLBACK'); return { ok: false, code: 'not_found', status: 404 }; }
+    if (row.status === 'rejected') { await client.query('ROLLBACK'); return { ok: false, code: 'map_rejected', status: 409 }; }
+    await client.query(`SELECT ${ACCEPT_LOCK}`);
+    const v = fr.validateRepoMap(row.map);
+    if (!v.ok) { await client.query('ROLLBACK'); return { ok: false, code: 'invalid_map', status: 409, errors: v.errors }; }
+    const goalRefs = [...new Set([...v.items.map((i) => i.ref), ...v.items.map((i) => i.goal_ref).filter(Boolean)])];
+    const already = await filedRefs(goalRefs, client);
+    const plan = fr.planAcceptance({ items: v.items, mapId: String(row.id), select, filedRefs: new Set(already.keys()) });
+    if (plan.unknown.length) { await client.query('ROLLBACK'); return { ok: false, code: 'unknown_items', status: 400, unknown: plan.unknown }; }
+
+    let versionId = null;
+    if (plan.goals.length || plan.tasks.length) {
+      const { rows: versions } = await client.query(FIRST_VERSION_SQL);
+      if (!versions.length) { await client.query('ROLLBACK'); return { ok: false, code: 'no_version', status: 409 }; }
+      versionId = versions[0].id;
+    }
+    // The filed refs are written in ONE statement after the creates, not one per item.
+    const remembered = [];
+    const remember = (ref, kind, id) => { remembered.push([ref, kind, String(id)]); };
+    const goalIds = new Map([...already].filter(([, f]) => f.kind === 'goal').map(([ref, f]) => [ref, f.entity_id]));
+    const filed = { goals: [], tasks: [] };
+    for (const g of plan.goals) {
+      const goal = await createGoal({ versionId, title: g.title, description: g.description, createdBy: builderId }, { client });
+      goalIds.set(g.ref, String(goal.id));
+      remember(g.ref, 'goal', goal.id);
+      filed.goals.push({ ref: g.ref, id: String(goal.id), title: g.title });
+    }
+    for (const t of plan.tasks) {
+      const task = await createTask({
+        versionId, title: t.title, description: t.description, status: 'backlog', kind: t.kind,
+        discipline: 'artisan', source: TASK_SOURCE, sourceRef: t.ref, goalId: goalIds.get(t.goalRef), createdBy: builderId,
+      }, { client });
+      remember(t.ref, 'task', task.id);
+      filed.tasks.push({ ref: t.ref, id: String(task.id), title: t.title, goal_id: goalIds.get(t.goalRef) });
+    }
+    if (remembered.length) {
+      await client.query(
+        `INSERT INTO lifecycle_repo_map_filed (ref, kind, entity_id, map_id, filed_by)
+         SELECT r, k, e, $4, $5 FROM unnest($1::text[], $2::text[], $3::bigint[]) AS u(r, k, e)`,
+        [remembered.map((x) => x[0]), remembered.map((x) => x[1]), remembered.map((x) => x[2]), row.id, builderId],
+      );
+    }
+    await client.query(
+      `UPDATE lifecycle_repo_maps SET status = 'accepted', reviewed_by = $2, reviewed_at = now() WHERE id = $1`,
+      [row.id, builderId],
+    );
+    await client.query('COMMIT');
+    return { ok: true, map_id: String(row.id), filed, skipped: plan.skipped };
+  } catch (e) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw e;
+  } finally {
+    client.release();
+  }
+}
+
+// rejectMap({ mapId, builderId }) → { ok } | { ok: false, code, status }. Files nothing.
+// Only a pending map can be rejected: an accepted one already has drafts the owner said yes to.
+async function rejectMap({ mapId, builderId = null }, deps = {}) {
+  const { rows } = await poolOf(deps).query(
+    `UPDATE lifecycle_repo_maps SET status = 'rejected', reviewed_by = $2, reviewed_at = now()
+      WHERE id = $1 AND status = 'pending' RETURNING id`,
+    [mapId, builderId],
+  );
+  if (rows.length) return { ok: true, map_id: String(rows[0].id) };
+  const { rows: [row] } = await poolOf(deps).query('SELECT status FROM lifecycle_repo_maps WHERE id = $1', [mapId]);
+  if (!row) return { ok: false, code: 'not_found', status: 404 };
+  return { ok: false, code: 'not_pending', status: 409, current: row.status };
+}
+
+module.exports = { TASK_SOURCE, submitMap, reviewMap, acceptMap, rejectMap };

package/modules/lifecycle/first-read.js

@@ -0,0 +1,265 @@
+// modules/lifecycle/first-read.js — the first run-through of a project that arrives with
+// code: the prompt the owner's OWN AI session runs, the repository map it writes back,
+// the map's validation, and the plan for filing the owner's accepted items (task 1005280,
+// goal 1000106 "Project creation").
+//
+// THE RULE THIS SERVES. The platform never reads a person's repository on its own AI
+// bill. So Bongos does not read it at all: it hands the owner a prompt, their own AI
+// session reads the repository on their own subscription, on their own computer, and
+// sends back a MAP — goals already in progress, the tasks under each, and what needs
+// doing next given errors or mishaps found in the code, each with a short reason and
+// where it was seen. Nothing here calls an AI, and the map's length caps keep it a
+// summary, never a copy of the code.
+//
+// NOTHING IS FILED WITHOUT THE OWNER'S YES. A submitted map waits as `pending`. Only an
+// explicit accept (all, or named items) files anything, and only as drafts: goals open
+// with their tasks in `backlog`, so nothing is claimable until someone promotes it.
+//
+// RE-RUNS DO NOT DUPLICATE. Each item's `ref` is derived from its title (never its
+// position), and every filed ref is remembered (lifecycle_repo_map_filed), so a second
+// map that names the same goal or task again plans to file nothing for it.
+//
+// ROOM TO GROW. Unknown top-level keys are kept, not refused — task 1005281 adds a
+// `recommended_modules` section the same way, with no change to this version's shape.
+//
+// Pure — no I/O. The DB half is first-read-db.js; the HTTP surface routes/first-read.js;
+// the CLI scripts/bongos/first-read.js; the Genesis step that hands out the prompt is
+// GENESIS_EXISTING_FIRST in kickoff-checklist.js.
+
+'use strict';
+
+const SCHEMA = 'bongos.repo-map/1';
+const MAP_FILE = 'bongos-repo-map.json';
+
+// Caps. Generous for a real project, small enough that a map cannot carry the code.
+const LIMITS = Object.freeze({
+  SUMMARY: 1200,
+  TITLE: 160,
+  WHY: 500,
+  SEEN_AT: 10,
+  SEEN_AT_CHARS: 300,
+  GOALS: 20,
+  TASKS_PER_GOAL: 30,
+  NEXT: 50,
+  BYTES: 60000,
+});
+const TASK_STATES = ['done', 'in_progress', 'not_started'];
+const NEXT_KINDS = ['error', 'mishap', 'gap'];
+// Top-level keys this version reads. Anything else is kept as-is for a later reader.
+const KNOWN_KEYS = ['schema', 'summary', 'goals', 'next'];
+const UNSAFE_KEYS = ['__proto__', 'constructor', 'prototype'];
+// The goal a `next` item lands under when it names no goal of the map.
+const NEXT_GOAL = Object.freeze({
+  ref: 'goal:fix-what-the-first-read-found',
+  title: 'Fix what the first read-through found',
+  why: 'Errors, mishaps and gaps the first read-through of the repository found, not tied to one goal.',
+});
+
+// slug(text) → a stable lower-case key: the same title always gives the same ref.
+function slug(text) {
+  return String(text || '').toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+}
+
+// The refs, in one place, so the plan and the review agree.
+const goalRef = (title) => `goal:${slug(title)}`;
+const taskRef = (goalTitle, title) => `task:${slug(goalTitle)}:${slug(title)}`;
+const nextRef = (title) => `next:${slug(title)}`;
+
+// ── the prompt ───────────────────────────────────────────────────────────────
+
+// An example map in the defined shape — printed in the prompt so the session copies it.
+function exampleMap() {
+  return {
+    schema: SCHEMA,
+    summary: 'A booking site for a dog-walking business. Sign-up and the booking calendar work; payments are half built.',
+    goals: [{
+      title: 'Take payments for bookings',
+      why: 'A payments folder and a half-finished checkout page exist, and the last ten commits are about it.',
+      seen_at: ['src/payments/', 'src/pages/checkout.js'],
+      tasks: [
+        { title: 'Finish the checkout page', status: 'in_progress', why: 'The page renders but the pay button does nothing.', seen_at: ['src/pages/checkout.js:88'] },
+        { title: 'Send a receipt by email', status: 'not_started', why: 'A TODO says receipts are still to do.', seen_at: ['src/payments/charge.js:12'] },
+      ],
+    }],
+    next: [
+      { title: 'Fix the failing booking test', kind: 'error', goal: '', why: 'The test command fails: the calendar test expects Monday-first weeks.', seen_at: ['tests/calendar.test.js:40'] },
+    ],
+  };
+}
+
+// firstReadPrompt({ cli }) → the full text the owner hands their own AI session. It is
+// also the Genesis step's description, so the hall's copy-prompt carries all of it.
+function firstReadPrompt({ cli = 'npx bongos' } = {}) {
+  return [
+    'First read-through of a project that already exists. You are the owner\'s own AI session, working on their computer, on their subscription. Bongos itself never reads this repository.',
+    '',
+    '1. Read the repository here yourself: the README and any docs or notes, the to-do comments, the recent git history and open branches, and the code. If the project has a test or build command, run it once to see what fails. Do not upload, paste or send any source code anywhere.',
+    '2. Write what you found as a map, in a file named ' + MAP_FILE + ' at the top of the repository (do not commit it):',
+    '   - "goals": the goals already in progress, each with the tasks under it (status done, in_progress or not_started).',
+    '   - "next": what needs doing next because of errors or mishaps you found in the code (kind error, mishap or gap). Name the goal it belongs to in "goal", or leave it empty.',
+    '   - Every goal, task and next item has a short "why" (one or two sentences, in plain words) and "seen_at" (where you saw it: file paths, with a line number when it helps). Reasons and places only, never copied code.',
+    '   Use exactly this shape:',
+    JSON.stringify(exampleMap(), null, 2).split('\n').map((l) => '   ' + l).join('\n'),
+    `3. Check the file: ${cli} first-read check ${MAP_FILE}  — fix anything it lists and check again.`,
+    `4. Send it to Bongos: ${cli} first-read submit ${MAP_FILE}  — this files nothing yet; it prints the map's number and every item's ref.`,
+    '5. Walk the owner through the map in plain words, goal by goal. Ask which items to accept: all of them, some of them, or none.',
+    `6. Only after the owner says yes, accept exactly what they chose: ${cli} first-read accept <map number> --all, or --items <ref>,<ref>. If they want none of it: ${cli} first-read reject <map number>. Never accept on your own. Accepted items become draft goals and tasks; nothing can be worked on until someone promotes it.`,
+    'Running the read-through again later is safe: anything already accepted is not filed twice.',
+  ].join('\n');
+}
+
+// ── validation ───────────────────────────────────────────────────────────────
+
+function str(v) { return typeof v === 'string' ? v.trim() : ''; }
+
+// Check a text field; push an error and return '' when it is missing or too long.
+function text(errors, where, v, max, { required = true } = {}) {
+  const s = str(v);
+  if (v != null && typeof v !== 'string') { errors.push(`${where} must be text`); return ''; }
+  if (!s) { if (required) errors.push(`${where} is missing`); return ''; }
+  if (s.length > max) { errors.push(`${where} is longer than ${max} characters — keep it short`); return ''; }
+  return s;
+}
+
+function seenAt(errors, where, v) {
+  if (!Array.isArray(v) || v.length === 0) { errors.push(`${where}.seen_at needs at least one place (a file path)`); return []; }
+  if (v.length > LIMITS.SEEN_AT) { errors.push(`${where}.seen_at lists more than ${LIMITS.SEEN_AT} places`); return []; }
+  const out = [];
+  v.forEach((p, i) => { const s = text(errors, `${where}.seen_at[${i}]`, p, LIMITS.SEEN_AT_CHARS); if (s) out.push(s); });
+  return out;
+}
+
+// validateRepoMap(raw) → { ok: true, map, items } | { ok: false, errors: [string] }
+// `map` is the normalised map (unknown top-level keys kept verbatim); `items` is the flat
+// review list: [{ ref, type: 'goal'|'task'|'next', title, why, seen_at, status?, kind?,
+// goal_ref }]. Every error names the field it is about, so a session can fix and retry.
+function validateRepoMap(raw) {
+  const errors = [];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, errors: ['the map must be a JSON object'] };
+  if (raw.schema !== SCHEMA) errors.push(`schema must be "${SCHEMA}"`);
+  // The server takes request bodies up to 64 KB; a map that size is a summary no longer.
+  if (JSON.stringify(raw).length > LIMITS.BYTES) errors.push(`the map is larger than ${LIMITS.BYTES} characters — shorten the reasons or list fewer items`);
+  const summary = text(errors, 'summary', raw.summary, LIMITS.SUMMARY);
+  const goalsIn = raw.goals == null ? [] : raw.goals;
+  const nextIn = raw.next == null ? [] : raw.next;
+  if (!Array.isArray(goalsIn)) errors.push('goals must be a list');
+  if (!Array.isArray(nextIn)) errors.push('next must be a list');
+  if (errors.length) return { ok: false, errors };
+  if (goalsIn.length > LIMITS.GOALS) errors.push(`goals lists more than ${LIMITS.GOALS}`);
+  if (nextIn.length > LIMITS.NEXT) errors.push(`next lists more than ${LIMITS.NEXT}`);
+  if (!goalsIn.length && !nextIn.length) errors.push('the map has no goals and nothing next — list at least one');
+
+  const items = [];
+  const seen = new Set();
+  const claimRef = (ref, where) => {
+    if (ref.endsWith(':') || ref.endsWith('-') || /:$|::/.test(ref)) { errors.push(`${where}.title needs letters or numbers`); return false; }
+    if (seen.has(ref)) { errors.push(`${where}.title repeats another item's title — make it distinct`); return false; }
+    seen.add(ref); return true;
+  };
+  const goals = [];
+  goalsIn.slice(0, LIMITS.GOALS).forEach((g, gi) => {
+    const w = `goals[${gi}]`;
+    if (!g || typeof g !== 'object' || Array.isArray(g)) { errors.push(`${w} must be an object`); return; }
+    const title = text(errors, `${w}.title`, g.title, LIMITS.TITLE);
+    const why = text(errors, `${w}.why`, g.why, LIMITS.WHY);
+    const where = seenAt(errors, w, g.seen_at);
+    const tasksIn = g.tasks == null ? [] : g.tasks;
+    if (!Array.isArray(tasksIn)) { errors.push(`${w}.tasks must be a list`); return; }
+    if (tasksIn.length > LIMITS.TASKS_PER_GOAL) errors.push(`${w}.tasks lists more than ${LIMITS.TASKS_PER_GOAL}`);
+    const ref = title ? goalRef(title) : null;
+    if (ref && claimRef(ref, w)) items.push({ ref, type: 'goal', title, why, seen_at: where, goal_ref: null });
+    const tasks = [];
+    tasksIn.slice(0, LIMITS.TASKS_PER_GOAL).forEach((t, ti) => {
+      const tw = `${w}.tasks[${ti}]`;
+      if (!t || typeof t !== 'object' || Array.isArray(t)) { errors.push(`${tw} must be an object`); return; }
+      const tt = text(errors, `${tw}.title`, t.title, LIMITS.TITLE);
+      const twhy = text(errors, `${tw}.why`, t.why, LIMITS.WHY);
+      const tat = seenAt(errors, tw, t.seen_at);
+      const status = t.status == null || t.status === '' ? 'not_started' : t.status;
+      if (!TASK_STATES.includes(status)) errors.push(`${tw}.status must be one of ${TASK_STATES.join(', ')}`);
+      const tref = title && tt ? taskRef(title, tt) : null;
+      if (tref && claimRef(tref, tw)) items.push({ ref: tref, type: 'task', title: tt, why: twhy, seen_at: tat, status, goal_ref: ref });
+      tasks.push({ title: tt, status, why: twhy, seen_at: tat });
+    });
+    goals.push({ title, why, seen_at: where, tasks });
+  });
+  const goalTitles = new Map(goals.map((g) => [slug(g.title), g.title]));
+  const next = [];
+  nextIn.slice(0, LIMITS.NEXT).forEach((n, ni) => {
+    const w = `next[${ni}]`;
+    if (!n || typeof n !== 'object' || Array.isArray(n)) { errors.push(`${w} must be an object`); return; }
+    const title = text(errors, `${w}.title`, n.title, LIMITS.TITLE);
+    const why = text(errors, `${w}.why`, n.why, LIMITS.WHY);
+    const where = seenAt(errors, w, n.seen_at);
+    const kind = n.kind == null || n.kind === '' ? 'error' : n.kind;
+    if (!NEXT_KINDS.includes(kind)) errors.push(`${w}.kind must be one of ${NEXT_KINDS.join(', ')}`);
+    const goal = text(errors, `${w}.goal`, n.goal, LIMITS.TITLE, { required: false });
+    if (goal && !goalTitles.has(slug(goal))) errors.push(`${w}.goal names "${goal}", which is not a goal in this map — use a goal's exact title or leave it empty`);
+    const ref = title ? nextRef(title) : null;
+    const gref = goal && goalTitles.has(slug(goal)) ? goalRef(goal) : NEXT_GOAL.ref;
+    if (ref && claimRef(ref, w)) items.push({ ref, type: 'next', title, why, seen_at: where, kind, goal_ref: gref });
+    next.push({ title, kind, goal, why, seen_at: where });
+  });
+  if (errors.length) return { ok: false, errors };
+
+  const map = { schema: SCHEMA, summary, goals, next };
+  // Forward-compatible: a later section (task 1005281's recommended_modules) rides along.
+  // Prototype-shaped keys are never copied (CWE-1321): a later section is plain data.
+  for (const [k, v] of Object.entries(raw)) if (!KNOWN_KEYS.includes(k) && !UNSAFE_KEYS.includes(k)) map[k] = v;
+  return { ok: true, map, items };
+}
+
+// ── acceptance ───────────────────────────────────────────────────────────────
+
+function describe(item, mapId) {
+  const lines = [item.why, '', `Seen at: ${item.seen_at.join(', ')}`];
+  if (item.status && item.status !== 'not_started') lines.push(`Status when read: ${item.status.replace('_', ' ')}`);
+  lines.push('', `From the first read-through of the repository (map ${mapId}, ${item.ref}). A draft: promote it when it is right.`);
+  return lines.join('\n');
+}
+
+// planAcceptance({ items, mapId, select, filedRefs }) → { goals, tasks, skipped, unknown }
+//   select    'all' | [ref] — what the owner said yes to. Nothing else is planned.
+//   filedRefs Set of refs already filed by an earlier accept (any map) — never filed again.
+// A chosen task or next item brings its goal along (a task needs a home); a goal that is
+// already filed is reused by ref. A task whose status is `done` is history, not work:
+// it is shown in review but never filed.
+function planAcceptance({ items, mapId, select, filedRefs = new Set() }) {
+  const byRef = new Map(items.map((i) => [i.ref, i]));
+  const wanted = select === 'all' ? items.map((i) => i.ref) : [...new Set(Array.isArray(select) ? select : [])];
+  const unknown = wanted.filter((r) => !byRef.has(r));
+  const goals = new Map();
+  const tasks = [];
+  const skipped = [];
+  const needGoal = (ref) => {
+    if (!ref || filedRefs.has(ref) || goals.has(ref)) return;
+    if (ref === NEXT_GOAL.ref) {
+      goals.set(ref, { ref, title: NEXT_GOAL.title, description: NEXT_GOAL.why });
+      return;
+    }
+    const g = byRef.get(ref);
+    if (g) goals.set(ref, { ref, title: g.title, description: describe(g, mapId) });
+  };
+  for (const ref of wanted) {
+    const it = byRef.get(ref);
+    if (!it) continue;
+    if (filedRefs.has(ref)) { skipped.push({ ref, reason: 'already_filed' }); continue; }
+    if (it.type === 'goal') { needGoal(ref); continue; }
+    if (it.type === 'task' && it.status === 'done') { skipped.push({ ref, reason: 'already_done' }); continue; }
+    needGoal(it.goal_ref);
+    tasks.push({
+      ref,
+      goalRef: it.goal_ref,
+      title: it.title,
+      description: describe(it, mapId),
+      kind: it.type === 'next' && it.kind !== 'gap' ? 'bug' : 'feature',
+    });
+  }
+  return { goals: [...goals.values()], tasks, skipped, unknown };
+}
+
+module.exports = {
+  SCHEMA, MAP_FILE, LIMITS, NEXT_GOAL,
+  exampleMap, firstReadPrompt, validateRepoMap, planAcceptance,
+};

package/modules/lifecycle/kickoff-checklist.js

@@ -9,7 +9,8 @@
 // filers read the same steps and the copy cannot drift. It lives with the lifecycle
 // module because tasks are its domain and the kernel doorway must not grow a domain
 // import (ADR 0091 §1); init is a core CLI and, like abandon.js or audit-deps.js,
-// may require module code directly. Pure — imports nothing.
+// may require module code directly. Pure — its one import, first-read.js (the
+// first read-through prompt, task 1005280), is pure too.
 //
 // Each step becomes a real, claimable task so it is tracked, never silently skipped
 // (grounded in the onboarding/deploy surfaces; the task 1204 mapping pass). Per-module
@@ -17,6 +18,8 @@
 
 'use strict';
 
+const { firstReadPrompt } = require('./first-read');
+
 // The one kickoff step the provisioning module AUTOMATES (ADR 0111 §3): standing up
 // production hosting/TLS/DNS/managed-DB. Kept as a named builder so init can either
 // FILE it (no provisioning requested, or the request couldn't be enqueued) or OMIT
@@ -144,7 +147,7 @@ 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',
@@ -163,14 +166,30 @@ const GENESIS_STEPS = Object.freeze({
       description: 'Genesis stage 5 (legislation). Who has a say, and the rule a decision passes by. When it is done, Ranks wake, and the project can come alive.' },
   ],
 });
+// task 1005280: the first read-through. The step's description IS the prompt the owner
+// copies into their own AI session (the hall's copy-prompt hands over a task's
+// description), so the repository is read on the owner's subscription, never the
+// platform's, and comes back as a map the owner accepts or rejects (first-read.js).
 const GENESIS_EXISTING_FIRST = {
-  title: 'Gather what already exists: link the documents, code and notes the project has',
-  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.',
+  title: 'Gather what already exists: have your own AI read the repository and map it',
+  description: 'Genesis stage 1 (scope), for a project that already exists. Before writing anything new, map what is already there, so the scope is written from it rather than beside it. ' +
+    'Copy this task\'s prompt into your own AI session, opened in the project\'s folder on your computer; it reads the code there and sends back a map for you to accept.\n\n' +
+    firstReadPrompt(),
 };
 
-// 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 +200,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;
 }