@bongos/core 1.25.16 → 1.25.18

package/modules/lifecycle/first-read.js

@@ -0,0 +1,330 @@
+// 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, so a later section needs
+// no change to this version's shape. `recommended_modules` (task 1005281) is the first:
+// modules from THIS project's live list that would do a job better than what the code
+// has (first-read-catalog.js supplies the list; a key not on it is refused on submit).
+// A recommendation is a suggestion: accepting files a draft task to switch it on, and
+// dismissing records the no, so a re-run does not raise it again.
+//
+// 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,
+  MODULES: 10,
+  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', 'recommended_modules'];
+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.',
+});
+
+// The goal an accepted module recommendation lands under.
+const MODULES_GOAL = Object.freeze({
+  ref: 'goal:modules-the-first-read-recommends',
+  title: 'Modules the first read-through recommends',
+  why: 'Modules from this project\'s own list that the first read-through of the repository found would do a job better than what the code has now.',
+});
+
+// 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)}`;
+const moduleRef = (key) => `module:${key}`;
+
+// ── 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'] },
+    ],
+  };
+}
+
+// The recommended_modules entry shape, shown in the prompt beside the example map.
+const MODULE_EXAMPLE = { module: '<a key from the module list>', found: 'What in the code is weak, in one or two sentences.', why: 'Why this module does that job better.', seen_at: ['src/billing/'] };
+
+// catalogText(catalog) → the module list as prompt lines, or a line saying there is none.
+function catalogText(catalog) {
+  if (!Array.isArray(catalog)) return '   (The module list could not be read. Leave "recommended_modules" out.)';
+  if (!catalog.length) return '   (This project has no modules left to switch on. Leave "recommended_modules" out.)';
+  return catalog.map((m) => `   - ${m.key}: ${m.title}. ${m.summary}`.trimEnd()).join('\n');
+}
+
+// firstReadPrompt({ cli, catalog }) → the full text the owner hands their own AI session.
+// Without a catalog it is the Genesis step's description (fixed text, so the hall's
+// copy-prompt carries all of it) and tells the session to fetch the live module list;
+// with one (`bongos first-read prompt`) the list is printed in.
+function firstReadPrompt({ cli = 'npx bongos', catalog } = {}) {
+  const modules = catalog === undefined
+    ? [`   Get the modules this project can switch on: ${cli} first-read catalog`]
+    : ['   The modules this project can switch on (key: name. what it does):', catalogText(catalog)];
+  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'),
+    '   - Optional "recommended_modules": compare what the code does with the modules below. Where a module would clearly do a job better than what is there (a billing system that keeps failing, say), add one entry: "module" (its key, exactly as listed), "found" (what in the code is weak), "why" (why the module is better) and "seen_at". Recommend only from the list, at most ' + LIMITS.MODULES + '. When nothing on it beats what the code already has, leave the section out: no recommendation is a good answer.',
+    '     Entry shape: ' + JSON.stringify(MODULE_EXAMPLE),
+    ...modules,
+    `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, then any recommended modules. Ask which items to accept: all of them, some of them, or none. Recommendations are suggestions; anything they say no to can be dismissed.',
+    `6. Only after the owner says yes, accept exactly what they chose: ${cli} first-read accept <map number> --all, or --items <ref>,<ref>. Items they turn down: ${cli} first-read dismiss <map number> --items <ref>,<ref> (a later read-through will not raise them again). If they want none of it: ${cli} first-read reject <map number>. Never accept or dismiss on your own. Accepted items become draft goals and tasks; nothing can be worked on until someone promotes it, and an accepted module is a to-do to switch it on, never switched on by itself.`,
+    '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, { catalog }) → { ok: true, map, items } | { ok: false, errors }
+// `map` is the normalised map (unknown top-level keys kept verbatim); `items` is the flat
+// review list: [{ ref, type: 'goal'|'task'|'next'|'module', title, why, seen_at, status?,
+// kind?, found?, module?, goal_ref }]. Every error names the field it is about, so a
+// session can fix and retry. `catalog` ([{ key, title }], or null when unreadable) is
+// given on SUBMIT: every recommended key must be on it, and the title is the catalog's.
+// It is left out when re-reading a stored map, which was checked when it came in.
+function validateRepoMap(raw, { catalog } = {}) {
+  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;
+  const modsIn = raw.recommended_modules == null ? [] : raw.recommended_modules;
+  if (!Array.isArray(goalsIn)) errors.push('goals must be a list');
+  if (!Array.isArray(nextIn)) errors.push('next must be a list');
+  if (!Array.isArray(modsIn)) errors.push('recommended_modules 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 (modsIn.length > LIMITS.MODULES) errors.push(`recommended_modules lists more than ${LIMITS.MODULES}`);
+  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 });
+  });
+  const known = Array.isArray(catalog) ? new Map(catalog.map((m) => [m.key, m])) : null;
+  const recommended = [];
+  modsIn.slice(0, LIMITS.MODULES).forEach((m, mi) => {
+    const w = `recommended_modules[${mi}]`;
+    if (!m || typeof m !== 'object' || Array.isArray(m)) { errors.push(`${w} must be an object`); return; }
+    const key = text(errors, `${w}.module`, m.module, LIMITS.TITLE);
+    const found = text(errors, `${w}.found`, m.found, LIMITS.WHY);
+    const why = text(errors, `${w}.why`, m.why, LIMITS.WHY);
+    const where = seenAt(errors, w, m.seen_at);
+    if (!key) return;
+    if (catalog !== undefined && !(known && known.has(key))) {
+      errors.push(known
+        ? `${w}.module "${key}" is not a module this project can switch on — use a key from the module list (first-read catalog)`
+        : `${w}.module: the module list could not be read here, so no module can be recommended — leave recommended_modules out`);
+      return;
+    }
+    const title = known ? known.get(key).title : (text([], '', m.title, LIMITS.TITLE) || key);
+    const ref = moduleRef(key);
+    if (seen.has(ref)) { errors.push(`${w}.module repeats a module already recommended`); return; }
+    seen.add(ref);
+    items.push({ ref, type: 'module', module: key, title, found, why, seen_at: where, goal_ref: MODULES_GOAL.ref });
+    recommended.push({ module: key, title, found, why, seen_at: where });
+  });
+  if (errors.length) return { ok: false, errors };
+
+  const map = { schema: SCHEMA, summary, goals, next };
+  if (recommended.length) map.recommended_modules = recommended;
+  // 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.type === 'module'
+    ? [`Found: ${item.found}`, '', `Why the ${item.title} module: ${item.why}`, '', `Seen at: ${item.seen_at.join(', ')}`,
+      'Switching it on is done on the Modules page by whoever may turn modules on; this task is the reminder.']
+    : [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, dismissedRefs }) → { 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.
+//   dismissedRefs Set of refs the owner said no to before — 'all' skips them; naming one
+//                 explicitly files it (the owner changed their mind).
+// 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(), dismissedRefs = 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;
+    const fixed = ref === NEXT_GOAL.ref ? NEXT_GOAL : ref === MODULES_GOAL.ref ? MODULES_GOAL : null;
+    if (fixed) { goals.set(ref, { ref, title: fixed.title, description: fixed.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 (select === 'all' && dismissedRefs.has(ref)) { skipped.push({ ref, reason: 'dismissed' }); 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.type === 'module' ? `Switch on the ${it.title} module` : 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, MODULES_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/migrations/lifecycle_023_repo_map_dismissed.sql

@@ -0,0 +1,19 @@
+-- lifecycle_023_repo_map_dismissed.sql — the owner's "no" to an item of a repository
+-- map is remembered too (task 1005281, goal 1000106).
+--
+-- A module recommendation is a suggestion the owner accepts OR dismisses. A dismissed
+-- item is a row in lifecycle_repo_map_filed with kind 'dismissed' and no entity, so a
+-- later read-through's "accept all" does not raise it again. Naming it explicitly later
+-- still files it: the accept upserts over a 'dismissed' row only, never over a filed one.
+-- Works for every item type, not only modules.
+
+ALTER TABLE lifecycle_repo_map_filed ALTER COLUMN entity_id DROP NOT NULL;
+
+ALTER TABLE lifecycle_repo_map_filed DROP CONSTRAINT IF EXISTS lifecycle_repo_map_filed_kind_chk;
+ALTER TABLE lifecycle_repo_map_filed ADD CONSTRAINT lifecycle_repo_map_filed_kind_chk
+  CHECK (kind IN ('goal', 'task', 'dismissed'));
+
+-- A filed item points at what it became; a dismissed one points at nothing.
+ALTER TABLE lifecycle_repo_map_filed DROP CONSTRAINT IF EXISTS lifecycle_repo_map_filed_entity_chk;
+ALTER TABLE lifecycle_repo_map_filed ADD CONSTRAINT lifecycle_repo_map_filed_entity_chk
+  CHECK ((kind = 'dismissed') = (entity_id IS NULL));

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,101 @@
+// 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 modulesCatalog = require('../first-read-catalog');
+
+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. The
+  // prompt carries the live module list (task 1005281), so a session recommends from it.
+  router.get('/first-read/prompt', api.requireBuilder, asyncHandler('GET /first-read/prompt', async (req, res) => {
+    const catalog = await modulesCatalog.switchOnCatalog();
+    res.json({ schema: fr.SCHEMA, file: fr.MAP_FILE, prompt: fr.firstReadPrompt({ catalog }), example: fr.exampleMap(), limits: fr.LIMITS, catalog });
+  }, { errorCode: 'first_read_prompt_failed' }));
+
+  // rank: any-builder — the modules this project can switch on, the only ones a map may
+  // recommend. `available: false` when the list cannot be read here.
+  router.get('/first-read/catalog', api.requireBuilder, asyncHandler('GET /first-read/catalog', async (req, res) => {
+    const catalog = await modulesCatalog.switchOnCatalog();
+    res.json({ available: Array.isArray(catalog), modules: catalog || [] });
+  }, { errorCode: 'first_read_catalog_failed' }));
+
+  // 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 catalog = await modulesCatalog.switchOnCatalog();
+    const out = await store.submitMap({ raw: req.body.map, builderId: req.builder.id, catalog });
+    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 to named items (a module recommendation, usually).
+  // Files nothing; a later "accept all" passes them by.
+  router.post('/first-read/maps/:id/dismiss', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('POST /first-read/maps/:id/dismiss', async (req, res) => {
+    const mapId = parseId(req, res, { positiveInt: true });
+    if (mapId == null) return undefined;
+    if (validateOrRespond(req, res, { items: { required: true, type: 'array', itemsType: 'string', maxItems: 500 } })) return undefined;
+    const out = await store.dismissItems({ mapId, refs: req.body.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_dismiss_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;
+};