doctrina-cli 0.15.0 → 0.16.0

package/src/lib/commands.js

@@ -20,7 +20,7 @@ export const COMMAND_NAMES = [
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
   // maintenance
-  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade",
+  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade", "ci",
 ];
 
 // The full operation surface — every `doctrina <command> [<subcommand>]` a
@@ -93,6 +93,7 @@ export const OPERATIONS = [
   ["metrics", "Local git-derived adoption metrics (no network)"],
   ["report", "Markdown digest for a period: changes, gates, git summary"],
   ["completion", "Print bash/zsh/pwsh completions (generated from the catalog)"],
+  ["ci", "Emit the CI pipeline for the declared gate sequence (--emit github)"],
   ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
 ];
 
@@ -118,7 +119,7 @@ export const COMMAND_META = {
   intake:       { moment: "Bootstrap",  when: "you have a full project description and no specs yet", purpose: "store the intent and print the bootstrap playbook" },
   adapter:      { moment: "Bootstrap",  when: "adding or removing an agent's pointer files", purpose: "install/remove agent adapters (additive)" },
 
-  prime:        { moment: "Orient",     when: "at the START of every session", purpose: "gates, standing rules, and open work in one read" },
+  prime:        { moment: "Orient",     when: "at the START of every session", purpose: "gates, open work and next steps in one read (--rules for the full standing rules)" },
   status:       { moment: "Orient",     when: "you need the health of the tree at a glance", purpose: "index, coverage, trace, and artifact counts" },
   next:         { moment: "Orient",     when: "you finished something and do not know what follows", purpose: "the recommended next workflow action" },
   context:      { moment: "Orient",     when: "before working on any task, to load the right files", purpose: "the read pack, assembled to fit a token budget" },
@@ -131,7 +132,7 @@ export const COMMAND_META = {
   triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
   work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", purpose: "scaffold a change and print the playbook to execute" },
   spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
-  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check / tick / diff / abandon" },
+  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check (--verbose) / tick / abandon" },
   decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
   contract:     { moment: "Change",     when: "the change touches ports, env vars, or public endpoints", purpose: "own and verify the integration surface" },
   intent:       { moment: "Change",     when: "new product intent appears after the intake", purpose: "append and list product intent anchors" },
@@ -155,6 +156,7 @@ export const COMMAND_META = {
   metrics:      { moment: "Maintain",   when: "reporting adoption over a period", purpose: "local git-derived adoption metrics" },
   report:       { moment: "Maintain",   when: "summarising a period for a human", purpose: "a Markdown digest of changes, gates, and git" },
   completion:   { moment: "Maintain",   when: "setting up a human's shell", purpose: "print shell completions from the catalog" },
+  ci:           { moment: "Maintain",   when: "the declared gate sequence changed and CI must follow", purpose: "emit the CI pipeline from the gate declaration" },
 };
 
 // The order moments appear in the generated block.
@@ -195,10 +197,48 @@ const SURFACE_HINTS = {
   clarify: "--all (--lang pt|en)",
   close: "<id...>",
   upgrade: "--write",
+  ci: "--emit github",
   prime: "(session start)",
   handoff: "(before compaction/handover)",
 };
 
+// ---------------------------------------------------------------------------
+// Deprecations (change 0049).
+//
+// The surface has a hard 40-line budget precisely so that adding a command
+// forces the question "what comes off?" — and for two releases the answer was
+// "nothing", while the budget was met by compressing a whole moment onto one
+// line (audit finding F23). These are the first two removals, and both are
+// MERGES: the surviving command already does everything the retired one did,
+// which is why they can go without waiting for usage evidence. Usage counts
+// can tell you a command is unloved; only redundancy can tell you it is
+// unnecessary, and an unloved command that does something nothing else does
+// has to stay.
+//
+// A deprecated operation keeps working, warns once on the way through, and
+// leaves the surface block — an agent should not reach for it, and the block
+// is the list of things to reach for. Removal is a later, separate change.
+export const DEPRECATED = Object.freeze({
+  "constitution": {
+    since: "0.16.0",
+    use: "doctrina prime --rules",
+    why: "prime renders the same standing-rules view, from the same collection",
+  },
+  "change diff": {
+    since: "0.16.0",
+    use: "doctrina change check --verbose",
+    why: "check runs every ops block against the target spec and now prints the same per-delta preview",
+  },
+});
+
+/** The deprecation record for an invocation, or null. */
+export function deprecationFor(argv) {
+  const words = argv.filter((a) => !a.startsWith("-"));
+  const two = words.slice(0, 2).join(" ");
+  const one = words[0] ?? "";
+  return DEPRECATED[two] ?? DEPRECATED[one] ?? null;
+}
+
 // The declared size budget for the generated block. A surface that cannot
 // describe itself in this many lines is too large — the answer is to cut
 // commands (M8), never to raise the number.
@@ -219,8 +259,13 @@ const COMPACT_MOMENTS = new Set(["Maintain"]);
 // a name index never told it. Same shape `context` prints for skills —
 // description plus `when:`, body on demand.
 export function surfaceMarkdown() {
+  // A deprecated operation stays in the catalog — `--help` and the shell
+  // completions must still know the name someone types — but leaves this
+  // block: it is the list of commands to REACH FOR, and pointing an agent at
+  // a name that warns when used is worse than not listing it.
   const subsByCmd = new Map();
   for (const [op] of OPERATIONS) {
+    if (DEPRECATED[op]) continue;
     const [cmd, sub] = op.split(" ");
     if (!subsByCmd.has(cmd)) subsByCmd.set(cmd, []);
     if (sub) subsByCmd.get(cmd).push(sub);
@@ -242,7 +287,7 @@ export function surfaceMarkdown() {
     "canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.",
   ];
   for (const moment of MOMENTS) {
-    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment);
+    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment && !DEPRECATED[n]);
     if (cmds.length === 0) continue;
     if (COMPACT_MOMENTS.has(moment)) {
       // Each name still carries the `doctrina ` prefix: the compact line is
@@ -402,6 +447,19 @@ export const AGENT_CHANGELOG_END = "<!-- doctrina:changed:end -->";
 // introduced it. Only entries that alter what an agent should DO belong
 // here — a bug fix nobody's behaviour depends on does not.
 export const AGENT_CHANGELOG = {
+  // Each entry lists only ITS OWN delta. The series carries the rest
+  // forward (see agentChangelogEntries), so a patch never has to restate
+  // the minor that introduced the commands, and never silently erases it.
+  "0.16.0": [
+    "A reference or path that does not resolve now answers exit 2 (USAGE) everywhere — `clarify`, `show`, `why`, `analyze`, `context`, `change check`, `spec set`, `decision accept|scope`. Correct the invocation; retrying it unchanged never succeeds.",
+    "The `--json` envelope names the OPERATION in `command` and carries arguments in `args` — branch on those two, not on a joined string. An undeclared flag now answers with `{ok: false, exit_code: 2}` instead of an empty stdout.",
+    "`analyze` executes a MODIFIED delta's `ops` block, so `analyze`, `change apply` and `close` all refuse the same unappliable block. Fix the ops before closing; a delta with no ops block is still a legitimate manual merge.",
+    "`validate` refuses more: an active spec declaring no acceptance criteria, an empty artifact, a scaffold section left unwritten, a reference that resolves to nothing. Write the criteria before flipping a spec to `active`.",
+    "`change new <id>` requires the `NNNN-slug` shape (lowercase letters, digits, hyphens) and writes nothing otherwise — `doctrina work \"<prompt>\"` derives one for you.",
+  ],
+  "0.15.1": [
+    "Exporting a variable under a name that is not its source's is routine — declare it in the Wiring row's Origin cell as `<origin>:<source>` (e.g. `secrets:NPM_TOKEN`) and RT02 stays silent until either side moves.",
+  ],
   "0.15.0": [
     "`doctrina triage \"<prompt>\"` — classify a request as PRODUCT / RUNTIME / CHORE BEFORE scaffolding. `work` now holds a runtime-shaped prompt with exit 3 and points here; `--force` opens the change anyway.",
     "`contract check` now holds the declared wiring to the implementation: a `vars`/`secrets` variable no workflow exports, a default an empty CI value never triggers, an unvalidated enum, a selector matching zero targets (RT01-RT05).",
@@ -420,9 +478,54 @@ export const AGENT_CHANGELOG = {
 
 // The block written into AGENTS.md for a given version. Empty string when
 // that version has no agent-visible changes.
+// How many bullets the block may carry. Not a style preference: AGENTS.md
+// is always-loaded context under a hard 150-line budget, and at the current
+// template size five bullets is exactly what fits. Raising this means
+// cutting elsewhere — see the `agents-md-lines` budget in the contract.
+export const AGENT_CHANGELOG_MAX_BULLETS = 5;
+
+/**
+ * The bullets an agent arriving at `version` needs, newest first.
+ *
+ * Keyed per version, but rendered per MINOR SERIES. The block REPLACES its
+ * predecessor in AGENTS.md rather than accumulating, so rendering only the
+ * current version's own entry meant every patch silently erased the minor
+ * that introduced the commands: an agent upgrading 0.14.0 -> 0.15.1 would
+ * read one bug fix and never learn `triage` exists. The alternative —
+ * making each patch author restate the whole minor by hand — worked once
+ * and does not scale, because the restating is invisible and the third
+ * patch quietly drops a line to fit the cap.
+ *
+ * So the series carries itself, newest first, and the cap truncates the
+ * OLDEST. A fact that must outlive its series does not belong here: it
+ * belongs in the surface block or the docs, which is the honest place for
+ * something permanent.
+ */
+export function agentChangelogEntries(version) {
+  const series = String(version).split(".").slice(0, 2).join(".");
+  const versions = Object.keys(AGENT_CHANGELOG)
+    .filter((v) => v.split(".").slice(0, 2).join(".") === series && compareVersions(v, version) <= 0)
+    .sort((a, b) => compareVersions(b, a));
+  const out = [];
+  for (const v of versions) out.push(...(AGENT_CHANGELOG[v] ?? []));
+  return out.slice(0, AGENT_CHANGELOG_MAX_BULLETS);
+}
+
+// Numeric semver comparison — "0.15.10" must sort above "0.15.9", which a
+// string compare gets wrong.
+function compareVersions(a, b) {
+  const pa = String(a).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 export function agentChangelogMarkdown(version) {
-  const entries = AGENT_CHANGELOG[version];
-  if (!entries || entries.length === 0) return "";
+  const entries = agentChangelogEntries(version);
+  if (entries.length === 0) return "";
   return [
     `## What changed in ${version}`,
     "",

package/src/lib/config.js

@@ -0,0 +1,206 @@
+// @ts-check
+// The project's configuration, in one place, with WHERE each value came from.
+//
+// Five files configured a Doctrina project and only one of them had an
+// `--init`: `index.json` (the context budget, under `config`), `config.json`
+// (the language, read by `clarify` alone), `rules.json` (project rules,
+// read by `validate` alone), `verify.json`, and `verify.signoffs.json`.
+// `config.json` and `rules.json` were created by nothing, documented in no
+// surface block, and reported by no command — they existed only for someone
+// who had read the source. The symptom that found this (audit finding F19):
+// a pt-BR project sits permanently red under `clarify` with no clue why.
+//
+// `.doctrina/config.json` is now the declared home. The old locations are
+// still READ — a project that configured a budget in `index.json` keeps
+// working, and removal is announced rather than performed here — but every
+// consumer asks this module, and every value carries its source so `doctor`
+// can print "configured" or "default" instead of leaving a project to guess.
+import path from "node:path";
+import { isFile, read } from "./fs-ops.js";
+
+export const CONFIG_REL = ".doctrina/config.json";
+export const RULES_REL = ".doctrina/rules.json";
+
+// The built-in default for every option. `language: null` means "detect per
+// file", which is what the absence of a declaration has always meant.
+export const DEFAULTS = Object.freeze({
+  language: null,
+  context_budget: 15000,
+  rules: [],
+});
+
+// Where a value came from, most authoritative first. The strings are printed
+// by `doctor`, so they name FILES a reader can open, not internal ids.
+export const SOURCES = Object.freeze({
+  config: CONFIG_REL,
+  index: ".doctrina/index.json (config block — legacy home)",
+  rules: RULES_REL + " (legacy home)",
+  default: "default",
+});
+
+export function configPath(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "config.json");
+}
+
+/**
+ * Read the effective configuration.
+ *
+ * Precedence, per option: `.doctrina/config.json` → the legacy home for that
+ * option → the built-in default. Malformed JSON is REPORTED, never thrown:
+ * a project cannot be left unable to assemble a context pack because someone
+ * left a trailing comma in a preferences file — `validate` is where that
+ * becomes an error.
+ *
+ * @param {string} projectRoot
+ * @returns {{
+ *   language: string|null, context_budget: number, rules: any[],
+ *   sources: {language: string, context_budget: string, rules: string},
+ *   errors: string[],
+ *   unknown: string[]
+ * }}
+ */
+export function loadConfig(projectRoot) {
+  const errors = [];
+  const cfg = readJson(configPath(projectRoot), CONFIG_REL, errors);
+  // Keys the CLI does not know (change 0115). `{"context_budjet": 10}` was
+  // silence at every door, and the author believed the budget was set.
+  // Reported, never rejected: the effective values are unchanged.
+  const KNOWN_KEYS = new Set(["language", "context_budget", "rules", "$comment", "$schema"]);
+  const unknown = cfg && typeof cfg === "object" && !Array.isArray(cfg)
+    ? Object.keys(cfg).filter((k) => !KNOWN_KEYS.has(k))
+    : [];
+  /** @type {{language: string, context_budget: string, rules: string}} */
+  const sources = { language: SOURCES.default, context_budget: SOURCES.default, rules: SOURCES.default };
+
+  // language — config.json has always been its only home.
+  //
+  // PRESENCE is what makes an option configured, not the value: a key
+  // scaffolded as its default is still a declaration, and reporting it as
+  // "default" would tell a reader the file does not say what it plainly
+  // says. Only a key that is absent, or one whose value is rejected, falls
+  // back to the default.
+  let language = DEFAULTS.language;
+  if (cfg && "language" in cfg) {
+    const rawLang = cfg.language;
+    sources.language = SOURCES.config;
+    if (rawLang === null) {
+      language = null; // an explicit "detect per file"
+    } else if (typeof rawLang === "string" && normalizeLanguage(rawLang) !== null) {
+      language = normalizeLanguage(rawLang);
+    } else {
+      errors.push(`${CONFIG_REL}: unknown language ${JSON.stringify(rawLang)} (use "en" or "pt", or null to detect per file)`);
+      sources.language = SOURCES.default;
+    }
+  }
+
+  // context_budget — declared here, historically in index.json's config block.
+  let context_budget = DEFAULTS.context_budget;
+  if (cfg && "context_budget" in cfg && isPositiveInt(cfg.context_budget)) {
+    context_budget = cfg.context_budget;
+    sources.context_budget = SOURCES.config;
+  } else {
+    if (cfg && "context_budget" in cfg) {
+      errors.push(`${CONFIG_REL}: context_budget must be a positive integer (got ${JSON.stringify(cfg.context_budget)})`);
+    }
+    const fromIndex = readJson(path.join(projectRoot, ".doctrina", "index.json"), ".doctrina/index.json", [])?.config?.context_budget;
+    if (isPositiveInt(fromIndex)) {
+      context_budget = fromIndex;
+      sources.context_budget = SOURCES.index;
+    }
+  }
+
+  // rules — declared here, historically a file of their own.
+  let rules = DEFAULTS.rules;
+  if (cfg && Array.isArray(cfg.rules)) {
+    rules = cfg.rules;
+    sources.rules = SOURCES.config;
+  } else {
+    if (cfg && "rules" in cfg) {
+      errors.push(`${CONFIG_REL}: rules must be an array`);
+    }
+    const rulesPath = path.join(projectRoot, ".doctrina", "rules.json");
+    if (isFile(rulesPath)) {
+      const legacy = readJson(rulesPath, RULES_REL, errors);
+      if (legacy && !Array.isArray(legacy.rules)) {
+        errors.push(`${RULES_REL}: expected { "rules": [...] }`);
+      } else if (legacy) {
+        rules = legacy.rules;
+        sources.rules = SOURCES.rules;
+      }
+    }
+  }
+
+  return { language, context_budget, rules, sources, errors, unknown };
+}
+
+/**
+ * The configuration as rows a reader can scan: option, effective value, and
+ * where it came from. `doctor` prints these; the point is that a project can
+ * see what it configured without reading the CLI's source.
+ *
+ * @param {string} projectRoot
+ * @returns {{option: string, value: string, source: string, configured: boolean}[]}
+ */
+export function configRows(projectRoot) {
+  const cfg = loadConfig(projectRoot);
+  const show = (v) => (v === null ? "auto-detect per file" : String(v));
+  return [
+    { option: "language", value: show(cfg.language), source: cfg.sources.language, configured: cfg.sources.language !== SOURCES.default },
+    { option: "context_budget", value: `${cfg.context_budget} tokens`, source: cfg.sources.context_budget, configured: cfg.sources.context_budget !== SOURCES.default },
+    { option: "rules", value: `${cfg.rules.length} rule${cfg.rules.length === 1 ? "" : "s"}`, source: cfg.sources.rules, configured: cfg.sources.rules !== SOURCES.default },
+  ];
+}
+
+/** "pt-BR" → "pt", "en-GB" → "en", anything else → null. */
+export function normalizeLanguage(raw) {
+  const lang = String(raw ?? "").toLowerCase();
+  if (lang.startsWith("pt")) return "pt";
+  if (lang.startsWith("en")) return "en";
+  return null;
+}
+
+function isPositiveInt(n) {
+  return Number.isInteger(n) && n > 0;
+}
+
+// A malformed file is a finding, not an exception: every caller of this
+// module is either a gate that will report it or a command that must keep
+// working without it.
+function readJson(file, rel, errors) {
+  if (!isFile(file)) return null;
+  try {
+    return JSON.parse(read(file));
+  } catch (err) {
+    errors.push(`${rel} is not valid JSON: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * The file `init` writes, from the same module that reads it.
+ *
+ * Written from the definition rather than from a template, for the reason
+ * index.json is: a template copy is how a project comes to be born already
+ * needing a scaffold update (audit item C5).
+ *
+ * It declares NOTHING. A scaffold that restated every default would make the
+ * file lie in two directions: `doctor` could no longer tell a choice from a
+ * default, and a written default would silently outrank a legacy declaration
+ * — a project that had set its budget in index.json would find it ignored by
+ * a file it never edited. So the scaffold is documentation of the options,
+ * and the first key a project adds is the first thing it has actually chosen.
+ * JSON carries no comments, hence `$comment`.
+ *
+ * @returns {string} the file's contents, newline-terminated
+ */
+export function scaffoldConfig() {
+  return JSON.stringify({
+    $comment:
+      "Doctrina project configuration. Nothing is declared here yet — add a key to " +
+      "change it. Options: \"language\" (\"en\" | \"pt\", or null to detect per file); " +
+      `"context_budget" (positive integer, default ${DEFAULTS.context_budget}); ` +
+      "\"rules\" (array of { id, forbid, paths, message } — permanent project " +
+      "constraints enforced by `doctrina validate`). Run `doctrina doctor` to see the " +
+      "effective value of each option and where it came from.",
+  }, null, 2) + "\n";
+}

package/src/lib/constitution-model.js

@@ -0,0 +1,102 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+
+// The standing-rules MODEL: the accepted ADRs and the named sections of
+// product.md that together are the project's constitution. `constitution`
+// renders them in full and `prime` digests them to titles, so the reading
+// belongs here rather than in either command (audit finding F7).
+
+// Accepted ADRs (NNNN-slug.md with Status: accepted), oldest first, with the
+// title read from the `# ADR NNNN — <title>` heading. Exported for `prime`,
+// which digests the same standing rules into the session primer.
+export function acceptedDecisions(projectRoot) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  const out = [];
+  if (!isDir(dir)) return out;
+  for (const f of readdirSync(dir).sort()) {
+    const m = f.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(path.join(dir, f));
+    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : f });
+  }
+  return out;
+}
+
+// Bullets under a named `## <section>` of product.md, each accumulated across
+// its continuation lines so a wrapped bullet reads as one rule. Exported for
+// `prime`.
+/**
+ * Does `product.md` carry this `## ` section at all? Separate from whether it
+ * holds anything, so a finding can name the remedy that actually resolves it
+ * (rule C2): "add the section" and "fill the section" are different asks.
+ *
+ * @param {string} projectRoot
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function hasProductSection(projectRoot, name) {
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return false;
+  return new RegExp(`^##\\s+${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "im")
+    .test(read(p));
+}
+
+export function productSection(projectRoot, name) {
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return [];
+  const lines = read(p).split(/\r?\n/);
+  let inSection = false;
+  let inComment = false;
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push(cur.replace(/\s+/g, " ").trim());
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) {
+        flush();
+        break;
+      }
+      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    // An HTML comment is annotation, not content (change 0055): the template's
+    // own instruction for this section must never read as a declared item.
+    if (inComment) {
+      if (line.includes("-->")) inComment = false;
+      continue;
+    }
+    if (line.trim().startsWith("<!--")) {
+      if (!line.includes("-->")) inComment = true;
+      continue;
+    }
+    const m = line.match(/^\s*[-*]\s+(.+)$/);
+    if (m) {
+      flush();
+      cur = m[1];
+    } else if (cur && line.trim() !== "") {
+      cur += " " + line.trim();
+    } else if (line.trim() === "") {
+      flush();
+    } else {
+      // PROSE (change 0069). The section's own template comment invites it —
+      // "Explicit things this project will NOT try to be" asks for no bullets
+      // — and reading only bullets made `prime --rules` report a filled
+      // section as "none declared" and tell the author to add a section that
+      // was already there. Rule C2: a finding may only name a remedy that
+      // resolves it, and this one named an act already done. A paragraph is
+      // one item; a blank line ends it, exactly as it ends a bullet.
+      cur = line.trim();
+    }
+  }
+  flush();
+  return out;
+}