@bongos/core 1.20.25 → 1.20.27

package/modules/government/board.js

@@ -57,6 +57,9 @@ const {
 // describeMembership renders a predicate in the words the proposer was thinking
 // in ("metic and above"), for the disenfranchisement refusal (task 1003094).
 const { describeMembership } = require('./membership-predicate');
+// The genesis charter + legislation vocabulary (task 1004427): the real form
+// and variable names, and the name a constitution reads as.
+const charter = require('./charter');
 
 // ADR 0175 §5: the completeness bar a Full Idea must clear to reach the board.
 // Held equal to economy's IDEA_FULL_PASS_BAR by test — see the header.
@@ -627,7 +630,12 @@ async function closeItem(item, { cause = 'vote' } = {}) {
   });
   if (!closed) return { closed: false, reason: 'already_closed' };
 
-  const authorKarma = outcome === 'passed' ? await awardAuthorRatifyKarma(closed) : null;
+  // A genesis stage ratifies no authored work — closing it is the project's
+  // decision that a stage is done, not a reward for the founder who put it up
+  // (task 1004429). Ideas and amendments pay exactly as before.
+  const authorKarma = outcome === 'passed' && closed.subject_type !== 'genesis_stage'
+    ? await awardAuthorRatifyKarma(closed)
+    : null;
 
   // R14: a PASSED amendment becomes the live constitution — applied AFTER the
   // close commits (the board's decision is the durable record), loudly on
@@ -652,6 +660,7 @@ async function closeItem(item, { cause = 'vote' } = {}) {
     try {
       if (api.emitAsync) await api.emitAsync('board.item.passed', payload);
     } catch (_) { /* emitAsync isolates listener errors; nothing that moves credits subscribes */ }
+    if (closed.subject_type === 'genesis_stage') await emitGenesisStagePassed(closed);
   }
 
   // R22's mirror event: BOTH outcomes, after commit, emitAsync. Separate from
