simt-dev 0.3.0 → 0.4.0

package/src/decisions/index.mjs

@@ -21,6 +21,8 @@ import { fileURLToPath } from 'node:url';
 import { MANIFEST_FILE } from '../name.mjs';
 import { CLI } from '../name.mjs';
 import { PREFIX_ARGUING, TOOL_WORDS } from '../toolwords.mjs';
+import { PARTIAL_CLAUSE, parseDecisionFrontmatter, splitFrontmatter } from '../memory/decide.mjs';
+import { affectsTokens } from '../index/govern.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const DECISIONS_DIR = resolve(HERE, '..', '..', 'docs', 'decisions');
@@ -96,19 +98,6 @@ const ADR_IN_TEXT = /\bADR-(\d{3})\b/g;
  */
 const SIBLING_FIELD = /^\*{0,2}[A-Z][\w]*(?:[ \t]+[\w]+){0,3}:\*{0,2}(?:[ \t]|$)/;
 
-/**
- * `ruling N <verb> by <ADR>`, in every form the corpus uses.
- *
- * Four spellings, all of them real: `ruling 3 superseded by ADR-046`, `rulings 1 and 2
- * narrowed by ADR-026`, `rulings 3 and 4 narrowed by the same record`, and `one ruling
- * narrowed by ADR-045` - which names no number at all, because the record does not say
- * which ruling it meant. That last one is carried with `ruling: null` rather than
- * dropped: a clause the tool can see but cannot resolve is reported as unresolved, and
- * the corpus test below pins that there are none.
- */
-const PARTIAL_CLAUSE =
-  /\b(?:one ruling|rulings?\s+(\d+(?:\s*(?:,|and)\s*\d+)*))\s+(superseded|narrowed|withdrawn)\s+by\s+(ADR-\d{3}|the same record)\b/gi;
-
 /** How a record says a ruling was numbered, when it did not use a digit. */
 const ORDINALS = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight', 'Nine', 'Ten'];
 const ORDINAL_NUMBER = new Map(ORDINALS.map((w, i) => [w, i + 1]));
@@ -173,6 +162,85 @@ export function citations(text) {
   return [...found].sort();
 }
 
+/**
+ * Parse one ADR markdown document, reading structured `simt-affects` and
+ * `simt-supersedes` frontmatter first (plan 0003 R34).
+ *
+ * @param {string} file filename (e.g. `ADR-097-example.md`)
+ * @param {string} text raw markdown content
+ * @param {{all?: boolean}} [options]
+ * @returns {{ok: boolean, decision?: object, error?: string, rawBody?: string}}
+ */
+export function parseDecision(file, text, { all = false } = {}) {
+  const fm = parseDecisionFrontmatter(text);
+  const { body } = splitFrontmatter(text);
+  const fileId = /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase();
+  const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? null;
+  const headId = heading ? /^(ADR-\d{3,})/i.exec(heading)?.[1]?.toUpperCase() : null;
+  const id = fileId ?? headId ?? null;
+  if (!id) {
+    return { ok: false, error: `${file}: filename does not start with ADR-NNN` };
+  }
+  if (!heading) {
+    return { ok: false, error: `${file}: no level-1 heading` };
+  }
+  const rawStatus = statusParagraph(body);
+  if (rawStatus === null) {
+    return { ok: false, error: `${file}: no Status: line, so currency cannot be reported` };
+  }
+  const status = stripMarkdown(rawStatus);
+  const selfNum = Number(id.replace(/^ADR-/i, ''));
+
+  const fmPartial = [];
+  const fmWholeSupersedes = [];
+  for (const entry of fm.supersedes) {
+    const otherNum = Number(entry.adr.replace(/^ADR-/i, ''));
+    if (entry.ruling === null) {
+      if (otherNum < selfNum) fmWholeSupersedes.push(entry.adr);
+    } else if (otherNum > selfNum || entry.adr === id) {
+      fmPartial.push({
+        ruling: entry.ruling,
+        kind: entry.kind ?? 'superseded',
+        by: entry.adr === id ? null : entry.adr,
+      });
+    }
+  }
+
+  const prosePartial = partialSupersessions(status);
+  const partial = [...fmPartial];
+  for (const p of prosePartial) {
+    if (!partial.some((x) => x.ruling === p.ruling && x.by === p.by)) {
+      partial.push(p);
+    }
+  }
+
+  const proseSupersedes = [...status.matchAll(/supersedes ADR-(\d{3,})(?!\s+[Ss]?rulings?\b)/g)].map(
+    (m) => `ADR-${m[1]}`,
+  );
+  const supersedes = [...new Set([...fmWholeSupersedes, ...proseSupersedes])];
+  const title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim();
+
+  return {
+    ok: true,
+    rawBody: body,
+    decision: {
+      id,
+      file,
+      title,
+      status: redactInternalPaths(redactCommand(status)),
+      accepted: /^accepted\b/i.test(status),
+      supersededBy: firstMatch(status, /^superseded by ADR-(\d{3,})/i),
+      supersedes,
+      supersedesRulings: fm.supersedes,
+      affects: affectsTokens(text),
+      frontmatter: fm.hasFrontmatter ? { affects: fm.affects, supersedes: fm.supersedes } : null,
+      partial,
+      summary: summarise(body, partial, { all, file }),
+      bytes: Buffer.byteLength(text),
+    },
+  };
+}
+
 /**
  * Load every ADR record once.
  *
@@ -181,69 +249,52 @@ export function citations(text) {
  *
  * @returns {Promise<{ok: boolean, decisions: object[], errors: string[]}>}
  */
