@thebattlearena/corner 0.9.0 → 0.10.0

package/ring/scripts/preparation.mjs

@@ -0,0 +1,547 @@
+// The preparation of a bout, told before its first round: «el pesaje del contrato» (what was
+// promoted, the size of the deliverable, the database diagram the judge signs, the cornerman's
+// findings on the contract by severity and the scale: does the contract make weight?) and «la
+// entrevista» (each question the referee escalated to the judge, with its options and the referee's
+// recommendation, the judge's answer with its time, and apart from them the decisions the referee
+// took itself). Not to be confused with `/ring:weigh-in`, which configures the host's gates.
+// PURE and zero-dependency: play-by-play.mjs reads the files and hands them here.
+//
+// The interview's ledger is `<bout dir>/interview.jsonl`, written by `judges-card.mjs log`:
+//   { "kind": "escalation", "id": "E1", "at": <ISO>, "body": <the escalation as sent> }
+//   { "kind": "answer", "id": "A1", "to": "E1", "at": <ISO>, "judge": <name>, "said": <words> }
+import { isTime, parseDecisionLine } from './chronicle.mjs';
+
+export const INTERVIEW = 'interview.jsonl';
+
+/** Severities a cornerman writes as the first word of a finding, most severe first. */
+export const SEVERITIES = ['BLOCKER', 'FIX', 'NIT'];
+
+const OPTION =
+  /\(([a-z])\)\s*([^]*?)(?=\s*(?:·\s*)?\([a-z]\)\s|\.\s*(?:I recommend|[Tt]e recomiendo|[Rr]ecomiendo)\b|$)/g;
+const RECOMMEND =
+  /(?:I recommend|[Tt]e recomiendo|[Rr]ecomiendo)\s*\**\s*\(([a-z])\)\s*\**\s*(?:[:,]|because|porque)?\s*([^]*)$/;
+
+const plain = (text) =>
+  String(text ?? '')
+    .replace(/\*\*/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/**
+ * The questions of an escalation as sent to the judge (`templates/escalation.md`): every numbered
+ * item that offers options `(a) … · (b) …`, with the option the referee recommends and why. Items
+ * without options (the numbered lists of the report) are not questions. A question that runs over
+ * several lines keeps them. PURE.
+ */
+export function parseEscalation(text) {
+  const items = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const start = /^\s*(\d+)\.\s+(.*)$/.exec(line);
+    if (start) {
+      items.push({ n: Number(start[1]), text: start[2] });
+      continue;
+    }
+    const last = items.at(-1);
+    if (last && line.trim() && /^\s{2,}\S/.test(line))
+      last.text += ` ${line.trim()}`;
+  }
+  return items
+    .map(({ n, text: raw }) => {
+      const body = plain(raw);
+      const first = body.search(/\([a-z]\)\s/);
+      if (first === -1) return null;
+      const recommend = RECOMMEND.exec(body);
+      const offered = recommend ? body.slice(0, recommend.index) : body;
+      const options = [...offered.slice(first).matchAll(OPTION)].map(
+        ([, key, option]) => ({
+          key,
+          text: option.replace(/[\s·.]+$/, '').trim(),
+        }),
+      );
+      return {
+        n,
+        question: body.slice(0, first).replace(/[\s·—–-]+$/, ''),
+        options,
+        recommended: recommend?.[1] ?? null,
+        why: recommend
+          ? recommend[2].replace(/^[\s.:,;]+/, '').trim() || null
+          : null,
+      };
+    })
+    .filter(Boolean);
+}
+
+/**
+ * The options the judge picked, from their own words: «1. a, 2. b», «1a 2b», «3) c». Each pick
+ * keeps the question number; anything else the judge said stays in `said`. PURE.
+ */
+export function parseAnswer(said) {
+  const picks = [];
+  for (const [, n, option] of String(said ?? '').matchAll(
+    /(?:^|[\s,;])(\d+)\s*[.):-]?\s*\(?([a-z])\)?(?=$|[\s,;.])/g,
+  ))
+    picks.push({ n: Number(n), option });
+  return picks;
+}
+
+/** The interview ledger's entries, skipping lines that are not JSON or have no time. PURE. */
+export function parseInterview(text) {
+  return String(text ?? '')
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry) => entry && isTime(entry.at))
+    .filter((entry) =>
+      ['escalation', 'answer', 'context'].includes(entry.kind),
+    );
+}
+
+/** The next id of a kind in the ledger: E1, E2… for escalations, A1… for answers. PURE. */
+export function nextInterviewId(entries, kind) {
+  const prefix = kind === 'escalation' ? 'E' : 'A';
+  return `${prefix}${entries.filter((entry) => entry.kind === kind).length + 1}`;
+}
+
+/**
+ * The escalation an answer goes to: the one named, else the last one asked. Throws when there is
+ * none, or the one named does not exist. PURE.
+ */
+export function answerTarget(entries, named) {
+  const asked = entries.filter((entry) => entry.kind === 'escalation');
+  if (!asked.length)
+    throw new Error(
+      'no escalation logged for this bout: log it first (`log <pr> escalation <file>`)',
+    );
+  if (!named) return asked.at(-1).id;
+  if (!asked.some((entry) => entry.id === named))
+    throw new Error(
+      `no escalation ${named} (${asked.map((e) => e.id).join(', ')})`,
+    );
+  return named;
+}
+
+/** The first word of a finding when it is a severity, else "OTHER". PURE. */
+export function severityOf(text) {
+  const word = /^\s*([A-Z]+)\b/.exec(String(text ?? ''))?.[1];
+  return SEVERITIES.includes(word) ? word : 'OTHER';
+}
+
+/**
+ * The judge's contract approval, from decisions.md (`approve-contract` writes it): the scale reads
+ * green from the first one on, red before. PURE.
+ */
+export function scaleOf(decisionsText) {
+  const approvals = String(decisionsText ?? '')
+    .split('\n')
+    .map(parseDecisionLine)
+    .filter(Boolean)
+    .filter(
+      (entry) =>
+        entry.at &&
+        ['judge', 'juez'].includes(entry.who) &&
+        /^contract approved\b/.test(entry.text),
+    );
+  const first = approvals[0];
+  if (!first) return { madeWeight: false, at: null, approvals: [] };
+  return {
+    madeWeight: true,
+    at: first.at,
+    approvals: approvals.map((entry) => ({
+      at: entry.at,
+      id: entry.id,
+      files: entry.text.split(' · ')[1] ?? '',
+      said: /said: «([^]*)»\s*$/.exec(entry.text)?.[1] ?? null,
+    })),
+  };
+}
+
+/**
+ * When the preparation ends: the judge's contract approval, else the wrestler's first commit, else
+ * it is still going on (null). PURE.
+ */
+export function preparationEnd(scale, firstCommitAt) {
+  return scale.at ?? firstCommitAt ?? null;
+}
+
+const before = (at, until) =>
+  until === null || Date.parse(at) <= Date.parse(until);
+
+/**
+ * The cornerman's findings on the contract: those reviewed outside a commit range (batch or
+ * concept, as §2b reviews a contract) and registered before the preparation ended, counted by
+ * severity and by state. PURE.
+ */
+export function contractFindings(ledger, until) {
+  const findings = (ledger?.findings ?? []).filter(
+    (finding) => !finding.range && before(finding.at, until),
+  );
+  const tally = (key) =>
+    findings.reduce(
+      (acc, finding) => ({
+        ...acc,
+        [key(finding)]: (acc[key(finding)] ?? 0) + 1,
+      }),
+      {},
+    );
+  return {
+    total: findings.length,
+    bySeverity: tally((finding) => severityOf(finding.text)),
+    byStatus: tally((finding) => finding.status),
+  };
+}
+
+/**
+ * The interview: each escalation asked before the preparation ended, its questions and, under each
+ * question, the judge's answers with their time (an answer can come in parts); then the decisions
+ * the referee took itself in the same window, marked «del réferi». Escalations asked later are
+ * listed in `later`: the rounds tell them. PURE.
+ */
+export function interviewOf(entries, decisionsText, until) {
+  const answers = entries.filter((entry) => entry.kind === 'answer');
+  const contextOf = (escalation) => {
+    const added = entries.filter(
+      (entry) => entry.kind === 'context' && entry.to === escalation.id,
+    );
+    return parseContext(added.at(-1)?.body ?? escalation.context ?? '');
+  };
+  const told = (escalation) => {
+    const context = contextOf(escalation);
+    const replies = answers.filter((answer) => answer.to === escalation.id);
+    const questions = parseEscalation(escalation.body).map((question) => ({
+      ...question,
+      context: context[question.n] ?? null,
+      answers: replies.flatMap((reply) =>
+        (reply.picks ?? parseAnswer(reply.said))
+          .filter((pick) => pick.n === question.n)
+          .map((pick) => ({
+            at: reply.at,
+            judge: reply.judge ?? null,
+            option: pick.option,
+            text: pick.text ?? null,
+            note: pick.note ?? null,
+            attachments: reply.attachments ?? [],
+            id: reply.id,
+          })),
+      ),
+    }));
+    return {
+      id: escalation.id,
+      at: escalation.at,
+      questions,
+      replies: replies.map(({ id, at, judge, said, attachments }) => ({
+        id,
+        at,
+        judge: judge ?? null,
+        said,
+        attachments: attachments ?? [],
+      })),
+      unanswered: questions
+        .filter((question) => !question.answers.length)
+        .map((question) => question.n),
+    };
+  };
+  const escalations = entries
+    .filter((entry) => entry.kind === 'escalation')
+    .map(told);
+  const referee = String(decisionsText ?? '')
+    .split('\n')
+    .map(parseDecisionLine)
+    .filter(Boolean)
+    .filter((entry) => entry.at && entry.who === 'referee')
+    .filter((entry) => before(entry.at, until))
+    .map(({ at, id, text }) => ({ at, id, text, by: 'del réferi' }));
+  return {
+    until,
+    escalations: escalations.filter((e) => before(e.at, until)),
+    later: escalations.filter((e) => !before(e.at, until)).map((e) => e.id),
+    referee,
+  };
+}
+
+/**
+ * The interview as timed events of the chronicle, with the eight types: an escalation is the
+ * referee's (arbitro), an answer is the judge's (juez). Those inside the preparation carry
+ * `stage: "entrevista"`, so the rounds do not tell them twice. PURE.
+ */
+export function interviewEvents(entries, until) {
+  // interviewOf tells an escalation of the window with all its answers, even a late one.
+  const told = new Set(
+    entries
+      .filter((entry) => entry.kind === 'escalation')
+      .filter((entry) => before(entry.at, until))
+      .map((entry) => entry.id),
+  );
+  return entries
+    .filter((entry) => ['escalation', 'answer'].includes(entry.kind))
+    .map((entry) => ({
+      at: entry.at,
+      type: entry.kind === 'escalation' ? 'arbitro' : 'juez',
+      title:
+        entry.kind === 'escalation'
+          ? `${entry.id} · escalated to the judge`
+          : `${entry.id} · the judge answered ${entry.to}`,
+      detail:
+        entry.kind === 'escalation'
+          ? `${parseEscalation(entry.body).length} question(s)`
+          : entry.said,
+      ref: entry.id,
+      source: `file:${INTERVIEW}`,
+      ...((
+        entry.kind === 'escalation' ? told.has(entry.id) : told.has(entry.to)
+      )
+        ? { stage: 'entrevista' }
+        : {}),
+    }));
+}
+
+/**
+ * Marks the events the preparation tells (the referee's decisions of the interview window and the
+ * judge's contract approval) with their stage, so the rounds do not tell them twice. PURE.
+ */
+export function withStages(events, interview, scale) {
+  const referee = new Set(interview.referee.map((decision) => decision.id));
+  const approvals = new Set(scale.approvals.map((approval) => approval.id));
+  return events.map((event) => {
+    if (event.source !== 'file:decisions.md') return event;
+    if (approvals.has(event.ref)) return { ...event, stage: 'pesaje' };
+    if (referee.has(event.ref) && event.type === 'arbitro')
+      return { ...event, stage: 'entrevista' };
+    return event;
+  });
+}
+
+/** `git diff --shortstat` → { files, insertions, deletions }. PURE. */
+export function parseShortstat(text) {
+  const number = (pattern) =>
+    Number(pattern.exec(String(text ?? ''))?.[1] ?? 0);
+  return {
+    files: number(/(\d+) files? changed/),
+    insertions: number(/(\d+) insertions?\(\+\)/),
+    deletions: number(/(\d+) deletions?\(-\)/),
+  };
+}
+
+/**
+ * The sparring's block once a bout opened from it: folded, with its one-line summary (the call, its
+ * time, the evidence links). Before any bout, the sparring is the whole chronicle and nothing
+ * folds. PURE.
+ */
+export function sparringFold(state, boutCount) {
+  const verdict = state.verdict ?? null;
+  const note = String(verdict?.note ?? '');
+  const links = [
+    ...(state.repos ?? []).map((entry) => entry.url).filter(Boolean),
+    ...(note.match(/https?:\/\/[^\s)»,;]+/g) ?? []),
+  ];
+  const withoutLinks = note.replace(/https?:\/\/\S+/g, '');
+  return {
+    folded: boutCount > 0,
+    call: verdict?.call ?? null,
+    at: verdict?.at ?? null,
+    note: verdict?.note ?? null,
+    evidence: [...new Set(links)],
+    media: [
+      ...new Set(
+        withoutLinks.match(/[\w.-]+\.(?:mp4|mov|webm|m4a|mp3|pdf|png)\b/gi) ??
+          [],
+      ),
+    ],
+  };
+}
+
+/**
+ * The preparation with `local` (HH:MM in the human's zone) next to every time it holds, since every
+ * time on the page comes from a `local` field. `toLocal` maps an ISO time. PURE.
+ */
+export function withLocalTimes({ weighIn, interview }, toLocal) {
+  const stamp = (item) => ({ ...item, local: toLocal(item.at) });
+  return {
+    weighIn: {
+      ...weighIn,
+      diagram: weighIn.diagram
+        ? { ...weighIn.diagram, local: toLocal(weighIn.diagram.drawnAt) }
+        : null,
+      scale: {
+        ...weighIn.scale,
+        local: weighIn.scale.at ? toLocal(weighIn.scale.at) : null,
+        approvals: weighIn.scale.approvals.map(stamp),
+      },
+    },
+    interview: {
+      ...interview,
+      escalations: interview.escalations.map((escalation) => ({
+        ...stamp(escalation),
+        replies: escalation.replies.map(stamp),
+        questions: escalation.questions.map((question) => ({
+          ...question,
+          answers: question.answers.map(stamp),
+        })),
+      })),
+      referee: interview.referee.map(stamp),
+    },
+  };
+}
+
+/**
+ * A warning for `summary` when the judges card lists questions for the judge (its hard-list section
+ * has a numbered item that is not the template's placeholder) while interview.jsonl has no
+ * escalation: the chronicle's interview would come out as a gap. Null otherwise. PURE.
+ */
+export function unloggedEscalationNotice(card, entries) {
+  if (entries.some((entry) => entry.kind === 'escalation')) return null;
+  const section =
+    /## Decisions that are yours[^\n]*\n([^]*?)(?=\n## |$)/.exec(
+      String(card ?? ''),
+    )?.[1] ?? '';
+  const asked = section
+    .split('\n')
+    .some((line) => /^\d+\.\s+(?!<topic>)\S/.test(line));
+  if (!asked) return null;
+  return 'the judges card has questions for the judge but interview.jsonl has no escalation: log it as sent (`judges-card.mjs log <pr> escalation <file>`) so the chronicle can tell the interview';
+}
+
+/**
+ * The answers the judge saved from the chronicle page (`respuestas` in the page's db, read with
+ * ArtifactData): every object that looks like one, wherever the listing nests it (`data`, `doc`,
+ * `fields`…). PURE.
+ */
+export function pageAnswerDocs(listing) {
+  const found = [];
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) return node.forEach(walk);
+    if (
+      typeof node.escalation === 'string' &&
+      node.question != null &&
+      isTime(node.answeredAt)
+    )
+      return void found.push(node);
+    Object.values(node).forEach(walk);
+  };
+  walk(listing);
+  return found;
+}
+
+/**
+ * The interview entries to log for the page's answers of bout `pr`: one per saved answer not
+ * logged yet (the same doc saved again is a new answer), at the time the judge saved it, with the
+ * option, the text as the judge left it, the note and the attachments. PURE.
+ */
+export function pageAnswerEntries(entries, docs, { pr, judge }) {
+  const logged = new Set(
+    entries.filter((entry) => entry.source).map((entry) => entry.source),
+  );
+  const asked = new Set(
+    entries.filter((e) => e.kind === 'escalation').map((e) => e.id),
+  );
+  const fresh = [];
+  docs
+    .map((doc) => ({
+      doc,
+      match: /^pr(\d+)-(E\d+)$/.exec(doc.escalation),
+      source: `page:${doc.escalation}-q${doc.question}@${doc.answeredAt}`,
+    }))
+    .filter(({ match }) => match && Number(match[1]) === Number(pr))
+    .filter(({ match }) => asked.has(match[2]))
+    .filter(({ source }) => !logged.has(source))
+    .sort((a, b) => Date.parse(a.doc.answeredAt) - Date.parse(b.doc.answeredAt))
+    .forEach(({ doc, match, source }) => {
+      const n = Number(doc.question);
+      const option = String(doc.choice);
+      const text = String(doc.text ?? '').trim();
+      const note = String(doc.note ?? '').trim();
+      fresh.push({
+        kind: 'answer',
+        id: nextInterviewId([...entries, ...fresh], 'answer'),
+        to: match[2],
+        at: doc.answeredAt,
+        judge,
+        said: `${n}. ${option === 'otro' ? 'otro' : option}${text ? ` — ${text}` : ''}${note ? ` · ${note}` : ''}`,
+        picks: [{ n, option, text: text || null, note: note || null }],
+        attachments: Array.isArray(doc.attachments) ? doc.attachments : [],
+        source,
+      });
+    });
+  return fresh;
+}
+
+/**
+ * The context of each question of an escalation, from its Markdown (`## Contexto <n> · <question>`
+ * sections, one per question): `{ <n>: <the section's Markdown> }`. What the judge reads in «Ver más
+ * información» before answering. PURE.
+ */
+export function parseContext(markdown) {
+  const out = {};
+  let current = null;
+  for (const line of String(markdown ?? '').split('\n')) {
+    const heading = /^##\s+(?:Contexto|Context)\s+(\d+)\b/i.exec(line);
+    if (heading) {
+      current = Number(heading[1]);
+      out[current] = [];
+      continue;
+    }
+    if (current !== null) out[current].push(line);
+  }
+  return Object.fromEntries(
+    Object.entries(out).map(([n, lines]) => [n, lines.join('\n').trim()]),
+  );
+}
+
+/**
+ * Each escalation's question contexts for the page, keyed by the page's escalation id
+ * (`pr<n>-E<k>`): `{ "pr7-E1": { "1": "<Markdown>" } }`. Escalations without context are left out.
+ * PURE.
+ */
+export function pageContexts(pr, entries) {
+  const interview = interviewOf(entries, '', null);
+  return Object.fromEntries(
+    interview.escalations
+      .map((escalation) => [
+        `pr${pr}-${escalation.id}`,
+        Object.fromEntries(
+          escalation.questions
+            .filter((question) => question.context)
+            .map((question) => [question.n, question.context]),
+        ),
+      ])
+      .filter(([, contexts]) => Object.keys(contexts).length),
+  );
+}
+
+/**
+ * The escalations whose latest context has no «## Contexto <n>» section (so no question shows «Ver
+ * más información»), as `#<pr> E<k>`. Only the latest counts: a context logged again with its
+ * sections replaces an old one without them. PURE.
+ */
+/** The numbers of the escalation's questions the context has no section for. PURE. */
+export function missingContext(escalationBody, contextBody) {
+  const sections = parseContext(contextBody);
+  return parseEscalation(escalationBody)
+    .map((question) => question.n)
+    .filter((n) => !(n in sections));
+}
+
+export function contextWarnings(pr, entries) {
+  const latest = {};
+  const bodies = Object.fromEntries(
+    entries
+      .filter((entry) => entry.kind === 'escalation')
+      .map((entry) => [entry.id, entry.body]),
+  );
+  entries
+    .filter((entry) => entry.kind === 'escalation' && entry.context)
+    .forEach((entry) => (latest[entry.id] = entry.context));
+  entries
+    .filter((entry) => entry.kind === 'context')
+    .forEach((entry) => (latest[entry.to] = entry.body));
+  return Object.entries(latest)
+    .map(([id, body]) => [id, missingContext(bodies[id], body)])
+    .filter(([, missing]) => missing.length)
+    .map(([id, missing]) => `#${pr} ${id} (questions ${missing.join(', ')})`);
+}

