cawdev-cli 0.9.0

package/lib/harness-prompt.mjs

@@ -0,0 +1,197 @@
+/**
+ * What a session is told before its task — R107, R108, R109.
+ *
+ * In `lib/` for `run-plugin.mjs`'s reason: this is where R107's TWO LEVELS of
+ * configuration meet — the console's instincts and the repository's own
+ * `.ai-config.md` — and "did both halves arrive, labelled, in the right order"
+ * is a question about a string. It needs no daemon, no platform and no
+ * repository to answer, so it should not need them to test.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Where R107's advanced half lives, in the target repository. */
+export const AI_CONFIG = '.ai-config.md';
+
+/** A ceiling on the repository's half. See `readRepoConfig`. */
+const MAX_CONFIG_BYTES = 32 * 1024;
+
+/**
+ * What this project makes an agent do without being asked, and what the last
+ * session left — R107, R108, R109.
+ *
+ * <p>APPENDED to the profile's prompt rather than woven into it, and the three
+ * blocks are labelled. A session that cannot tell "what this project always
+ * wants" from "what you were asked to do" will treat one as the other, and the
+ * failure mode of getting that backwards is a run that does the standing rule
+ * instead of the task.
+ *
+ * <p>The `.ai-config.md` half of R107 is read HERE, out of the checkout, and
+ * never through the platform: the repository is the source of truth for what is
+ * in it, and a file copied into a database is a reading that goes stale. So the
+ * two halves meet in this function and nowhere else.
+ */
+export function harnessPrompt({
+  instincts, briefing, plan, lifecycle, repoConfig, experts, skills, cannotDelegate,
+}) {
+  const parts = [];
+
+  // R147. What this session was handed, by the NAME the CLI answers to. Before
+  // this the experts and skills reached the session only through the CLI's own
+  // tool listing, beside its built-in agents, and nothing in a hundred and
+  // forty runs chose one. A capability nobody mentions is a capability nobody
+  // uses; this is the mention. Experts and skills are listed separately
+  // because they are used differently — one is delegated to, the other is read
+  // before work it covers — and each line carries its own description, which
+  // is what the model decides on.
+  //
+  // R161. A REQUIRED one is named FIRST and in its own block. Two lists rather
+  // than one annotated list, because a `(required)` suffix on a line in a list
+  // of twelve is a detail; a heading is an instruction. The AS_NEEDED wording
+  // below is byte-for-byte what it was — when a project requires nothing, and
+  // that is every project until somebody says otherwise, this function returns
+  // exactly what it returned before the entry.
+  const reach = [];
+  const requiredOf = (list) => (list ?? []).filter((each) => each.required);
+  const optionalOf = (list) => (list ?? []).filter((each) => !each.required);
+  const lines = (list) => list
+    .map((each) => `- \`${each.qualified}\` — ${each.description}`).join('\n');
+
+  const mustExperts = requiredOf(experts);
+  const mayExperts = optionalOf(experts);
+  if (mustExperts.length) {
+    reach.push('**Experts you MUST use** — this project requires each of these. Delegate '
+      + 'with the `Agent` tool, `subagent_type` exactly as written, before this stage is '
+      + `finished.\n${lines(mustExperts)}`);
+  }
+  if (mayExperts.length) {
+    reach.push('**Experts** — delegate with the `Agent` tool, `subagent_type` exactly as '
+      + 'written. Use one whenever its description fits the step you are on; they were '
+      + 'chosen for this project.\n'
+      + lines(mayExperts));
+  } else if (!mustExperts.length && cannotDelegate?.length) {
+    reach.push(`**Experts** — ${cannotDelegate.join(' ')}`);
+  }
+
+  const mustSkills = requiredOf(skills);
+  const maySkills = optionalOf(skills);
+  if (mustSkills.length) {
+    reach.push('**Skills you MUST use** — this project requires each of these. Invoke it '
+      + 'with the `Skill` tool, `skill` exactly as written, before this stage is '
+      + `finished.\n${lines(mustSkills)}`);
+  }
+  if (maySkills.length) {
+    reach.push('**Skills** — invoke with the `Skill` tool, `skill` exactly as written, BEFORE '
+      + 'work its description covers.\n'
+      + lines(maySkills));
+  }
+  if (reach.length) {
+    parts.push(`## What this session may reach\n\n${reach.join('\n\n')}`);
+  }
+
+  const rules = [
+    ...(instincts ?? []).map((each) => `- **${each.name}** — ${each.body}`),
+  ];
+  if (rules.length) {
+    parts.push(`## How work is done here\n\n${rules.join('\n')}`);
+  }
+  if (repoConfig) {
+    // Verbatim and last of the two, so a rule somebody put in the repository
+    // wins a disagreement with one set in the console. The file is the thing
+    // they can see from the checkout they are standing in.
+    parts.push(`## From \`${AI_CONFIG}\` in this repository\n\n${repoConfig}`);
+  }
+
+  if (briefing) {
+    parts.push(`## Where this work had got to\n\nA previous session on this branch left `
+      + `this. It is what it believed, not necessarily what is true now — check `
+      + `anything you are about to rely on.\n\n${briefing}`);
+  }
+
+  // R124. The plan somebody approved, handed to the phase that carries it out.
+  //
+  // AFTER the briefing and BEFORE the steps, which is the order a person would
+  // read them in: what this project always wants, where the work had got to,
+  // what was decided for this card, and then what to do about it.
+  //
+  // VERBATIM, for `stagePrompt`'s reason — a session that re-derived the plan
+  // from a précis would be planning again, which is the one thing a phase after
+  // an approved plan must not do.
+  //
+  // The staleness note is part of the same block rather than a warning
+  // somewhere else. A plan and the reason to doubt it belong in one place, or
+  // the plan gets read and the doubt does not.
+  //
+  // R145's collisions sit beside it for the same reason, and NOT in bold: bold
+  // is for the line that says the plan itself may be wrong. This one says
+  // something ELSE may be moving, and it is a heads-up rather than a stop.
+  if (plan?.body) {
+    parts.push(`## The plan for this card\n\n`
+      + `This was written and agreed in the plan phase. Follow it. If it turns out to be `
+      + `wrong, say so and say why — do not quietly do something else.`
+      + `${plan.staleness ? `\n\n**${plan.staleness}**` : ''}`
+      + `${plan.collisions ? `\n\n${plan.collisions}` : ''}`
+      + `\n\n${plan.body}`);
+  }
+
+  // i138. The steps are the DAEMON's to report, and the wording used to say the
+  // opposite. R109 handed the lifecycle to the session as an instruction —
+  // "report each one as you begin and end it" — and R112 took it back: one
+  // process per stage, the daemon reports each, and `toolsForStage` strips
+  // `report` from every stage because "done" ends the RUN. The sentence stayed.
+  // So every staged session was told to use a tool it did not hold, and a
+  // session told to do something finds a way: on a stage spawned with a
+  // permission prompt, `report` became a question on the inbox — one of the two
+  // i138 was filed about — and where a person allowed it, the run ended in the
+  // middle of the walk with the stages behind it SKIPPED. The gate line said the
+  // same thing about `ask_user`, and the daemon raises the gate itself.
+  if (lifecycle?.length) {
+    const steps = lifecycle.map((stage, at) => {
+      const gate = stage.gate === 'ASK'
+        ? ' — **a person decides here**: when this step ends, they read what it produced, '
+          + 'and the next step waits for their answer'
+        : '';
+      // R129. The one step whose MEANING the project can change. A person
+      // reading this list should not have to know the project's settings to
+      // understand what the TEST step was going to do.
+      const mode = stage.stage === 'TEST' && stage.testMode === 'TESTBOOK'
+        ? ' — writing the testbook, not running it'
+        : '';
+      return `${at + 1}. **${stage.stage}**${mode}${gate}`;
+    });
+    parts.push('## The steps to work in\n\n'
+      + 'Each step is its own session, and this session is one of them — which one is said '
+      + 'below. The daemon reports each step as it begins and ends, so the people watching '
+      + 'can see where you are; you do not, and `report` is not among this step\'s tools. '
+      + 'Where the instructions above say to finish with `report`, that is a run with no '
+      + 'steps: here, say it as your last message instead. That message is what is recorded '
+      + 'as this step\'s output, what the next step is handed, and what a person reads at a '
+      + `gate. The step ends when your turn does.\n\n${steps.join('\n')}`);
+  }
+
+  return parts.length ? `\n\n---\n\n${parts.join('\n\n')}` : '';
+}
+
+/**
+ * The repository's own half of R107, if it has one.
+ *
+ * <p>Capped, and the cap is not paranoia: this goes into an opening prompt, and
+ * a repository that committed a megabyte here would crowd out the task without
+ * anybody being told why.
+ */
+export async function readRepoConfig(cwd) {
+  try {
+    const path = join(cwd, AI_CONFIG);
+    const size = (await stat(path)).size;
+    if (size > MAX_CONFIG_BYTES) {
+      return `(${AI_CONFIG} is ${Math.round(size / 1024)}kB and was not read — it is meant to `
+        + 'be a page of rules, not a document.)';
+    }
+    return (await readFile(path, 'utf8')).trim() || null;
+  } catch {
+    // Not having one is the ordinary case, not a failure.
+    return null;
+  }
+}
+