@@ -806,6 +815,237 @@ async function proposeAmendment({
   return { ok: true, amendment, item };
 }
 
+// ── the genesis charter + legislation choice (task 1004427, spec D10) ───────
+//
+// A founder picks a form of government (the charter stage) and fine-tunes its
+// settings (the legislation stage). Both land HERE and nowhere else: the choice
+// is built into a whole constitution on top of the live one (charter.js) and
+// filed as an ordinary AMENDMENT — validated strictly, decided under the
+// constitution in force, and applied by the close like any amendment. Under
+// the monarchy default the founder's one yes applies it; under any other form
+// it is a real sitting. There is no second write path to the constitution, and
+// the disenfranchisement guard applies exactly as it does to a hand-written
+// proposal (a founder choosing a council they do not sit on is asked to
+// acknowledge it).
+//
+// Returns proposeAmendment's shape plus `reads_as` (the form the PROPOSED
+// constitution will read as, or Custom), or a named refusal:
+//   charter.buildCharterProposal's reasons | 'unknown_council_rank' | 'no_change'
+//   | any proposeAmendment refusal.
+async function proposeCharter({
+  form, franchise, councilRank, passRule, windowMinutes,
+  rationaleMd = null, proposedBy, acknowledgeSelfRemoval = false,
+} = {}) {
+  const { board: live } = loadGovernmentConfig();
+  const built = charter.buildCharterProposal(live, { form, franchise, councilRank, passRule, windowMinutes });
+  if (!built.ok) return built;
+  const v = validateProposedConstitution(built.proposal);
+  if (!v.ok) return { ok: false, ...v };
+  if (proposedBy == null || proposedBy === '') return { ok: false, reason: 'missing_proposer' };
+  // A council is a custom rank, which is a DB row this module's pure half
+  // cannot see. A council that does not exist would seat nobody — fail-closed,
+  // but a sitting nobody can ever vote on — so it is refused before filing.
+  if (charter.readCharter(v.proposal).franchise === 'council') {
+    const key = v.proposal.membership.slice('rank:'.length);
+    if (!(await db.getRankByKey(key))) return { ok: false, reason: 'unknown_council_rank', rank_key: key };
+  }
+  const unchanged = ['membership', 'pass_rule', 'window_minutes', 'close_early_on_full_turnout']
+    .every((k) => v.proposal[k] === live[k]);
+  if (unchanged) return { ok: false, reason: 'no_change' };
+
+  const readsAs = charter.readCharter(v.proposal);
+  const out = await proposeAmendment({
+    proposal: v.proposal,
+    // The record says in words what was chosen, so the amendment history reads
+    // "Charter: Direct Democracy" rather than a bare JSON block.
+    rationaleMd: rationaleMd || `Charter: ${readsAs.name}. ${readsAs.explanation}`,
+    proposedBy,
+    acknowledgeSelfRemoval,
+  });
+  return out.ok ? { ...out, reads_as: readsAs } : out;
+}
+
+// ── the board's third subject: closing a genesis stage (task 1004429) ───────
+//
+// Spec decision D7 (docs/specs/bongos-v2-project-startup.md): a new project is
+// founded through five stages, and when a stage's tasks are all finished its
+// close is put to the constitution IN FORCE. It is an ordinary board item, and
+// that is the whole design — the stage borrows every rule the board already
+// has rather than bringing one of its own:
+//
+//   • THE CONSTITUTION IS SNAPSHOTTED, like every item, so a charter adopted
+//     mid-sitting does not change how an already-open stage closes.
+//   • NO NEW PASS RULE, NO GENESIS BYPASS. Under the monarchy default
+//     (first_ratifier) the founder's single confirm closes the stage because
+//     the founder is the first ratifier — not because anything special-cases
+//     genesis. Under consent, majority or unanimous it is a real sitting, with
+//     the clock and turnout rules unchanged.
+//   • THE AUTHOR RULE IS UNCHANGED — which means it does not reach a stage. It
+//     is full_idea-scoped (authorRuleApplies, ADR 0191): it guards an author
+//     who GAINS from ratification, and closing a stage pays nobody. A stage is
+//     in the amendment's position, where §7 already says the one member of a
+//     monarchy must be able to decide their own item.
+//   • IT PAYS NOTHING. No credit (the reward port is only reached for a
+//     full_idea) and no ratify karma (closeItem skips it for a stage).
+//
+// The subject_id is the stage NUMBER. An instance is one project, so the
+// number names a stage uniquely, and government_003's one-open-per-subject
+// index then keeps at most one sitting per stage STRUCTURALLY — the same
+// idempotency a Full Idea gets. A passed stage may be sat again later (the
+// design's "second pass once your builders join"); the index is partial on
+// open items only. government_020 widens the subject CHECK and bounds the range.
+const GENESIS_STAGES = Object.freeze([
+  Object.freeze({ key: 'scope', number: 1, label: 'Scope' }),
+  Object.freeze({ key: 'strategize', number: 2, label: 'Strategize' }),
+  Object.freeze({ key: 'charter', number: 3, label: 'Charter' }),
+  Object.freeze({ key: 'legalize', number: 4, label: 'Legalize' }),
+  Object.freeze({ key: 'legislation', number: 5, label: 'Legislation' }),
+]);
+
+// "Finished" is the task's terminal states: shipped, or dropped — which the
+// tasks table spells `abandoned` (migration 012; a merged-away task lands
+// there too). `confirmed` is NOT finished: the work is graded but not landed.
+const STAGE_TASK_FINISHED_STATUSES = Object.freeze(['shipped', 'abandoned']);
+
+const stageByKey = (key) => GENESIS_STAGES.find((s) => s.key === key) || null;
+const stageByNumber = (n) => GENESIS_STAGES.find((s) => s.number === Number(n)) || null;
+
+// The pass rules, said in words for the founding band. Keyed by exactly
+// config.js PASS_RULES (held equal by tests/government_board_genesis_stage.mjs,
+// so a fifth rule cannot land without its words); an unknown rule in an old
+// snapshot says so rather than guessing. The sentences are written ONCE, as the
+// pass-rule explanations in charter.js (task 1004427), so the legislation stage
+// and the founding band can never describe one rule two ways.
+const PASS_RULE_WORDS = Object.freeze(Object.fromEntries(
+  charter.PASS_RULE_OPTIONS.map((o) => [o.key, o.explanation]),
+));
+
+// Put a finished stage to the board. Returns, never throws for a refusal:
+//   { opened: true,  item, stage }
+//   { opened: false, reason: 'unknown_stage' | 'no_stage_tasks' }
+//   { opened: false, reason: 'stage_tasks_unfinished', unfinished: [{ task_id, status }] }
+//   { opened: false, reason: 'already_open', item, stage }
+//
+// THE FINISHED-TASKS GATE LIVES HERE, not in the caller — the same posture as
+// the Full Idea bar: the genesis home says which tasks make up the stage, and
+// this module checks them against the tasks table before anything is written.
+// An empty list is refused rather than read as "nothing left to do", because a
+// stage close with no tasks behind it would be exactly the bypass D7 rules out.
+// `openedBy` is the founder (or whoever put it up); it may be null for an
+// automatic open, the same as a grade-opened idea.
+//
+// WHO MAY CALL THIS is the caller's gate, by design, exactly as for
+// openWindowForFullIdea: this is a port method with no HTTP route, and opening
+// a sitting decides nothing — it only asks the board. Whoever exposes it to a
+// person (the genesis home) must gate that route itself. The deciding wall is
+// unchanged either way: only a member under the snapshot can vote it closed.
+async function openGenesisStageClose({ stageKey, taskIds, openedBy = null } = {}) {
+  const stage = stageByKey(stageKey);
+  if (!stage) return { opened: false, reason: 'unknown_stage' };
+  const ids = Array.isArray(taskIds) ? taskIds.map(Number) : [];
+  if (!ids.length || !ids.every((n) => Number.isInteger(n) && n > 0)) {
+    return { opened: false, reason: 'no_stage_tasks' };
+  }
+  const unique = [...new Set(ids)];
+  const rows = await db.getTaskStatuses(unique);
+  const statusById = new Map(rows.map((r) => [String(r.id), r.status]));
+  const unfinished = unique
+    .filter((id) => !STAGE_TASK_FINISHED_STATUSES.includes(statusById.get(String(id))))
+    .map((id) => ({ task_id: String(id), status: statusById.get(String(id)) ?? null }));
+  if (unfinished.length) return { opened: false, reason: 'stage_tasks_unfinished', unfinished };
+
+  const { board } = loadGovernmentConfig();
+  const item = await db.openBoardItem({
+    subjectType: 'genesis_stage',
+    subjectId: stage.number,
+    openedBy: openedBy == null || openedBy === '' ? null : openedBy,
+    constitution: board,
+    windowMinutes: board.window_minutes,
+  });
+  if (!item) {
+    return { opened: false, reason: 'already_open', item: await db.getOpenBoardItem('genesis_stage', stage.number), stage };
+  }
+  await emitWindowOpened(item);
+  return { opened: true, item, stage };
+}
+
+// The genesis home's cue (spec D7 / task 1004423): a stage's sitting PASSED,
+// so mark it done and wake its room. Emitted after the close commits, beside
+// the general `board.item.passed`, carrying what that contract deliberately
+// does not — which stage. Best-effort by construction, like every board event:
+// the durable fact is the `outcome = 'passed'` row, which genesisStageStatus
+// reads, so a listener that missed the nudge can always recover the state.
+async function emitGenesisStagePassed(closed) {
+  const stage = stageByNumber(closed.subject_id);
+  if (!stage) return;
+  try {
+    if (api.emitAsync) {
+      await api.emitAsync('board.genesis_stage.passed', {
+        item_id: String(closed.id),
+        stage_key: stage.key,
+        stage_number: stage.number,
+        passed_at: closed.closed_at || null,
+      });
+    }
+  } catch (_) { /* a nudge that fails is recoverable from the passed row */ }
+}
+
+// "Who is this stage waiting on" — for the founding band. One entry per stage,
+// from the LATEST sitting on it:
+//   state: 'not_put' (never put to the board) | 'sitting' | 'passed' | 'returned'
+// and for a sitting, the members under the item's OWN snapshot (not the live
+// config), split into who has voted and who is still to — per request,
+// uncached, the ADR 0016 posture of every membership read here. Under monarchy
+// `one_vote_decides` is true and `waiting_on` names everyone who could give
+// that vote. The countdown is the database's (`remaining_seconds`); the client
+// never does clock math. Membership is resolved once per distinct predicate.
+async function genesisStageStatus() {
+  const items = await db.listLatestGenesisStageItems();
+  const open = items.filter((i) => !i.closed_at);
+  const votes = open.length ? await db.getVotesForItems(open.map((i) => i.id)) : [];
+  const membersByPredicate = new Map();
+  const stages = [];
+  for (const stage of GENESIS_STAGES) {
+    const item = items.find((i) => Number(i.subject_id) === stage.number);
+    const base = { key: stage.key, number: stage.number, label: stage.label };
+    if (!item) {
+      stages.push({ ...base, state: 'not_put', item_id: null, voted: [], waiting_on: [] });
+      continue;
+    }
+    const constitution = item.constitution || {};
+    const common = {
+      ...base,
+      item_id: String(item.id),
+      opened_at: item.opened_at || null,
+      pass_rule: constitution.pass_rule || null,
+      needs: PASS_RULE_WORDS[constitution.pass_rule] || 'The rule this sitting runs under is not one this version knows; only its clock can close it.',
+      one_vote_decides: constitution.pass_rule === 'first_ratifier',
+    };
+    if (item.closed_at) {
+      stages.push({ ...common, state: item.outcome, closed_at: item.closed_at, voted: [], waiting_on: [] });
+      continue;
+    }
+    const key = String(constitution.membership || '');
+    if (!membersByPredicate.has(key)) membersByPredicate.set(key, await resolveBoardMembers(constitution));
+    const members = membersByPredicate.get(key);
+    const cast = votes.filter((v) => String(v.item_id) === String(item.id));
+    const castBy = new Map(cast.map((v) => [String(v.voter_id), v]));
+    stages.push({
+      ...common,
+      state: 'sitting',
+      closes_at: item.closes_at || null,
+      remaining_seconds: item.remaining_seconds ?? null,
+      voted: cast.map((v) => ({
+        builder_id: String(v.voter_id), github_login: v.github_login, display_name: v.display_name, direction: v.direction,
+      })),
+      waiting_on: members.filter((m) => !castBy.has(String(m.builder_id))).map((m) => ({
+        builder_id: m.builder_id, github_login: m.github_login, display_name: m.display_name,
+      })),
+    });
+  }
+  return { stages };
+}
+
 // ── the Board Room view (BV1.R16 of goal 1000069, ADR 0175 §9) ──────────────
 //
 // One assembled read for the room: open items with their clock, the OPEN
@@ -851,7 +1091,17 @@ async function boardRoomView({ closedLimit = 20 } = {}) {
     });
   }
   const project = (item) => {
-    const subject = item.subject_type === 'full_idea'
+    // A genesis stage's subject is the stage itself — named from the one list,
+    // so the room never mistakes it for an amendment (task 1004429).
+    const subject = item.subject_type === 'genesis_stage'
+      ? (() => {
+          const s = stageByNumber(item.subject_id);
+          return s ? {
+            stage_key: s.key, stage_number: s.number, label: s.label,
+            author_id: item.opened_by == null ? null : String(item.opened_by),
+          } : null;
+        })()
+      : item.subject_type === 'full_idea'
       ? (() => {
           const r = ideaById.get(String(item.subject_id));
           return r ? {
@@ -1001,6 +1251,10 @@ async function constitutionView({ historyLimit = 50 } = {}) {
     // last passed one is not a shape this system has, and the honest failure
     // there is a missed warning rather than a wrong one.
     divergence: constitutionDivergence(live, history),
+    // The genesis charter + legislation stages' payload (task 1004427): every
+    // form and variable by its real name with its plain explanation, and the
+    // form the constitution in force reads as (or Custom). Pure — no query.
+    charter: charter.charterView(live),
     // THE CLOCK ADVICE THE AMENDMENT FORM NEEDS (task 1003733, ADR 0267 §3).
     // A proposer choosing a pass rule has to choose a window in the same breath
     // — a constitution is ratified whole, never by diff — and the two choices
@@ -1138,6 +1392,11 @@ async function pendingVotesFor(builderId) {
 }
 
 module.exports = {
+  GENESIS_STAGES,
+  PASS_RULE_WORDS,
+  proposeCharter,
+  openGenesisStageClose,
+  genesisStageStatus,
   pendingVotesFor,
   hasMajority,
   majorityDecided,

package/modules/government/charter.js

@@ -0,0 +1,232 @@
+'use strict';
+
+// modules/government/charter.js — the genesis charter and legislation stages'
+// vocabulary, on the REAL constitution (task 1004427 / BV2.PS13, spec decision
+// D10 in docs/specs/bongos-v2-project-startup.md).
+//
+// REAL NAMES, EACH EXPLAINED PLAINLY. Real-world governments are the model for
+// a project's structure, so every form and every setting is called what it
+// actually is — Monarchy / BDFL, Timocratic Republic, franchise, judicial
+// review — and carries a one- or two-sentence explanation of how it works in a
+// project. The explanation is simpler than the academic definition and never a
+// replacement for the name.
+//
+// ONLY WHAT IS BUILT CLAIMS TO BE. Two variables are the live board block:
+// franchise (`membership`) and pass rule (`pass_rule`). Loyalty of enforcement
+// is always on — authority is resolved from the rank you hold, per request and
+// uncached (ADR 0016), so nobody keeps a rank's powers after leaving it. The
+// other four are shown as coming later, and so are the three forms that need
+// machinery this system does not have (elections, member shares, federated
+// chambers).
+//
+// THE NAME FOLLOWS THE SETTINGS. `readCharter` reads what a constitution SEATS
+// (through the real membership parser) and its pass rule, and names the form
+// those make — or "Custom" when they make none. It reads the seated set, not
+// the spelling, so `rank:metic+` and `rank:metic,archon` read the same.
+//
+// APPLYING IS AN AMENDMENT. `buildCharterProposal` only BUILDS a whole
+// constitution from a choice; board.js `proposeCharter` files it through the
+// ordinary amendment path, so the choice is validated strictly and decided
+// under the constitution in force (under monarchy, the founder's one yes
+// applies it). There is no second write path to the constitution.
+//
+// Pure and DB-free: it requires only the catalog's ladder and the membership
+// grammar, so a test (or a boot-time caller) can use it without a database.
+//
+// The form names are held equal to the hall's charter library
+// (modules/hall-ui/public/government.js CHARTERS) by
+// tests/government_charter_forms.mjs — browser code cannot require this file,
+// and one form must never go by two names.
+
+const { RANK_ORDER } = require('./catalog');
+const { parseMembershipPredicate } = require('./membership-predicate');
+
+const freezeAll = (list) => Object.freeze(list.map((x) => Object.freeze({ ...x })));
+
+// ── franchise: who gets a vote ───────────────────────────────────────────────
+// `predicate` is the exact membership string written to the constitution, and
+// `seats` is what it must resolve to. `council` names a custom rank the owner
+// chooses, so its predicate is built from that choice.
+const FRANCHISE_OPTIONS = freezeAll([
+  { key: 'founder', name: 'The founder', predicate: 'rank:archon', seats: ['archon'],
+    explanation: 'Only the founder votes (the Archon rank). Right for a solo start, when there is nobody else to ask.' },
+  { key: 'trusted', name: 'Trusted builders and up', predicate: 'rank:metic+', seats: ['metic', 'archon'],
+    explanation: 'Builders who have earned the trusted rank by shipping get a vote, along with the founder.' },
+  { key: 'everyone', name: 'Every builder', predicate: 'rank:xenos+', seats: [...RANK_ORDER],
+    explanation: 'Everyone on the project gets a vote, from the newest builder to the founder.' },
+  { key: 'council', name: 'A council you name', predicate: null, seats: null,
+    explanation: 'Only the members of a council rank you create get a vote. You choose who sits on it.' },
+]);
+
+// ── pass rule (winning coalition): how many must agree ───────────────────────
+// Exactly the four rules config.js PASS_RULES knows (held equal by test).
+const PASS_RULE_OPTIONS = freezeAll([
+  { key: 'first_ratifier', name: 'One yes is enough',
+    explanation: 'One yes from any member decides it.' },
+  { key: 'consent', name: 'Passes unless someone objects',
+    explanation: 'It passes unless a member objects, once everyone has voted or the clock runs out.' },
+  { key: 'majority', name: 'More than half',
+    explanation: 'More than half of all members must say yes.' },
+  { key: 'unanimous', name: 'Everyone who votes agrees',
+    explanation: 'Everyone who votes must agree, and at least one member must say yes.' },
+]);
+
+// ── trajectory: how the government changes as the project grows ─────────────
+const TRAJECTORIES = freezeAll([
+  { key: 'locked', name: 'Locked',
+    explanation: 'The government stays as founded until the project votes to change it.' },
+  { key: 'laddered', name: 'Laddered',
+    explanation: 'The government steps up automatically as the team crosses each size threshold.' },
+  { key: 'scheduled', name: 'Scheduled',
+    explanation: 'The government changes on dates the project commits to in advance.' },
+]);
+
+// ── the government doc's seven variables ─────────────────────────────────────
+// status: 'live' (a real setting of the constitution today) | 'always_on' |
+// 'later' (shown, explained, and not yet settable).
+const VARIABLES = freezeAll([
+  { key: 'franchise', name: 'Franchise', question: 'Who gets a vote?', status: 'live',
+    explanation: 'Who sits on the board and votes on the project\'s decisions.' },
+  { key: 'pass_rule', name: 'Pass rule (winning coalition)', question: 'How many must agree?', status: 'live',
+    explanation: 'How much agreement a decision needs before it passes.' },
+  { key: 'veto_points', name: 'Veto points', question: 'How many checkpoints must a big change pass?', status: 'later',
+    explanation: 'How many separate approvals a big change must collect before it happens.' },
+  { key: 'executive_legislative', name: 'Executive–legislative relationship',
+    question: 'Does the leader serve at the team\'s confidence?', status: 'later',
+    explanation: 'Whether the team can replace its leader by vote, or the leader holds office for a set term.' },
+  { key: 'judicial_review', name: 'Judicial review', question: 'Who can void a decision that breaks the charter?', status: 'later',
+    explanation: 'Who may cancel a decision that goes against the project\'s charter.' },
+  { key: 'loyalty_of_enforcement', name: 'Loyalty of enforcement',
+    question: 'Does power belong to the office or the person?', status: 'always_on',
+    explanation: 'Whoever holds a rank holds its powers, and nobody keeps them after leaving it.' },
+  { key: 'trajectory', name: 'Trajectory', question: 'How does the government change as you grow?', status: 'later',
+    explanation: 'Whether the government stays put, grows with the team, or changes on a schedule.' },
+]);
+
+// ── the forms ────────────────────────────────────────────────────────────────
+// An available form is a franchise + a pass rule; choosing it sets exactly
+// those two. `key` matches the hall charter library's key.
+const FORMS = freezeAll([
+  { key: 'monarchy', name: 'Monarchy / BDFL', available: true, franchise: 'founder', pass_rule: 'first_ratifier',
+    explanation: 'One leader decides. In a project the founder makes the calls, which is fast, clear and honest for a solo start.' },
+  { key: 'timocratic-republic', name: 'Timocratic Republic', available: true, franchise: 'trusted', pass_rule: 'consent',
+    explanation: 'A say is earned, not given. Builders who have reached the trusted rank decide together.' },
+  { key: 'direct-democracy', name: 'Direct Democracy', available: true, franchise: 'everyone', pass_rule: 'consent',
+    explanation: 'Every builder votes directly. A decision passes unless someone objects with a reason.' },
+  { key: 'foundation', name: 'Foundation', available: true, franchise: 'council', pass_rule: 'consent',
+    explanation: 'A written charter looked after by a small council of trustees you appoint.' },
+  { key: 'presidential', name: 'Presidential', available: false,
+    explanation: 'The team elects a leader for a fixed term. Coming later, because it needs elections.' },
+  { key: 'cooperative', name: 'Cooperative', available: false,
+    explanation: 'Every member holds a share and gets one vote. Coming later, because it needs member shares.' },
+  { key: 'federation', name: 'Federation', available: false,
+    explanation: 'Self-governing teams coordinate under one shared pact. Coming later, for projects with many teams.' },
+]);
+
+const CUSTOM_EXPLANATION = 'These settings match no named form of government. They are still the real rules the board runs under.';
+
+const byKey = (list, key) => list.find((x) => x.key === key) || null;
+const sameSet = (a, b) => a.length === b.length && a.every((k) => b.includes(k));
+
+// Is this a single CUSTOM rank (a council)? A custom rank is a DB row this file
+// cannot see, so "not on the standard ladder" is the whole test here; whether
+// it exists is board.js's check against the live rows.
+const isCustomRankKey = (key) => typeof key === 'string' && !RANK_ORDER.includes(key);
+
+// Which franchise option does a membership predicate SEAT? Read through the
+// real parser, so an equivalent spelling reads the same and an unparseable one
+// reads as custom rather than as a guess.
+function franchiseOf(membership) {
+  const parsed = parseMembershipPredicate(membership);
+  if (!parsed) return 'custom';
+  const seats = [...parsed.rankKeys];
+  for (const o of FRANCHISE_OPTIONS) if (o.seats && sameSet(o.seats, seats)) return o.key;
+  if (seats.length === 1 && isCustomRankKey(seats[0])) return 'council';
+  return 'custom';
+}
+
+// The name follows the settings: which form does this board block make?
+function readCharter(board) {
+  const b = board || {};
+  const franchise = franchiseOf(b.membership);
+  const passRule = byKey(PASS_RULE_OPTIONS, b.pass_rule) ? b.pass_rule : 'custom';
+  const form = FORMS.find((f) => f.available && f.franchise === franchise && f.pass_rule === passRule);
+  return Object.freeze(form
+    ? { form: form.key, name: form.name, explanation: form.explanation, franchise, pass_rule: passRule }
+    : { form: 'custom', name: 'Custom', explanation: CUSTOM_EXPLANATION, franchise, pass_rule: passRule });
+}
+
+// Build the WHOLE constitution a charter choice makes, on top of the live one.
+// A choice is a form, a franchise, a pass rule, a window, or a form fine-tuned by
+// the others (the legislation stage tunes what the charter stage picked). The
+// fields a charter does not speak to — the clock and the full-turnout early
+// close — are KEPT from the live constitution unless a window is named, because
+// a constitution is ratified whole and the choice must not quietly change them.
+// Returns { ok: true, proposal } or { ok: false, reason }; the caller validates
+// the result strictly and files it as an amendment.
+function buildCharterProposal(liveBoard, { form, franchise, councilRank, passRule, windowMinutes } = {}) {
+  const live = liveBoard || {};
+  let franchiseKey = franchise;
+  let rule = passRule;
+  if (form !== undefined && form !== null) {
+    const f = byKey(FORMS, form);
+    if (!f) return { ok: false, reason: 'unknown_form' };
+    if (!f.available) return { ok: false, reason: 'form_not_available' };
+    if (franchiseKey == null) franchiseKey = f.franchise;
+    if (rule == null) rule = f.pass_rule;
+  }
+  if (franchiseKey == null && rule == null && windowMinutes === undefined) return { ok: false, reason: 'nothing_chosen' };
+
+  let membership = live.membership;
+  if (franchiseKey != null) {
+    const option = byKey(FRANCHISE_OPTIONS, franchiseKey);
+    if (!option) return { ok: false, reason: 'unknown_franchise' };
+    if (option.key === 'council') {
+      if (councilRank == null || councilRank === '') return { ok: false, reason: 'council_needs_a_rank' };
+      const predicate = `rank:${councilRank}`;
+      const parsed = parseMembershipPredicate(predicate);
+      if (!parsed || parsed.rankKeys.length !== 1 || !isCustomRankKey(parsed.rankKeys[0])) {
+        return { ok: false, reason: 'council_needs_a_custom_rank' };
+      }
+      membership = predicate;
+    } else {
+      membership = option.predicate;
+    }
+  }
+  if (rule != null && !byKey(PASS_RULE_OPTIONS, rule)) return { ok: false, reason: 'unknown_pass_rule' };
+
+  return {
+    ok: true,
+    proposal: {
+      membership,
+      pass_rule: rule != null ? rule : live.pass_rule,
+      window_minutes: windowMinutes !== undefined ? windowMinutes : (live.window_minutes ?? null),
+      close_early_on_full_turnout: live.close_early_on_full_turnout,
+    },
+  };
+}
+
+// The whole vocabulary plus what the constitution in force reads as — the
+// payload the genesis charter and legislation stages render from.
+function charterView(liveBoard) {
+  return {
+    forms: FORMS,
+    variables: VARIABLES.map((v) => (
+      v.key === 'franchise' ? { ...v, options: FRANCHISE_OPTIONS }
+        : v.key === 'pass_rule' ? { ...v, options: PASS_RULE_OPTIONS }
+          : v.key === 'trajectory' ? { ...v, options: TRAJECTORIES }
+            : v)),
+    reads_as: readCharter(liveBoard),
+  };
+}
+
+module.exports = {
+  FORMS,
+  VARIABLES,
+  FRANCHISE_OPTIONS,
+  PASS_RULE_OPTIONS,
+  TRAJECTORIES,
+  readCharter,
+  buildCharterProposal,
+  charterView,
+};

package/modules/government/db.js

@@ -688,7 +688,12 @@ async function getExpiredOpenBoardItems(limit = 100) {
 async function openBoardItemsAwaitingVoter(voterId) {
   const { rows } = await pool.query(
     `SELECT i.id, i.subject_type, i.subject_id, i.constitution, i.opened_at, i.closes_at,
-            CASE WHEN i.subject_type = 'full_idea' THEN idea.captured_by ELSE i.opened_by END AS author_id,
+            -- A genesis stage has no author to hold back (task 1004429): the
+            -- founder who put it up IS the confirm monarchy waits on, so they
+            -- must be summoned, not skipped.
+            CASE WHEN i.subject_type = 'full_idea' THEN idea.captured_by
+                 WHEN i.subject_type = 'genesis_stage' THEN NULL
+                 ELSE i.opened_by END AS author_id,
             (v.id IS NOT NULL) AS already_voted
        FROM government_board_items i
        LEFT JOIN idea_inbox idea
@@ -703,6 +708,40 @@ async function openBoardItemsAwaitingVoter(voterId) {
   return rows;
 }
 
+// --- genesis stages (task 1004429 / BV2.PS04) --------------------------------
+
+// The status of each task a stage names, for the "are this stage's tasks all
+// finished" gate. `tasks` is a core table; READING it is the sanctioned pattern
+// (the boundary is code imports, not table access). An id with no row comes
+// back absent, and the caller counts that as unfinished — a stage cannot close
+// on a task nobody can find.
+async function getTaskStatuses(taskIds) {
+  if (!taskIds || !taskIds.length) return [];
+  const { rows } = await pool.query(
+    `SELECT id, status FROM tasks WHERE id = ANY($1::bigint[])`,
+    [taskIds],
+  );
+  return rows;
+}
+
+// The latest sitting for each genesis stage (one row per stage number, newest
+// first within it), with the same database-clock fields the room reads. Served
+// by government_020's partial index, keyed to exactly this ORDER BY — the table
+// holds every idea and amendment sitting forever, and without it this read
+// would scan all of that history to find a handful of stage rows.
+async function listLatestGenesisStageItems() {
+  const { rows } = await pool.query(
+    `SELECT DISTINCT ON (subject_id) *,
+            (closes_at IS NOT NULL AND closes_at < now()) AS expired,
+            CASE WHEN closes_at IS NULL THEN NULL
+                 ELSE GREATEST(0, EXTRACT(EPOCH FROM (closes_at - now()))::int) END AS remaining_seconds
+       FROM government_board_items
+      WHERE subject_type = 'genesis_stage'
+      ORDER BY subject_id, opened_at DESC, id DESC`,
+  );
+  return rows;
+}
+
 // Author-ratification karma (+3, board.js AUTHOR_RATIFY_KARMA_DELTA) — fired by
 // the R10 close on a passed item. IDEMPOTENT: the reason key is unique per item
 // and the INSERT is one atomic WHERE-NOT-EXISTS statement (the economy
@@ -731,6 +770,8 @@ async function insertVoteKarma({ voterId, itemId, delta }) {
 
 module.exports = {
   openBoardItemsAwaitingVoter,
+  getTaskStatuses,
+  listLatestGenesisStageItems,
   getPermissionKeysForBuilder,
   getRankKeysForBuilder,
   getSeededRanks,

package/modules/government/migrations/government_020_genesis_stage_subject.sql

@@ -0,0 +1,55 @@
+-- government_020_genesis_stage_subject.sql — the board's third subject: closing
+-- a genesis stage (task 1004429 / BV2.PS04, spec docs/specs/bongos-v2-project-
+-- startup.md decision D7).
+--
+-- government_003 built `subject_type` so that a third subject would be "a row,
+-- not a migration". That held for the ROWS — no new table, no new column — but
+-- the column carries a CHECK naming the two subjects it knew about, so the
+-- vocabulary itself still has to widen here. That is the whole of this file.
+--
+-- A genesis stage's subject_id is its STAGE NUMBER (1 scope · 2 strategize ·
+-- 3 charter · 4 legalize · 5 legislation — board.js GENESIS_STAGES is the one
+-- list). An instance is one project, so the number names the stage uniquely,
+-- and that is what lets government_003's partial unique index keep AT MOST ONE
+-- OPEN SITTING PER STAGE structurally, the same way it keeps one per idea: a
+-- double-fired "the stage's tasks are done" opens exactly one item. A stage
+-- that passed can be sat again later (the "second pass once your builders
+-- join" in the design of record) — the index is partial on open items only.
+--
+-- Nothing about deciding changes. The item snapshots the constitution in force
+-- like every other item, the pass rules are the same four, and the author and
+-- clock rules are the ones every item runs under.
+--
+-- Additive, idempotent: dropping and re-adding a CHECK that only WIDENS admits
+-- every row already in the table.
+
+BEGIN;
+
+ALTER TABLE government_board_items
+  DROP CONSTRAINT IF EXISTS government_board_items_subject_type_check;
+
+ALTER TABLE government_board_items
+  ADD CONSTRAINT government_board_items_subject_type_check
+  CHECK (subject_type IN ('full_idea', 'constitutional_amendment', 'genesis_stage'));
+
+-- The stage number is a small closed range; a stray id would be a sitting on a
+-- stage that does not exist. Scoped to genesis_stage so the other subjects'
+-- ids (idea and amendment row ids) are untouched.
+ALTER TABLE government_board_items
+  DROP CONSTRAINT IF EXISTS government_board_items_genesis_stage_number;
+
+ALTER TABLE government_board_items
+  ADD CONSTRAINT government_board_items_genesis_stage_number
+  CHECK (subject_type <> 'genesis_stage' OR subject_id BETWEEN 1 AND 5);
+
+-- Serves the founding band's read (db.js listLatestGenesisStageItems: the latest
+-- sitting per stage, DISTINCT ON subject_id ORDER BY subject_id, opened_at DESC,
+-- id DESC). The table only grows — every Full Idea and amendment sitting stays
+-- forever — so a read that filters by subject_type alone would scan that whole
+-- history to find at most a handful of stage rows. Partial on the one subject it
+-- asks for and keyed to its ORDER BY exactly, the government_006/018 shape.
+CREATE INDEX IF NOT EXISTS government_board_items_genesis_stage_latest
+  ON government_board_items (subject_id, opened_at DESC, id DESC)
+  WHERE subject_type = 'genesis_stage';
+
+COMMIT;