@thebattlearena/corner 0.10.0 → 0.10.1-beta.78

package/ring/scripts/brief.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// The briefs of the ring's agents, generated from the templates with the rules embedded in full, so
+// what a wrestler or a cornerman knows does not depend on what the referee still remembers.
+// Zero-dependency; the rules are brief-build.mjs.
+//
+//   node brief.mjs wrestler  <pr> --mode start|resume|cutoff --vars <file.json>
+//   node brief.mjs cornerman <pr> --mode range|concept|batch --vars <file.json>
+//                            [--range <A>..<B>] [--files <f1,f2,…>]
+//   node brief.mjs verify <brief.md>      exit 0 while it holds, 1 when it does not
+//
+// The referee writes only its own values (the assignment, the invariants…) to the --vars JSON; the
+// script fills the rest from the bout, writes `<bout dir>/briefs/<kind>-<mode>-<n>.md`, logs it in
+// `briefs/index.jsonl` and prints the path and the Agent call. The referee passes the file as it is.
+import { execFileSync } from 'node:child_process';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  briefStatus,
+  decisionsExcerpt,
+  fill,
+  readSeal,
+  rulesBlock,
+  seal,
+  sha256,
+  strayPaths,
+} from './brief-build.mjs';
+import {
+  boutDir,
+  isMain,
+  loadConfig,
+  projectDir,
+  readState,
+  repoSlug,
+  ringHome,
+  RING_ROOT,
+} from './config.mjs';
+import { loadRules } from './rule-ids.mjs';
+
+const TEMPLATES = join(RING_ROOT, 'skills', 'referee', 'templates');
+
+/** Per kind and mode: the templates in order, and whether the rules go in (a cut-off resumes the same agent). */
+const SHAPES = {
+  wrestler: {
+    start: { templates: ['wrestler-brief.md'], rules: true },
+    resume: {
+      templates: ['wrestler-resume.md', 'wrestler-brief.md'],
+      rules: true,
+    },
+    cutoff: { templates: ['wrestler-cutoff.md'], rules: false },
+  },
+  cornerman: {
+    range: { templates: ['cornerman-range.md'], rules: true },
+    concept: { templates: ['cornerman-concept.md'], rules: true },
+    batch: { templates: ['cornerman-batch.md'], rules: true },
+  },
+};
+
+/** What the referee may leave out, and what stands in for it. */
+const OPTIONAL = {
+  claims: 'none',
+  comments: 'none',
+  referencePattern: 'none yet: no round-bell approved so far',
+  designReference: 'not applicable: this concept draws no screen',
+};
+
+const git = (dir, args) =>
+  execFileSync('git', ['-C', dir, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+
+function flags(argv) {
+  const values = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (!argv[i].startsWith('--')) {
+      rest.push(argv[i]);
+      continue;
+    }
+    values[argv[i].slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return { values, rest };
+}
+
+/** The bout of `pr` in this repo: its dir, its state and its venue's config. */
+function boutOf(pr) {
+  const dir = boutDir(repoSlug(projectDir()), pr);
+  if (!existsSync(join(dir, 'state.json')))
+    throw new Error(`no bout #${pr} in this repo (${dir})`);
+  const state = readState(dir);
+  const { config } = loadConfig(projectDir(), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  return { dir, state, config };
+}
+
+/** The rules block of a bout and its hash: what a brief embeds and what a seal is checked against. */
+function rulesOf(config) {
+  const block = rulesBlock(loadRules(config));
+  return { block, hash: sha256(block) };
+}
+
+/** What the script knows about the bout and its worktree. */
+function boutVars({ dir, state, config }, values) {
+  const { worktree } = state;
+  const head = git(worktree, ['rev-parse', 'HEAD']);
+  const range =
+    values.range ??
+    (state.lastReviewed ? `${state.lastReviewed}..${head}` : null);
+  const commits = range
+    ? git(worktree, ['log', '--reverse', '--format=- `%h` %s', range]) ||
+      '(none)'
+    : '(no range)';
+  const files = values.files
+    ? values.files
+        .split(',')
+        .map((file) => file.trim())
+        .filter(Boolean)
+    : range
+      ? git(worktree, ['diff', '--name-only', range])
+          .split('\n')
+          .filter(Boolean)
+      : [];
+  const gate = (name) => config.gates?.[name] ?? 'none configured';
+  return {
+    files,
+    vars: {
+      pr: state.pr,
+      branch: state.branch,
+      base: `origin/${state.base}`,
+      worktree,
+      boutDir: dir,
+      ring: RING_ROOT,
+      venue: config.venue,
+      range: range ?? '',
+      commits,
+      headSha: head.slice(0, 12),
+      lastSubject: git(worktree, ['log', '-1', '--format=%s']),
+      gateTypecheck: gate('typecheck'),
+      gateTest: gate('test'),
+      gateLint: gate('lint'),
+      forbidAiTrailers: String(config.forbidAiTrailers),
+      diskFloor: String(config.diskFloorGb ?? 5),
+      backupBranch: String(config.backupBranch ?? 'none').replace(
+        '{pr}',
+        state.pr,
+      ),
+      lenses: (config.lenses ?? []).join('; '),
+      leftoverPaths: files.join(', ') || 'the files of the range',
+      files: files.map((file) => `- ${file}`).join('\n'),
+    },
+  };
+}
+
+const real = (path) => (existsSync(path) ? realpathSync(path) : path);
+
+function generate(kind, [pr, ...argv]) {
+  const { values } = flags(argv);
+  const shape = SHAPES[kind]?.[values.mode];
+  if (!pr || !shape)
+    throw new Error(
+      `usage: ${kind} <pr> --mode ${Object.keys(SHAPES[kind]).join('|')} --vars <file.json>`,
+    );
+  const bout = boutOf(pr);
+  const own = values.vars ? JSON.parse(readFileSync(values.vars, 'utf8')) : {};
+  const roots = [
+    projectDir(),
+    bout.state.worktree,
+    bout.dir,
+    RING_ROOT,
+    ringHome(),
+  ].map(real);
+  const stray = strayPaths(own, roots);
+  if (stray.length)
+    throw new Error(
+      `paths outside the repo, the worktree, the bout dir and the ring (a session scratchpad is wiped on restart; what the human asked for goes to decisions.md or the technical plan):\n${stray.map(({ name, path }) => `  ${name}: ${path}`).join('\n')}`,
+    );
+  const { vars, files } = boutVars(bout, values);
+  const text = fill(
+    shape.templates
+      .map((name) => readFileSync(join(TEMPLATES, name), 'utf8'))
+      .join('\n'),
+    { ...OPTIONAL, ...vars, ...own },
+  );
+  const decisionsPath = join(bout.dir, 'decisions.md');
+  const decisions = decisionsExcerpt(
+    existsSync(decisionsPath) ? readFileSync(decisionsPath, 'utf8') : '',
+    files,
+  );
+  const rules = rulesOf(bout.config);
+  // The task goes first and the rules last, as the reference: a brief that opens with the rules
+  // reads as a checklist, and a 2026-11 lab on #1212 found fewer real problems that way.
+  const body = [
+    text.trim(),
+    '## Decisions already taken (excerpt: every foul, the ones on these files, the last 20)',
+    decisions,
+    `The whole ledger: \`${decisionsPath}\`.`,
+    ...(shape.rules ? ['---', rules.block] : []),
+  ].join('\n\n');
+  const briefs = join(bout.dir, 'briefs');
+  mkdirSync(briefs, { recursive: true });
+  const index = join(briefs, 'index.jsonl');
+  const n = existsSync(index)
+    ? readFileSync(index, 'utf8').split('\n').filter(Boolean).length + 1
+    : 1;
+  const meta = {
+    kind,
+    mode: values.mode,
+    pr,
+    n,
+    rules: shape.rules ? rules.hash : 'none',
+  };
+  const file = join(briefs, `${kind}-${values.mode}-${n}.md`);
+  writeFileSync(file, seal(body, meta));
+  appendFileSync(
+    index,
+    `${JSON.stringify({ ...meta, range: vars.range || null, at: new Date().toISOString(), vars: Object.keys(own) })}\n`,
+  );
+  const launch = bout.config.agents?.[kind] ?? {};
+  console.log(file);
+  console.log(
+    `Agent{subagent_type: "ring:${kind}", model: "${launch.model}", effort: "${launch.effort}", prompt: "ring-brief: ${file}"}`,
+  );
+}
+
+/**
+ * Whether a brief's text still holds: sealed by brief.mjs, unedited, and on the rules in force
+ * today. Returns the seal's meta too (kind, mode, pr) so a caller can check it is the right brief.
+ */
+export function checkBrief(text) {
+  const sealed = readSeal(text);
+  const rulesNow = (meta) =>
+    meta.rules === 'none' ? 'none' : rulesOf(boutOf(meta.pr).config).hash;
+  return {
+    ...briefStatus(text, sealed ? rulesNow(sealed.meta) : null),
+    meta: sealed?.meta ?? null,
+  };
+}
+
+function verify([path]) {
+  if (!path) throw new Error('usage: verify <brief.md>');
+  const status = checkBrief(readFileSync(path, 'utf8'));
+  console.log(
+    status.ok ? 'brief holds' : `brief does not hold: ${status.reason}`,
+  );
+  return status.ok ? 0 : 1;
+}
+
+if (isMain(import.meta.url)) {
+  const [command, ...rest] = process.argv.slice(2);
+  try {
+    if (command === 'verify') process.exit(verify(rest));
+    if (!SHAPES[command])
+      throw new Error(
+        'usage: brief.mjs wrestler|cornerman <pr> --mode … | verify <brief.md>',
+      );
+    generate(command, rest);
+  } catch (error) {
+    console.error(`brief: ${error.message}`);
+    process.exit(1);
+  }
+}

package/ring/scripts/compact-hook.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Hook on SessionStart (matcher `compact`): after a compaction the referee's context loses what it
+// knew of the bout. This puts back, in under 10,000 characters (Claude Code's cap for hook output),
+// what must not be lost: which bout it referees and where its card and ledger live, the
+// architecture checklist, the bout's fouls (what must not happen again), the card's latest «how to
+// resume», and the rule that every wrestler and cornerman is launched with a brief from brief.mjs.
+// Zero-dependency. Only a session registered in a bout gets it; any error ends in exit 0, silent.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  isMain,
+  loadConfig,
+  projectDir,
+  readState,
+  RING_ROOT,
+} from './config.mjs';
+import { findBout, sessionRegistered } from './live.mjs';
+import { checklistLines, loadRules } from './rule-ids.mjs';
+
+/** Claude Code's cap for SessionStart output, with room to spare. */
+export const BUDGET = 9500;
+const RESUME = /^##\s+(How to resume|Cómo reanudar)\b/i;
+
+/** The card's first «how to resume» section (the newest is on top), cut to `max` characters. PURE. */
+export function resumeSection(card, max = 2500) {
+  const lines = String(card ?? '').split('\n');
+  const start = lines.findIndex((line) => RESUME.test(line));
+  if (start < 0) return '';
+  const end = lines.findIndex((line, i) => i > start && /^##\s/.test(line));
+  const text = lines
+    .slice(start + 1, end < 0 ? undefined : end)
+    .join('\n')
+    .trim();
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/** The ledger's fouls, newest last, cut to `max` characters from the oldest. PURE. */
+export function foulLines(decisions, max = 3000) {
+  const fouls = String(decisions ?? '')
+    .split('\n')
+    .filter((line) => /\bFOUL\b/.test(line));
+  const kept = [];
+  let size = 0;
+  for (const line of fouls.reverse()) {
+    if (size + line.length + 1 > max) break;
+    kept.unshift(line);
+    size += line.length + 1;
+  }
+  const dropped = fouls.length - kept.length;
+  return [
+    ...(dropped ? [`(${dropped} older fouls in decisions.md)`] : []),
+    ...kept,
+  ].join('\n');
+}
+
+/** The text a compacted referee gets back. PURE. */
+export function compactContext({ pr, dir, checklist, fouls, resume }) {
+  const text = [
+    `# Ring: you referee bout #${pr} (context restored after a compaction)`,
+    '',
+    `Reread before acting: the judges card \`${join(dir, 'judges-card.md')}\` and the ledger \`${join(dir, 'decisions.md')}\`. Every wrestler and cornerman is launched with a brief from \`node ${RING_ROOT}/scripts/brief.mjs\` and \`prompt: "ring-brief: <path>"\`; never a brief written by hand. Every finding cites its rule id (or X0).`,
+    '',
+    '## Architecture checklist (the full rules go in every brief)',
+    checklist || '(none for this venue)',
+    '',
+    '## Fouls of this bout (never again)',
+    fouls || '(none)',
+    ...(resume ? ['', '## How to resume (from the card)', resume] : []),
+  ].join('\n');
+  return text.length > BUDGET ? `${text.slice(0, BUDGET)}…` : text;
+}
+
+const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : '');
+
+/** The hook on one input: the text to print, or null. */
+export function restore(input) {
+  if (input?.hook_event_name !== 'SessionStart') return null;
+  if (input.source && input.source !== 'compact') return null;
+  const dir = findBout({ cwd: input.cwd });
+  if (!dir || !sessionRegistered(dir, input.session_id)) return null;
+  const state = readState(dir);
+  const { config } = loadConfig(projectDir(process.env, input.cwd), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  return compactContext({
+    pr: state.pr,
+    dir,
+    checklist: checklistLines(loadRules(config).entries).join('\n'),
+    fouls: foulLines(read(join(dir, 'decisions.md'))),
+    resume: resumeSection(read(join(dir, 'judges-card.md'))),
+  });
+}
+
+if (isMain(import.meta.url)) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => (raw += chunk));
+  process.stdin.on('end', () => {
+    let out = null;
+    try {
+      out = restore(JSON.parse(raw));
+    } catch {
+      out = null;
+    }
+    if (out) process.stdout.write(out);
+    process.exit(0);
+  });
+}

package/ring/scripts/config.mjs

@@ -106,6 +106,9 @@ export const DEFAULT_HEAVY_COMMANDS = [
   'make test',
 ];
 
+/** What brief-guard does with a launch whose brief brief.mjs did not generate. */
+export const BRIEF_GUARD_MODES = ['warn', 'block', 'off'];
+
 export const DEFAULTS = Object.freeze({
   gates: { typecheck: null, test: null, lint: null },
   validateCommand: null,
@@ -136,6 +139,17 @@ export const DEFAULTS = Object.freeze({
     previewTimeoutMin: 20,
     staleDays: 7,
   }),
+  // brief-guard on every Agent launch of a wrestler or cornerman in a bout: 'warn' lets a brief
+  // that brief.mjs did not generate through and says so; 'block' refuses it; 'off' does nothing.
+  briefGuard: 'warn',
+  // The model and effort of each ring agent, passed on every launch. Who writes runs on the
+  // cheaper model at high effort; who reviews keeps the strongest one (what slipped in bout #1223
+  // slipped in review). A host overrides a role in `.claude/ring.json` (`agents.wrestler.model`).
+  agents: Object.freeze({
+    wrestler: Object.freeze({ model: 'sonnet', effort: 'high' }),
+    rudo: Object.freeze({ model: 'sonnet', effort: 'high' }),
+    cornerman: Object.freeze({ model: 'opus', effort: 'high' }),
+  }),
 });
 
 const GATES = ['typecheck', 'test', 'lint'];
@@ -331,6 +345,10 @@ export function mergeConfig(detected, host) {
     throw new Error(
       `.claude/ring.json: "delegation" must be one of ${DELEGATION_LEVELS.join(', ')}, not ${JSON.stringify(own.delegation)}`,
     );
+  if ('briefGuard' in own && !BRIEF_GUARD_MODES.includes(own.briefGuard))
+    throw new Error(
+      `.claude/ring.json: "briefGuard" must be one of ${BRIEF_GUARD_MODES.join(', ')}, not ${JSON.stringify(own.briefGuard)}`,
+    );
   validateVenues(own.venues, VENUE_NAMES);
   return {
     ...DEFAULTS,
@@ -349,6 +367,12 @@ export function mergeConfig(detected, host) {
         ? null
         : { ...DEFAULTS.findingsGate, ...(own.findingsGate ?? {}) },
     sparring: { ...DEFAULTS.sparring, ...(own.sparring ?? {}) },
+    agents: Object.fromEntries(
+      Object.entries(DEFAULTS.agents).map(([role, launch]) => [
+        role,
+        { ...launch, ...(own.agents?.[role] ?? {}) },
+      ]),
+    ),
   };
 }
 

package/ring/scripts/findings.mjs

@@ -4,6 +4,9 @@
 //   node findings.mjs add <pr> --source range|concept|batch|final|copilot|human|contract [--range <from>..<to>]
 //                         (contract: the judge's «se mejora» on an endpoint, from judges-card page-verdicts)
 //                         (<text> | --file <report>)       one finding, or one per line of a report
+//                         [--rule <id>]  the referee's own rule for the lines that cite none (logged as theirs)
+//                         A reviewer's finding (range, concept, batch, final, human) cites a rule of the venue
+//                         in its second field (`<file:line> — R11 — …`); X0 when none covers it.
 //   node findings.mjs clean <pr> --range <from>..<to>      the cornerman found nothing in that range
 //   node findings.mjs applied <pr> F<n>[,F<m>…] <sha>      the wrestler applied it in that commit
 //   node findings.mjs discard <pr> F<n>[,…] --id D<k> --reason "<why>"
@@ -39,8 +42,16 @@ import {
   repoSlug,
 } from './config.mjs';
 import { record } from './live.mjs';
+import {
+  citedRules,
+  loadRules,
+  NO_RULE,
+  uncitedFindings,
+} from './rule-ids.mjs';
 
 export const LEDGER = 'findings.json';
+/** Sources whose findings come from a review against the rulebook, so each one cites a rule. */
+export const CITED_SOURCES = ['range', 'concept', 'batch', 'final', 'human'];
 export const SOURCES = [
   'range',
   'concept',
@@ -379,19 +390,85 @@ function scorecard(dir, ledger, label) {
   });
 }
 
+/**
+ * The rule each finding line answers to: the one it cites, or the referee's `--rule` for a line
+ * that cites none. Throws listing every line without a valid one. PURE.
+ */
+export function ruledLines(texts, ids, rule) {
+  if (rule && rule !== NO_RULE && !ids.has(rule))
+    throw new Error(`--rule ${rule} is not a rule of this venue`);
+  const lines = texts.map((text) => ({
+    text,
+    by: citedRules(text) || !rule ? null : 'referee',
+  }));
+  const pending = lines.filter((line) => !line.by).map((line) => line.text);
+  const wrong = uncitedFindings(pending, ids);
+  if (wrong.length)
+    throw new Error(
+      `every finding cites a rule of the venue in its second field (\`<file:line> — R11 — …\`), or X0 when none covers it; rebound the report to the cornerman, or take the line as yours with --rule <id>:\n${wrong.map(({ line, reason }) => `  ${line}  (${reason})`).join('\n')}`,
+    );
+  return lines.map(({ text, by }) => (by ? { text, by, rule } : { text }));
+}
+
+/** The findings no rule covers, as proposals for the rulebook in the judges card. */
+function proposeRules(dir, findings) {
+  const card = join(dir, 'judges-card.md');
+  const uncovered = findings.filter(
+    (finding) =>
+      finding.rule === NO_RULE || citedRules(finding.text)?.includes(NO_RULE),
+  );
+  if (!uncovered.length || !existsSync(card)) return;
+  const text = uncovered.reduce(
+    (current, finding) =>
+      withSectionLine(
+        current,
+        'For the rulebook / precedents',
+        `- ${finding.id} (X0, no rule covers it): ${finding.text} — which rule is missing?`,
+      ),
+    readFileSync(card, 'utf8'),
+  );
+  writeFileSync(card, text);
+}
+
 function add([pr, ...argv]) {
   const { values, rest } = flags(argv);
   const { dir, state } = bout(pr);
   const texts = values.file
     ? reportLines(readFileSync(values.file, 'utf8'))
     : [rest.join(' ').trim()].filter(Boolean);
+  const cited = CITED_SOURCES.includes(values.source);
+  const ids = cited
+    ? loadRules(
+        loadConfig(projectDir(), {
+          contract: false,
+          venue: state.venue ?? 'backend',
+        }).config,
+      ).ids
+    : null;
+  const lines = cited
+    ? ruledLines(texts, ids, values.rule)
+    : texts.map((text) => ({ text }));
   const { ledger, added } = withFindings(readLedger(dir), {
     source: values.source,
     ...rangeOf(state, values.range),
-    texts,
+    texts: lines.map((line) => line.text),
     at: now(),
   });
-  scorecard(dir, writeLedger(dir, ledger), 'registró hallazgos');
+  const authored = new Map(added.map((finding, i) => [finding.id, lines[i]]));
+  const findings = ledger.findings.map((finding) =>
+    authored.get(finding.id)?.by
+      ? { ...finding, by: 'referee', rule: authored.get(finding.id).rule }
+      : finding,
+  );
+  scorecard(
+    dir,
+    writeLedger(dir, { ...ledger, findings }),
+    'registró hallazgos',
+  );
+  proposeRules(
+    dir,
+    findings.filter((finding) => authored.has(finding.id)),
+  );
   for (const finding of added) console.log(`${finding.id} · ${finding.text}`);
 }
 

package/ring/scripts/rule-ids.mjs

@@ -0,0 +1,124 @@
+// The rules a bout runs on, read from its rulebooks and precedent files: the ids that exist (so a
+// finding cites a real one) and the one-line checklist every brief opens with. Zero-dependency.
+import { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * `**R11. SRP, SOLID…**` → { id: 'R11', title }. The heading of every rule and precedent; a long
+ * heading wraps onto the next lines, so the bold runs across them until its closing `**`.
+ */
+const ENTRY = /^\*\*([A-Z]{1,2}\d+)\.\s+([\s\S]+?)\*\*/gm;
+
+/**
+ * What the human's reviews keep finding and line-by-line reviews let through (bout #1223 and the
+ * review Tapes of 11 nov 2026: optionals and ternaries dragged downstream, defensive code, code
+ * coupled to each channel, repositories off the host's standard, hand-written types, raw provider
+ * responses): every brief opens with these in one line each, before the full text. Ids a venue
+ * does not define are skipped.
+ */
+export const ARCHITECTURE_CHECKLIST = [
+  'R3',
+  'R6',
+  'R8',
+  'R11',
+  'R12',
+  'R15',
+  'R16',
+  'R17',
+  'R18',
+  'R19',
+  'R20',
+  'R21',
+  'R22',
+  'R23',
+  'R24',
+  'R25',
+  'R26',
+  'R27',
+  'U6',
+  'U7',
+  'P14',
+  'P16',
+];
+
+/** The id that marks a finding no rule covers; it becomes a proposal for the rulebook. */
+export const NO_RULE = 'X0';
+
+/** Every rule or precedent heading of a Markdown file. PURE. */
+export function ruleEntries(markdown) {
+  return [...String(markdown ?? '').matchAll(ENTRY)].map(([, id, title]) => ({
+    id,
+    title: title.replace(/\s+/g, ' ').replace(/\.$/, ''),
+  }));
+}
+
+/**
+ * The rule files of a venue, in the order a brief embeds them: the rulebook, the venue's
+ * rulebooks, the bundled precedents, the venue's precedents and the host's (HPn, which win).
+ */
+export function ruleFiles(config) {
+  return [
+    config.rulebookPath,
+    ...(config.venueRulebookPaths ?? []),
+    config.bundledPrecedentsPath,
+    ...(config.venuePrecedentsPaths ?? []),
+    config.precedentsPath,
+  ].filter((path) => path && existsSync(path));
+}
+
+/** The rule files with their text and the ids they define. */
+export function loadRules(config) {
+  const sources = ruleFiles(config).map((path) => ({
+    path,
+    text: readFileSync(path, 'utf8'),
+  }));
+  const entries = sources.flatMap((source) => ruleEntries(source.text));
+  return { sources, entries, ids: new Set(entries.map((entry) => entry.id)) };
+}
+
+/** The checklist as Markdown lines, from whichever of its ids the rules define. PURE. */
+export function checklistLines(entries, ids = ARCHITECTURE_CHECKLIST) {
+  const byId = new Map(entries.map((entry) => [entry.id, entry.title]));
+  return ids
+    .filter((id) => byId.has(id))
+    .map((id) => `- **${id}** ${byId.get(id)}`);
+}
+
+const ID = /\b[A-Z]{1,2}\d+\b/g;
+const FORMAT_LINE = /(?:^|\s—\s)format\s—\s|NO VERIFICADO/;
+
+/**
+ * The rule ids a finding line cites in its rule field: the second field of
+ * `<file:line> — <rule id> — <what> — <how>`, or of a table row `| file | rule | … |`. The field
+ * may carry a severity or a note around the ids (`BLOCKER (P16/PR11)`, `X0 (security)`); only the
+ * ids count. Null when the field names none. PURE.
+ */
+export function citedRules(line) {
+  const text = String(line).trim();
+  const fields = text.startsWith('|')
+    ? text
+        .split('|')
+        .map((field) => field.trim())
+        .filter(Boolean)
+    : text.split(/\s+—\s+/);
+  const field = (fields[1] ?? '').replace(/`/g, '').trim();
+  const ids = field.match(ID);
+  return ids ? [...new Set(ids)] : null;
+}
+
+/**
+ * The finding lines that do not cite a real rule, with why: no rule field, or ids no loaded rule
+ * defines. A format line and `X0` (no rule covers it) are valid. PURE.
+ */
+export function uncitedFindings(lines, ids) {
+  return lines
+    .map((line) => ({ line, cited: citedRules(line) }))
+    .filter(({ line }) => !FORMAT_LINE.test(line))
+    .map(({ line, cited }) => {
+      if (!cited) return { line, reason: 'no rule id in its second field' };
+      const unknown = cited.filter((id) => id !== NO_RULE && !ids.has(id));
+      return unknown.length
+        ? { line, reason: `no rule ${unknown.join(', ')} in this venue` }
+        : null;
+    })
+    .filter(Boolean);
+}