@bongos/core 1.25.16 → 1.25.18

package/modules/government/charter-advice.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// modules/government/charter-advice.js — what the genesis charter stage RECOMMENDS
+// from the founder's own answers (task 1005119, goal 1000106; owner feedback
+// 2026-11-07: "a line of questioning that makes it easier for our system to
+// recommend a form of government", and "understand the owner's principles they want
+// to use to shape their bylaws").
+//
+// ONE ANSWER FOR EVERY PRESENTATION. The onboarding module reads the founder's
+// charter answers from the genesis store and asks this, through the government
+// port, for one block: the form of government to start from and why, the
+// strictness preset their principles point at (or none), and a draft of the bylaws
+// and code of conduct. The game frame, the hall and `npx bongos genesis show
+// charter` all render this same block.
+//
+// NOTHING HERE DECIDES OR WRITES. The form comes from recommendations.js
+// recommendedCharter, the one recommender, widened by the answers; the preset from
+// presets.js recommendedPreset. Both stay recommendations: the founder picks a form
+// (or Custom) through the ordinary charter amendment, and a preset only through a
+// passed laws vote. The draft is words for the founder to edit and save as their
+// stage page; it is never saved for them.
+//
+// THE PROSE AND THE LAWS AGREE. The draft's "rules our agents follow" section is the
+// recommended preset's own laws, word for word, and says plainly when there are none,
+// so the written bylaws cannot promise one thing while the law book does another.
+
+const recommendations = require('./recommendations');
+const presets = require('./presets');
+const charter = require('./charter');
+
+const PROSE = Object.freeze(['leave_behaviour', 'feel', 'write_down']);
+const text = (v) => (typeof v === 'string' ? v.trim() : '');
+const optionOf = (list, key) => list.find((o) => o.key === key) || null;
+
+// draftBylaws({ charter, preset, prose }) → markdown, built only from what the
+// founder said and what was recommended from it.
+function draftBylaws({ charter: rec, preset, prose = {} }) {
+  const out = ['# Bylaws and code of conduct (draft)', '',
+    '_Drafted from your answers. Edit it freely; it becomes yours when you save it as this stage\'s page._', ''];
+
+  out.push('## How decisions are made', '');
+  const franchise = optionOf(charter.FRANCHISE_OPTIONS, rec.franchise);
+  const rule = optionOf(charter.PASS_RULE_OPTIONS, rec.pass_rule);
+  out.push(`This project is governed as a **${rec.name}**. ${franchise ? franchise.explanation : ''} ${rule ? `How a decision passes: ${rule.name}. ${rule.explanation}` : ''}`.replace(/\s+/g, ' ').trim(), '');
+
+  out.push('## Rules our AI agents follow', '');
+  if (preset) {
+    out.push(`These are the **${preset.name}** laws. Once the board passes them, every AI agent on the project obeys them, and a law that locks a setting is enforced on everyone's own settings. If a different preset is switched on, its laws replace this list.`, '');
+    for (const l of preset.laws) out.push(`- **${l.text}.** ${l.effect_on_ai}`);
+    out.push('');
+  } else {
+    out.push('No laws are switched on. The principles below guide people, and nothing enforces them on an agent.', '');
+  }
+
+  const feel = text(prose.feel);
+  const leave = text(prose.leave_behaviour);
+  if (feel || leave) {
+    out.push('## Code of conduct', '');
+    if (feel) out.push(`**What working here should feel like.** ${feel}`, '');
+    if (leave) out.push(`**What gets someone asked to leave.** ${leave}`, '');
+  }
+  const down = text(prose.write_down);
+  if (down) out.push('## Written down now, so it is not argued about later', '', down, '');
+  return out.join('\n').trimEnd() + '\n';
+}
+
+// buildAdvice({ answers, prose, headcount, type, laws }) — PURE. `answers` holds only
+// the closed answers the founder actually gave (not "not sure yet", not skipped);
+// `laws` is db.listLaws() rows, so the preset view says which is in force now.
+function buildAdvice({ answers = {}, prose = {}, headcount = 0, type = null, laws = [] } = {}) {
+  const rec = recommendedCharter(headcount, type, answers);
+  const preset = presets.recommendedPreset(answers);
+  const view = presets.presetsView(laws);
+  return {
+    charter: rec,
+    // null when the founder's principles do not point at one — no preset is fine
+    preset: preset ? { ...preset, locks: (view.presets.find((p) => p.key === preset.key) || {}).locks || [] } : null,
+    preset_in_force: view.current,
+    preset_is: presets.PRESET_IS,
+    draft_md: draftBylaws({ charter: rec, preset, prose }),
+    headcount,
+  };
+}
+
+function recommendedCharter(headcount, type, answers) {
+  return recommendations.recommendedCharter(headcount, type, answers);
+}
+
+// charterAdvice — THE PORT'S ENTRY (government port `charterAdvice`). The head
+// count is the founder's own expected number when they gave one at decide,
+// otherwise the live count of active builders.
+async function charterAdvice({ answers, prose, headcount = null, type = null } = {}, deps = {}) {
+  const db = deps.db || require('./db');
+  const [count, laws] = await Promise.all([
+    headcount != null && Number(headcount) > 0 ? Number(headcount) : db.countActiveBuilders(),
+    db.listLaws(),
+  ]);
+  const p = {};
+  for (const k of PROSE) if (prose && text(prose[k])) p[k] = text(prose[k]);
+  return buildAdvice({ answers, prose: p, headcount: count, type, laws });
+}
+
+module.exports = { buildAdvice, charterAdvice };

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/government/presets.js