-export async function loadDecisions({ all = false } = {}) {
+export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   let names;
   try {
-    names = (await readdir(DECISIONS_DIR)).filter((n) => /^ADR-\d{3}-.*\.md$/.test(n)).sort();
+    names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/.test(n)).sort();
   } catch (error) {
-    return { ok: false, decisions: [], errors: [`${DECISIONS_DIR}: unreadable (${error.message})`] };
+    return { ok: false, decisions: [], errors: [`${dir}: unreadable (${error.message})`] };
   }
 
   const decisions = [];
+  const rawBodies = new Map();
   const errors = [];
 
   for (const file of names) {
-    const text = await readFile(join(DECISIONS_DIR, file), 'utf8');
-    const id = /^ADR-(\d{3})/.exec(file)?.[0];
-    if (!id) {
-      errors.push(`${file}: filename does not start with ADR-NNN`);
+    const text = await readFile(join(dir, file), 'utf8');
+    const parsed = parseDecision(file, text, { all });
+    if (!parsed.ok) {
+      errors.push(parsed.error);
       continue;
     }
-    const heading = /^#\s+(.*)$/m.exec(text)?.[1] ?? null;
-    if (!heading) {
-      errors.push(`${file}: no level-1 heading`);
-      continue;
-    }
-    const rawStatus = statusParagraph(text);
-    if (rawStatus === null) {
-      errors.push(`${file}: no Status: line, so currency cannot be reported`);
-      continue;
+    rawBodies.set(parsed.decision.id, parsed.rawBody);
+    decisions.push(parsed.decision);
+  }
+
+  const index = byId(decisions);
+  for (const d of decisions) {
+    const selfNum = Number(d.id.replace(/^ADR-/i, ''));
+    for (const entry of d.supersedesRulings ?? []) {
+      const otherNum = Number(entry.adr.replace(/^ADR-/i, ''));
+      if (otherNum >= selfNum) continue;
+      const target = index.get(entry.adr);
+      if (!target) continue;
+      if (entry.ruling === null) {
+        target.supersededBy = d.id;
+        target.accepted = false;
+      } else if (!target.partial.some((p) => p.ruling === entry.ruling && p.by === d.id)) {
+        target.partial.unshift({
+          ruling: entry.ruling,
+          kind: entry.kind ?? 'superseded',
+          by: d.id,
+        });
+        target.summary = summarise(rawBodies.get(target.id) ?? '', target.partial, {
+          all,
+          file: target.file,
+        });
+      }
     }
-    // Every field below is read off the flattened paragraph, with markdown already
-    // removed. The link form and the bare form are then one spelling, so a record that
-    // writes `superseded by ADR-046` and one that writes `superseded by
-    // [ADR-046](...)` are read by the same line of code rather than by two regexes that
-    // have to be kept in step.
-    const status = stripMarkdown(rawStatus);
-    const partial = partialSupersessions(status);
-    // The heading repeats the id; the decision title is what follows the dash.
-    const title = heading.replace(/^ADR-\d{3}\s*[—–-]\s*/, '').trim();
-
-    decisions.push({
-      id,
-      file,
-      title,
-      // Everything structural above this line is derived from the record's own prose and
-      // is therefore unredacted: `partial` in particular has to say "ruling 1 superseded
-      // by ADR-053", and a ruling number is not a location. What a reader in another
-      // repository receives is the status line, so that is what is scrubbed — here, once,
-      // rather than at each of the four places that print it.
-      status: redactInternalPaths(redactCommand(status)),
-      // Anchored to the start of the status, and this is the whole of the rule. A record
-      // is superseded only when its own status says so first. Unanchored, the clause
-      // "ruling 2 superseded by [ADR-024]" inside ADR-023's paragraph matched, and the
-      // command would then answer "ruling 2" by printing ADR-024's rulings and
-      // suppressing the five in ADR-023 that still stand - a partial supersession
-      // silently becoming a total one, which is the reverse of what the status says.
-      accepted: /^accepted\b/i.test(status),
-      supersededBy: firstMatch(status, /^superseded by ADR-(\d{3})/i),
-      supersedes: [...status.matchAll(/supersedes ADR-(\d{3})(?!\s+[Ss]?rulings?\b)/g)].map(
-        (m) => `ADR-${m[1]}`,
-      ),
-      partial,
-      summary: summarise(text, partial, { all, file }),
-      bytes: Buffer.byteLength(text),
-    });
   }
 
   return { ok: errors.length === 0, decisions, errors };
@@ -524,7 +575,7 @@ export function redactEstate(text) {
  * Only a real verb follows, which is what keeps `simt-dev.json`, `simt-dev-check.yml` and
  * `simt-dev's` untouched - those are the project's artefacts and the project keeps its name.
  */
-const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|mcp|rules|skills|graph|tokens|harness|bench|--[a-z-]+)';
+const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|agent-hook|agent-hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|lessons|decide|brief|plan|--[a-z-]+)';
 
 function redactCommand(text) {
   return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);

package/src/federation/client.mjs

@@ -0,0 +1,188 @@
+// The federation client: one stdio MCP conversation, spoken directly (plan 0003 R26).
+//
+// simt-dev carries no runtime dependency, and an external code-graph server speaks MCP over
+// stdio, which is newline-delimited JSON-RPC. That is a shape small enough to speak without
+// a client library, so this file is the whole client: start the server, initialize, ask one
+// tool for one text answer, and return that answer or the reason there is none.
+//
+// Two rules make it safe to put inside a brief:
+//
+//   * It never throws. A command that is not installed, a server that exits, one that
+//     answers with a protocol error, one that never answers at all — every one of them
+//     comes back as `{ error }` for the caller to render as a sentence. A brief that died
+//     because an optional server misbehaved would be a brief nobody keeps installed.
+//   * It always cleans up, and it always ends. The child is killed on the first answer, on
+//     an error and on the timeout, and the timeout is a real bound on a server that has
+//     forgotten how to read. Federation adds a wait with a ceiling, never an open one.
+//
+// The conversation is exactly three messages deep, which is the minimum MCP allows:
+// `initialize`, the `notifications/initialized` acknowledgement, then one `tools/call`.
+
+import { spawn } from 'node:child_process';
+
+/**
+ * The protocol revision this client opens with.
+ *
+ * Not this tool's newest — an external server predates it far more often than not — but the
+ * oldest revision every MCP server of the current generation is required to accept. A
+ * server that answers with a revision of its own is answering, and the reply is not
+ * second-guessed: this is a client for asking, not for negotiating.
+ */
+const PROTOCOL_VERSION = '2025-06-18';
+
+/** The longest a single server may take before the client stops waiting, in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 5000;
+
+const CLIENT_INFO = { name: 'simt-dev', version: '1' };
+
+/** The first non-blank text part of a result, or null when the result carries none. */
+function textOf(result) {
+  if (result === null || typeof result !== 'object') return null;
+  const content = Array.isArray(result.content) ? result.content : [];
+  for (const part of content) {
+    if (part !== null && typeof part === 'object' && part.type === 'text' && typeof part.text === 'string') {
+      if (part.text.trim().length > 0) return part.text;
+    }
+  }
+  return null;
+}
+
+/** One sentence for a JSON-RPC error object. */
+function reasonOf(error) {
+  if (error === null || typeof error !== 'object') return 'the server returned an error';
+  if (typeof error.message === 'string' && error.message.length > 0) return error.message;
+  if (error.code !== undefined) return `the server answered with error code ${error.code}`;
+  return 'the server returned an error';
+}
+
+/**
+ * Ask one server, over stdio, for one text answer to one question.
+ *
+ * @param {object} request
+ * @param {string} request.command the executable to start
+ * @param {string[]} [request.args] its arguments
+ * @param {string} [request.cwd] the directory to start it in
+ * @param {string} request.tool the MCP tool to call
+ * @param {string} [request.argument] the argument the question is placed in
+ * @param {string} request.query the question
+ * @param {number} [request.timeoutMs] how long to wait, in milliseconds
+ * @returns `{ text }` on an answer, `{ error }` on anything else — never a rejection
+ */
+export async function callTool({
+  command,
+  args = [],
+  cwd = undefined,
+  tool,
+  argument = 'query',
+  query,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'], cwd });
+    } catch (error) {
+      resolve({ error: `could not start \`${command}\` (${error.message})` });
+      return;
+    }
+
+    let settled = false;
+    let buffer = '';
+    let nextId = 1;
+    const pending = new Map();
+
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child.stdin.end();
+      } catch {
+        // The pipe may already be gone; nothing to close in that case.
+      }
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // A process that has already exited cannot be killed again.
+      }
+      resolve(payload);
+    };
+
+    const timer = setTimeout(() => finish({ error: `no answer within ${timeoutMs} ms` }), timeoutMs);
+
+    child.on('error', (error) => finish({ error: `could not start \`${command}\` (${error.message})` }));
+    child.on('exit', (code) => {
+      if (!settled) finish({ error: `the server exited with code ${code} before answering` });
+    });
+    // stderr is not this client's to interpret, but it has to be read: an unread pipe fills
+    // and a server blocked on its own diagnostics never reaches the answer.
+    child.stderr.on('data', () => {});
+    child.stdin.on('error', () => {});
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      let index = buffer.indexOf('\n');
+      while (index !== -1) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (line.length > 0) {
+          let message;
+          try {
+            message = JSON.parse(line);
+          } catch {
+            message = null;
+          }
+          const id = message !== null && typeof message === 'object' ? message.id : undefined;
+          const waiter = id !== undefined ? pending.get(id) : undefined;
+          if (waiter !== undefined) {
+            pending.delete(id);
+            waiter(message);
+          }
+        }
+        index = buffer.indexOf('\n');
+      }
+    });
+
+    const request = (method, params) =>
+      new Promise((done) => {
+        const id = nextId;
+        nextId += 1;
+        pending.set(id, done);
+        try {
+          child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        } catch (error) {
+          pending.delete(id);
+          finish({ error: `could not talk to \`${command}\` (${error.message})` });
+        }
+      });
+
+    const notify = (method, params) => {
+      try {
+        child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, params })}\n`);
+      } catch {
+        // A notification that cannot be written is a server that is already gone, and the
+        // exit handler reports that with a better sentence than this one could.
+      }
+    };
+
+    (async () => {
+      await request('initialize', {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: CLIENT_INFO,
+      });
+      notify('notifications/initialized', {});
+      const answer = await request('tools/call', { name: tool, arguments: { [argument]: query } });
+      if (answer.error !== undefined) {
+        finish({ error: reasonOf(answer.error) });
+        return;
+      }
+      const text = textOf(answer.result);
+      if (text === null) {
+        finish({ error: `\`${tool}\` returned no text` });
+        return;
+      }
+      finish({ text });
+    })().catch((error) => finish({ error: error.message }));
+  });
+}

