@bongos/core 1.25.17 → 1.25.18

package/modules/lifecycle/first-read.js

@@ -19,8 +19,12 @@
 // 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.
+// 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
@@ -41,12 +45,13 @@ const LIMITS = Object.freeze({
   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'];
+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({
@@ -55,6 +60,13 @@ const NEXT_GOAL = Object.freeze({
   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, '')
@@ -65,6 +77,7 @@ function slug(text) {
 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 ───────────────────────────────────────────────────────────────
 
@@ -88,9 +101,24 @@ function exampleMap() {
   };
 }
 
-// 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' } = {}) {
+// 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.',
     '',
@@ -101,10 +129,13 @@ function firstReadPrompt({ cli = 'npx bongos' } = {}) {
     '   - 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. 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.`,
+    '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');
 }
@@ -130,11 +161,14 @@ function seenAt(errors, where, v) {
   return out;
 }
 
-// validateRepoMap(raw) → { ok: true, map, items } | { ok: false, errors: [string] }
+// 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', 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) {
+// 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}"`);
@@ -143,11 +177,14 @@ function validateRepoMap(raw) {
   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 = [];
@@ -201,9 +238,33 @@ function validateRepoMap(raw) {
     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;
@@ -213,19 +274,24 @@ function validateRepoMap(raw) {
 // ── acceptance ───────────────────────────────────────────────────────────────
 
 function describe(item, mapId) {
-  const lines = [item.why, '', `Seen at: ${item.seen_at.join(', ')}`];
+  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 }) → { 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.
+// 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() }) {
+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));
@@ -234,10 +300,8 @@ function planAcceptance({ items, mapId, select, filedRefs = new Set() }) {
   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 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) });
   };
@@ -245,13 +309,14 @@ function planAcceptance({ items, mapId, select, filedRefs = new Set() }) {
     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.title,
+      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',
     });
@@ -260,6 +325,6 @@ function planAcceptance({ items, mapId, select, filedRefs = new Set() }) {
 }
 
 module.exports = {
-  SCHEMA, MAP_FILE, LIMITS, NEXT_GOAL,
+  SCHEMA, MAP_FILE, LIMITS, NEXT_GOAL, MODULES_GOAL,
   exampleMap, firstReadPrompt, validateRepoMap, planAcceptance,
 };

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

@@ -13,23 +13,34 @@ 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.
-  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: 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 out = await store.submitMap({ raw: req.body.map, builderId: req.builder.id });
+    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,
@@ -66,6 +77,17 @@ module.exports = function buildFirstReadRouter() {
       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 });

package/modules/onboarding/genesis-work.js

@@ -41,7 +41,8 @@
 //
 // WHICH STAGES. A stage adopts the pattern by declaring its questions in QUESTIONS.
 // Strategize does (task 1005116); scope's guided door is its project interview (task 1005114);
-// charter, legalize and legislation adopt it when they are next touched. A stage with
+// charter asks how decisions should go and the founder's principles (task 1005119);
+// legalize and legislation adopt it when they are next touched. A stage with
 // no questions still takes a free page and a link.
 //
 // THE BOUNDARY. Pure apart from the store. The store is injected (tests) or the
@@ -57,6 +58,9 @@ const STATES = Object.freeze(['answered', 'not_sure', 'skipped']);
 const ORIGINS = Object.freeze(['founder', 'assisted', 'carried_over']);
 const LIMITS = Object.freeze({ answer: 4000, page: 20000, link: 500 });
 
+// A closed question's options: [key, label] pairs, frozen.
+const choices = (pairs) => Object.freeze(pairs.map(([key, label]) => Object.freeze({ key, label })));
+
 // Each adopted stage's questions, in the order the guided door asks them. `id` is
 // stable: a stored answer names it, so never rename or reuse one. `hint` is the shape
 // of a good answer, shown under the question in every door. `group` (optional) is a
@@ -83,6 +87,47 @@ const QUESTIONS = Object.freeze({
     Object.freeze({ id: 'others_wrong', group: 'The bet', ask: 'What is everyone else in this area getting wrong?',
       hint: 'The thing you believe that others in this space do not. This is the bet the project makes.' }),
   ]),
