@bongos/core 1.21.113 → 1.21.115

package/modules/government/decision-board.js

@@ -15,8 +15,10 @@
 const api = require('../../src/module-api');
 const db = require('./db');
 const { loadGovernmentConfig, isClockSafe } = require('./config');
-const { isBoardMember } = require('./board-membership');
+const { isBoardMember, resolveBoardMembers } = require('./board-membership');
 const decisionRules = require('./decision-rules');
+const { charterLine, isLeadAct, answerFor, ownerOf, leadsView: leadsBook } = require('./leads');
+const buildouts = require('./buildouts');
 
 const log = api.logger('government');
 
@@ -60,7 +62,15 @@ async function actOnPassedMatter(closed) {
   try {
     matter = await db.getMatter(closed.subject_id);
     const action = matter && matter.action;
-    if (area === 'people' && action && (action.type === 'assign_rank' || action.type === 'unassign_rank')) {
+    if (action && action.type === 'build_out') {
+      // A build-out the vote allowed (task 1004711): put on the record naming
+      // this very item, which government_030's trigger checks.
+      result = { ...result, ...(await actOnBuildOutMatter(closed, matter, area)) };
+    } else if (area === 'people' && action && isLeadAct(action.type)) {
+      // A Lead appointed or removed (task 1004709): carried out here, in one
+      // transaction the table's trigger checks against this very item.
+      result = { ...result, ...(await actOnLeadMatter(closed, action)) };
+    } else if (area === 'people' && action && (action.type === 'assign_rank' || action.type === 'unassign_rank')) {
       // The same walls as the direct route: a custom rank that still exists,
       // never a seeded one (a seeded rank follows the builder's rank — R95b).
       const rank = await db.getRankByKey(action.rank_key);
@@ -111,6 +121,45 @@ async function actOnPassedMatter(closed) {
   };
 }
 
+// A passed appoint_lead / remove_lead (task 1004709). Re-validated first (the
+// stored row was checked when opened and is immutable since); the appointee must
+// still be an active builder of the project. Never throws past the caller's catch.
+async function actOnLeadMatter(closed, action) {
+  const v = validateMatterAction('people', action);
+  if (!v.ok) return { action: action.type || null, done: false, reason: 'bad_action' };
+  const a = v.action;
+  if (a.type === 'appoint_lead' && !(await db.getActiveBuilder(a.builder_id))) {
+    return { action: a.type, done: false, reason: 'builder_gone', building: a.building };
+  }
+  const out = await db.applyLeadAct({ itemId: closed.id, action: a });
+  return {
+    action: a.type,
+    done: out.done === true,
+    building: a.building,
+    ...(a.type === 'appoint_lead' ? { builder_id: String(a.builder_id) } : {}),
+    ...(out.reason ? { reason: out.reason } : {}),
+  };
+}
+
+// A passed build_out (task 1004711). Re-validated first (the stored row was
+// checked when opened and is immutable since). Never throws past the caller's catch.
+async function actOnBuildOutMatter(closed, matter, area) {
+  const v = validateMatterAction(area, matter.action);
+  if (!v.ok) return { action: 'build_out', done: false, reason: 'bad_action' };
+  const a = v.action;
+  const out = await db.insertBuildout({
+    building: a.building, capsule: a.capsule, name: a.name, line: a.line,
+    builtBy: matter.proposed_by == null ? null : matter.proposed_by, itemId: closed.id,
+  });
+  return {
+    action: 'build_out',
+    done: out.done === true,
+    building: a.building,
+    capsule: a.capsule,
+    ...(out.reason ? { reason: out.reason } : {}),
+  };
+}
+
 // ── who decides what: proposing a change (task 1004529) ─────────────────────
 //
 // A change to who decides what at a building is an AMENDMENT — of kind
@@ -180,11 +229,15 @@ const MATTER_DETAIL_MAX = 5000;
 // contributed to 'governor.matterAct' as { area, type, act }. This table is only
 // the SHAPE of each act (field → kind), checked when the matter is opened and
 // again before it acts. 'id' is a positive integer, 'rank' a custom rank key,
-// 'usd' a non-negative amount or null (no limit).
+// 'usd' a non-negative amount or null (no limit), 'building' one of the nine,
+// 'charter' a Lead's one-line charter (absent: the building's default).
 const MATTER_ACTIONS = Object.freeze({
   people: Object.freeze({
     assign_rank: Object.freeze({ builder_id: 'id', rank_key: 'rank' }),
     unassign_rank: Object.freeze({ builder_id: 'id', rank_key: 'rank' }),
+    // task 1004709: the Lead of a building, appointed and removed by vote
+    appoint_lead: Object.freeze({ building: 'building', builder_id: 'id', charter: 'charter' }),
+    remove_lead: Object.freeze({ building: 'building' }),
   }),
   automation: Object.freeze({
     switch_on: Object.freeze({}),
@@ -205,7 +258,12 @@ const MATTER_ACTIONS = Object.freeze({
 const MATTER_ACT_POINT = 'governor.matterAct';
 const MAX_BUDGET_USD = 100000;
 
-function fieldValue(kind, raw) {
+function fieldValue(kind, raw, action) {
+  if (kind === 'building') return decisionRules.AREA_KEYS.includes(raw) ? { ok: true, v: raw } : { ok: false };
+  if (kind === 'charter') {
+    const line = charterLine(raw, action && action.building);
+    return line ? { ok: true, v: line } : { ok: false };
+  }
   if (kind === 'id') {
     const n = Number(raw);
     return Number.isSafeInteger(n) && n > 0 && raw !== null && raw !== '' && typeof raw !== 'boolean' ? { ok: true, v: n } : { ok: false };
@@ -220,6 +278,17 @@ function fieldValue(kind, raw) {
 
 function validateMatterAction(area, action) {
   if (action == null) return { ok: true, action: null };
+  // A build-out (task 1004711) is a matter at the building it adds to — the
+  // Charter's at People (buildouts.matterAreaFor) — carried out here, at every
+  // building, whichever modules are on.
+  if (action && typeof action === 'object' && action.type === 'build_out') {
+    const b = buildouts.checkBuildOut(action);
+    if (!b.ok) return { ok: false, reason: b.reason === 'unknown_field' ? 'unknown_field' : 'bad_action', field: b.field ? `action.${b.field}` : undefined };
+    if (buildouts.matterAreaFor(b.buildout.building) !== area) {
+      return { ok: false, reason: 'bad_action', field: 'action.building', expected: `a build-out is a matter at the building it adds to (${buildouts.matterAreaFor(b.buildout.building)})` };
+    }
+    return { ok: true, action: b.buildout };
+  }
   const acts = MATTER_ACTIONS[area];
   if (!acts) return { ok: false, reason: 'action_not_supported_here', expected: `a matter acts by itself only at ${Object.keys(MATTER_ACTIONS).join(', ')}` };
   if (typeof action !== 'object' || Array.isArray(action)) return { ok: false, reason: 'bad_action' };
@@ -230,8 +299,9 @@ function validateMatterAction(area, action) {
   }
   const out = { type: action.type };
   for (const [k, kind] of Object.entries(shape)) {
-    if (!Object.prototype.hasOwnProperty.call(action, k)) return { ok: false, reason: 'bad_action', field: `action.${k}` };
-    const f = fieldValue(kind, action[k]);
+    // a Lead's charter may be left out: the building's default is filed in its place
+    if (!Object.prototype.hasOwnProperty.call(action, k) && kind !== 'charter') return { ok: false, reason: 'bad_action', field: `action.${k}` };
+    const f = fieldValue(kind, action[k], action);
     if (!f.ok) return { ok: false, reason: 'bad_action', field: `action.${k}` };
     out[k] = f.v;
   }
@@ -256,6 +326,36 @@ async function openMatter({ area, title, detailMd = null, action = null, propose
   const { board } = loadGovernmentConfig();
   const rows = await db.listDecisionRules();
   const resolved = decisionRules.resolveAll(rows, { board }).find((r) => r.area === area);
+  // A Lead is the government's to appoint (task 1004709, ADR 0374): where People
+  // has no sitting of its own (decided as today), the matter sits under the board
+  // in force, like an amendment; where People names a sitting, it sits there.
+  const leadAct = !!(a.action && area === 'people' && isLeadAct(a.action.type));
+  // A build-out (task 1004711, ADR 0378) is the government's to allow, like a
+  // Lead: it sits under the board in force where its building has no sitting of
+  // its own, and ALWAYS when it is a district (a new part of the city) or the
+  // Charter's own (the board's building); otherwise at the building's sitting —
+  // the same places build-rights.js says the vote goes.
+  const isBuildOut = !!(a.action && a.action.type === 'build_out');
+  // Only the building's holder may ask, by this path too (ADR 0378 D2): a
+  // build-out filed straight at the matters route meets the same wall.
+  if (isBuildOut) {
+    const notYours = await buildOutHolderRefusal(a.action.building, proposedBy);
+    if (notYours) return notYours;
+  }
+  const boardBuilds = isBuildOut && (resolved.as_today || a.action.capsule === 'district' || a.action.building === 'charter');
+  if ((leadAct && resolved.as_today) || boardBuilds) {
+    const refused = leadAct ? await leadMatterRefusal(a.action) : null;
+    if (refused) return refused;
+    const matter = await db.createMatter({ area, title: title.trim(), detailMd, action: a.action, proposedBy });
+    const item = await db.openBoardItem({
+      subjectType: decisionRules.MATTER_SUBJECT_TYPES[area],
+      subjectId: matter.id,
+      openedBy: proposedBy,
+      constitution: board,
+      windowMinutes: board.window_minutes,
+    });
+    return { ok: true, matter, item, decided: { ...resolved, sat_under: 'board' } };
+  }
   if (resolved.as_today) {
     return {
       ok: false, reason: 'decided_by_gate', area, gate: resolved.gate,
@@ -263,10 +363,13 @@ async function openMatter({ area, title, detailMd = null, action = null, propose
     };
   }
   if (!resolved.sitting) return { ok: false, reason: 'no_one_holds_this', area, what_this_means: `No one holds ${resolved.name} yet, so nothing there can be decided.` };
-  if (a.action && area !== 'people' && !matterActFor(area, a.action.type)) {
+  if (a.action && area !== 'people' && !isBuildOut && !matterActFor(area, a.action.type)) {
     return { ok: false, reason: 'action_not_wired', area, what_this_means: `Nothing at ${resolved.name} can carry that out right now, so it would pass and do nothing. Turn on the module that owns ${resolved.name}, or file the matter without an act.` };
   }
-  if (a.action && area === 'people') {
+  if (leadAct) {
+    const refused = await leadMatterRefusal(a.action);
+    if (refused) return refused;
+  } else if (a.action && area === 'people' && !isBuildOut) {
     const rank = await db.getRankByKey(a.action.rank_key);
     if (!rank) return { ok: false, reason: 'unknown_rank', rank_key: a.action.rank_key };
     if (rank.is_system) return { ok: false, reason: 'seeded_rank', rank_key: a.action.rank_key, expected: 'a custom rank — a seeded rank follows the builder\'s rank' };
@@ -285,6 +388,21 @@ async function openMatter({ area, title, detailMd = null, action = null, propose
   return { ok: true, matter, item, decided: resolved };
 }
 
+// Why a Lead matter cannot be filed, or null when it can (task 1004709): the
+// appointee must be an active builder and not already lead the building on the
+// same charter; a removal needs a Lead in office.
+async function leadMatterRefusal(action) {
+  const inOffice = (await db.listLeads()).find((l) => l.building === action.building) || null;
+  if (action.type === 'remove_lead') {
+    return inOffice ? null : { ok: false, reason: 'no_lead', area: 'people', building: action.building, what_this_means: `${decisionRules.areaByKey(action.building).name} has no Lead to remove.` };
+  }
+  if (!(await db.getActiveBuilder(action.builder_id))) return { ok: false, reason: 'unknown_builder', builder_id: String(action.builder_id) };
+  if (inOffice && String(inOffice.builder_id) === String(action.builder_id) && inOffice.charter === action.charter) {
+    return { ok: false, reason: 'already_lead', area: 'people', building: action.building, what_this_means: 'They already lead it, on that charter.' };
+  }
+  return null;
+}
+
 // May this builder act ALONE at this building — the check a building's own
 // direct route runs before acting (People's rank assignments here; every other
 // building's routes through the doorway's requireActAlone, task 1004657 — the
@@ -332,6 +450,112 @@ async function announcePassedMatter(acted) {
 
 // ── the reads board.js shows ────────────────────────────────────────────────
 
+// GET /government/leads (task 1004709): the nine buildings, each with its Lead in
+// office or null, and who answers for it (its Lead, or the owner when unseated).
+// Read per request, uncached.
+//
+// Each building also carries `build_rights` (task 1004710): what its holder may
+// build out without a vote, from the FORM OF GOVERNMENT in force and the
+// building's own decision row (build-rights.js is the rule). The context is
+// resolved here, server-side and uncached (ADR 0016): the board block, the
+// resolved decision table, who the board seats, and who each 'decide' / 'first'
+// sitting seats. Every part FAILS CLOSED: an unreadable part reads as "a vote",
+// never as "at once". No goal stores build terms yet, so the goals hook is [].
+async function buildRightsContext() {
+  let board = {};
+  // read through the module object (not the destructured name) so a test can
+  // hand it a constitution
+  try { board = require('./config').loadGovernmentConfig().board || {}; } catch (_) { board = {}; }
+  const decisions = (await decisionRulesFor(board)) || [];
+  const idsOf = async (membership) => {
+    try { return (await resolveBoardMembers({ membership })).map((m) => String(m.builder_id)); } catch (_) { return []; }
+  };
+  const boardMemberIds = await idsOf(board.membership);
+  const sittingMemberIds = {};
+  // only a sitting whose rule lets a seated member act alone can let its holder
+  // build at once, so only those are asked who they seat
+  const actsAlone = decisionRules.DECISION_RULES.filter((r) => r.actsAlone).map((r) => r.key);
+  for (const d of decisions) {
+    if (d.sitting && actsAlone.includes(d.rule)) sittingMemberIds[d.area] = await idsOf(d.decided_by);
+  }
+  return { board, decisions, boardMemberIds, sittingMemberIds, goals: [] };
+}
+
+// Each building also carries its `structure` (task 1004711): the build-outs on
+// the record (built, or going up) and the ones waiting on a vote. A failed read
+// of either leaves the building's structure out (null), never invented.
+// `structure: false` skips the build-out reads (a caller that needs only who
+// answers for a building and its build_rights).
+async function leadsView({ includePast = false, now = Date.now(), structure: withStructure = true } = {}) {
+  const [rows, archons, rights, standing, pending] = await Promise.all([
+    db.listLeads({ includePast }), db.listActiveArchons(), buildRightsContext(),
+    withStructure ? db.listBuildouts().catch(() => null) : null, withStructure ? db.listPendingBuildouts().catch(() => null) : null,
+  ]);
+  const structure = standing && pending ? { rows: standing, pending, now } : null;
+  return leadsBook(rows, archons, { includePast, rights, structure });
+}
+
+// ── a Lead's build-outs (task 1004711, ADR 0378) ────────────────────────────
+
+// The refusal when someone other than the building's holder asks, with where to go instead.
+function notTheHolder(building, leadName) {
+  const area = decisionRules.areaByKey(building);
+  const name = area ? area.name : 'This building';
+  return {
+    ok: false, reason: 'not_the_holder', building,
+    what_this_means: leadName
+      ? `${name} is led by ${leadName}, and only they grow it. Ask them to put it up.`
+      : `${name} has no Lead, so only the owner grows it. Ask the owner to put it up.`,
+  };
+}
+
+// Only the building's holder may ask for a build-out, whichever path files it
+// (answerFor, the one rule): null when `builderId` holds it, else the refusal.
+async function buildOutHolderRefusal(building, builderId) {
+  const [rows, archons] = await Promise.all([db.listLeads(), db.listActiveArchons()]);
+  const answers = answerFor(building, rows, ownerOf(archons));
+  if (answers && answers.builder_ids.map(String).includes(String(builderId))) return null;
+  const lead = (rows || []).find((l) => l && l.building === building && !l.removed_at) || null;
+  return notTheHolder(building, lead ? lead.display_name || lead.github_login || 'its Lead' : null);
+}
+//
+// POST /government/buildouts. The building's HOLDER (its Lead, or the owner
+// seat when unseated — leads.answerFor) asks for a build-out; build-rights.js,
+// read off the same server-side view GET /government/leads serves, says whether
+// it goes up at once or goes to a vote. At once: put on the record now, with the
+// rule's ground and why. A vote: filed as a build_out matter through openMatter,
+// the same path POST /government/board/matters runs (the caller, board.js, adds
+// the window-open nudge). Fails closed: rights that cannot be read are a vote.
+//
+// Returns { ok: true, path: 'at_once', buildout, rights } |
+//         { ok: true, path: 'vote', matter, item, decided, rights } |
+//         { ok: false, reason, … } ('bad_buildout', 'unknown_field', 'not_the_holder', openMatter's).
+async function buildOut({ buildout, builderId } = {}) {
+  const b = buildouts.checkBuildOut({ type: 'build_out', ...(buildout || {}) });
+  if (!b.ok) return { ok: false, reason: b.reason, field: b.field };
+  if (builderId == null || builderId === '') return { ok: false, reason: 'missing_proposer' };
+  const a = b.buildout;
+  const view = await leadsView({ structure: false });
+  const here = view.buildings.find((x) => x.building === a.building) || null;
+  const holders = ((here && here.answers && here.answers.builder_ids) || []).map(String);
+  if (!holders.includes(String(builderId))) return notTheHolder(a.building, here && here.lead ? here.lead.builder.name : null);
+  const rights = here.build_rights && here.build_rights.capsules ? here.build_rights.capsules[a.capsule] || null : null;
+  if (rights && rights.without_vote === true && a.capsule !== 'district') {
+    const out = await db.insertBuildout({
+      building: a.building, capsule: a.capsule, name: a.name, line: a.line,
+      builtBy: builderId, ground: rights.ground, why: rights.why,
+    });
+    return { ok: true, path: 'at_once', buildout: out.buildout || null, rights };
+  }
+  const what = { committee: 'a committee room', floor: 'a new floor', annex: 'an annex', district: 'a district of its own' }[a.capsule];
+  const title = a.capsule === 'district' ? `Grow ${here.name} into a district: ${a.name}` : `Add ${what} to ${here.name}: ${a.name}`;
+  const filed = await openMatter({
+    area: buildouts.matterAreaFor(a.building), title: title.slice(0, MATTER_TITLE_MAX), detailMd: a.line || null, action: a, proposedBy: builderId,
+  });
+  if (!filed.ok) return { ...filed, rights };
+  return { ok: true, path: 'vote', matter: filed.matter, item: filed.item, decided: filed.decided, rights };
+}
+
 // The Board Room's matter subjects, keyed by id. No query when no matter is on
 // the board, so a project that never amended itself reads exactly what it did.
 async function matterSubjectsById(items) {
@@ -386,4 +610,6 @@ module.exports = {
   MATTER_ACT_POINT,
   openMatter,
   checkActAlone,
+  leadsView,
+  buildOut,
 };

package/modules/government/decision-rules.js

@@ -115,6 +115,8 @@ const AREAS = Object.freeze([
   Object.freeze({ key: 'treasury', name: 'Treasury', gate: 'builder.budget.set',
     today: 'whoever may set spending limits', acts: Object.freeze([
       'PATCH /builders/:id/budget',
+      // task 1004712: the project's optional spend cap (off by default: no limit)
+      'PATCH /project-settings/spend-cap',
     ]) }),
 ]);
 const AREA_KEYS = Object.freeze(AREAS.map((a) => a.key));

package/modules/government/docket.js

@@ -83,6 +83,9 @@ const resolver = require('./resolver');
 const decisionRules = require('./decision-rules');
 const docketFloors = require('./docket-floors');
 const governmentConfig = require('./config');
+const asksDb = require('./asks-db');
+const routing = require('./routing');
+const { ownerOf } = require('./leads');
 
 const log = api.logger('government');
 
@@ -108,6 +111,8 @@ const EXPECTED_SOURCES = Object.freeze([
   Object.freeze({ source: 'gate_approvals', building: 'release', label: 'CI gate approvals' }),
   Object.freeze({ source: 'autobongos_fence', building: 'automation', label: 'the Autobongos fence' }),
   Object.freeze({ source: 'module_rechecks', building: 'release', label: 'module re-checks' }),
+  // task 1004712: a dry pot's borrow from the reserve, a treasury matter (treasury.js)
+  Object.freeze({ source: 'treasury_spending', building: 'treasury', label: 'spending matters' }),
 ]);
 
 // Named by the design, not yet recorded anywhere. Each says why, in words.
@@ -116,8 +121,6 @@ const COMING_SOURCES = Object.freeze([
     reason: 'There is no way to appeal a grade yet.' }),
   Object.freeze({ source: 'standing_rules', building: 'rules', label: 'standing rules',
     reason: 'A new standing rule has nowhere to be proposed yet. The one rule in force, idea routing, is counted in the rules-at-work reading.' }),
-  Object.freeze({ source: 'treasury_spending', building: 'treasury', label: 'spending matters',
-    reason: 'The project has no budget or spending votes recorded yet.' }),
 ]);
 
 // Floors the design names whose engine does not exist yet. Drawn, and say why.
@@ -339,7 +342,9 @@ function countStates(matters) {
   return c;
 }
 
-// The home line under "start governing", in the design's words.
+// The home line under "start governing", in the design's words. `counts.needs`
+// is what waits on the viewer: on a routed docket (task 1004705) the matters on
+// the viewer's own seats, not every matter that needs somebody.
 function homeLine(counts) {
   if (!counts.needs && !counts.moving) return 'nothing waits on you.';
   const parts = [];
@@ -519,6 +524,28 @@ function registeredContributions() {
   return { sources, readings, floors, histories, desks };
 }
 
+// ── the ask each matter carries (task 1004703) ───────────────────────────────
+
+// A matter an agent put to a person carries its ASK (asks.js): the question, two
+// or three tap answers, the pick and why, the seat it waits on and what happens
+// if nobody answers, stored per matter id in government_asks. Attached only to
+// the matters this viewer already sees, so an ask is never more visible than its
+// matter. A read that fails or is slow attaches none: the city still stands, and
+// each matter keeps its own words.
+async function attachAsks(matters, readAsks, timeoutMs) {
+  if (typeof readAsks !== 'function' || !matters.length) return;
+  try {
+    const found = await withTimeout(Promise.resolve(readAsks(matters.map((m) => m.id))), timeoutMs);
+    if (!found || typeof found.get !== 'function') return;
+    for (const m of matters) {
+      const ask = found.get(m.id);
+      if (ask) m.ask = ask;
+    }
+  } catch (err) {
+    log.warn({ err: err && err.message }, 'governor docket: asks unreadable');
+  }
+}
+
 // ── the collector ────────────────────────────────────────────────────────────
 
 // Build the docket for one viewer. `permissions` is the viewer's resolved set;
@@ -529,7 +556,12 @@ function registeredContributions() {
 // rather than a guess.
 // `government` is what docketFor() read once for this module's own floors and
 // record (loadGovernment below); null leaves those floors `unavailable`.
-async function buildDocket({ viewer, permissions, contributions = registeredContributions(), now = Date.now(), timeoutMs = SOURCE_TIMEOUT_MS, decisions = null, government = null } = {}) {
+// `readAsks(matterIds)` → Map(matter id → ask) reads the stored asks (task
+// 1004703, asks-db.js asksFor); null attaches none.
+// `seats` is who sits in each seat (loadSeats below: Leads in office, the owner
+// seat, each building's holders); given, every matter carries `route` (routing.js,
+// task 1004705) and the docket says `routed: true`. null routes nothing.
+async function buildDocket({ viewer, permissions, contributions = registeredContributions(), now = Date.now(), timeoutMs = SOURCE_TIMEOUT_MS, decisions = null, government = null, readAsks = null, seats = null } = {}) {
   const held = new Set(permissions || []);
   const ctx = Object.freeze({
     builderId: String(viewer.id),
@@ -581,6 +613,9 @@ async function buildDocket({ viewer, permissions, contributions = registeredCont
   const order = declared.map((d) => d.source);
   sourceStatus.sort((a, b) => order.indexOf(a.source) - order.indexOf(b.source));
   matters.sort(compareMatters);
+  await attachAsks(matters, readAsks, timeoutMs);
+  // THE DIRECTION DESK (task 1004705): who each matter waits on, from real seats.
+  const yours = seats ? routing.routeAll(matters, ctx.builderId, seats, now) : null;
 
   // Readings: contributed + this module's own + the ones derived from matters.
   const readingImpls = new Map(contributions.readings);
@@ -689,6 +724,7 @@ async function buildDocket({ viewer, permissions, contributions = registeredCont
   historySources.sort((a, b) => (a.source < b.source ? -1 : 1));
 
   const counts = countStates(matters);
+  if (yours != null) counts.yours = yours;
   const decisionBy = new Map((Array.isArray(decisions) ? decisions : []).filter(Boolean).map((d) => [d.area, d]));
   const holdersBy = govAllowed && government && government.holders ? government.holders : {};
   const buildings = vocab.BUILDINGS.map((b) => {
@@ -712,7 +748,8 @@ async function buildDocket({ viewer, permissions, contributions = registeredCont
     viewer: { id: ctx.builderId },
     generated_at: new Date(now).toISOString(),
     counts,
-    line: homeLine(counts),
+    line: homeLine(yours != null ? { needs: yours, moving: counts.moving } : counts),
+    routed: yours != null,
     matters,
     buildings,
     sources: sourceStatus,
@@ -729,6 +766,41 @@ async function buildDocket({ viewer, permissions, contributions = registeredCont
   };
 }
 
+// ONE matter, as this viewer's docket would show it (task 1004703): the write
+// side of an ask may only reach a matter its writer can see. Reads that one
+// source under the gate it declared — the same gate the docket applies — and
+// finds the matter in it. → { matter } | { reason: 'no_such_source' |
+// 'not_yours' | 'not_found' | 'unavailable' }. Pure over its inputs, like
+// buildDocket.
+async function findMatter({ viewer, permissions, matterId, contributions = registeredContributions(), now = Date.now(), timeoutMs = SOURCE_TIMEOUT_MS } = {}) {
+  const id = String(matterId || '');
+  const cut = id.indexOf(':');
+  const source = cut > 0 ? id.slice(0, cut) : '';
+  const decl = EXPECTED_SOURCES.find((d) => d.source === source);
+  const c = source === 'board' ? BOARD_SOURCE : new Map(contributions.sources).get(source);
+  if (!decl || !c) return { reason: 'no_such_source' };
+  const held = new Set(permissions || []);
+  const ctx = Object.freeze({ builderId: String(viewer.id), rank: viewer.rank || null, has: (p) => held.has(p) });
+  if (!gateAllows(c.gate, ctx)) return { reason: 'not_yours' };
+  const memo = new Map();
+  const once = (key, fn) => {
+    if (!memo.has(key)) memo.set(key, Promise.resolve().then(fn));
+    return memo.get(key);
+  };
+  try {
+    const raw = await withTimeout(Promise.resolve(c.read(ctx, { now, once })), timeoutMs);
+    const matter = (Array.isArray(raw) ? raw : []).map((m) => normalizeMatter(m, { source, building: c.building || decl.building })).find((m) => m && m.id === id);
+    return matter ? { matter } : { reason: 'not_found' };
+  } catch (err) {
+    log.warn({ source, err: err && err.message }, 'governor docket: a matter could not be read');
+    return { reason: 'unavailable' };
+  }
+}
+async function findMatterFor(builder, matterId) {
+  const permissions = await resolver.resolveBuilderPermissions(builder.id);
+  return findMatter({ viewer: builder, permissions, matterId });
+}
+
 // The route's entry point: resolve the viewer's permissions server-side (fresh,
 // uncached — ADR 0016), then build.
 async function docketFor(builder) {
@@ -740,7 +812,38 @@ async function docketFor(builder) {
     return null;
   });
   const government = permissions.includes(GOVERNMENT_GATE.permission) ? await loadGovernment({ decisions }) : null;
-  return buildDocket({ viewer: builder, permissions, decisions, government });
+  const seats = government ? await loadSeats(government) : null;
+  return buildDocket({ viewer: builder, permissions, decisions, government, readAsks: asksDb.asksFor, seats });
+}
+
+// Who sits in each seat now (task 1004705), read per request, uncached (ADR
+// 0016): the Leads in office, the owner seat (every active Archon) and each
+// building's holders as loadGovernment resolved them. A read that fails routes
+// nothing — the docket then says `routed: false` rather than guess whose it is.
+async function loadSeats(government) {
+  try {
+    const [leads, archons] = await Promise.all([db.listLeads(), db.listActiveArchons()]);
+    return { leads, owner: ownerOf(archons), holders: (government && government.holders) || {} };
+  } catch (err) {
+    log.warn({ err: err && err.message }, 'governor docket: seats unreadable, nothing routed');
+    return null;
+  }
+}
+
+// One matter with its stored ask and the seats, for passing it on to `toSeat`
+// (task 1004705): → { matter, seats } | { reason } as findMatter answers. A
+// board's holders are read only when a board seat is involved.
+async function matterWithSeats(builder, matterId, toSeat = '') {
+  const found = await findMatterFor(builder, matterId);
+  if (!found.matter) return found;
+  const ask = (await asksDb.asksFor([found.matter.id])).get(found.matter.id);
+  if (ask) found.matter.ask = ask;
+  const boardSeat = [toSeat, ask && ask.waits_on].some((s) => /^board:/.test(String(s || '')));
+  const government = boardSeat
+    ? await loadGovernment({ decisions: await board.decisionRulesView().catch(() => null) })
+    : { holders: {} };
+  const seats = await loadSeats(government);
+  return seats ? { matter: found.matter, seats } : { reason: 'unavailable' };
 }
 
 // This module's own floors and record, read ONCE per request (task 1004527),
@@ -809,4 +912,9 @@ module.exports = {
   registeredContributions,
   buildDocket,
   docketFor,
+  attachAsks,
+  findMatter,
+  findMatterFor,
+  loadSeats,
+  matterWithSeats,
 };