package/src/federation/config.mjs

@@ -0,0 +1,134 @@
+// Federation configuration: the servers a repository names, and nothing else (plan 0003 R26).
+//
+// A brief is deterministic by default. Federation is the one opt-in exception, and the
+// opt-in is a `federation` block in the repository's own manifest. Nothing here probes a
+// harness config, scans for a server that might exist, or opens a socket the manifest did
+// not ask for — a repository that declared nothing pays nothing and reads nothing. Where
+// a harness would keep the same names is R42's several slices away, and it is a different
+// question: this one is "what did the repository commit", not "what did the editor
+// configure".
+//
+// The trust model is the one `gates.commands` already has. Those are commands a repository
+// declares and this tool runs; a federation server is the same declaration one layer up.
+// The manifest is the file a person reviews before they commit the change, so a command in
+// it is a command the repository meant to run.
+//
+// The block is deliberately small, because every field in it is a promise the packet has
+// to keep:
+//
+//   "federation": {
+//     "servers": [
+//       {
+//         "name": "serena",                  // required, unique; the name the packet cites
+//         "command": "uvx",                  // required; started with stdio pipes
+//         "args": ["serena", "start-mcp-server"],
+//         "tool": "find_symbol",             // optional; the MCP tool to call, default "query"
+//         "argument": "query",               // optional; where the question goes, default "query"
+//         "languages": ["python"],           // optional; the coverage the packet records
+//         "timeoutMs": 4000                  // optional; the wait, default 5000
+//       }
+//     ]
+//   }
+//
+// An entry that breaks the shape is not a crash and not a silent skip. It becomes a finding
+// with a sentence in it, the brief turns that into a caution, and every other entry still
+// runs. A malformed block costs the reader one line, which is exactly what they need to fix
+// it — and a silent skip is the failure that line exists to prevent.
+
+import { readManifest } from '../projection/manifest.mjs';
+import { DEFAULT_TIMEOUT_MS } from './client.mjs';
+
+/** The tool a server is asked for when it does not name one. */
+const DEFAULT_TOOL = 'query';
+
+/** The argument the question is placed in when a server does not name one. */
+const DEFAULT_ARGUMENT = 'query';
+
+/** A list of strings, or null when the value is anything else. */
+function strings(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? [...value] : null;
+}
+
+/** A non-empty trimmed string, or the empty string. */
+function word(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** One declared server, or the sentence explaining why it is not one. */
+function serverOf(entry, seen) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { finding: 'a federation server must be an object' };
+  }
+  const name = word(entry.name);
+  if (name.length === 0) return { finding: 'a federation server needs a `name`' };
+  // The name is claimed before the rest is checked, so a rejected entry still reserves it:
+  // two entries called `serena` are a mistake whether or not the first one is also
+  // malformed, and a duplicate that only surfaced once both were valid would be the harder
+  // mistake to see.
+  if (seen.has(name)) return { finding: `two federation servers are named \`${name}\`` };
+  seen.add(name);
+
+  const command = word(entry.command);
+  if (command.length === 0) return { finding: `the \`${name}\` server needs a \`command\`` };
+
+  const args = entry.args === undefined ? [] : strings(entry.args);
+  if (args === null) return { finding: `the \`${name}\` server's \`args\` must be a list of strings` };
+  const languages = entry.languages === undefined ? [] : strings(entry.languages);
+  if (languages === null) return { finding: `the \`${name}\` server's \`languages\` must be a list of strings` };
+
+  const tool = entry.tool === undefined ? DEFAULT_TOOL : word(entry.tool);
+  if (tool.length === 0) return { finding: `the \`${name}\` server's \`tool\` must be a tool name` };
+  const argument = entry.argument === undefined ? DEFAULT_ARGUMENT : word(entry.argument);
+  if (argument.length === 0) return { finding: `the \`${name}\` server's \`argument\` must be an argument name` };
+
+  const timeoutMs = entry.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : entry.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    return { finding: `the \`${name}\` server's \`timeoutMs\` must be a positive whole number` };
+  }
+
+  return { server: { name, command, args, tool, argument, languages, timeoutMs } };
+}
+
+/**
+ * The servers a manifest declares, and the reason each rejected one was rejected.
+ *
+ * Pure: the manifest comes in, the decision comes out, and the same manifest always gives
+ * the same two lists. The order is the manifest's, because a packet's items are ordered and
+ * a federation answer is a packet item.
+ */
+export function federationServers(manifest) {
+  const block = manifest?.federation;
+  if (block === undefined || block === null) return { servers: [], findings: [] };
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    return { servers: [], findings: ['`federation` must be an object'] };
+  }
+  const declared = block.servers;
+  if (declared === undefined || declared === null) return { servers: [], findings: [] };
+  if (!Array.isArray(declared)) return { servers: [], findings: ['`federation.servers` must be a list'] };
+
+  const servers = [];
+  const findings = [];
+  const seen = new Set();
+  for (const entry of declared) {
+    const parsed = serverOf(entry, seen);
+    if (parsed.finding !== undefined) {
+      findings.push(parsed.finding);
+      continue;
+    }
+    servers.push(parsed.server);
+  }
+  return { servers, findings };
+}
+
+/**
+ * The same two lists, read from the repository's manifest.
+ *
+ * A repository with no manifest, an unreadable one or none at all declares no servers and
+ * reports no finding: federation is silent unless it was asked for, and "you did not
+ * configure this" is not a fault a reader needs told.
+ */
+export async function readFederation(root) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists || error !== null || manifest === null) return { servers: [], findings: [] };
+  return federationServers(manifest);
+}