@@ -141,8 +141,50 @@ function presetsView(rows) {
   };
 }
 
+// ── which preset the founder's principles point at (task 1005119) ───────────
+// The genesis charter stage asks two closed principle questions (keys held equal
+// to modules/onboarding/genesis-work.js QUESTIONS.charter by test). How much people
+// are trusted picks the preset; "catch it early" or "move fast" moves it one step
+// stricter or looser. No answer to either: no recommendation, and that is fine — a
+// project may run on written principles and no laws at all.
+const PRINCIPLE_ANSWERS = Object.freeze({
+  trust_level: Object.freeze(['a_lot', 'some', 'little']),
+  catch_or_fix: Object.freeze(['catch_early', 'move_fast']),
+});
+const TRUST_PRESET = { a_lot: 'open', some: 'guild', little: 'factory' };
+const TRUST_SAID = { a_lot: 'people should be trusted a lot to get on with it', some: 'people should be trusted some, with a few rules everyone follows', little: 'people should work under tight rules, checked often' };
+
+// WHAT A PRESET IS, said every time one is recommended: it is not a style guide.
+const PRESET_IS = "A preset is not a style guide. Switching one on is a vote that passes real laws: every AI agent on the project obeys them, and a law that locks a setting is enforced on every builder's own settings.";
+
+// recommendedPreset(answers) → null, or { key, name, line, why, laws, is }.
+function recommendedPreset(answers) {
+  const a = answers && typeof answers === 'object' ? answers : {};
+  const trust = PRINCIPLE_ANSWERS.trust_level.includes(a.trust_level) ? a.trust_level : null;
+  const pace = PRINCIPLE_ANSWERS.catch_or_fix.includes(a.catch_or_fix) ? a.catch_or_fix : null;
+  if (!trust && !pace) return null;
+  const order = KEYS; // open → guild → factory, loosest first
+  let i = trust ? order.indexOf(TRUST_PRESET[trust]) : 1;
+  const why = [];
+  if (trust) why.push(`You said ${TRUST_SAID[trust]}`);
+  if (pace === 'catch_early' && i < order.length - 1) { i += 1; why.push('You would rather catch problems early, so it is one step stricter' + (trust ? '' : ' than the standard set')); }
+  else if (pace === 'move_fast' && i > 0) { i -= 1; why.push('You would rather move fast and fix things, so it is one step looser' + (trust ? '' : ' than the standard set')); }
+  const p = presetOf(order[i]);
+  return {
+    key: p.key,
+    name: p.name,
+    line: p.line,
+    why: why.map((w) => `${w}.`).join(' '),
+    laws: p.laws.map((l) => ({ text: l.text, effect_on_ai: l.effect_on_ai, locks: l.locks.map((x) => ({ ...x })) })),
+    is: PRESET_IS,
+  };
+}
+
 module.exports = {
   PRESETS,
+  PRINCIPLE_ANSWERS,
+  PRESET_IS,
+  recommendedPreset,
   currentPreset,
   switchProposal,
   presetsView,

package/modules/government/recommendations.js

@@ -156,22 +156,116 @@ const TYPE_OVERRIDES = freeze({
 
 const formByKey = (key) => charter.FORMS.find((f) => f.key === key) || null;
 
-function recommendedCharter(headcount, type) {
+// ── what the founder said about how decisions should go (task 1005119) ────
+// The genesis charter stage asks the founder a short line of questions, and the
+// answers WIDEN this ladder rather than replace it: there is one recommender, so it
+// can never disagree with itself. The keys are the closed choices of
+// modules/onboarding/genesis-work.js QUESTIONS.charter (held equal by
+// tests/government_recommendations.mjs; a module may not import a sibling, ADR
+// 0083). An answer that is missing, "not sure yet" or unknown is simply not here,
+// and with none at all the ladder answers exactly as it always has.
+const CHARTER_ANSWERS = freeze({
+  final_say: freeze(['founder', 'trusted', 'everyone', 'council']),
+  agreement: freeze(['first_ratifier', 'consent', 'majority', 'unanimous']),
+  strangers: freeze(['yes', 'no']),
+  answers_to: freeze(['yes', 'no']),
+  step_back: freeze(['yes', 'no']),
+  speed: freeze(['fast', 'bought_in']),
+});
+
+// Each franchise makes exactly one available form (charter.js FORMS).
+const FORM_OF_FRANCHISE = freeze({ founder: 'monarchy', trusted: 'timocratic-republic', everyone: 'direct-democracy', council: 'foundation' });
+
+// The founder's own answer, said back to them.
+const SAID = freeze({
+  final_say: freeze({ founder: 'you should have the final say', trusted: 'the people who have earned trust by shipping should have the final say',
+    everyone: 'everyone on the project should have the final say', council: 'a small group you appoint should have the final say' }),
+  agreement: freeze({ first_ratifier: 'one yes should be enough', consent: 'a decision should pass unless someone objects',
+    majority: 'more than half should have to say yes', unanimous: 'everyone who votes should have to agree' }),
+});
+
+function cleanAnswers(answers) {
+  const out = {};
+  if (!answers || typeof answers !== 'object') return out;
+  for (const [k, allowed] of Object.entries(CHARTER_ANSWERS)) {
+    if (allowed.includes(answers[k])) out[k] = answers[k];
+  }
+  return out;
+}
+
+const sentence = (t) => `${t[0].toUpperCase()}${t.slice(1)}.`;
+
+// recommendedCharter(headcount, type, answers?) — the form to start from, and WHY.
+// Without answers: the size ladder, unchanged. With them: the franchise follows
+// who the founder said should have the final say (or what their other answers
+// imply), the pass rule follows how much agreement they asked for, and `why` is
+// written from their answers. Always an adoptable form; the founder still picks.
+function recommendedCharter(headcount, type, answers) {
   const t = normalizeType(type);
   const size = sizeBandFor(headcount);
   const row = (TYPE_OVERRIDES[t] && TYPE_OVERRIDES[t][size.key]) || CHARTER_LADDER[size.key];
-  const form = formByKey(row.form);
-  const later = row.later ? formByKey(row.later) : null;
-  const councilRank = row.form === 'foundation' ? JOB_NAMES[t].council.key : null;
+  const a = cleanAnswers(answers);
+  const ladderForm = formByKey(row.form);
+
+  const reasons = [];
+  let franchise = ladderForm.franchise;
+  let franchiseFromAnswers = true;
+  if (a.final_say) {
+    franchise = a.final_say;
+    reasons.push(`You said ${SAID.final_say[a.final_say]}`);
+  } else if (a.answers_to === 'yes') {
+    franchise = 'council';
+    reasons.push('You said the project answers to something outside it, so a council you appoint holds it to that');
+  } else if (a.step_back === 'yes' && franchise === 'founder') {
+    franchise = 'trusted';
+    reasons.push('You want to be able to step back later, so the say goes to builders who earn trust by shipping, and it carries on without you');
+  } else if (a.strangers === 'yes' && franchise === 'everyone') {
+    franchise = 'trusted';
+    reasons.push('You expect people you have not met, so a say is earned by shipping first rather than given on arrival');
+  } else {
+    franchiseFromAnswers = false;
+  }
+  const form = formByKey(FORM_OF_FRANCHISE[franchise]);
+
+  let passRule = form.pass_rule;
+  if (franchise === 'founder') {
+    if (a.agreement && a.agreement !== 'first_ratifier') {
+      reasons.push('With you as the only voter, your one yes is the whole vote, so the pass rule makes no difference yet');
+    }
+  } else if (a.agreement) {
+    passRule = a.agreement;
+    reasons.push(`You said ${SAID.agreement[a.agreement]}`);
+  } else if (a.speed === 'fast') {
+    reasons.push('You would rather decide fast, and "passes unless someone objects" needs no vote count, only no objection');
+  } else if (a.speed === 'bought_in') {
+    reasons.push('You would rather have everyone bought in, and "passes unless someone objects" lets anyone stop a decision they cannot live with');
+  }
+  const tuned = passRule !== form.pass_rule;
+  if (tuned) {
+    const rule = charter.PASS_RULE_OPTIONS.find((r) => r.key === passRule);
+    reasons.push(`So it is ${form.name} with its pass rule set to "${rule.name}", which you set in the legislation stage`);
+  }
+
+  const fromAnswers = reasons.length > 0;
+  let why = row.why;
+  if (fromAnswers) {
+    why = reasons.map(sentence).join(' ');
+    if (!franchiseFromAnswers) why += ` Who votes follows your size: ${row.why}.`;
+  }
+  const later = row.later && form.key === row.form ? formByKey(row.later) : null;
   return freeze({
-    key: row.form,
+    key: form.key,
     name: form.name,
     rung: row.rung,
-    why: row.why,
+    why,
     type: t,
     size: size.key,
-    council_rank: councilRank,
+    council_rank: form.key === 'foundation' ? JOB_NAMES[t].council.key : null,
     later: later ? freeze({ key: later.key, name: later.name, explanation: later.explanation }) : null,
+    franchise,
+    pass_rule: passRule,
+    pass_rule_tuned: tuned,
+    from_answers: fromAnswers,
   });
 }
 
@@ -222,6 +316,7 @@ function recommendationsFor({ type, headcount } = {}) {
 
 module.exports = {
   PROJECT_TYPES,
+  CHARTER_ANSWERS,
   JOB_GRANTS,
   JOB_CAN,
   sizeBandFor,

package/modules/government/routes/government.js

@@ -138,6 +138,7 @@ const governmentPort = {
   // home, which renders the stages from GET /government/constitution's
   // `charter` block. Opening a sitting decides nothing; the vote does.
   proposeCharter: board.proposeCharter,
+  charterAdvice: (input) => require('../charter-advice').charterAdvice(input), // task 1005119: advice only, never a write
   genesisStageStatus: board.genesisStageStatus,
   // task 1004529 — who decides what. The table, resolved, and the check a
   // building's own direct route runs before letting one builder act alone.

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

@@ -0,0 +1,62 @@
+// modules/lifecycle/first-read-catalog.js — the module list the first read-through may
+// recommend from (task 1005281, goal 1000106): the modules THIS project can switch on
+// and has not, read live on every call.
+//
+// WHY LIVE, AND WHY ONLY THIS. A recommendation names a module the owner can actually
+// switch on, so the list is the project's own (the kernel's `modules.catalog` port, the
+// same listing the Modules page shows), minus what is already on. Where the hub's
+// project-creation picker is mounted (`provisioning.moduleCatalog`), its plain words
+// replace a module's own description; the keys still come from this project. The owner's
+// AI session gets the list in its prompt and the server checks every recommended key
+// against it on submit, so a recommendation can never name a module that is not there.
+// Nothing here reads a repository or calls an AI.
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+const SUMMARY_MAX = 200;
+
+// First sentence, capped: a manifest description is written for engineers and long.
+function shortWords(text) {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  const first = (s.match(/^.*?[.!?](\s|$)/) || [s])[0].trim();
+  return first.length > SUMMARY_MAX ? first.slice(0, SUMMARY_MAX - 1).trimEnd() + '…' : first;
+}
+
+// buildCatalog(listed, picker) → [{ key, title, summary }] sorted by key. Pure.
+//   listed  the `modules.catalog` port's answer: [{ key, title, description, enabled }]
+//   picker  optional `provisioning.moduleCatalog` answer: { optional: [{ key, label, summary }] }
+function buildCatalog(listed, picker) {
+  const words = new Map(((picker && picker.optional) || []).filter((m) => m && m.key).map((m) => [m.key, m]));
+  return (Array.isArray(listed) ? listed : [])
+    .filter((m) => m && typeof m.key === 'string' && m.key && m.enabled !== true)
+    .map((m) => {
+      const w = words.get(m.key);
+      return {
+        key: m.key,
+        title: String((w && w.label) || m.title || m.key),
+        summary: shortWords((w && w.summary) || m.description),
+      };
+    })
+    .sort((a, b) => a.key.localeCompare(b.key));
+}
+
+// switchOnCatalog() → [{ key, title, summary }] | null. null means the list could not be
+// read here; the submit then refuses any recommendation rather than trusting one.
+async function switchOnCatalog() {
+  const listed = api.resolveOptional('modules.catalog');
+  if (typeof listed !== 'function') return null;
+  try {
+    const picker = api.resolveOptional('provisioning.moduleCatalog');
+    let pickerAnswer = null;
+    if (typeof picker === 'function') {
+      try { pickerAnswer = await picker(); } catch { pickerAnswer = null; }
+    }
+    return buildCatalog(await listed(), pickerAnswer);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { buildCatalog, switchOnCatalog };

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

@@ -0,0 +1,190 @@
+// 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, catalog }) → { ok: true, map_id, items } | { ok: false, errors }
+// Validates, then stores the NORMALISED map (unknown sections kept). Files nothing.
+// `catalog` is the live module list (first-read-catalog.js; null when unreadable): every
+// recommended module must be on it, and its words are the catalog's, not the session's.
+async function submitMap({ raw, builderId = null, catalog = null }, deps = {}) {
+  const v = fr.validateRepoMap(raw, { catalog });
+  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: r.entity_id == null ? null : 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', 'recommended_modules'].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 known = await filedRefs(goalRefs, client);
+    // A dismissed item is not filed: 'all' passes it by, naming it files it (planAcceptance).
+    const already = new Map([...known].filter(([, f]) => f.kind !== 'dismissed'));
+    const dismissed = new Set([...known].filter(([, f]) => f.kind === 'dismissed').map(([ref]) => ref));
+    const plan = fr.planAcceptance({ items: v.items, mapId: String(row.id), select, filedRefs: new Set(already.keys()), dismissedRefs: dismissed });
+    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)
+         ON CONFLICT (ref) DO UPDATE SET kind = EXCLUDED.kind, entity_id = EXCLUDED.entity_id,
+           map_id = EXCLUDED.map_id, filed_by = EXCLUDED.filed_by, filed_at = now()
+         WHERE lifecycle_repo_map_filed.kind = 'dismissed'`,
+        [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 };
+}
+
+// dismissItems({ mapId, refs, builderId }) → { ok, dismissed, skipped } | { ok: false, code, status, ... }
+// The owner's no to named items (a module recommendation, usually). Files nothing; it
+// records the no, so a later "accept all" passes the item by. An item already filed is
+// left as it is (skipped), and a ref the map does not hold is refused.
+async function dismissItems({ mapId, refs, builderId = null }, deps = {}) {
+  if (!Array.isArray(refs) || !refs.length) return { ok: false, code: 'nothing_selected', status: 400 };
+  const pool = poolOf(deps);
+  const { rows: [row] } = await pool.query('SELECT id, status, map FROM lifecycle_repo_maps WHERE id = $1', [mapId]);
+  if (!row) return { ok: false, code: 'not_found', status: 404 };
+  if (row.status === 'rejected') return { ok: false, code: 'map_rejected', status: 409 };
+  const v = fr.validateRepoMap(row.map);
+  if (!v.ok) return { ok: false, code: 'invalid_map', status: 409, errors: v.errors };
+  const held = new Set(v.items.map((i) => i.ref));
+  const wanted = [...new Set(refs)];
+  const unknown = wanted.filter((r) => !held.has(r));
+  if (unknown.length) return { ok: false, code: 'unknown_items', status: 400, unknown };
+  const known = await filedRefs(wanted, pool);
+  const skipped = wanted.filter((r) => known.has(r) && known.get(r).kind !== 'dismissed').map((ref) => ({ ref, reason: 'already_filed' }));
+  const fresh = wanted.filter((r) => !known.has(r));
+  if (fresh.length) {
+    await pool.query(
+      `INSERT INTO lifecycle_repo_map_filed (ref, kind, entity_id, map_id, filed_by)
+       SELECT r, 'dismissed', NULL, $2, $3 FROM unnest($1::text[]) AS u(r)
+       ON CONFLICT (ref) DO NOTHING`,
+      [fresh, row.id, builderId],
+    );
+  }
+  return { ok: true, map_id: String(row.id), dismissed: wanted.filter((r) => !skipped.some((x) => x.ref === r)), skipped };
+}
+
+module.exports = { TASK_SOURCE, submitMap, reviewMap, acceptMap, rejectMap, dismissItems };