package/ring/scripts/round-bell.mjs

@@ -2,7 +2,8 @@
 // Round-bells: small temporary draft PRs so the human reviews each concept early. Zero-dependency.
 //
 //   node round-bell.mjs open <pr> <concept> <sha> [--from <sha>] [--verified <text>]
-//                            [--pending <text>] [--read-first <text>] [--dry-run]
+//                            [--pending <text>] [--read-first <text>] [--flow-change <text>]
+//                            [--dry-run]
 //   node round-bell.mjs list <pr>     open round-bells, with the commands for the HUMAN to close them
 //
 // Round N is pushed as ring/<pr>/round-<N> and opened as a draft stacked on round N-1 (round 1 on
@@ -15,6 +16,7 @@
 // closes, merges or readies anything. It refuses while a cornerman finding from a range inside the
 // round is still open, and its body lists every finding the referee discarded or ticketed that the
 // human has not seen yet, which then count as shown (findings.mjs).
+import { boutFormatGate } from './format-gate.mjs';
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -201,7 +203,7 @@ function open(argv) {
   const { flags, positional } = options(argv);
   const [pr, concept, ref, extra] = positional;
   const usage =
-    'usage: open <pr> "<concept>" <sha> [--from <sha>] [--verified <text>] [--pending <text>] [--read-first <text>] [--dry-run]; <sha> is the tip of the round, a single commit (quote a concept with spaces)';
+    'usage: open <pr> "<concept>" <sha> [--from <sha>] [--verified <text>] [--pending <text>] [--read-first <text>] [--flow-change <text>] [--dry-run]; <sha> is the tip of the round, a single commit (quote a concept with spaces)';
   if (extra !== undefined)
     throw new Error(`unexpected argument "${extra}". ${usage}`);
   if (!pr || !concept || !ref) throw new Error(usage);
@@ -216,6 +218,8 @@ function open(argv) {
     gateLimits(),
   );
   if (blocked) throw new Error(`round-bell waits: ${blocked}`);
+  const format = boutFormatGate(dir, state, sha);
+  if (format.refusal) throw new Error(`round-bell waits: ${format.refusal}`);
 
   const remote = read('git', [
     'ls-remote',
@@ -304,6 +308,9 @@ function open(argv) {
       pending: flags.pending ?? '_Not stated by the referee._',
       readFirst:
         flags['read-first'] ?? '_One concept: read the commits in order._',
+      flowChange:
+        flags['flow-change'] ??
+        '_Not applicable: this concept does not change how any flow works today._',
       findings: unshownSection(ledger),
     }),
   );

package/ring/scripts/tech-plan-log.mjs

@@ -0,0 +1,81 @@
+// Reads and writes a bout's technical plan (tech-plan.mjs): `judges-card.mjs plan` changes a
+// point's state or adds one, `page-verdicts` adds each judge's «se mejora», and `play-by-play.mjs
+// embed --plan` puts the plan into the chronicle. Zero-dependency.
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { readState } from './config.mjs';
+import { scriptJson } from './contract-endpoints.mjs';
+import {
+  parsePlan,
+  parsePlanLog,
+  PLAN,
+  PLAN_LOG,
+  planForPage,
+  planItem,
+  planState,
+  withPlanItem,
+  withPlanState,
+} from './tech-plan.mjs';
+
+const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null);
+
+/** `plan <pr> <n|title> <state> [--ref <sha|round-bell>]`: a new state, stamped in plan.jsonl. */
+export function setPlanState(
+  dir,
+  target,
+  state,
+  ref = null,
+  at = new Date().toISOString(),
+) {
+  const file = join(dir, PLAN);
+  const markdown = read(file);
+  if (markdown === null) throw new Error(`no ${PLAN} in ${dir}`);
+  const item = planItem(parsePlan(markdown), target);
+  const next = planState(state);
+  writeFileSync(file, withPlanState(markdown, item, next));
+  appendFileSync(
+    join(dir, PLAN_LOG),
+    `${JSON.stringify({ at, n: item.n, title: item.title, from: item.state, to: next, ref })}\n`,
+  );
+  return { ...item, from: item.state, to: next };
+}
+
+/** Adds a point to the plan (creating the file when it does not exist); returns whether it was new. */
+export function addPlanItem(dir, point, at = new Date().toISOString()) {
+  const file = join(dir, PLAN);
+  const markdown =
+    read(file) ?? `# El plan del técnico · #${readState(dir).pr}\n`;
+  const next = withPlanItem(markdown, point);
+  if (next === markdown) return false;
+  writeFileSync(file, next);
+  appendFileSync(
+    join(dir, PLAN_LOG),
+    `${JSON.stringify({ at, title: point.title, from: null, to: point.state ?? 'pendiente', ref: point.origins?.join(', ') ?? null })}\n`,
+  );
+  return true;
+}
+
+/** The block after `<!-- ring:tech-plan #<pr> -->`: the container and the plan as JSON. */
+export function planBlock(dir) {
+  const markdown = read(join(dir, PLAN));
+  if (markdown === null) throw new Error(`no ${PLAN} in ${dir}`);
+  const pr = readState(dir).pr;
+  const plan = {
+    pr,
+    ...planForPage(markdown, parsePlanLog(read(join(dir, PLAN_LOG)))),
+  };
+  const total = plan.groups.reduce((sum, group) => sum + group.total, 0);
+  return {
+    pr,
+    html: [
+      `<div class="tech-plan" data-ring-plan="${pr}"><p class="endpoints-wait">El plan del técnico (${total} puntos) se dibuja al abrir la página.</p></div>`,
+      `<script type="application/json" id="ring-plan-${pr}">${scriptJson(plan)}</script>`,
+    ].join('\n'),
+  };
+}