@bongos/core 1.25.16 → 1.25.17

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
@@ -163,9 +166,15 @@ 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(),
 };
 
 // GENESIS_AFTER — "this step follows that one", by ref (task 1005110). A step listed

package/modules/lifecycle/migrations/lifecycle_022_repo_maps.sql

@@ -0,0 +1,44 @@
+-- lifecycle_022_repo_maps.sql — the first read-through's repository maps (task 1005280,
+-- goal 1000106).
+--
+-- WHAT IT IS. A project that arrives with code gets a prompt for the owner's OWN AI
+-- session; that session reads the repository on the owner's computer and subscription
+-- and sends back a map (modules/lifecycle/first-read.js). A map waits here as `pending`
+-- until the owner accepts it — whole or item by item — or rejects it. Nothing is filed
+-- by the submit itself.
+--
+-- WHY A SECOND TABLE. Re-running the read-through must not file the same goal or task
+-- twice, and goals carry no source_ref to dedup on. So every accepted item's stable
+-- `ref` (derived from its title, never its position) is a row in
+-- lifecycle_repo_map_filed, PRIMARY KEY on the ref: the next accept skips it, whichever
+-- map names it again.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed (ADR 0083 §Decision #5).
+
+CREATE TABLE IF NOT EXISTS lifecycle_repo_maps (
+  id            bigserial PRIMARY KEY,
+  schema        text NOT NULL,
+  map           jsonb NOT NULL,
+  status        text NOT NULL DEFAULT 'pending',
+  submitted_by  bigint REFERENCES builders(id),
+  submitted_at  timestamptz NOT NULL DEFAULT now(),
+  reviewed_by   bigint REFERENCES builders(id),
+  reviewed_at   timestamptz,
+
+  CONSTRAINT lifecycle_repo_maps_status_chk
+    CHECK (status IN ('pending', 'accepted', 'rejected'))
+);
+
+CREATE INDEX IF NOT EXISTS lifecycle_repo_maps_newest_idx
+  ON lifecycle_repo_maps (submitted_at DESC);
+
+CREATE TABLE IF NOT EXISTS lifecycle_repo_map_filed (
+  ref        text PRIMARY KEY,
+  kind       text NOT NULL,
+  entity_id  bigint NOT NULL,
+  map_id     bigint NOT NULL REFERENCES lifecycle_repo_maps(id),
+  filed_by   bigint REFERENCES builders(id),
+  filed_at   timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT lifecycle_repo_map_filed_kind_chk CHECK (kind IN ('goal', 'task'))
+);

package/modules/lifecycle/module.json

@@ -38,7 +38,8 @@
       "home-city",
       "home-gallery",
       "task-votes",
-      "notes"
+      "notes",
+      "first-read"
     ],
     "pollers": [
       "publish-reconciler"

package/modules/lifecycle/routes/first-read.js

@@ -0,0 +1,79 @@
+// modules/lifecycle/routes/first-read.js — the HTTP surface of the first read-through
+// (task 1005280, goal 1000106): hand out the prompt, take a repository map from the
+// owner's own AI session, show it for review, and accept or reject it.
+//
+// No route here calls an AI, reads a repository, or files anything on submit. Filing is
+// the accept route alone, gated like creating a goal (`goal.create` + the planning
+// act-alone rule), because accepting a map IS creating goals and tasks. The rules are
+// first-read.js; the store is first-read-db.js. Reaches core only through the doorway.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const fr = require('../first-read');
+const store = require('../first-read-db');
+
+const { asyncHandler, parseId, validateOrRespond } = api;
+
+module.exports = function buildFirstReadRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — the prompt and the shape are instructions, not project data.
+  router.get('/first-read/prompt', api.requireBuilder, (req, res) => {
+    res.json({ schema: fr.SCHEMA, file: fr.MAP_FILE, prompt: fr.firstReadPrompt(), example: fr.exampleMap(), limits: fr.LIMITS });
+  });
+
+  // rank: goal.create — a map is a planning proposal for this project. Stores it
+  // pending; files nothing. A malformed map is refused with every error named.
+  router.post('/first-read/maps', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('POST /first-read/maps', async (req, res) => {
+    // The envelope is checked here; the map inside it by first-read.js, which names every error.
+    if (validateOrRespond(req, res, { map: { required: true, type: 'object' } })) return undefined;
+    const out = await store.submitMap({ raw: req.body.map, builderId: req.builder.id });
+    if (!out.ok) return res.fail('invalid_map', 400, { errors: out.errors });
+    return res.status(201).json({
+      map_id: out.map_id, status: out.status,
+      items: out.items.map((i) => ({ ref: i.ref, type: i.type, title: i.title })),
+      next: 'Show the owner the map. File it only with their yes: POST /first-read/maps/' + out.map_id + '/accept { all: true } or { items: [ref] }.',
+    });
+  }, { errorCode: 'first_read_submit_failed' }));
+
+  // rank: goal.create — the review is for whoever may accept or reject it.
+  router.get('/first-read/maps/:id', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('GET /first-read/maps/:id', async (req, res) => {
+    const id = req.params.id === 'latest' ? 'latest' : parseId(req, res, { positiveInt: true });
+    if (id == null) return undefined;
+    const review = await store.reviewMap(id);
+    if (!review) return res.fail('not_found', 404);
+    return res.json(review);
+  }, { errorCode: 'first_read_review_failed' }));
+
+  // rank: goal.create + act-alone planning — the owner's yes. Files the chosen items as
+  // draft goals (open) and tasks (backlog); an item already filed is skipped.
+  router.post('/first-read/maps/:id/accept', api.requireBuilder, api.requirePermission('goal.create'), api.requireActAlone('planning'),
+    asyncHandler('POST /first-read/maps/:id/accept', async (req, res) => {
+      const mapId = parseId(req, res, { positiveInt: true });
+      if (mapId == null) return undefined;
+      if (validateOrRespond(req, res, {
+        all: { type: 'boolean' },
+        items: { type: 'array', itemsType: 'string', maxItems: 500 },
+      })) return undefined;
+      const { all, items } = req.body || {};
+      if ((all === true) === Array.isArray(items)) {
+        return res.fail('invalid_items', 400, { hint: 'send { all: true } or { items: [ref, …] } — the refs from the review' });
+      }
+      const out = await store.acceptMap({ mapId, select: all === true ? 'all' : items, builderId: req.builder.id });
+      if (!out.ok) { const { code, status, ...rest } = out; return res.fail(code, status, rest); }
+      return res.json(out);
+    }, { errorCode: 'first_read_accept_failed' }));
+
+  // rank: goal.create — the owner's no. Files nothing.
+  router.post('/first-read/maps/:id/reject', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('POST /first-read/maps/:id/reject', async (req, res) => {
+    const mapId = parseId(req, res, { positiveInt: true });
+    if (mapId == null) return undefined;
+    const out = await store.rejectMap({ mapId, builderId: req.builder.id });
+    if (!out.ok) { const { code, status, ...rest } = out; return res.fail(code, status, rest); }
+    return res.json(out);
+  }, { errorCode: 'first_read_reject_failed' }));
+
+  return router;
+};