package/lib/roadmap-format.mjs

@@ -0,0 +1,453 @@
+// The ROADMAP.md format, in one place: parsing it and writing it.
+//
+// The importer and the exporter must agree exactly, or export → import → export
+// is not a fixed point and the generated file churns on every release. Keeping
+// both halves in one file is how they stay agreed.
+
+/**
+ * What to call a card — R127 — and, since R221, what identifies one.
+ *
+ * <p>The API says, in `ref`. This is the fallback for an entry parsed out of a
+ * file, where the prefix in the heading is the only thing there is to read. One
+ * place on this side of the wire spells the prefix, so the parser and the
+ * writer cannot drift apart.
+ *
+ * <p>R221 gave each kind its own number sequence, so `R12` and `i12` are two
+ * cards and the ref — not the number — is what names one: in a heading, in a
+ * `Related:` line, and in what the importer sends back.
+ */
+export function entryRef(entry) {
+  return entry.ref ?? ((entry.kind === 'ISSUE' ? 'i' : 'R') + entry.number);
+}
+
+/**
+ * A `Related:` / `After:` token, normalised — `R12`, `i12`; a bare `12` is a
+ * roadmap card, which is what a bare number meant before R221 and what the
+ * server reads it as. Null for a token that is not a card at all.
+ */
+export function parseRefToken(token) {
+  const match = /^([RrIi])?(\d+)$/.exec(token.trim());
+  if (!match || Number(match[2]) <= 0) return null;
+  const kind = match[1]?.toLowerCase() === 'i' ? 'ISSUE' : 'ROADMAP';
+  return { ref: entryRef({ kind, number: Number(match[2]) }), kind, number: Number(match[2]) };
+}
+
+/**
+ * The order refs are written in: by number, a roadmap card before the issue
+ * sharing its number — the same order the server keeps them in, so an export
+ * does not churn on the order the ids happen to arrive in.
+ */
+function byNumberThenKind(a, b) {
+  return a.number - b.number || (a.kind === 'ISSUE' ? 1 : 0) - (b.kind === 'ISSUE' ? 1 : 0);
+}
+
+/** Status as stored, from how the file writes it: "IN PROGRESS" -> IN_PROGRESS. */
+export function statusFromDisplay(display) {
+  return display.trim().replace(/\s+/g, '_').toUpperCase();
+}
+
+/** Status as the file writes it: IN_PROGRESS -> "IN PROGRESS". */
+export function statusToDisplay(status) {
+  return status.replace(/_/g, ' ');
+}
+
+/**
+ * Sections that come from a status rather than from the entry's own `section`.
+ * The file has always grouped these two this way, and deriving them means a
+ * declined entry cannot end up filed under a phase it is no longer part of.
+ *
+ * Two, and REVIEW is deliberately not a third: work waiting to be read is still
+ * part of the phase it belongs to, and moving it to a section of its own would
+ * take it out of its phase for a few days and put it back afterwards.
+ */
+export const STATUS_SECTIONS = {
+  CONSIDERING: 'Considering — wanted, not settled',
+  DECLINED: 'Declined — decided against, with the reason',
+};
+
+/**
+ * ISSUES.md's sections — R85.
+ *
+ * Every one of them is derived from the status, because an issue has no phase:
+ * a defect does not belong to "Phase 3", it belongs to "open" or "fixed". That
+ * is the whole reason the two files are separate rather than one file with a
+ * kind column — the roadmap is organised by intent and this is organised by
+ * whether it is still true.
+ */
+export const ISSUE_SECTIONS = {
+  NEW: 'New — filed, not yet triaged',
+  CONFIRMED: 'Confirmed — real, waiting for somebody',
+  IN_DEVELOPMENT: 'In development — somebody is fixing it',
+  MERGED: 'Resolved — the fix landed',
+  SHIPPED: 'Released — the fix shipped',
+  DECLINED: "Won't fix — decided against, with the reason",
+};
+
+/** The order ISSUES.md reads in: what needs somebody first, history last. */
+export const ISSUE_SECTION_ORDER = Object.values(ISSUE_SECTIONS);
+
+/** Where an issue belongs in ISSUES.md. */
+export function issueSectionOf(entry) {
+  return ISSUE_SECTIONS[entry.status] ?? 'Open';
+}
+
+/**
+ * Issues, rendered as their own file.
+ *
+ * Sorted by severity inside each section, critical first, because that IS the
+ * question the file is read to answer. `renderRoadmap` sorts by number, which
+ * on a roadmap is chronological and useful and here would bury a critical
+ * defect behind six minor ones filed after it.
+ */
+export function renderIssues(entries, { preamble }) {
+  const rank = { CRITICAL: 0, MEDIUM: 1, MINOR: 2 };
+  const bySection = new Map();
+  for (const entry of entries) {
+    const section = issueSectionOf(entry);
+    if (!bySection.has(section)) bySection.set(section, []);
+    bySection.get(section).push(entry);
+  }
+  for (const list of bySection.values()) {
+    list.sort((a, b) =>
+      (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3) || a.number - b.number);
+  }
+
+  const ordered = [
+    ...ISSUE_SECTION_ORDER.filter((section) => bySection.has(section)),
+    ...[...bySection.keys()].filter((section) => !ISSUE_SECTION_ORDER.includes(section)),
+  ];
+
+  const parts = [preamble.trimEnd(), ''];
+  for (const section of ordered) {
+    parts.push('---', '', `## ${section}`, '');
+    for (const entry of bySection.get(section)) {
+      parts.push(renderEntry(entry), '');
+    }
+  }
+  return `${parts.join('\n').trimEnd()}\n`;
+}
+
+/** Where an entry belongs in the exported file. */
+export function sectionOf(entry) {
+  return STATUS_SECTIONS[entry.status] ?? entry.section ?? 'Roadmap';
+}
+
+/**
+ * Sections these entries use that the given order does not name, with how many
+ * entries each holds.
+ *
+ * `renderRoadmap` appends an unknown section rather than refusing it — a new
+ * phase is legitimate, and an exporter that fails on one would block the
+ * release that introduces it. But appending silently is how the list fell
+ * behind in the first place, so the exporter says which sections it did not
+ * know about. Status-derived sections are never "unlisted": they are the
+ * format's own, and no `sectionOrder` should have to repeat them.
+ */
+export function unlistedSections(entries, sectionOrder = []) {
+  const known = new Set([...sectionOrder, ...Object.values(STATUS_SECTIONS)]);
+  const counts = new Map();
+  for (const entry of entries) {
+    const section = sectionOf(entry);
+    if (known.has(section)) continue;
+    counts.set(section, (counts.get(section) ?? 0) + 1);
+  }
+  return [...counts].map(([section, count]) => ({ section, count }));
+}
+
+/**
+ * Parses a ROADMAP.md into entries.
+ *
+ * Only the part after the preamble's closing rule is considered. The Format
+ * section contains a fenced *example* heading — "### R7 — a short title" —
+ * which is not an entry; parsing the whole file silently shifts every number
+ * after it by one. That cost a run of misnumbered entries the first time.
+ */
+export function parseRoadmap(text) {
+  const body = afterPreamble(text);
+  const entries = [];
+  const problems = [];
+
+  let currentSection = null;
+
+  for (const block of splitBlocks(body)) {
+    if (block.kind === 'section') {
+      currentSection = block.title;
+      continue;
+    }
+
+    // Either prefix — R127. An old export headed `### R90` still parses, which
+    // is what import.mjs needs; the prefix says which kind the card is.
+    const heading = /^([Ri])(\d+)\s+[—–-]\s+(.+)$/.exec(block.heading);
+    if (!heading) {
+      problems.push(
+        `Entry heading is not "R<number> — title" or "i<number> — title": ${block.heading}`,
+      );
+      continue;
+    }
+
+    const entry = {
+      number: Number(heading[2]),
+      kind: heading[1] === 'i' ? 'ISSUE' : 'ROADMAP',
+      title: heading[3].trim(),
+      status: 'PLANNED',
+      branch: null,
+      merge: null,
+      version: null,
+      reason: null,
+      related: [],
+      after: [],
+      section: currentSection,
+      sprint: null,
+      body: '',
+    };
+
+    const bodyLines = [];
+    for (const line of block.lines) {
+      const status = /^Status:\s*(.+)$/.exec(line.trim());
+      if (status) {
+        const value = status[1].trim();
+        const shipped = /^SHIPPED\s+(\S+)$/.exec(value);
+        if (shipped) {
+          entry.status = 'SHIPPED';
+          entry.version = shipped[1];
+        } else {
+          entry.status = statusFromDisplay(value);
+        }
+        continue;
+      }
+      const branch = /^Branch:\s*(.+)$/.exec(line.trim());
+      if (branch) {
+        entry.branch = branch[1].trim();
+        continue;
+      }
+      const severity = /^Severity:\s*(.+)$/.exec(line.trim());
+      if (severity) {
+        entry.severity = severity[1].trim();
+        continue;
+      }
+      const development = /^Development:\s*(.+)$/.exec(line.trim());
+      if (development) {
+        entry.development = statusFromDisplay(development[1].trim());
+        continue;
+      }
+      const merge = /^Merged:\s*(.+)$/.exec(line.trim());
+      if (merge) {
+        entry.merge = merge[1].trim();
+        continue;
+      }
+      const related = /^Related:\s*(.+)$/.exec(line.trim());
+      if (related) {
+        // Both prefixes — R127 — and the prefix is kept, because since R221
+        // it is the identity: `i91` and `R91` are two cards. Without that,
+        // render → parse → render would rewrite one as the other and the
+        // round trip would stop being a fixed point.
+        const tokens = related[1].split(/[,\s]+/).map(parseRefToken).filter(Boolean);
+        entry.related = tokens.map(({ number }) => number);
+        entry.relatedRefs = tokens.map(({ ref }) => ref);
+        continue;
+      }
+      const after = /^After:\s*(.+)$/.exec(line.trim());
+      if (after) {
+        // R181: the cards this one starts coding after. Same shape and same
+        // fixed-point reasoning as Related above.
+        const tokens = after[1].split(/[,\s]+/).map(parseRefToken).filter(Boolean);
+        entry.after = tokens.map(({ number }) => number);
+        entry.afterRefs = tokens.map(({ ref }) => ref);
+        continue;
+      }
+      const sprint = /^Sprint:\s*S(\d+)\s*(.*)$/.exec(line.trim());
+      if (sprint) {
+        // R257: `Sprint: S1 Notifications` — the sprint's number and its name
+        // as the file says it. The same shape the API's `sprint` has, so a
+        // re-render from either is byte-identical; the importer sends only
+        // the number, since a sprint's name is the database's to say.
+        const number = Number(sprint[1]);
+        entry.sprint = { number, ref: `S${number}`, name: sprint[2].trim() };
+        continue;
+      }
+      bodyLines.push(line);
+    }
+
+    // A horizontal rule at column 0 separates sections in this format, so a
+    // trailing one belongs to the file's structure, not to the last entry of a
+    // section. Left in, it reappears inside the body on the next export and the
+    // round trip stops being a fixed point — which is exactly how this was
+    // found.
+    while (bodyLines.length && /^\s*$|^-{3,}\s*$/.test(bodyLines.at(-1))) {
+      bodyLines.pop();
+    }
+    entry.body = bodyLines.join('\n').trim();
+
+    // DECLINED needs a reason; the file writes it as a "Reason:" paragraph.
+    if (entry.status === 'DECLINED') {
+      const found = /Reason:\s*([\s\S]*)/.exec(entry.body);
+      entry.reason = (found ? found[1] : entry.body).replace(/\s+/g, ' ').trim();
+    }
+
+    entries.push(entry);
+  }
+
+  entries.sort((left, right) => left.number - right.number);
+  return { entries, problems };
+}
+
+function afterPreamble(text) {
+  const separator = text.indexOf('\n---\n');
+  return separator === -1 ? text : text.slice(separator);
+}
+
+/** Yields section headings and entry blocks in document order. */
+function* splitBlocks(text) {
+  const lines = text.split('\n');
+  let entry = null;
+
+  for (const line of lines) {
+    const section = /^##\s+(.+)$/.exec(line);
+    if (section && !line.startsWith('###')) {
+      if (entry) {
+        yield entry;
+        entry = null;
+      }
+      yield { kind: 'section', title: section[1].trim() };
+      continue;
+    }
+
+    const heading = /^###\s+(.+)$/.exec(line);
+    if (heading) {
+      if (entry) yield entry;
+      entry = { kind: 'entry', heading: heading[1].trim(), lines: [] };
+      continue;
+    }
+
+    if (entry) entry.lines.push(line);
+  }
+  if (entry) yield entry;
+}
+
+/**
+ * Writes entries as ROADMAP.md's entry sections.
+ *
+ * Sections appear in `sectionOrder`, then any others in first-appearance order,
+ * with the two status-derived sections last — a roadmap reads forward through
+ * the work and ends with what was set aside.
+ */
+export function renderRoadmap(entries, { preamble, sectionOrder = [] }) {
+  const bySection = new Map();
+  for (const entry of [...entries].sort((left, right) => left.number - right.number)) {
+    const section = sectionOf(entry);
+    if (!bySection.has(section)) bySection.set(section, []);
+    bySection.get(section).push(entry);
+  }
+
+  const statusSections = Object.values(STATUS_SECTIONS);
+  const ordered = [
+    ...sectionOrder.filter((section) => bySection.has(section)),
+    ...[...bySection.keys()].filter(
+      (section) => !sectionOrder.includes(section) && !statusSections.includes(section),
+    ),
+    ...statusSections.filter((section) => bySection.has(section)),
+  ];
+
+  const parts = [preamble.trimEnd(), ''];
+  for (const section of ordered) {
+    parts.push('---', '', `## ${section}`, '');
+    for (const entry of bySection.get(section)) {
+      parts.push(renderEntry(entry), '');
+    }
+  }
+
+  // Exactly one trailing newline, so the file is stable under any editor.
+  return parts.join('\n').replace(/\n+$/, '') + '\n';
+}
+
+function renderEntry(entry) {
+  const lines = [`### ${entryRef(entry)} — ${entry.title}`, ''];
+
+  const status =
+    entry.status === 'SHIPPED' && entry.version
+      ? `SHIPPED ${entry.version}`
+      : statusToDisplay(entry.status);
+  lines.push(`Status: ${status}`);
+
+  // R85. An issue carries how badly it is broken, and it is a line rather than
+  // a prefix on the title: welded into a title it goes stale the moment
+  // somebody re-ranks it, which is exactly what triage is for.
+  if (entry.severity) {
+    lines.push(`Severity: ${entry.severity}`);
+  }
+
+  // Each status writes only what it currently claims. A MERGED entry keeps its
+  // branch in the database as history, but the file must not print it: the
+  // branch is expected to be deleted, and `--live` would then be reading a claim
+  // the entry is no longer making.
+  //
+  // IN DEVELOPMENT does print it, for the mirror-image reason: the branch is
+  // where the work is, and it is still there until MERGED says where it went.
+  // R84 — one status where CODING, REVIEW and DONE each printed one.
+  if (entry.status === 'IN_DEVELOPMENT' && entry.branch) {
+    lines.push(`Branch: ${entry.branch}`);
+  }
+  // How far that branch has got, when the platform knows — R84. It is the WORK
+  // ITEM's status and not the card's, which is exactly why it is a second line
+  // rather than a fifth spelling of Status. A file whose cards say only "in
+  // development" is still a valid roadmap; this line is what makes it readable.
+  const development = entry.development ?? entry.workItem?.status;
+  if (entry.status === 'IN_DEVELOPMENT' && development) {
+    lines.push(`Development: ${statusToDisplay(development)}`);
+  }
+  if (entry.status === 'MERGED' && entry.merge) {
+    lines.push(`Merged: ${entry.merge}`);
+  }
+  if (entry.related?.length) {
+    // Each card written the way its own card is written — R127 — and since
+    // R221 the ref is what tells R12 from i12, so the pair is kept together
+    // rather than keyed by a number two cards may share. Sorted, so an export
+    // does not churn on the order the ids happen to arrive in.
+    const written = entry.related
+      .map((number, index) => parseRefToken(entry.relatedRefs?.[index] ?? `R${number}`))
+      .filter(Boolean)
+      .sort(byNumberThenKind)
+      .map(({ ref }) => ref);
+    lines.push(`Related: ${written.join(', ')}`);
+  }
+  if (entry.after?.length) {
+    // R181. The API gives `after` as cards ({number, ref, ...}); the parser
+    // gives numbers beside `afterRefs`. Either way, written as its own card is
+    // written and sorted, for Related's reasons.
+    const written = entry.after
+      .map((item, index) =>
+        typeof item === 'number'
+          ? parseRefToken(entry.afterRefs?.[index] ?? `R${item}`)
+          : parseRefToken(item.ref ?? `R${item.number}`),
+      )
+      .filter(Boolean)
+      .sort(byNumberThenKind)
+      .map(({ ref }) => ref);
+    lines.push(`After: ${written.join(', ')}`);
+  }
+  if (entry.sprint) {
+    // R257. A line on the card and never a heading: the section is where the
+    // file groups, and a sprint is a set a person opened across sections. The
+    // API's `sprint` and the parser's are the same shape, which is what makes
+    // render → parse → render a fixed point. State is not written — the file
+    // says which sprint, the database says whether it is still open.
+    lines.push(`Sprint: ${entry.sprint.ref ?? `S${entry.sprint.number}`} ${entry.sprint.name}`.trimEnd());
+  }
+
+  if (entry.body?.trim()) {
+    lines.push('', entry.body.trim());
+  }
+
+  // i232. A card declined through the API keeps its body and its reason in two
+  // columns (`declinedReason` from the API, `reason` from the parser); the
+  // hand-written file kept the reason inside the body as a "Reason:"
+  // paragraph, and the parser still reads it back out of there. So the reason
+  // is written as its own paragraph after the body — unless the body already
+  // carries one, judged by the same test the parser uses, since writing a
+  // second would break the fixed point the round-trip test pins.
+  const reason = (entry.declinedReason ?? entry.reason)?.trim();
+  if (entry.status === 'DECLINED' && reason && !/Reason:/.test(entry.body ?? '')) {
+    lines.push('', `Reason: ${reason}`);
+  }
+  return lines.join('\n');
+}