package/src/federation/query.mjs

@@ -0,0 +1,48 @@
+// The federation query: one structural question per task, one answer per server (0003 R26).
+//
+// The slice is narrow on purpose. When a repository names external code-graph servers, the
+// brief delegates a single structural question to each and cites where the answer came from,
+// and the `federation_query` tool asks one on demand. Neither is a general proxy: a question
+// goes to the tool and argument the manifest declared, so a server exposes no tool here that
+// the repository did not name. It is not a second index, so there is no coverage bookkeeping
+// to keep in sync. And it is not a gate, so a server that is down produces a sentence and
+// never a failure.
+//
+// The servers are asked in the order the manifest declares them, one at a time. Parallel
+// would be faster and would make the packet's item order a race, and a packet whose order
+// depends on which server answered first is the one property this whole module exists
+// beside.
+
+import { callTool } from './client.mjs';
+
+/**
+ * Ask each declared server the same question.
+ *
+ * @param {object} request
+ * @param {string} request.root the repository the servers are started in
+ * @param {string} request.query the structural question, already non-empty
+ * @param {object[]} request.servers the servers `readFederation` returned
+ * @returns `{ answers, findings }` — one `{ server, tool, query, text }` per server that
+ *   answered, one sentence per server that did not
+ */
+export async function consult({ root, query, servers }) {
+  const answers = [];
+  const findings = [];
+  for (const server of servers) {
+    const result = await callTool({
+      command: server.command,
+      args: server.args,
+      cwd: root,
+      tool: server.tool,
+      argument: server.argument,
+      query,
+      timeoutMs: server.timeoutMs,
+    });
+    if (result.error !== undefined) {
+      findings.push(`the \`${server.name}\` server did not answer (${result.error})`);
+      continue;
+    }
+    answers.push({ server: server.name, tool: server.tool, query, text: result.text });
+  }
+  return { answers, findings };
+}