package/modules/provisioning/pollers/app-liveness.js

@@ -86,7 +86,29 @@ async function sweepOnce(deps = {}) {
       [r.id, h.state]);
     if (rowCount) { live++; log(`[app-liveness] ${r.slug}: its app answers at ${h.serviceUrl} — live`); }
   }
-  return { checked: rows.length, live };
+  // The project's SANDBOX (ADR 0406, task 1005289) gets the same knock until its first
+  // answer, then never again: it sleeps on the free plan, and a knock would wake it.
+  const { rows: sbs } = await db.query(
+    `SELECT id, slug, app_host->'sandbox' AS sb FROM provisioning_instances
+      WHERE app_host->>'platform' = 'render' AND app_host->'sandbox'->>'state' = 'deploying'
+        AND status <> 'torn_down'
+      ORDER BY id LIMIT ${SWEEP_LIMIT}`);
+  // the same few-at-a-time knocking as the apps above, so one slow sandbox holds none up
+  const sbAnswers = [];
+  for (let i = 0; i < sbs.length; i += CONCURRENCY) {
+    const batch = sbs.slice(i, i + CONCURRENCY);
+    sbAnswers.push(...(await Promise.all(batch.map((r) => appAnswers((r.sb || {}).serviceUrl, { fetchImpl: deps.fetchImpl, timeoutMs: deps.timeoutMs })))));
+  }
+  for (const [i, r] of sbs.entries()) {
+    const sb = r.sb || {};
+    if (!sbAnswers[i]) continue;
+    const { rowCount } = await db.query(
+      `UPDATE provisioning_instances
+          SET app_host = jsonb_set(app_host, '{sandbox}', (app_host->'sandbox') || jsonb_build_object('state', 'live', 'liveAt', now()::text))
+        WHERE id = $1 AND app_host->'sandbox'->>'state' = 'deploying'`, [r.id]);
+    if (rowCount) { live++; log(`[app-liveness] ${r.slug}: its sandbox answers at ${sb.serviceUrl} — live`); }
+  }
+  return { checked: rows.length + sbs.length, live };
 }
 
 function start(deps = {}) {