paseo-bm-plugin 0.0.0-placeholder.0

package/shared/bm-format.ts

@@ -0,0 +1,424 @@
+/**
+ * Strict template check of the `BM-*` blocks agents send each other
+ * (delta 20260918g §4.6, REQ-061 e, owner decisions Q2 a and Q7 a).
+ *
+ * The readers in `bm-report.ts` and `bm-questions.ts` are tolerant on purpose:
+ * they recover what they can from a sloppy block, because a card that shows
+ * something beats one that shows nothing. This module is the other half: it
+ * says exactly where a block departs from the templates in `plugin/roles/*.md`
+ * (BM-REPORT and BM-QUESTIONS in worker.md, BM-ANSWERS in manager.md,
+ * BM-REVIEW in reviewer.md), so the sender can be told and the user can see it.
+ * Every rule below comes from those templates and nothing else.
+ *
+ * Issue messages are English: they are sent back to agents.
+ *
+ * Pure and environment-neutral: no Node API, no React; the client (card chip)
+ * and the server (BM-FORMAT notice) import it alike.
+ */
+import { BEAD_ID } from "./bm-report";
+
+export type BlockKind = "BM-REPORT" | "BM-QUESTIONS" | "BM-ANSWERS" | "BM-REVIEW";
+
+export interface FormatIssue {
+  kind: BlockKind;
+  /** The field or question the issue is about; null for the block as a whole. */
+  field: string | null;
+  message: string;
+}
+
+export interface CheckedBlock {
+  kind: BlockKind;
+  requestId: string | null;
+  /** The block's own lines, as sent. */
+  text: string;
+  issues: FormatIssue[];
+}
+
+/** Longest message checked; the rest is reported as not checked. */
+export const MAX_CHECKED_CHARS = 20_000;
+
+const MARKER = /^(?:[-*]\s+)?(?:\*\*)?(BM-REPORT|BM-QUESTIONS|BM-ANSWERS|BM-REVIEW)(?:\*\*)?(\s+STOPPED)?\s*$/;
+const FENCE = /^\s*(?:```|~~~)/;
+const QUOTE = /^\s*>\s?/;
+const FIELD = /^([A-Za-z][A-Za-z0-9]*):(?:\s(.*))?$/;
+const REQUEST_ID = /^req-\d{8}T\d{6}Z$/;
+const PLACEHOLDER = /^<[^>]*>$/;
+const DASH = "(?:—|–|-)";
+
+export const REPORT_FIELDS = [
+  "requestId",
+  "phase",
+  "tier",
+  "filesChanged",
+  "beadsCreated",
+  "beadsUpdated",
+  "beadsClosed",
+  "beadsReady",
+  "reviewFindingsOpen",
+  "buildAndTests",
+  "skillsUsed",
+  "blockers",
+] as const;
+const PHASES = ["received", "beads-done", "blocked", "finished"];
+const TIER = /^(Small|Medium|Large) \(changed: (no|from (Small|Medium|Large), .+)\)$/;
+const BEAD_FIELDS = new Set(["beadsCreated", "beadsUpdated", "beadsClosed", "beadsReady"]);
+const SKILL = /^[a-z0-9][a-z0-9-]*$/i;
+const FINDING_OPEN = /^b\d+: \S.*$/;
+const BLOCKERS_QUESTIONS = new RegExp(`^(\\d+) questions?: (Q\\d+(?:, Q\\d+)*) ${DASH} see BM-QUESTIONS\\b`);
+
+const REVIEW_FIELDS = ["requestId", "batchId", "reviewKind", "verdict", "checked", "findings", "notChecked"] as const;
+const FINDING_FIELDS = ["severity", "location", "reason", "suggestedFix"] as const;
+
+const QUESTION = /^Q(\d+): \S.*$/;
+const OPTION = /^- ([a-z]): \S.*$/;
+const RECOMMENDED = /\(recommended\)\s*$/;
+const ANSWER = new RegExp(`^Q(\\d+): (?:[a-z]|other) ${DASH} \\S.*$`);
+
+const isNone = (value: string) => value.trim().toLowerCase() === "none";
+
+/** The block marker of a line (quote stripped), or null. */
+function markerOf(line: string): { kind: BlockKind; bare: boolean; stopped: boolean } | null {
+  const match = MARKER.exec(line.trim());
+  if (match === null) return null;
+  const kind = match[1] as BlockKind;
+  const stopped = match[2] !== undefined;
+  const bare = line.trim() === (stopped ? "BM-REVIEW STOPPED" : kind);
+  return { kind, bare, stopped };
+}
+
+/** Does `line` belong to a block of this kind (used to tell a stray blank line from the block's end)? */
+function continues(kind: BlockKind, line: string): boolean {
+  switch (kind) {
+    case "BM-REPORT":
+      return FIELD.test(line) && (REPORT_FIELDS as readonly string[]).includes(FIELD.exec(line)![1]!);
+    case "BM-QUESTIONS":
+      return /^Q\d+:/.test(line) || /^- [a-z]:/.test(line);
+    case "BM-ANSWERS":
+      return /^Q\d+:/.test(line);
+    case "BM-REVIEW":
+      return /^\s+\S/.test(line) || /^- severity:/.test(line) || (FIELD.test(line) && (REVIEW_FIELDS as readonly string[]).includes(FIELD.exec(line)![1]!));
+  }
+}
+
+interface RawBlock {
+  kind: BlockKind;
+  stopped: boolean;
+  bare: boolean;
+  lines: string[];
+  blankInside: boolean;
+  template: boolean;
+}
+
+/** Fields whose template value lists the allowed choices (`received | beads-done | …`). */
+const CHOICE_FIELDS = new Set(["phase", "tier", "reviewKind", "verdict", "severity"]);
+
+/** A line that shows the format rather than fills it: a `<placeholder>`, or a choice field listing `a | b`. */
+function isTemplateLine(line: string): boolean {
+  const field = FIELD.exec(line.replace(/^\s*-?\s*/, ""));
+  if (field === null) return false;
+  const value = (field[2] ?? "").trim();
+  return PLACEHOLDER.test(value) || (CHOICE_FIELDS.has(field[1]!) && /\S\s\|\s\S/.test(value));
+}
+
+/** Splits a message into its BM-* blocks. */
+function blocksOf(message: string): RawBlock[] {
+  const lines = message.split(/\r?\n/).map((line) => line.replace(QUOTE, ""));
+  const blocks: RawBlock[] = [];
+  let index = 0;
+  while (index < lines.length) {
+    const marker = markerOf(lines[index]!);
+    if (marker === null) {
+      index += 1;
+      continue;
+    }
+    const block: RawBlock = { kind: marker.kind, stopped: marker.stopped, bare: marker.bare, lines: [], blankInside: false, template: false };
+    index += 1;
+    if (!marker.stopped) {
+      while (index < lines.length) {
+        const line = lines[index]!;
+        if (FENCE.test(line) || markerOf(line) !== null) break;
+        if (line.trim() === "") {
+          let next = index + 1;
+          while (next < lines.length && lines[next]!.trim() === "") next += 1;
+          if (next < lines.length && !FENCE.test(lines[next]!) && markerOf(lines[next]!) === null && continues(block.kind, lines[next]!)) {
+            if (block.kind !== "BM-REVIEW") block.blankInside = true;
+            index = next;
+            continue;
+          }
+          break;
+        }
+        if (isTemplateLine(line)) block.template = true;
+        block.lines.push(line);
+        index += 1;
+      }
+    }
+    if (!block.template) blocks.push(block);
+  }
+  return blocks;
+}
+
+/** `key: value` lines of a block, in order; other lines as `null` keys. */
+function fieldsOf(lines: readonly string[]): Array<{ key: string | null; value: string; line: string }> {
+  return lines.map((line) => {
+    const match = FIELD.exec(line);
+    return match === null ? { key: null, value: "", line } : { key: match[1]!, value: (match[2] ?? "").trim(), line };
+  });
+}
+
+function shorten(line: string): string {
+  const flat = line.trim();
+  return flat.length > 60 ? `${flat.slice(0, 57)}…` : flat;
+}
+
+function checkReport(block: RawBlock, questions: RawBlock | undefined, issue: (field: string | null, message: string) => void): string | null {
+  const fields = fieldsOf(block.lines);
+  const seen = new Map<string, string>();
+  const order: string[] = [];
+  for (const { key, value, line } of fields) {
+    if (key === null) {
+      issue(null, `line "${shorten(line)}" is not a field of the template`);
+      continue;
+    }
+    if (!(REPORT_FIELDS as readonly string[]).includes(key)) {
+      issue(key, "is not a field of the template");
+      continue;
+    }
+    if (seen.has(key)) {
+      issue(key, "appears twice");
+      continue;
+    }
+    seen.set(key, value);
+    order.push(key);
+  }
+  for (const key of REPORT_FIELDS) if (!seen.has(key)) issue(key, "is missing");
+  const expected = REPORT_FIELDS.filter((key) => seen.has(key));
+  const outOfPlace = order.findIndex((key, position) => key !== expected[position]);
+  if (outOfPlace !== -1) {
+    issue(null, `fields must follow the template order (${REPORT_FIELDS.join(", ")}); "${order[outOfPlace]}" is out of place`);
+  }
+
+  const requestId = seen.get("requestId");
+  if (requestId !== undefined && !REQUEST_ID.test(requestId)) issue("requestId", `must look like req-YYYYMMDDTHHMMSSZ (got "${shorten(requestId)}")`);
+  const phase = seen.get("phase");
+  if (phase !== undefined && !PHASES.includes(phase)) issue("phase", `must be one of ${PHASES.join(", ")} (got "${shorten(phase)}")`);
+  const tier = seen.get("tier");
+  if (tier !== undefined && !TIER.test(tier)) {
+    issue("tier", 'must be "Small|Medium|Large (changed: no)" or "… (changed: from <tier>, <reason>)"');
+  }
+  for (const key of BEAD_FIELDS) {
+    const value = seen.get(key);
+    if (value === undefined || isNone(value)) continue;
+    if (value.trim() === "") {
+      issue(key, "must be none or full bead ids separated by commas");
+      continue;
+    }
+    const bad = value.split(",").map((part) => part.trim()).filter((part) => !BEAD_ID.test(part) || /^\.\d/.test(part));
+    if (bad.length > 0) issue(key, `must be none or full bead ids separated by commas ("${shorten(bad[0]!)}" is not one)`);
+  }
+  const skills = seen.get("skillsUsed");
+  if (skills !== undefined && !isNone(skills) && skills.split(",").some((part) => !SKILL.test(part.trim()))) {
+    issue("skillsUsed", "must be none or skill names separated by commas");
+  }
+  const findings = seen.get("reviewFindingsOpen");
+  if (findings !== undefined && !isNone(findings) && findings.split(";").some((part) => !FINDING_OPEN.test(part.trim()))) {
+    issue("reviewFindingsOpen", 'must be none or "b<n>: <finding>" items separated by ";"');
+  }
+  for (const key of ["filesChanged", "buildAndTests", "blockers"]) {
+    if (seen.get(key) === "") issue(key, "is empty; write none");
+  }
+
+  if (phase === "blocked") {
+    if (questions === undefined) {
+      issue(null, "a blocked report must be followed by a BM-QUESTIONS block in the same message");
+    } else {
+      const ids = questionIds(questions);
+      const match = BLOCKERS_QUESTIONS.exec(seen.get("blockers") ?? "");
+      const listed = match === null ? null : match[2]!.split(", ");
+      if (match === null || Number(match[1]) !== listed!.length || listed!.join(",") !== ids.join(",")) {
+        issue("blockers", `must start "${ids.length} ${ids.length === 1 ? "question" : "questions"}: ${ids.join(", ")} — see BM-QUESTIONS"`);
+      }
+    }
+  }
+  return requestId ?? null;
+}
+
+function questionIds(block: RawBlock): string[] {
+  return block.lines.map((line) => QUESTION.exec(line)).filter((match) => match !== null).map((match) => `Q${match![1]}`);
+}
+
+function checkQuestions(block: RawBlock, reportRequestId: string | null, issue: (field: string | null, message: string) => void): string | null {
+  const [first, ...rest] = block.lines;
+  const head = first === undefined ? null : FIELD.exec(first);
+  let requestId: string | null = null;
+  if (head === null || head[1] !== "requestId") {
+    issue("requestId", "must be the first line of the block");
+  } else {
+    requestId = (head[2] ?? "").trim();
+    if (!REQUEST_ID.test(requestId)) issue("requestId", `must look like req-YYYYMMDDTHHMMSSZ (got "${shorten(requestId)}")`);
+    else if (reportRequestId !== null && requestId !== reportRequestId) issue("requestId", `must equal the report's ${reportRequestId}`);
+  }
+  const body = head !== null && head[1] === "requestId" ? rest : block.lines;
+
+  const questions: Array<{ id: string; number: number; options: string[] }> = [];
+  for (const line of body) {
+    const question = QUESTION.exec(line);
+    if (question !== null) {
+      questions.push({ id: `Q${question[1]}`, number: Number(question[1]), options: [] });
+      continue;
+    }
+    if (OPTION.test(line) && questions.length > 0) {
+      questions.at(-1)!.options.push(line);
+      continue;
+    }
+    issue(null, `line "${shorten(line)}" is neither "Q<n>: <question>" nor "- <letter>: <option>"`);
+  }
+  if (questions.length < 1 || questions.length > 5) issue(null, `needs 1 to 5 questions (found ${questions.length})`);
+  const seen = new Set<string>();
+  let previous = 0;
+  for (const question of questions) {
+    if (seen.has(question.id)) issue(question.id, "appears twice");
+    else if (question.number <= previous) issue(question.id, `must come after Q${previous}: numbers go up`);
+    seen.add(question.id);
+    previous = Math.max(previous, question.number);
+    if (question.options.length < 2) issue(question.id, `needs at least 2 options (found ${question.options.length})`);
+    const letters = question.options.map((option) => OPTION.exec(option)![1]!);
+    if (letters.some((letter, position) => letter !== String.fromCharCode(97 + position))) {
+      issue(question.id, `option letters must run a, b, c… (found ${letters.join(", ")})`);
+    }
+    const recommended = question.options.filter((option) => RECOMMENDED.test(option)).length;
+    if (recommended !== 1) issue(question.id, `needs exactly one option ending in (recommended) (found ${recommended})`);
+  }
+  return requestId;
+}
+
+function checkAnswers(block: RawBlock, issue: (field: string | null, message: string) => void): string | null {
+  const [first, ...rest] = block.lines;
+  const head = first === undefined ? null : FIELD.exec(first);
+  let requestId: string | null = null;
+  if (head === null || head[1] !== "requestId") issue("requestId", "must be the first line of the block");
+  else {
+    requestId = (head[2] ?? "").trim();
+    if (!REQUEST_ID.test(requestId)) issue("requestId", `must look like req-YYYYMMDDTHHMMSSZ (got "${shorten(requestId)}")`);
+  }
+  const body = head !== null && head[1] === "requestId" ? rest : block.lines;
+  const seen = new Set<string>();
+  for (const line of body) {
+    const answer = ANSWER.exec(line);
+    if (answer === null) {
+      issue(null, `line "${shorten(line)}" must be "Q<n>: <letter> — <option>" or "Q<n>: other — <words>"`);
+      continue;
+    }
+    const id = `Q${answer[1]}`;
+    if (seen.has(id)) issue(id, "is answered twice");
+    seen.add(id);
+  }
+  if (seen.size === 0) issue(null, "answers no question");
+  return requestId;
+}
+
+function checkReview(block: RawBlock, issue: (field: string | null, message: string) => void): string | null {
+  if (block.stopped) return null;
+  const seen = new Map<string, string>();
+  const findings: Array<Map<string, string>> = [];
+  let inFindings = false;
+  for (const line of block.lines) {
+    const item = /^- ([A-Za-z]+):(?:\s(.*))?$/.exec(line);
+    const nested = /^\s+([A-Za-z]+):(?:\s(.*))?$/.exec(line);
+    if (inFindings && item !== null) {
+      findings.push(new Map([[item[1]!, (item[2] ?? "").trim()]]));
+      continue;
+    }
+    if (inFindings && nested !== null && findings.length > 0) {
+      findings.at(-1)!.set(nested[1]!, (nested[2] ?? "").trim());
+      continue;
+    }
+    const field = FIELD.exec(line);
+    if (field === null) {
+      issue(null, `line "${shorten(line)}" is not a field of the template`);
+      continue;
+    }
+    const key = field[1]!;
+    inFindings = key === "findings";
+    if (!(REVIEW_FIELDS as readonly string[]).includes(key)) issue(key, "is not a field of the template");
+    else if (seen.has(key)) issue(key, "appears twice");
+    else seen.set(key, (field[2] ?? "").trim());
+  }
+  for (const key of REVIEW_FIELDS) if (!seen.has(key)) issue(key, "is missing");
+  const requestId = seen.get("requestId");
+  if (requestId !== undefined && !REQUEST_ID.test(requestId)) issue("requestId", `must look like req-YYYYMMDDTHHMMSSZ (got "${shorten(requestId)}")`);
+  const batchId = seen.get("batchId");
+  if (batchId !== undefined && !/^b\d+$/.test(batchId)) issue("batchId", `must look like b<n> (got "${shorten(batchId)}")`);
+  const kind = seen.get("reviewKind");
+  if (kind !== undefined && kind !== "first" && kind !== "re-review") issue("reviewKind", "must be first or re-review");
+  const verdict = seen.get("verdict");
+  if (verdict !== undefined && verdict !== "pass" && verdict !== "changes-required") issue("verdict", "must be pass or changes-required");
+
+  const listed = seen.get("findings");
+  if (listed !== undefined) {
+    if (isNone(listed) && findings.length > 0) issue("findings", "says none but lists findings");
+    if (!isNone(listed) && listed !== "") issue("findings", 'must be "none" or be followed by "- severity: …" items');
+    if (listed === "" && findings.length === 0) issue("findings", 'lists no finding; write "findings: none"');
+  }
+  findings.forEach((finding, position) => {
+    const name = `finding ${position + 1}`;
+    for (const key of FINDING_FIELDS) if (!finding.has(key) || finding.get(key) === "") issue(name, `is missing "${key}"`);
+    for (const key of finding.keys()) if (!(FINDING_FIELDS as readonly string[]).includes(key)) issue(name, `has an unknown field "${key}"`);
+    const severity = finding.get("severity");
+    if (severity !== undefined && severity !== "blocking" && severity !== "non-blocking") issue(name, "severity must be blocking or non-blocking");
+  });
+  const blocking = findings.some((finding) => finding.get("severity") === "blocking");
+  if (verdict === "pass" && blocking) issue("verdict", "must be changes-required: a finding is blocking");
+  if (verdict === "changes-required" && !blocking) issue("verdict", "must be pass: no finding is blocking");
+  return requestId ?? null;
+}
+
+/**
+ * Every BM-* block of a message, in order, each with its template issues.
+ * Blocks that only show the format (a `<placeholder>` or `a | b` choices) are
+ * left out. Never throws.
+ */
+export function checkBlocks(message: unknown): CheckedBlock[] {
+  try {
+    if (typeof message !== "string" || message === "") return [];
+    const tooLong = message.length > MAX_CHECKED_CHARS;
+    const raw = blocksOf(tooLong ? message.slice(0, MAX_CHECKED_CHARS) : message);
+    let reportRequestId: string | null = null;
+    const out = raw.map((block, position): CheckedBlock => {
+      const issues: FormatIssue[] = [];
+      const issue = (field: string | null, text: string) => issues.push({ kind: block.kind, field, message: text });
+      if (!block.bare) issue(null, `the block must start with the bare line ${block.stopped ? "BM-REVIEW STOPPED" : block.kind}`);
+      if (block.blankInside) issue(null, "has a blank line inside; the template has none");
+      let requestId: string | null = null;
+      switch (block.kind) {
+        case "BM-REPORT": {
+          const next = raw[position + 1];
+          requestId = checkReport(block, next?.kind === "BM-QUESTIONS" ? next : undefined, issue);
+          reportRequestId = requestId;
+          break;
+        }
+        case "BM-QUESTIONS":
+          requestId = checkQuestions(block, raw[position - 1]?.kind === "BM-REPORT" ? reportRequestId : null, issue);
+          break;
+        case "BM-ANSWERS":
+          requestId = checkAnswers(block, issue);
+          break;
+        case "BM-REVIEW":
+          requestId = checkReview(block, issue);
+          break;
+      }
+      return { kind: block.kind, requestId, text: [block.stopped ? "BM-REVIEW STOPPED" : block.kind, ...block.lines].join("\n"), issues };
+    });
+    if (tooLong && out.length > 0) {
+      const last = out.at(-1)!;
+      last.issues.push({ kind: last.kind, field: null, message: `message too long to check in full (over ${MAX_CHECKED_CHARS} characters)` });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/** `BM-REPORT phase: must be …` — one line per issue, as the card lists them. */
+export function issueText(issue: FormatIssue): string {
+  return issue.field === null ? `${issue.kind}: ${issue.message}` : `${issue.kind} ${issue.field}: ${issue.message}`;
+}

package/shared/bm-questions.ts

@@ -0,0 +1,213 @@
+/**
+ * Reader for the `BM-QUESTIONS` block a Worker puts right after its `blocked`
+ * `BM-REPORT`, and writer of the `BM-ANSWERS` block that answers it
+ * (delta 20260918c-question-cards §4.1–§4.3).
+ *
+ * Like the report reader next door, it reads what a language model wrote, so
+ * it is forgiving: quoting, fences, bold ids, `(a)` instead of `a:`, wrapped
+ * lines. What it cannot read it leaves out rather than guesses — a card
+ * without buttons falls back to a free-text reply, while a guessed split could
+ * put an option under the wrong question.
+ *
+ * Kept apart from `bm-report.ts` so the consumed `BM-REPORT` contract and its
+ * fixtures do not change: a `BM-QUESTIONS` line has no `key:` shape, so it
+ * already ends a report block there.
+ *
+ * Pure and environment-neutral: the chat card runs it on every message.
+ */
+
+export interface QuestionOption {
+  /** Lowercase letter: `a`, `b`, … */
+  key: string;
+  text: string;
+  recommended: boolean;
+}
+
+export interface Question {
+  /** `Q<n>`; unique within one request, because Workers count on across rounds. */
+  id: string;
+  text: string;
+  options: QuestionOption[];
+}
+
+export interface QuestionSet {
+  requestId: string | null;
+  questions: Question[];
+}
+
+/** One answer: an option's key, or the user's own words. */
+export type Pick = { key: string } | { other: string };
+
+/** Characters read from the marker on. The marker itself is found in the whole message. */
+export const MAX_BLOCK_CHARS = 20_000;
+export const MAX_QUESTIONS = 10;
+export const MAX_OPTIONS = 8;
+export const MAX_TEXT_CHARS = 1000;
+
+const QUESTIONS_MARKER = /^\s*(?:>\s*)*(?:[-*]\s+)?(?:\*\*)?bm-questions(?:\*\*)?\s*$/i;
+/** Any paseo-bm block start: the end of this block. */
+const ANY_MARKER = /^\s*(?:>\s*)*(?:[-*]\s+)?(?:\*\*)?bm-(?:report|review|questions|answers)\b/i;
+const FENCE = /^\s*(?:>\s*)*(?:```|~~~)/;
+const QUOTE = /^\s*(?:>\s?)+/;
+const REQUEST_ID = /^\s*(?:[-*]\s+)?requestId\s*:\s*(.*)$/i;
+const QUESTION = /^\s*(?:[-*]\s+)?(?:\*\*)?Q(\d{1,3})(?:\*\*)?\s*[:.)]\s*(?:\*\*)?\s*(.*)$/;
+/** `- a: …`, `- a) …`, `- a. …`, `- (a) …` */
+const BULLET_OPTION = /^\s*[-*]\s+(?:\(([a-z])\)|([a-z])\s*[:.)])\s*(.*)$/i;
+/** `(a) …`, `a) …` — without a bullet the parenthesis is required, so prose `a: …` is not an option. */
+const PAREN_OPTION = /^\s*(?:\(([a-z])\)|([a-z])\))\s+(.*)$/i;
+const RECOMMENDED = /\s*[([]\s*recommended\s*[)\]]/i;
+const RECOMMENDED_ALL = new RegExp(RECOMMENDED.source, "gi");
+const INDENTED = /^\s{2,}\S/;
+const ABSENT = new Set(["", "none", "n/a", "na", "-", "null", "nil"]);
+
+function cut(text: string): string {
+  return text.length <= MAX_TEXT_CHARS ? text : `${text.slice(0, MAX_TEXT_CHARS - 1)}…`;
+}
+
+/** Appends a wrapped line, stopping once the text is already at its cap. */
+function appended(text: string, more: string): string {
+  if (text.length >= MAX_TEXT_CHARS) return text;
+  return text === "" ? more : `${text} ${more}`;
+}
+
+function cleanRequestId(raw: string): string | null {
+  const value = raw.trim().replace(/^[`*]+|[`*]+$/g, "").trim();
+  return ABSENT.has(value.toLowerCase()) ? null : value;
+}
+
+interface Draft {
+  id: string;
+  text: string;
+  options: Array<{ key: string; text: string }>;
+}
+
+function finish(draft: Draft): Question {
+  const options = draft.options.map((option) => {
+    const recommended = RECOMMENDED.test(option.text);
+    return { key: option.key, text: cut(option.text.replace(RECOMMENDED_ALL, "").trim()), recommended };
+  });
+  // More than one recommendation is no recommendation: the card never picks.
+  const marked = options.filter((option) => option.recommended).length;
+  return {
+    id: draft.id,
+    text: cut(draft.text.replace(/\*\*/g, "").trim()),
+    options: marked > 1 ? options.map((option) => ({ ...option, recommended: false })) : options,
+  };
+}
+
+/**
+ * The last `BM-QUESTIONS` block of a message, or null when it has none.
+ *
+ * The block follows a report that can be long, so the marker is looked for
+ * across the whole message (one anchored test per line, linear); only the
+ * reading from the marker on is capped at `MAX_BLOCK_CHARS`.
+ */
+export function parseQuestions(text: string): QuestionSet | null {
+  if (typeof text !== "string" || text === "") return null;
+  const lines = text.split(/\r?\n/);
+  let start = -1;
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (QUESTIONS_MARKER.test(lines[index]!)) {
+      start = index;
+      break;
+    }
+  }
+  if (start === -1) return null;
+
+  let requestId: string | null = null;
+  const drafts: Draft[] = [];
+  const seenIds = new Set<string>();
+  /** Null before the first question and after a duplicate id, whose options are dropped with it. */
+  let current: Draft | null = null;
+  let budget = MAX_BLOCK_CHARS - lines[start]!.length - 1;
+  let started = false;
+
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const raw = lines[index]!;
+    budget -= raw.length + 1;
+    if (budget < 0) break;
+    const line = raw.replace(QUOTE, "");
+    if (line.trim() === "") continue;
+    if (FENCE.test(raw)) {
+      // A fence right after the marker opens the block; a later one closes it.
+      if (!started) continue;
+      break;
+    }
+    if (ANY_MARKER.test(raw)) break;
+
+    const request = REQUEST_ID.exec(line);
+    if (request !== null) {
+      started = true;
+      if (requestId === null) requestId = cleanRequestId(request[1] ?? "");
+      continue;
+    }
+
+    const question = QUESTION.exec(line);
+    if (question !== null) {
+      started = true;
+      const id = `Q${Number.parseInt(question[1]!, 10)}`;
+      if (seenIds.has(id)) {
+        current = null;
+        continue;
+      }
+      if (drafts.length >= MAX_QUESTIONS) break;
+      seenIds.add(id);
+      current = { id, text: cut(question[2] ?? ""), options: [] };
+      drafts.push(current);
+      continue;
+    }
+
+    const option = BULLET_OPTION.exec(line) ?? PAREN_OPTION.exec(line);
+    if (option !== null) {
+      if (current === null) continue;
+      const key = (option[1] ?? option[2] ?? "").toLowerCase();
+      const body = (option[3] ?? "").replace(/^[:.]\s*/, "");
+      if (current.options.length < MAX_OPTIONS && !current.options.some((known) => known.key === key)) {
+        current.options.push({ key, text: cut(body) });
+      }
+      continue;
+    }
+
+    if (INDENTED.test(line)) {
+      const last = current?.options.at(-1);
+      if (last !== undefined) last.text = appended(last.text, line.trim());
+      else if (current !== null) current.text = appended(current.text, line.trim());
+      continue;
+    }
+
+    // Prose before the first question is an introduction; after it, the end.
+    if (drafts.length === 0) continue;
+    break;
+  }
+
+  return { requestId, questions: drafts.map(finish) };
+}
+
+function oneLine(text: string): string {
+  return text.replace(/\s*\r?\n\s*/g, " ").trim();
+}
+
+/**
+ * The `BM-ANSWERS` block for `picks`, one line per question in question order.
+ *
+ * Every question must have an answer: a missing pick, an unknown key or a
+ * blank `other` throws, so a programming error can never send a partial
+ * answer the Worker would take for the user's whole reply.
+ */
+export function answersText(requestId: string, questions: readonly Question[], picks: Readonly<Record<string, Pick>>): string {
+  const lines = ["BM-ANSWERS", `requestId: ${requestId}`];
+  for (const question of questions) {
+    const pick = picks[question.id];
+    if (pick === undefined) throw new Error(`No answer for ${question.id}.`);
+    if ("key" in pick) {
+      const option = question.options.find((candidate) => candidate.key === pick.key);
+      if (option === undefined) throw new Error(`${question.id} has no option "${pick.key}".`);
+      lines.push(`${question.id}: ${option.key} — ${oneLine(option.text)}`);
+    } else {
+      const words = oneLine(pick.other);
+      if (words === "") throw new Error(`The answer to ${question.id} is empty.`);
+      lines.push(`${question.id}: other — ${words}`);
+    }
+  }
+  return lines.join("\n");
+}