+  // CHARTER (task 1005119): how decisions should go, then the founder's principles.
+  // A question with `choices` is a CLOSED one: an answer is one of its keys, because
+  // the government module's recommender reads it (recommendations.js CHARTER_ANSWERS
+  // and presets.js PRINCIPLE_ANSWERS hold the same keys, by test; a module may not
+  // import a sibling, ADR 0083). The prose ones shape the drafted bylaws and code of
+  // conduct in the founder's own words. Every one is skippable and "not sure yet".
+  charter: Object.freeze([
+    Object.freeze({ id: 'final_say', group: 'How decisions go', ask: 'When people disagree, who should have the final say?',
+      hint: 'Who settles it in the end. This is who gets a vote.',
+      choices: choices([['founder', 'Me, the founder'], ['trusted', 'The people who have earned trust by shipping'],
+        ['everyone', 'Everyone on the project'], ['council', 'A small group I appoint']]) }),
+    Object.freeze({ id: 'agreement', group: 'How decisions go', ask: 'How much agreement should a decision need?',
+      hint: 'Fewer means faster; more means everyone is bought in.',
+      choices: choices([['first_ratifier', 'One yes is enough'], ['consent', 'It passes unless someone objects'],
+        ['majority', 'More than half must say yes'], ['unanimous', 'Everyone who votes must agree']]) }),
+    Object.freeze({ id: 'strangers', group: 'How decisions go', ask: 'Do you expect people you have not met to show up and contribute?',
+      hint: 'Whether newcomers should get a say straight away or earn it first.',
+      choices: choices([['yes', 'Yes'], ['no', 'No, it is people I know']]) }),
+    Object.freeze({ id: 'answers_to', group: 'How decisions go', ask: 'Is there anyone outside the project it answers to: funders, a mission, a legal entity?',
+      hint: 'Something the project must stay true to, whoever is building it.',
+      choices: choices([['yes', 'Yes'], ['no', 'No']]) }),
+    Object.freeze({ id: 'step_back', group: 'How decisions go', ask: 'Do you want to be able to step back later and hand this over?',
+      hint: 'Whether the project should keep deciding well without you.',
+      choices: choices([['yes', 'Yes'], ['no', 'No, I plan to stay at the helm']]) }),
+    Object.freeze({ id: 'speed', group: 'How decisions go', ask: 'Would you rather decide fast, or have everyone bought in?',
+      hint: 'When the two pull apart, which wins.',
+      choices: choices([['fast', 'Decide fast'], ['bought_in', 'Everyone bought in']]) }),
+    Object.freeze({ id: 'trust_level', group: 'Principles', ask: 'How much should people be trusted to work without checking in first?',
+      hint: 'This shapes how strict the rules for the project\'s AI agents are.',
+      choices: choices([['a_lot', 'A lot: let them get on with it'], ['some', 'Some: a few rules everyone follows'],
+        ['little', 'Little: tight rules, checked often']]) }),
+    Object.freeze({ id: 'catch_or_fix', group: 'Principles', ask: 'When something goes wrong, would you rather have caught it early, or move fast and fix it?',
+      hint: 'Neither is wrong. It sets how much is checked before work goes ahead.',
+      choices: choices([['catch_early', 'Catch it early'], ['move_fast', 'Move fast and fix it']]) }),
+    Object.freeze({ id: 'leave_behaviour', group: 'Principles', ask: 'What behaviour would make you ask someone to leave?',
+      hint: 'The line nobody crosses. It becomes the heart of the code of conduct.' }),
+    Object.freeze({ id: 'feel', group: 'Principles', ask: 'What do you want this project to feel like to work on?',
+      hint: 'A few words: calm, fast, careful, playful, serious.' }),
+    Object.freeze({ id: 'write_down', group: 'Principles', ask: 'Is there anything you want written down now, so it is not argued about later?',
+      hint: 'A rule, a promise or a boundary. It goes into the bylaws as you wrote it.' }),
+  ]),
   strategize: Object.freeze([
     Object.freeze({ id: 'big_pieces', ask: 'What are the big pieces, and in what order do they get built?',
       hint: 'Three to six pieces is plenty. Say why that order: what has to exist before what.' }),
@@ -116,6 +161,14 @@ function checkAnswer(stage, questionId, body = {}) {
   const words = text(b.text);
   if (words.length > LIMITS.answer) return { ok: false, reason: 'answer_too_long' };
   if (state === 'answered' && !words) return { ok: false, reason: 'empty_answer' };
+  // A closed question's answer is one of its keys (or its label, read back as the key),
+  // so the recommender reading it never has to guess at prose.
+  const q = questionFor(stage, questionId);
+  if (state === 'answered' && q.choices) {
+    const hit = q.choices.find((c) => c.key === words || c.label.toLowerCase() === words.toLowerCase());
+    if (!hit) return { ok: false, reason: 'not_a_choice', expected: q.choices.map((c) => c.key) };
+    return { ok: true, value: { state, answer_md: hit.key, origin } };
+  }
   return { ok: true, value: { state, answer_md: words || null, origin } };
 }
 
@@ -130,6 +183,7 @@ function checkLink(url) {
 
 // ── pure: the view ────────────────────────────────────────────────────────────
 
+const labelOf = (q, key) => { const c = (q.choices || []).find((x) => x.key === key); return c ? c.label : null; };
 const iso = (v) => (v ? new Date(v).toISOString() : null);
 
 // shapeStage(stage, work, answers) → one stage's record as every door sees it.
@@ -141,8 +195,11 @@ function shapeStage(stage, work, answers = []) {
     const a = byId.get(q.id);
     return {
       id: q.id, ask: q.ask, hint: q.hint, group: q.group || null,
+      choices: q.choices || null,
       answer: a ? {
         state: a.state, text: a.answer_md || null, origin: a.origin,
+        // a closed answer's words, for a reader who should not see the key
+        choice_label: q.choices && a.state === 'answered' ? labelOf(q, a.answer_md) : null,
         // A carried-over answer is shown as such until the founder makes it theirs.
         carried_over: a.origin === 'carried_over',
         updated_at: iso(a.updated_at),
@@ -190,7 +247,7 @@ function contextMarkdown(stages) {
     out.push(`## ${s.stage[0].toUpperCase()}${s.stage.slice(1)}`);
     for (const q of said) {
       const a = q.answer;
-      const body = a.state === 'answered' ? a.text : `${STATE_WORDS[a.state]}${a.text ? ` — ${a.text}` : ''}`;
+      const body = a.state === 'answered' ? (a.choice_label || a.text) : `${STATE_WORDS[a.state]}${a.text ? ` — ${a.text}` : ''}`;
       out.push(`- **${q.ask}**${ORIGIN_WORDS[a.origin] || ''}\n  ${String(body).replace(/\n/g, '\n  ')}`);
     }
     if (s.page) out.push('', '**In the founder\'s own words:**', '', s.page);
@@ -223,7 +280,11 @@ function assistPrompt(stage) {
   ];
   if (qs.length) {
     lines.push('The questions (the id in brackets is what you record the answer under):');
-    qs.forEach((q, i) => lines.push(`${i + 1}. [${q.id}] ${q.ask} (${q.hint})`));
+    qs.forEach((q, i) => {
+      lines.push(`${i + 1}. [${q.id}] ${q.ask} (${q.hint})`);
+      // A closed question records one of its keys, never prose.
+      if (q.choices) lines.push(`   Record one of: ${q.choices.map((c) => `${c.key} (${c.label})`).join(' · ')}`);
+    });
     lines.push('');
   }
   lines.push('To see what I have already said:  npx bongos genesis show ' + stage);
@@ -316,7 +377,43 @@ async function readAll(deps = {}) {
 async function readStage(stage, deps = {}) {
   if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
   const all = await readAll(deps);
-  return { ok: true, work: all.find((s) => s.stage === stage) };
+  const work = all.find((s) => s.stage === stage);
+  if (stage === 'charter') work.advice = await charterAdvice(work, deps);
+  return { ok: true, work };
+}
+
+// charterAdvice(work, deps) — THE CHARTER STAGE'S RECOMMENDATION (task 1005119): the
+// founder's answers, handed to the government module's one recommender through its
+// port. Closed answers go as their keys, prose ones as the founder's words; "not sure
+// yet" and skipped are not sent, so the recommender falls back to what it does
+// without them. The head count is the founder's own expected number from the plan
+// when they gave one. Null with no government module, and null (never a failed read)
+// if the advice cannot be built: the questions still work without it.
+async function charterAdvice(work, deps = {}) {
+  try {
+    const api = deps.api || require('../../src/module-api');
+    const gov = deps.government !== undefined ? deps.government : api.resolveOptional('government');
+    if (!gov || typeof gov.charterAdvice !== 'function') return null;
+    const answers = {};
+    const prose = {};
+    for (const q of work.questions) {
+      if (!q.answer || q.answer.state !== 'answered') continue;
+      (q.choices ? answers : prose)[q.id] = q.answer.text;
+    }
+    let headcount = null;
+    const get = deps.getSetting || (api.projectSettings && api.projectSettings.get);
+    if (get) {
+      const row = await get('founding.plan');
+      try {
+        const v = row && row.value;
+        const plan = typeof v === 'string' ? JSON.parse(v) : v;
+        headcount = (plan && plan.expected_builders) || null;
+      } catch (_) { headcount = null; }
+    }
+    return await gov.charterAdvice({ answers, prose, headcount });
+  } catch (_) {
+    return null;
+  }
 }
 
 async function setDoor(stage, door, by, deps = {}) {

package/modules/onboarding/routes/genesis-work.js

@@ -15,7 +15,7 @@ const work = require('../genesis-work');
 
 const REFUSALS = {
   unknown_stage: 404, unknown_question: 404, bad_door: 400, bad_state: 400, bad_origin: 400,
-  empty_answer: 400, answer_too_long: 400, page_too_long: 400, link_too_long: 400, bad_link: 400,
+  empty_answer: 400, not_a_choice: 400, answer_too_long: 400, page_too_long: 400, link_too_long: 400, bad_link: 400,
 };
 
 // `deps` is for tests only (an in-memory store); production passes none.
@@ -25,7 +25,7 @@ module.exports = function mountGenesisWorkRoutes(router, deps = {}) {
     try {
       const r = await fn(req);
       if (r && r.ok === false) {
-        return res.status(REFUSALS[r.reason] || 409).json({ error: { code: r.reason, message: r.reason } });
+        return res.status(REFUSALS[r.reason] || 409).json({ error: { code: r.reason, message: r.reason, ...(r.expected ? { expected: r.expected } : {}) } });
       }
       res.set('Cache-Control', 'no-store');
       res.json(r);

package/modules/platform-identity/module.json

@@ -12,7 +12,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "sso-invites", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
+    "routes": ["sso", "sso-invites", "sso-app-status", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull", "guild-totals"]
   },

package/modules/platform-identity/routes/sso-app-status.js

@@ -0,0 +1,65 @@
+// modules/platform-identity/routes/sso-app-status.js — a hosted project asks the hub where
+// its own APP runs (task 1004571). Server-to-server, authenticated by client_id +
+// client_secret like the membership check-in and the invite notices; the asker is core's
+// readAppStatusFromHub (src/bongos/auth-admission.js), and its hall shows the answer in the
+// options menu.
+//
+//   POST /sso/app-status  { client_id, client_secret } → { ok, known, app, sandbox }
+//
+// A PROJECT READS ITS OWN ROW, NEVER ANOTHER'S. The project is the authenticated client
+// itself, named by both halves of the ADR 0246 projection (client_id = slug at the client's
+// registered origin) — nothing in the body can name a different one. The row and its
+// app-status reading belong to the provisioning module, so this asks through the
+// `provisioning.projectAppStatus` port; a hub without provisioning answers `known: false`.
+//
+// WHAT IT CARRIES is app-status.js's shape as is: the project is already trusted with its
+// own setup (it is the project's own hall asking). Its hall decides, per viewer, what an
+// owner sees beyond the state. Nothing here calls Render.
+//
+// WIRE SKEW (ADR 0352): a NEW route, so an older hub answers 404 and the hall says it could
+// not ask. The body is validated strictly, so a field added later must ride a header, or ship
+// on the hub and be released before any instance sends it.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pi = require('../platform-identity');
+
+const log = api.logger('platform-identity');
+const { pool, validateOrRespond } = api;
+
+/** The host a client's registered origin names, lowercased; null for no usable origin. */
+function originHost(origin) {
+  try { return new URL(String(origin || '')).host.toLowerCase() || null; } catch { return null; }
+}
+
+module.exports = function ssoAppStatusRoutes({ resolvePort = (name) => api.resolveOptional(name), db = pool } = {}) {
+  const router = express.Router();
+
+  // rank: public — authenticated by client_id + client_secret, not a builder rank.
+  router.post('/sso/app-status', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      client_id: { required: true, type: 'string', maxLength: 200 },
+      client_secret: { required: true, type: 'string', maxLength: 512 },
+    }, { strict: true })) return undefined;
+    const { client_id, client_secret } = req.body;
+    try {
+      const client = await pi.getClient(client_id, { pool: db });
+      if (!client || client.status !== 'active' || !pi.clientSecretValid(client, client_secret)) {
+        return res.fail('invalid_client', 401);
+      }
+      const read = resolvePort('provisioning.projectAppStatus');
+      const host = originHost(client.origin);
+      const found = typeof read === 'function' && host ? await read({ slug: client.client_id, host }) : null;
+      if (!found) return res.json({ ok: true, known: false, app: null, sandbox: null });
+      return res.json({ ok: true, known: true, app: found.app || null, sandbox: found.sandbox || null });
+    } catch (err) {
+      log.error('[platform-identity] /sso/app-status', err && err.message);
+      return res.fail('app_status_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+module.exports.originHost = originHost;

package/modules/provisioning/module.json

@@ -40,6 +40,7 @@
     "provisioning.projectOwnedBy",
     "provisioning.projectPublishIdentity",
     "provisioning.selfUpdateChannel",
+    "provisioning.projectAppStatus",
     "provisioning.moduleCatalog"
   ],
   "consumes": []