@bongos/core 1.21.97 → 1.21.99

package/scripts/gds/government-walk.js

@@ -0,0 +1,842 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/government-walk.js — THE GOVERNMENT WALK: one repeatable end-to-end
+// pass over a throwaway test project's government, producing a pass/fail table
+// (task 1004658, goal 1000111, criterion gov-proven-and-kept-proven).
+//
+// WHAT IT WALKS, in four sections:
+//   1. Genesis — start founding, decide with a chosen government, close all five
+//      stages, come alive; the constitution reads as the choice.
+//   2. Every available form (Monarchy / BDFL, Timocratic Republic, Direct Democracy,
+//      Foundation with a council rank) plus the two pass rules no form uses
+//      (majority, unanimous): switch to it through a charter amendment, then confirm
+//      who can vote and what passes.
+//   3. Every building: set it to decide by vote (a decision-rules amendment), try to
+//      act alone on each of its bound routes (refused), restore it (reachable again).
+//   4. Every matter action: open the matter, pass it, confirm the effect happened.
+//
+// HOW REAL IT IS. Every request is real HTTP through the real routers (government,
+// onboarding/genesis, and every building's own router), with the real
+// requirePermission gate resolving the real government port, and every decision is
+// the real code: the board, membership, the tally, the close, the charter apply
+// (written to a throwaway instance folder), the decision-rules apply, act-alone, and
+// each module's matter act. What is NOT real is the storage under them: there is no
+// Postgres on the machine this was built on, so the government module's db layer is
+// an in-memory fake with the same row shapes and the same guards (one open sitting
+// per subject, one vote per member, single-winner close, the decision-rules write
+// only from a passed decision-rules amendment), and the few writes a passed matter
+// makes into other modules are recorded in memory instead of written to a database
+// (or, for a gate approval, sent to GitHub). The table says which mode ran.
+//
+// Usage:
+//   node scripts/gds/government-walk.js           run it and print the table
+//   node scripts/gds/government-walk.js --write   also write docs/governance/government-walk.md
+//   node scripts/gds/government-walk.js --check   exit 1 if the committed table differs
+// tests/government_walk.mjs runs --check, so a change that flips any row reds CI.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const DOC_PATH = path.join(ROOT, 'docs', 'governance', 'government-walk.md');
+
+// Bugs this walk found, filed as tasks under goal 1000111. A FAIL row names its task
+// so the table reads as a worklist; a row that starts passing again just passes.
+const KNOWN_BUGS = Object.freeze({});
+
+// ── the throwaway project ───────────────────────────────────────────────────
+
+// The test project's people. 42 founds it. 47 left the project; it only ever
+// authors the probe ideas, so no probe is decided by its own author.
+const BUILDERS = Object.freeze([
+  { id: '42', rank: 'archon', github_login: 'ada', display_name: 'Ada (founder)', status: 'active' },
+  { id: '43', rank: 'metic', github_login: 'ben', display_name: 'Ben', status: 'active' },
+  { id: '44', rank: 'metic', github_login: 'cy', display_name: 'Cy', status: 'active' },
+  { id: '45', rank: 'thetes', github_login: 'dee', display_name: 'Dee', status: 'active' },
+  { id: '46', rank: 'xenos', github_login: 'eve', display_name: 'Eve', status: 'active' },
+  { id: '47', rank: 'xenos', github_login: 'fay', display_name: 'Fay (left)', status: 'left' },
+]);
+const ACTIVE_IDS = BUILDERS.filter((b) => b.status === 'active').map((b) => b.id);
+const FOUNDER = '42';
+const COUNCIL = ['43', '44'];
+
+// Each bound route as a request that, as today, stops in its handler's own first
+// check (a bad id or body) before any database write — the same requests as
+// tests/government_act_alone_buildings.mjs, with People's two carrying a real
+// custom rank and builder of this project.
+const BAD = 'x';
+const REQUESTS = Object.freeze({
+  'PATCH /project-settings/rot-days': ['PATCH', '/project-settings/rot-days', { days: 'soon' }],
+  'PATCH /project-settings/ship-mode': ['PATCH', '/project-settings/ship-mode', { mode: 'sometimes' }],
+  'PATCH /work-categories/:id': ['PATCH', `/work-categories/${BAD}`, {}],
+  'POST /security/reports/:id/confirm': ['POST', `/security/reports/${BAD}/confirm`, {}],
+  'POST /security/reports/:id/dispute': ['POST', `/security/reports/${BAD}/dispute`, {}],
+  'POST /security/reports/:id/fix': ['POST', `/security/reports/${BAD}/fix`, {}],
+  'POST /government/assignments': ['POST', '/government/assignments', { builder_id: 46, rank_key: 'tester' }],
+  'DELETE /government/assignments/:builderId/:rankKey': ['DELETE', '/government/assignments/46/tester'],
+  'PATCH /access-requests/:id': ['PATCH', `/access-requests/${BAD}`, { status: 'invited' }],
+  'POST /access-requests/invite': ['POST', '/access-requests/invite', {}],
+  'POST /goals': ['POST', '/goals', {}],
+  'POST /goals/reorder': ['POST', '/goals/reorder', {}],
+  'POST /work-categories': ['POST', '/work-categories', {}],
+  'PUT /versions/focus': ['PUT', '/versions/focus', { version_id: '   ' }],
+  'POST /autonomy/fence': ['POST', '/autonomy/fence', { enabled: 'yes' }],
+  'POST /autonomy/fence/goals': ['POST', '/autonomy/fence/goals', { goal_id: 0 }],
+  'DELETE /autonomy/fence/goals/:goalId': ['DELETE', `/autonomy/fence/goals/${BAD}`],
+  'POST /autonomy/fence/priority': ['POST', '/autonomy/fence/priority', {}],
+  'POST /autonomy/builders/:builderId/pause': ['POST', `/autonomy/builders/${BAD}/pause`, { paused: false }],
+  'POST /done-when/:criterionId/satisfy': ['POST', `/done-when/${BAD}/satisfy`, {}],
+  'POST /done-when/:criterionId/unsatisfy': ['POST', `/done-when/${BAD}/unsatisfy`, {}],
+  'POST /gate-approvals/:pr/approve': ['POST', `/gate-approvals/${BAD}/approve`, {}],
+  'POST /override-requests/:id/decide': ['POST', `/override-requests/${BAD}/decide`, { decision: 'approve' }],
+  'POST /provisioning/instances/:id/core-upgrade': ['POST', `/provisioning/instances/${BAD}/core-upgrade`, { to: '1.2.3' }],
+  'POST /provisioning/instances/:id/update-channel': ['POST', `/provisioning/instances/${BAD}/update-channel`, { channel: 'nightly' }],
+  'POST /render-deploy/act': ['POST', '/render-deploy/act', { action: 'launch' }],
+  'POST /npm-release/release': ['POST', '/npm-release/release', { version: 'v-next' }],
+  'PATCH /builders/:id/budget': ['PATCH', `/builders/${BAD}/budget`, { monthly_budget_usd: 5 }],
+});
+
+// Every matter action, as the matter the walk opens and passes: [area, title, action,
+// the effect in words]. runWalk observes each effect (its HAPPENED table).
+const MATTER_PLAN = Object.freeze([
+  ['people', 'Give Eve the tester rank', { type: 'assign_rank', builder_id: 46, rank_key: 'tester' }, 'Eve holds tester'],
+  ['people', 'Take the tester rank from Eve', { type: 'unassign_rank', builder_id: 46, rank_key: 'tester' }, 'Eve no longer holds tester'],
+  ['automation', 'Switch unattended building on', { type: 'switch_on' }, 'fence on'],
+  ['automation', 'Switch unattended building off', { type: 'switch_off' }, 'fence off'],
+  ['automation', 'Allow goal 77 to build unattended', { type: 'allow_goal', goal_id: 77 }, 'goal 77 allowed'],
+  ['release', 'Approve override request 5', { type: 'approve_override', request_id: 5 }, 'request 5 approved'],
+  ['release', 'Clear the gate on PR 1500', { type: 'approve_gate', pr: 1500 }, 'PR 1500 cleared'],
+  ['review', 'Sign off criterion 9', { type: 'satisfy_criterion', criterion_id: 9 }, 'criterion 9 satisfied'],
+  ['treasury', 'Dee gets $50 a month', { type: 'set_budget', builder_id: 45, monthly_usd: 50 }, 'Dee\'s limit is $50'],
+]);
+
+// Every router the walk drives, mounted as the server mounts them.
+const ROUTERS = Object.freeze([
+  'modules/government/routes/government.js',
+  'modules/onboarding/routes/onboarding.js',
+  'modules/autonomy/routes/autonomy.js',
+  // no HTTP surface; it contributes the Release and Review matter acts, as at boot
+  'modules/lifecycle/routes/lifecycle.js',
+  'modules/lifecycle/routes/done-when.js',
+  'modules/lifecycle/routes/gate-approvals.js',
+  'modules/lifecycle/routes/tasks.js',
+  'modules/lifecycle/routes/goals.js',
+  'modules/lifecycle/routes/versions.js',
+  'modules/lifecycle/routes/project-settings.js',
+  'modules/render-deploy/routes/act.js',
+  'modules/npm-release/routes/release.js',
+  'modules/provisioning/routes/core-upgrade.js',
+  'src/bongos/routes/builders.js',
+  'modules/security/routes/reports.js',
+]);
+
+// ── the in-memory government store ──────────────────────────────────────────
+//
+// The government module's db.js, with the same row shapes and the same guards the
+// SQL carries. Any db function the walk did not expect throws, so a code path that
+// reaches storage this fake does not model shows up as a FAIL rather than a quiet
+// undefined.
+function makeStore(catalog) {
+  const s = {
+    seq: 100,
+    clock: 0,
+    builders: new Map(BUILDERS.map((b) => [b.id, { ...b }])),
+    customRanks: new Map(),
+    assignments: [], // { builder_id, rank_key, assigned_by }
+    items: [],
+    votes: [],
+    amendments: new Map(),
+    matters: new Map(),
+    rules: new Map(),
+    ideas: new Map(),
+    tasks: new Map(),
+    karma: [],
+    unexpected: [],
+  };
+  const next = () => String(++s.seq);
+  const tick = () => `T${String(++s.clock).padStart(4, '0')}`;
+  const heldRanks = (id) => {
+    const b = s.builders.get(String(id));
+    if (!b) return [];
+    return [b.rank, ...s.assignments.filter((a) => a.builder_id === String(id)).map((a) => a.rank_key)];
+  };
+  const isLive = (b) => b && b.status === 'active';
+  const copy = (x) => (x == null ? x : JSON.parse(JSON.stringify(x)));
+  const withExpiry = (i) => ({ ...copy(i), expired: false, remaining_seconds: null });
+  const voteRow = (v) => {
+    const b = s.builders.get(v.voter_id) || {};
+    return { ...copy(v), github_login: b.github_login || null, display_name: b.display_name || null };
+  };
+
+  const fns = {
+    async getPermissionKeysForBuilder(id) {
+      const keys = new Set();
+      for (const r of heldRanks(id)) for (const k of catalog.RANK_SEED[r] || []) keys.add(k);
+      return [...keys];
+    },
+    async getRankKeysForBuilder(id) { return heldRanks(id).sort(); },
+    async getRankByKey(k) {
+      if (catalog.RANK_SEED[k]) return { rank_key: k, label: k, is_system: true, seeded_rank: k };
+      return copy(s.customRanks.get(k)) || null;
+    },
+    async createRank({ rankKey, label, description, createdBy }) {
+      if (catalog.RANK_SEED[rankKey] || s.customRanks.has(rankKey)) throw Object.assign(new Error('dup'), { code: '23505' });
+      const row = { rank_key: rankKey, label, description: description ?? null, is_system: false, seeded_rank: null, created_by: String(createdBy) };
+      s.customRanks.set(rankKey, row);
+      return copy(row);
+    },
+    async assignRank({ builderId, rankKey, assignedBy }) {
+      const id = String(builderId);
+      if (!s.builders.has(id)) throw Object.assign(new Error('fk'), { code: '23503' });
+      if (s.assignments.some((a) => a.builder_id === id && a.rank_key === rankKey)) return false;
+      s.assignments.push({ builder_id: id, rank_key: rankKey, assigned_by: assignedBy == null ? null : String(assignedBy) });
+      return true;
+    },
+    async unassignRank({ builderId, rankKey }) {
+      const before = s.assignments.length;
+      s.assignments = s.assignments.filter((a) => !(a.builder_id === String(builderId) && a.rank_key === rankKey));
+      return s.assignments.length < before;
+    },
+    async listAssignments() { return copy(s.assignments); },
+    async getActiveBuildersWithRank(rankKeys) {
+      return [...s.builders.values()]
+        .filter((b) => isLive(b) && heldRanks(b.id).some((r) => rankKeys.includes(r)))
+        .sort((a, b) => Number(a.id) - Number(b.id))
+        .map((b) => ({ builder_id: b.id, github_login: b.github_login, display_name: b.display_name }));
+    },
+    async builderHoldsRankActive(id, rankKeys) {
+      const b = s.builders.get(String(id));
+      return isLive(b) && heldRanks(id).some((r) => rankKeys.includes(r));
+    },
+    async countActiveBuilders() { return [...s.builders.values()].filter(isLive).length; },
+    async openBoardItem({ subjectType, subjectId, openedBy = null, constitution, windowMinutes = null }) {
+      if (s.items.some((i) => i.subject_type === subjectType && i.subject_id === String(subjectId) && !i.closed_at)) return null;
+      const row = {
+        id: next(), subject_type: subjectType, subject_id: String(subjectId),
+        opened_by: openedBy == null ? null : String(openedBy), opened_at: tick(),
+        closes_at: windowMinutes == null ? null : `in ${windowMinutes} minutes`,
+        closed_at: null, outcome: null, constitution: copy(constitution || {}),
+      };
+      s.items.push(row);
+      return copy(row);
+    },
+    async getOpenBoardItem(type, subjectId) {
+      return copy(s.items.find((i) => i.subject_type === type && i.subject_id === String(subjectId) && !i.closed_at)) || null;
+    },
+    async getBoardItemForVote(id) {
+      const i = s.items.find((x) => x.id === String(id));
+      return i ? withExpiry(i) : null;
+    },
+    async getBoardItemAuthor(item) {
+      if (!item) return null;
+      if (item.subject_type === 'full_idea') {
+        const idea = s.ideas.get(String(item.subject_id));
+        return idea ? idea.captured_by : null;
+      }
+      return item.opened_by ?? null;
+    },
+    async insertBoardVote({ itemId, voterId, direction, reasonMd = null, sectionKey = null }) {
+      if (s.votes.some((v) => v.item_id === String(itemId) && v.voter_id === String(voterId))) return null;
+      const row = { id: next(), item_id: String(itemId), voter_id: String(voterId), direction, reason_md: reasonMd, section_key: sectionKey, cast_at: tick() };
+      s.votes.push(row);
+      return copy(row);
+    },
+    async getBoardVote(itemId, voterId) {
+      return copy(s.votes.find((v) => v.item_id === String(itemId) && v.voter_id === String(voterId))) || null;
+    },
+    async insertVoteKarma({ voterId, itemId, delta }) { s.karma.push({ builder_id: String(voterId), reason: `vote:${itemId}`, delta }); },
+    async getVotesForItem(id) { return s.votes.filter((v) => v.item_id === String(id)).map(copy); },
+    async getVotesForItems(ids) { const want = ids.map(String); return s.votes.filter((v) => want.includes(v.item_id)).map(voteRow); },
+    async closeBoardItem({ itemId, outcome, afterClose = null }) {
+      const i = s.items.find((x) => x.id === String(itemId) && !x.closed_at);
+      if (!i) return null;
+      // A transaction: the close and whatever rides it land together or not at all.
+      const rulesBefore = new Map(s.rules);
+      i.closed_at = tick();
+      i.outcome = outcome;
+      if (typeof afterClose === 'function') {
+        try {
+          await afterClose({ query: async () => { throw new Error('walk store: no raw SQL inside a close'); } }, copy(i));
+        } catch (err) {
+          i.closed_at = null;
+          i.outcome = null;
+          s.rules = rulesBefore;
+          throw err;
+        }
+      }
+      return copy(i);
+    },
+    async createAmendment({ proposed, rationaleMd = null, proposedBy, kind = 'constitution' }) {
+      const row = { id: next(), proposed: copy(proposed), rationale_md: rationaleMd, proposed_by: String(proposedBy), kind };
+      s.amendments.set(row.id, row);
+      return copy(row);
+    },
+    async getAmendment(id) { return copy(s.amendments.get(String(id))) || null; },
+    async listAmendmentHistory(limit = 50) {
+      return s.items
+        .filter((i) => i.subject_type === 'constitutional_amendment' && i.closed_at)
+        .sort((a, b) => (a.closed_at < b.closed_at ? 1 : -1))
+        .slice(0, limit)
+        .map((i) => {
+          const a = s.amendments.get(i.subject_id) || {};
+          return {
+            item_id: i.id, amendment_id: i.subject_id, proposed: copy(a.proposed), rationale_md: a.rationale_md,
+            proposed_by: a.proposed_by, opened_at: i.opened_at, closed_at: i.closed_at, outcome: i.outcome,
+            decided_under: copy(i.constitution), kind: a.kind || 'constitution',
+          };
+        });
+    },
+    async listDecisionRules() { return [...s.rules.values()].map(copy); },
+    // The SQL's guard: written only by a PASSED decision-rules amendment item.
+    async applyDecisionRules(_client, { itemId, rules }) {
+      const i = s.items.find((x) => x.id === String(itemId));
+      const a = i && s.amendments.get(i.subject_id);
+      const allowed = i && a && i.subject_type === 'constitutional_amendment' && i.outcome === 'passed' && a.kind === 'decision_rules';
+      if (!allowed) throw new Error(`decision rules not written (item ${itemId} is not a passed decision-rules amendment)`);
+      for (const r of rules) {
+        s.rules.set(r.area, { area: r.area, decided_by: r.decided_by, rule: r.rule, who: r.who, set_by_item_id: String(itemId), updated_at: tick() });
+      }
+      return rules.length;
+    },
+    async createMatter({ area, title, detailMd = null, action = null, proposedBy }) {
+      const row = { id: next(), area, title, detail_md: detailMd, action: copy(action), proposed_by: String(proposedBy) };
+      s.matters.set(row.id, row);
+      return copy(row);
+    },
+    async getMatter(id) { return copy(s.matters.get(String(id))) || null; },
+    async getMatterSubjects(ids) { return ids.map((id) => s.matters.get(String(id))).filter(Boolean).map(copy); },
+    async getTaskStatuses(ids) {
+      return ids.map(String).filter((id) => s.tasks.has(id)).map((id) => ({ id, status: s.tasks.get(id).status }));
+    },
+    async listLatestGenesisStageItems() {
+      const latest = new Map();
+      for (const i of s.items.filter((x) => x.subject_type === 'genesis_stage')) latest.set(i.subject_id, i);
+      return [...latest.values()].map(withExpiry);
+    },
+    async insertAuthorRatifyKarma({ authorId, itemId, delta }) {
+      const reason = `board.item.ratified:${itemId}`;
+      if (s.karma.some((k) => k.reason === reason)) return false;
+      s.karma.push({ builder_id: String(authorId), reason, delta });
+      return true;
+    },
+    async getIdeaCompleteness(id) { const idea = s.ideas.get(String(id)); return idea ? idea.completeness : null; },
+  };
+  return { s, fns };
+}
+
+function installStore(govDb, fns, unexpected) {
+  for (const k of Object.keys(govDb)) {
+    if (typeof govDb[k] !== 'function') continue;
+    govDb[k] = fns[k] || (async () => {
+      unexpected.push(k);
+      throw new Error(`walk store: unexpected db call ${k}`);
+    });
+  }
+}
+
+// ── the walk ────────────────────────────────────────────────────────────────
+
+async function runWalk() {
+  // The constitution is host content: point the instance root at a throwaway folder
+  // BEFORE anything reads it, so a ratified charter is written there (the real
+  // applyBoardAmendment) and never into this checkout.
+  const instanceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'government-walk-'));
+  process.env.BONGOS_INSTANCE_ROOT = instanceRoot;
+  delete process.env.DATABASE_URL; // the walk never touches a real database
+  // The modules' info lines (a fence switched, a budget set) would bury the table.
+  if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = 'warn';
+
+  const req = (rel) => require(path.join(ROOT, rel));
+  const api = req('src/module-api.js');
+  const seams = req('src/module-seams.js');
+  const authMod = req('src/bongos/auth.js');
+  const projectSettings = req('src/bongos/project-settings.js');
+  const { attachFail } = req('src/bongos/middleware/error-envelope.js');
+  const catalog = req('modules/government/catalog.js');
+  const govDb = req('modules/government/db.js');
+  const config = req('modules/government/config.js');
+  const board = req('modules/government/board.js');
+  const charter = req('modules/government/charter.js');
+  const membership = req('modules/government/board-membership.js');
+  const dr = req('modules/government/decision-rules.js');
+  const genesis = req('modules/onboarding/genesis-home.js');
+  const autoDb = req('modules/autonomy/db.js');
+  const lifeDb = req('modules/lifecycle/db.js');
+  const doneWhen = req('modules/lifecycle/done-when.js');
+  const doneWhenRoutes = req('modules/lifecycle/routes/done-when.js');
+  const gateRoutes = req('modules/lifecycle/routes/gate-approvals.js');
+  const express = require('express');
+  const http = require('http');
+
+  const { s: store, fns } = makeStore(catalog);
+  installStore(govDb, fns, store.unexpected);
+
+  // Project settings (founding mode + the plan) live in memory.
+  const settings = new Map();
+  projectSettings.getSetting = async (k) => (settings.has(k) ? { key: k, value: settings.get(k) } : null);
+  projectSettings.setSetting = async (k, v) => { settings.set(k, String(v)); return { key: k, value: String(v) }; };
+
+  // What passed matters write into other modules, recorded.
+  const effects = { fence: null, allowedGoals: [], overrides: [], gates: [], criteria: new Map([['9', false]]), budgets: new Map() };
+  autoDb.setFenceEnabled = async ({ enabled }) => { effects.fence = enabled; return { enabled }; };
+  autoDb.allowGoal = async ({ goalId }) => { effects.allowedGoals.push(String(goalId)); return { goal_id: goalId }; };
+  lifeDb.decideOverrideRequest = async ({ requestId, decision }) => { effects.overrides.push([String(requestId), decision]); return {}; };
+  gateRoutes.approveGatePr = async ({ number }) => { effects.gates.push(String(number)); return { ok: true, body: {} }; };
+  doneWhen.getCriterion = async (id) => (effects.criteria.has(String(id)) ? { id, satisfied: effects.criteria.get(String(id)) } : null);
+  doneWhenRoutes.satisfyByOverride = async ({ criterionId }) => { effects.criteria.set(String(criterionId), true); return { updated: {}, goalResult: {} }; };
+
+  // Ports the routers would otherwise reach a database for: the genesis seeder and
+  // the Treasury write. Registered first, so the routers' own registrations step aside.
+  const STAGE_TASK_IDS = { scope: '9001', strategize: '9002', charter: '9003', legalize: '9004', legislation: '9005' };
+  seams.registerProvider('lifecycle.kickoffSeed', {
+    seedGenesis: async () => {
+      for (const [stage, id] of Object.entries(STAGE_TASK_IDS)) store.tasks.set(id, { id, stage, title: `${stage} (walk)`, status: 'ready' });
+      return { seeded: 5 };
+    },
+    genesisTasks: async () => {
+      const out = {};
+      for (const t of store.tasks.values()) (out[t.stage] = out[t.stage] || []).push({ id: t.id, title: t.title, status: t.status });
+      return out;
+    },
+  });
+  seams.registerProvider('reward', {
+    setBuilderMonthlyBudget: async (id, usd) => {
+      if (!store.builders.has(String(id))) return null;
+      effects.budgets.set(String(id), usd);
+      return { id, monthly_budget_usd: usd };
+    },
+  });
+
+  // The session: whoever the request says it is, from this project's people.
+  const asHeader = 'x-walk-builder';
+  const fakeBuilder = (r, res, nextFn) => {
+    const b = store.builders.get(String(r.headers[asHeader] || ''));
+    if (!b || b.status !== 'active') return res.status(401).json({ error: { code: 'not_signed_in' } });
+    r.builder = { id: Number(b.id), rank: b.rank, github_login: b.github_login, display_name: b.display_name };
+    return nextFn();
+  };
+  api.requireBuilder = fakeBuilder;
+  authMod.requireBuilder = fakeBuilder;
+
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  for (const rel of ROUTERS) app.use(req(rel)());
+  const server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const BASE = `http://127.0.0.1:${server.address().port}`;
+
+  async function call(as, method, p, body) {
+    const res = await fetch(`${BASE}${p}`, {
+      method,
+      headers: { [asHeader]: as, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    let json = null;
+    try { json = await res.json(); } catch (_) { /* no body */ }
+    return { status: res.status, json };
+  }
+  const code = (r) => (r.json && r.json.error && r.json.error.code) || null;
+  const vote = (as, itemId, direction = 'yes') => call(as, 'POST', `/government/board/items/${itemId}/votes`,
+    direction === 'yes' ? { direction } : { direction, reason_md: 'Not yet: the walk objects.', section_key: 'purpose' });
+  const itemOf = (id) => store.items.find((i) => i.id === String(id)) || null;
+  const constitution = async () => (await call(FOUNDER, 'GET', '/government/constitution')).json;
+  const live = () => config.loadGovernmentConfig().board;
+  const stateOf = (id) => { const i = itemOf(id); return !i ? 'missing' : i.closed_at ? i.outcome : 'open'; };
+
+  // ── the table ──
+  const rows = [];
+  let current = '';
+  const section = (name) => { current = name; };
+  async function check(name, expected, fn) {
+    let got;
+    let pass = false;
+    try {
+      const out = await fn();
+      got = out.got;
+      pass = out.pass === true;
+    } catch (err) {
+      got = `threw: ${err && err.message}`;
+    }
+    const n = rows.filter((r) => r.section === current).length + 1;
+    rows.push({ section: current, key: `${current.split(' ')[0]}${n}`, name, expected, got: String(got), pass });
+    return pass;
+  }
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+  // Every voter in `voters` votes; returns the state after each vote.
+  async function voteAll(itemId, voters, direction = 'yes') {
+    const after = [];
+    for (const v of voters) {
+      const r = await vote(v, itemId, direction);
+      after.push(r.status === 201 ? stateOf(itemId) : `${r.status} ${code(r)}`);
+      if (stateOf(itemId) !== 'open') break;
+    }
+    return after;
+  }
+
+  // ── setup: the council and the rank People's acts give ──
+  await call(FOUNDER, 'POST', '/government/ranks', { rank_key: 'council', label: 'Council' });
+  await call(FOUNDER, 'POST', '/government/ranks', { rank_key: 'tester', label: 'Tester' });
+  for (const id of COUNCIL) await call(FOUNDER, 'POST', '/government/assignments', { builder_id: Number(id), rank_key: 'council' });
+
+  // ══ 1. Genesis ══
+  section('G Genesis');
+  const CHOSEN = 'timocratic-republic';
+  await check('The test project is born a Monarchy (the state every genesis starts from)', 'reads as monarchy', async () => {
+    const f = charter.readCharter(live()).form;
+    return { got: `reads as ${f}`, pass: f === 'monarchy' };
+  });
+  await check('Founding starts', '200, stage decide', async () => {
+    const r = await call(FOUNDER, 'POST', '/founding/start');
+    const stage = r.json && r.json.mode && r.json.mode.stage;
+    return { got: `${r.status}, stage ${stage}`, pass: r.status === 200 && stage === 'decide' };
+  });
+  let charterItem = null;
+  await check(`Deciding with ${CHOSEN} saves the plan and files the pick as a charter amendment`, 'plan saved, charter sitting, one vote decides', async () => {
+    const r = await call(FOUNDER, 'POST', '/founding/plan', { government: CHOSEN });
+    const c = (r.json && r.json.charter) || {};
+    charterItem = c.item_id || null;
+    return { got: `${r.status}, charter ${c.state}, one vote decides ${c.one_vote_decides}`, pass: r.status === 200 && c.state === 'sitting' && c.one_vote_decides === true };
+  });
+  await check('Saving the plan moved the project to its first stage', 'stage scope', async () => {
+    const g = await genesis.readGenesis();
+    return { got: `stage ${g && g.stage}`, pass: !!g && g.stage === 'scope' };
+  });
+  await check('The founder\'s one yes ratifies the pick under the Monarchy it is born with', 'passed', async () => {
+    const r = await vote(FOUNDER, charterItem);
+    return { got: `${r.status} ${r.json && r.json.outcome}`, pass: r.status === 201 && r.json.outcome === 'passed' };
+  });
+  await check('The constitution now reads as the government chosen at decide', `reads as ${CHOSEN}, no divergence`, async () => {
+    const c = await constitution();
+    const f = c && c.charter && c.charter.reads_as && c.charter.reads_as.form;
+    return { got: `reads as ${f}, divergence ${c && c.divergence ? 'yes' : 'none'}`, pass: f === CHOSEN && !c.divergence };
+  });
+  await check('A stage with unfinished tasks cannot be put to the board', '409 stage_tasks_unfinished', async () => {
+    const r = await call(FOUNDER, 'POST', '/founding/stages/scope/close');
+    return { got: `${r.status} ${code(r)}`, pass: r.status === 409 && code(r) === 'stage_tasks_unfinished' };
+  });
+  const timocrats = ['42', '43', '44'];
+  for (const stage of genesis.PROPER) {
+    store.tasks.get(STAGE_TASK_IDS[stage]).status = 'shipped';
+    let itemId = null;
+    await check(`${stage}: its finished stage is put to the board`, 'a sitting under the chosen government', async () => {
+      const r = await call(FOUNDER, 'POST', `/founding/stages/${stage}/close`);
+      itemId = r.json && r.json.item_id;
+      const snap = itemId && itemOf(itemId) ? itemOf(itemId).constitution : {};
+      const reads = charter.readCharter(snap).form;
+      return { got: `${r.status}, sitting under ${reads}`, pass: r.status === 200 && !!itemId && reads === CHOSEN };
+    });
+    await check(`${stage}: the founder alone cannot close it; every trusted member's yes does`, 'open, open, passed', async () => {
+      const after = await voteAll(itemId, timocrats);
+      return { got: after.join(', '), pass: same(after, ['open', 'open', 'passed']) };
+    });
+    const nextStage = genesis.PROPER[genesis.PROPER.indexOf(stage) + 1];
+    await check(`${stage}: a pass moves the project on`, nextStage ? `stage ${nextStage}` : 'come-alive door opens', async () => {
+      const g = await genesis.readGenesis();
+      if (nextStage) return { got: `stage ${g && g.stage}`, pass: !!g && g.stage === nextStage };
+      return { got: `can come alive ${g && g.can_come_alive}`, pass: !!g && g.can_come_alive === true };
+    });
+  }
+  await check('The project comes alive', '200, founding over', async () => {
+    const r = await call(FOUNDER, 'POST', '/founding/alive');
+    const g = await genesis.readGenesis();
+    return { got: `${r.status}, founding ${g ? 'still on' : 'over'}`, pass: r.status === 200 && g === null };
+  });
+  await check('Alive, it is still governed by the choice', `reads as ${CHOSEN}`, async () => {
+    const f = charter.readCharter(live()).form;
+    return { got: `reads as ${f}`, pass: f === CHOSEN };
+  });
+
+  // ══ 2. Every form ══
+  section('F Forms');
+  let ideaSeq = 500;
+  // A probe: a Full Idea (by someone who left, so no author rule bends the count)
+  // put to the board in force, voted on to show who may vote and what passes.
+  async function probe() {
+    const id = String(++ideaSeq);
+    store.ideas.set(id, { captured_by: '47', completeness: 80 });
+    const out = await board.openWindowForFullIdea({ ideaId: id, completenessScore: 80 });
+    return out.item.id;
+  }
+  const FORMS = [
+    // key, how to switch, who is seated, the yes-path states, the objection path (voter order + states)
+    { key: 'timocratic-republic', label: 'Timocratic Republic (in force from genesis)', body: null,
+      seated: ['42', '43', '44'], outsider: '45', yes: ['open', 'open', 'passed'], no: { voters: ['43', '42', '44'], dir: ['no', 'yes', 'yes'], states: ['open', 'open', 'returned'] },
+      rule: 'consent: a yes does not end it; full turnout passes; one objection returns it' },
+    { key: 'direct-democracy', label: 'Direct Democracy', body: { form: 'direct-democracy' },
+      seated: ACTIVE_IDS, outsider: null, yes: ['open', 'open', 'open', 'open', 'passed'], no: { voters: ['46', '42', '43', '44', '45'], dir: ['no', 'yes', 'yes', 'yes', 'yes'], states: ['open', 'open', 'open', 'open', 'returned'] },
+      rule: 'consent over every builder' },
+    { key: 'foundation', label: 'Foundation (council rank)', body: { form: 'foundation', council_rank: 'council' }, selfRemoval: true,
+      seated: COUNCIL, outsider: '42', yes: ['open', 'passed'], no: { voters: ['44', '43'], dir: ['no', 'yes'], states: ['open', 'returned'] },
+      rule: 'consent over the council only' },
+    { key: 'custom', label: 'Every builder, majority (no named form)', body: { franchise: 'everyone', pass_rule: 'majority' }, passRule: 'majority',
+      seated: ACTIVE_IDS, outsider: null, yes: ['open', 'open', 'passed'], no: { voters: ['42', '43', '44'], dir: ['no', 'no', 'no'], states: ['open', 'open', 'returned'] },
+      rule: 'majority: 3 of 5 yes carries; 3 of 5 no makes it unreachable' },
+    { key: 'custom', label: 'Every builder, unanimous (no named form)', body: { pass_rule: 'unanimous' }, passRule: 'unanimous',
+      seated: ACTIVE_IDS, outsider: null, yes: ['open', 'open', 'open', 'open', 'passed'], no: { voters: ['43'], dir: ['no'], states: ['returned'] },
+      rule: 'unanimous: one yes does not end it; full turnout passes; one objection returns it at once' },
+    { key: 'monarchy', label: 'Monarchy / BDFL', body: { form: 'monarchy' },
+      seated: ['42'], outsider: '43', yes: ['passed'], no: { voters: ['42'], dir: ['no'], states: ['returned'] },
+      rule: 'first yes: the founder\'s one vote decides' },
+  ];
+  let seatedNow = ['42', '43', '44']; // who sits under the form in force
+  for (const form of FORMS) {
+    const tag = form.label;
+    if (form.body) {
+      let itemId = null;
+      await check(`${tag}: the switch is filed as a charter amendment`, form.selfRemoval ? '409 proposer_would_lose_their_seat, then 201 once acknowledged' : '201', async () => {
+        let r = await call(FOUNDER, 'POST', '/government/board/charter', form.body);
+        let got = `${r.status}`;
+        if (form.selfRemoval) {
+          const first = `${r.status} ${code(r)}`;
+          r = await call(FOUNDER, 'POST', '/government/board/charter', { ...form.body, acknowledge_self_removal: true });
+          got = `${first}, then ${r.status}`;
+          itemId = r.json && r.json.item && r.json.item.id;
+          return { got, pass: first === '409 proposer_would_lose_their_seat' && r.status === 201 && !!itemId };
+        }
+        itemId = r.json && r.json.item && r.json.item.id;
+        return { got, pass: r.status === 201 && !!itemId };
+      });
+      await check(`${tag}: the government in force decides the switch`, 'passed once every seated member has said yes', async () => {
+        const after = await voteAll(itemId, seatedNow);
+        return { got: after.join(', '), pass: after[after.length - 1] === 'passed' };
+      });
+    }
+    await check(`${tag}: the constitution reads as it`, form.key === 'custom' ? `reads as Custom, pass rule ${form.passRule}` : `reads as ${form.key}`, async () => {
+      const c = await constitution();
+      const ra = (c && c.charter && c.charter.reads_as) || {};
+      const ok = ra.form === form.key && (!form.passRule || ra.pass_rule === form.passRule) && !c.divergence;
+      return { got: `reads as ${ra.form === 'custom' ? 'Custom' : ra.form}${form.passRule ? `, pass rule ${ra.pass_rule}` : ''}${c.divergence ? ', DIVERGES' : ''}`, pass: ok };
+    });
+    await check(`${tag}: who is seated`, `builders ${form.seated.join(', ')}`, async () => {
+      const members = (await membership.resolveBoardMembers(live())).map((m) => String(m.builder_id));
+      return { got: `builders ${members.join(', ') || 'none'}`, pass: same(members, form.seated) };
+    });
+    if (form.outsider) {
+      await check(`${tag}: someone not seated cannot vote`, '403 not_board_member', async () => {
+        const id = await probe();
+        const r = await vote(form.outsider, id);
+        return { got: `${r.status} ${code(r)}`, pass: r.status === 403 && code(r) === 'not_board_member' };
+      });
+    }
+    await check(`${tag}: what passes (${form.rule})`, form.yes.join(', '), async () => {
+      const id = await probe();
+      const after = await voteAll(id, form.seated);
+      return { got: after.join(', '), pass: same(after, form.yes) };
+    });
+    await check(`${tag}: what returns`, form.no.states.join(', '), async () => {
+      const id = await probe();
+      const after = [];
+      for (let k = 0; k < form.no.voters.length; k += 1) {
+        const r = await vote(form.no.voters[k], id, form.no.dir[k]);
+        after.push(r.status === 201 ? stateOf(id) : `${r.status} ${code(r)}`);
+        if (stateOf(id) !== 'open') break;
+      }
+      return { got: after.join(', '), pass: same(after, form.no.states) };
+    });
+    seatedNow = form.seated;
+  }
+
+  // ══ 3. Every building ══
+  section('B Buildings');
+  // Who decides at a building is changed by an amendment, decided here under the
+  // Monarchy the walk restored: the founder's one yes.
+  async function setRules(rules) {
+    const r = await call(FOUNDER, 'POST', '/government/board/decision-rules', { rules });
+    const itemId = r.json && r.json.item && r.json.item.id;
+    if (r.status !== 201 || !itemId) return { ok: false, why: `${r.status} ${code(r)}` };
+    const v = await vote(FOUNDER, itemId);
+    return { ok: v.status === 201 && v.json.outcome === 'passed', why: `vote ${v.status} ${v.json && v.json.outcome}` };
+  }
+  const rowOf = async (area) => {
+    const c = await constitution();
+    return ((c.decision_rules && c.decision_rules.areas) || []).find((a) => a.area === area) || {};
+  };
+  for (const area of dr.AREAS.filter((a) => a.acts.length)) {
+    await check(`${area.name}: set to decide by vote (council, majority) by a passed amendment`, 'sitting, majority vote', async () => {
+      const out = await setRules([{ area: area.key, decided_by: 'rank:council', rule: 'majority' }]);
+      const row = await rowOf(area.key);
+      return { got: `${out.ok ? 'passed' : out.why}; ${row.sitting ? 'sitting' : 'as today'}, ${row.rule_words}`, pass: out.ok && row.sitting === true && row.rule === 'majority' };
+    });
+    for (const act of area.acts) {
+      await check(`${area.name}: acting alone on ${act} is refused`, `409 decided_by_sitting (${area.key})`, async () => {
+        const [method, p, body] = REQUESTS[act];
+        const r = await call(FOUNDER, method, p, body);
+        const d = (r.json && r.json.error && (r.json.error.details || r.json.error)) || {};
+        return { got: `${r.status} ${code(r)} (${d.area})`, pass: r.status === 409 && code(r) === 'decided_by_sitting' && d.area === area.key };
+      });
+    }
+    await check(`${area.name}: restored to as today, every one of its ${area.acts.length} routes reaches its own handler again`, 'none refused', async () => {
+      const out = await setRules([{ area: area.key, decided_by: 'gate' }]);
+      const bad = [];
+      for (const act of area.acts) {
+        const [method, p, body] = REQUESTS[act];
+        const r = await call(FOUNDER, method, p, body);
+        const reached = act.includes('/government/assignments') ? r.status < 300 : (r.status >= 400 && r.status < 500 && r.status !== 403 && code(r) !== 'decided_by_sitting');
+        if (!reached) bad.push(`${act} ${r.status} ${code(r)}`);
+      }
+      return { got: `${out.ok ? 'restored' : out.why}; ${bad.length ? bad.join('; ') : 'none refused'}`, pass: out.ok && bad.length === 0 };
+    });
+  }
+
+  // ══ 4. Every matter action ══
+  section('M Matters');
+  const SITTINGS = {
+    people: 'consent', automation: 'majority', release: 'unanimous', review: 'signoff', treasury: 'first',
+  };
+  await check('Each acting building is put to the council by one passed amendment', Object.entries(SITTINGS).map(([a, r]) => `${a} ${r}`).join(', '), async () => {
+    const out = await setRules(Object.entries(SITTINGS).map(([area, rule]) => ({ area, decided_by: 'rank:council', rule })));
+    const got = [];
+    for (const area of Object.keys(SITTINGS)) got.push(`${area} ${(await rowOf(area)).rule}`);
+    return { got: `${out.ok ? '' : `${out.why}; `}${got.join(', ')}`, pass: out.ok && same(got, Object.entries(SITTINGS).map(([a, r]) => `${a} ${r}`)) };
+  });
+  // Open a matter as the founder (not on the council), pass it with council votes.
+  async function passMatter(area, title, action, voters = COUNCIL, direction = 'yes') {
+    const r = await call(FOUNDER, 'POST', '/government/board/matters', { area, title, action });
+    const itemId = r.json && r.json.item && r.json.item.id;
+    if (r.status !== 201 || !itemId) return { outcome: `not opened: ${r.status} ${code(r)}` };
+    const after = await voteAll(itemId, voters, direction);
+    return { outcome: stateOf(itemId), after };
+  }
+  const holds = (id, rank) => store.assignments.some((a) => a.builder_id === id && a.rank_key === rank);
+  // Did the act happen? One observation per matter action in MATTER_PLAN.
+  const HAPPENED = {
+    'people.assign_rank': () => holds('46', 'tester'),
+    'people.unassign_rank': () => !holds('46', 'tester'),
+    'automation.switch_on': () => effects.fence === true,
+    'automation.switch_off': () => effects.fence === false,
+    'automation.allow_goal': () => effects.allowedGoals.includes('77'),
+    'release.approve_override': () => effects.overrides.some(([id, d]) => id === '5' && d === 'approve'),
+    'release.approve_gate': () => effects.gates.includes('1500'),
+    'review.satisfy_criterion': () => effects.criteria.get('9') === true,
+    'treasury.set_budget': () => effects.budgets.get('45') === 50,
+  };
+  const MATTERS = MATTER_PLAN.map(([area, title, action, effect]) => [area, title, action, effect, HAPPENED[`${area}.${action.type}`]]);
+  // How each building's sitting closes as Ben then Cy say yes, under its rule: the
+  // two-member consent, majority and unanimous sittings need both; first yes and
+  // sign-off (by someone who did not propose it) close on the first.
+  const CLOSES = { people: 'open, passed', automation: 'open, passed', release: 'open, passed', review: 'passed', treasury: 'passed' };
+  await check('Someone the building\'s row does not seat cannot vote on its matter', '403 not_board_member', async () => {
+    const r = await call(FOUNDER, 'POST', '/government/board/matters', { area: 'automation', title: 'Who may vote here?' });
+    const itemId = r.json && r.json.item && r.json.item.id;
+    const v = await vote(FOUNDER, itemId);
+    await voteAll(itemId, COUNCIL, 'no'); // close the probe so it carries out nothing
+    return { got: `${r.status}, then ${v.status} ${code(v)}`, pass: r.status === 201 && v.status === 403 && code(v) === 'not_board_member' };
+  });
+  for (const [area, title, action, effect, happened] of MATTERS) {
+    await check(`${area} ${action.type}: "${title}" passes under ${SITTINGS[area]} and is carried out`, `${CLOSES[area]}; ${effect}`, async () => {
+      const out = await passMatter(area, title, action);
+      const done = happened();
+      const steps = out.after ? out.after.join(', ') : out.outcome;
+      return { got: `${steps}; ${done ? effect : `NOT ${effect}`}`, pass: out.outcome === 'passed' && steps === CLOSES[area] && done };
+    });
+  }
+  await check('A returned matter carries out nothing', 'returned; fence unchanged', async () => {
+    const before = effects.fence;
+    const out = await passMatter('automation', 'Switch it on again', { type: 'switch_on' }, COUNCIL, 'no');
+    return { got: `${out.outcome}; fence ${effects.fence === before ? 'unchanged' : 'CHANGED'}`, pass: out.outcome === 'returned' && effects.fence === before };
+  });
+  await check('Every building restored to as today', 'all as today', async () => {
+    const out = await setRules(Object.keys(SITTINGS).map((area) => ({ area, decided_by: 'gate' })));
+    const c = await constitution();
+    const sitting = c.decision_rules.areas.filter((a) => a.sitting).map((a) => a.area);
+    return { got: `${out.ok ? '' : `${out.why}; `}${sitting.length ? `still sitting: ${sitting.join(', ')}` : 'all as today'}`, pass: out.ok && sitting.length === 0 };
+  });
+
+  // Any storage the fake did not model is a finding about the walk itself.
+  section('S Store');
+  await check('No code path reached storage the walk does not model', 'none', async () => {
+    const u = [...new Set(store.unexpected)];
+    return { got: u.length ? u.join(', ') : 'none', pass: u.length === 0 };
+  });
+
+  await new Promise((r) => server.close(r));
+  try { fs.rmSync(instanceRoot, { recursive: true, force: true }); } catch (_) { /* best effort */ }
+  return { mode: 'in-memory', rows };
+}
+
+// ── the table, as Markdown ──────────────────────────────────────────────────
+
+const SECTION_TITLES = {
+  G: '1. Genesis: founded, decided, five stages closed, alive',
+  F: '2. Every form: who can vote and what passes',
+  B: '3. Every building: decide by vote refuses acting alone',
+  M: '4. Every matter action: passed and carried out',
+  S: 'The walk itself',
+};
+const cell = (v) => String(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+
+function renderTable({ mode, rows }) {
+  const out = [];
+  out.push('<!-- GENERATED by scripts/gds/government-walk.js - do not hand-edit. Regenerate: node scripts/gds/government-walk.js --write -->');
+  out.push('');
+  out.push('# The government walk');
+  out.push('');
+  out.push('One repeatable walk over a throwaway test project\'s government (task 1004658, goal 1000111). Re-run it with `node scripts/gds/government-walk.js`; `tests/government_walk.mjs` re-runs it in CI and fails if any row below changes, so this table is kept true, not just written once.');
+  out.push('');
+  out.push(`**Mode: ${mode}.** Every request is real HTTP through the real routers, and every decision is the real code: the permission gate, board membership, the vote, the tally, the close, the charter apply (written to a throwaway folder), the decision-rules apply, the act-alone gate on every building, and each module's matter act. The storage underneath is an in-memory stand-in for the government tables with the same guards (no Postgres was available where this was built), and the writes a passed matter makes into other modules (the automation fence, override requests, criteria, the GitHub gate approval, budgets) are recorded in memory. A real-database run of this walk is not built yet.`);
+  out.push('');
+  out.push('The test project: Ada founds it (Archon); Ben and Cy are trusted builders (Metic) and sit on a Council rank; Dee (Thetes) and Eve (Xenos) are newer builders; Fay has left and only authors the probe ideas, so no probe is decided by its own author.');
+  out.push('');
+  const keys = Object.keys(SECTION_TITLES).filter((k) => rows.some((r) => r.section.startsWith(k)));
+  out.push('| Section | Pass | Fail |');
+  out.push('|---|---|---|');
+  for (const k of keys) {
+    const rs = rows.filter((r) => r.section.startsWith(k));
+    out.push(`| ${SECTION_TITLES[k]} | ${rs.filter((r) => r.pass).length} | ${rs.filter((r) => !r.pass).length} |`);
+  }
+  out.push(`| **All** | **${rows.filter((r) => r.pass).length}** | **${rows.filter((r) => !r.pass).length}** |`);
+  for (const k of keys) {
+    out.push('');
+    out.push(`## ${SECTION_TITLES[k]}`);
+    out.push('');
+    out.push('| # | Check | Expected | Got | Result |');
+    out.push('|---|---|---|---|---|');
+    for (const r of rows.filter((x) => x.section.startsWith(k))) {
+      const bug = KNOWN_BUGS[r.key];
+      const result = r.pass ? 'PASS' : `**FAIL**${bug ? ` (${bug})` : ''}`;
+      out.push(`| ${r.key} | ${cell(r.name)} | ${cell(r.expected)} | ${cell(r.got)} | ${result} |`);
+    }
+  }
+  out.push('');
+  return out.join('\n');
+}
+
+async function main(argv) {
+  // Logs from the modules go to stderr so the table on stdout stays readable.
+  const realLog = console.log;
+  console.log = (...a) => console.error(...a);
+  const result = await runWalk();
+  const md = renderTable(result);
+  console.log = realLog;
+  const fails = result.rows.filter((r) => !r.pass);
+  if (argv.includes('--check')) {
+    const committed = fs.existsSync(DOC_PATH) ? fs.readFileSync(DOC_PATH, 'utf8').replace(/\r\n/g, '\n') : '';
+    if (committed !== md) {
+      process.stdout.write(md);
+      process.stdout.write(`\ngovernment-walk: the committed table (${path.relative(ROOT, DOC_PATH)}) differs from this run. A row changed: find it above, then regenerate with node scripts/gds/government-walk.js --write (and file any new FAIL as a bug under goal 1000111).\n`);
+      return 1;
+    }
+    process.stdout.write(`government-walk: ${result.rows.length - fails.length} pass, ${fails.length} fail - matches the committed table.\n`);
+    return 0;
+  }
+  process.stdout.write(md);
+  if (argv.includes('--write')) {
+    fs.writeFileSync(DOC_PATH, md);
+    process.stdout.write(`\nwrote ${path.relative(ROOT, DOC_PATH)}\n`);
+  }
+  process.stdout.write(`\ngovernment-walk: ${result.rows.length - fails.length} pass, ${fails.length} fail (${result.mode}).\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((exitCode) => process.exit(exitCode), (err) => {
+    console.error(err);
+    process.exit(2);
+  });
+}
+
+module.exports = { runWalk, renderTable, REQUESTS, ROUTERS, MATTER_PLAN, KNOWN_BUGS };