doctrina-cli 0.13.0 → 0.14.0

package/src/lib/commands.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Single canonical list of top-level `doctrina` commands.
 //
 // This is the one place the command surface is named. `src/index.js` builds
@@ -13,7 +14,7 @@ export const COMMAND_NAMES = [
   // bootstrap / day-to-day
   "init", "intake", "work",
   // authoring
-  "spec", "change", "contract", "decision", "skill", "intent",
+  "spec", "change", "contract", "decision", "skill", "intent", "adapter",
   // read / orient
   "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
   // gates
@@ -54,10 +55,14 @@ export const OPERATIONS = [
   ["decision land", "Record that an accepted ADR is now implemented (non-mutating)"],
   ["decision supersede", "Create a new ADR that supersedes an existing one"],
   ["decision list", "List ADRs with status, date, and title"],
+  ["decision scope", "Show and propose the capabilities each ADR governs"],
   ["skill new", "Scaffold an on-demand procedural memory skill"],
   ["skill list", "List skills with their descriptions"],
   ["skill sync", "Mirror skill frontmatter descriptions into index.json"],
   ["skill suggest", "Surface fix-shaped lessons worth a skill (--write scaffolds)"],
+  ["adapter list", "Inventory agent adapters: installed / available / native"],
+  ["adapter add", "Install one agent adapter (additive; never touches AGENTS.md)"],
+  ["adapter remove", "Delete the files an adapter installed"],
   ["intent add", "Append a new product intent anchor post-intake (- [SC5] ...)"],
   ["intent list", "List product.md intent anchors in document order"],
   ["analyze", "Inspect a change folder before applying"],
@@ -90,6 +95,69 @@ export const OPERATIONS = [
   ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
 ];
 
+// ---------------------------------------------------------------------------
+// Per-command PURPOSE and WHEN (audit item M2).
+//
+// The generated surface block was a name index. An agent reading
+// "`doctrina trace --strict`" learns that the command exists and nothing
+// about what triggers it, what it costs, or what it returns — so learning
+// the surface meant running `--help` 35 times, roughly the whole context
+// budget spent on a lookup.
+//
+// Doctrina already solved this for SKILLS: `context` prints a description
+// and a `when:` trigger per skill and tells the agent to load the body only
+// when the trigger fires. Commands get the same treatment.
+//
+// `when` is the moment you reach for it, in the agent's own terms.
+// `purpose` is one line on what it does. Both are required: a command that
+// cannot state its trigger has not earned a place on the surface, and
+// `templates check` fails when either is missing.
+export const COMMAND_META = {
+  init:         { moment: "Bootstrap",  when: "starting a project that has no AGENTS.md yet", purpose: "scaffold AGENTS.md and .doctrina/" },
+  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" },
+  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" },
+  show:         { moment: "Orient",     when: "you need one requirement, criterion, or ADR, not a file", purpose: "point-read a single artifact by reference" },
+  search:       { moment: "Orient",     when: "you do not know which artifact mentions a term", purpose: "search the artifact tree, grouped by category" },
+  why:          { moment: "Orient",     when: "you need to justify or trace a capability's existence", purpose: "provenance: intent, proof, ADRs, and history" },
+  constitution: { moment: "Orient",     when: "you need the standing rules before deciding something", purpose: "accepted ADRs and product non-goals" },
+  handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
+
+  work:         { moment: "Change",     when: "any request arrives that changes behaviour", 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" },
+  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" },
+  skill:        { moment: "Change",     when: "a lesson is worth not relearning", purpose: "capture on-demand procedural memory" },
+
+  analyze:      { moment: "Gate",       when: "before applying a change", purpose: "structural pre-flight on a change folder" },
+  clarify:      { moment: "Gate",       when: "before applying, or before opening a PR", purpose: "smell-test Markdown for ambiguity" },
+  validate:     { moment: "Gate",       when: "after any artifact edit, and before considering work done", purpose: "schema, structure, EARS, and index drift" },
+  coverage:     { moment: "Gate",       when: "before claiming a capability is proven", purpose: "acceptance criteria against cited evidence" },
+  trace:        { moment: "Gate",       when: "checking that product intent still maps to capabilities", purpose: "intent provenance across the tree" },
+  review:       { moment: "Gate",       when: "before handing work back, to self-review it", purpose: "conformance of your changes vs specs/ADRs/contracts" },
+  verify:       { moment: "Gate",       when: "the real build gate must run", purpose: "the project's declared typecheck/test/build checks" },
+  close:        { moment: "Gate",       when: "a change is implemented and ready to finish", purpose: "the whole closing sequence in one attested pass" },
+  doctor:       { moment: "Gate",       when: "something looks wrong and you do not know which gate to ask", purpose: "aggregate diagnostic with per-finding remedies" },
+
+  templates:    { moment: "Maintain",   when: "after upgrading the CLI, or to customise a scaffold", purpose: "inspect, check, and refresh the template shape" },
+  upgrade:      { moment: "Maintain",   when: "you just updated the doctrina-cli package", purpose: "bring this project up to the installed CLI" },
+  index:        { moment: "Maintain",   when: "the index drifted from the tree", purpose: "regenerate index.json from the artifacts on disk" },
+  hooks:        { moment: "Maintain",   when: "setting up a repo so drift cannot be committed", purpose: "install the pre-commit gate" },
+  watch:        { moment: "Maintain",   when: "you want the tree re-synced on every save", purpose: "re-run validate --fix and next continuously" },
+  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" },
+};
+
+// The order moments appear in the generated block.
+export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Maintain"];
+
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the
 // printed surface can never omit an operation the catalog knows about.
 export function surfaceHelp() {
@@ -112,23 +180,13 @@ export const SURFACE_BEGIN =
   "<!-- doctrina:surface:begin — CLI-owned block, generated from the installed command catalog. Refreshed by `doctrina upgrade --write`; edits inside are overwritten. -->";
 export const SURFACE_END = "<!-- doctrina:surface:end -->";
 
-// Workflow grouping for the generated block. A test asserts the flattened
-// names equal COMMAND_NAMES, so a new command cannot ship ungrouped (and
-// therefore cannot ship invisible to AGENTS.md).
-export const SURFACE_GROUPS = [
-  ["Start", ["init", "intake", "work"]],
-  ["Author", ["spec", "change", "contract", "decision", "skill", "intent"]],
-  ["Read / orient", ["prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution"]],
-  ["Gates", ["analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor"]],
-  ["Maintain", ["templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade"]],
-];
 
 // Per-command usage hints appended to the generated reference — arguments and
 // the flags an agent reaches for daily. Cosmetic only; the operation list
 // itself always comes from OPERATIONS.
 const SURFACE_HINTS = {
   work: '"<prompt>" (--capability · --chore · --from-diff · --quiet)',
-  context: "[<cap>] --concat",
+  context: "[<cap>] --for \"<task>\" --concat",
   validate: "(--fix)",
   coverage: "--strict",
   trace: "--strict",
@@ -139,7 +197,25 @@ const SURFACE_HINTS = {
   handoff: "(before compaction/handover)",
 };
 
+// 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.
+export const SURFACE_LINE_BUDGET = 40;
+
+// Moments an agent works IN get a trigger per command. "Maintain" is
+// compressed to one line: those commands are reached for by a human after
+// an upgrade or when wiring a repo, not by an agent mid-loop, and giving
+// each its own line pushed the block past its budget. The budget is the
+// forcing function — a surface that cannot describe itself in 40 lines is
+// too large, and the answer is to cut commands (M8), not to raise it.
+const COMPACT_MOMENTS = new Set(["Maintain"]);
+
 // The full managed section, heading included, between the markers.
+//
+// Organised by MOMENT rather than by category, and each line carries the
+// trigger: an agent scanning it learns WHEN to reach for a command, which
+// a name index never told it. Same shape `context` prints for skills —
+// description plus `when:`, body on demand.
 export function surfaceMarkdown() {
   const subsByCmd = new Map();
   for (const [op] of OPERATIONS) {
@@ -147,26 +223,36 @@ export function surfaceMarkdown() {
     if (!subsByCmd.has(cmd)) subsByCmd.set(cmd, []);
     if (sub) subsByCmd.get(cmd).push(sub);
   }
-  const renderCmd = (cmd) => {
+  const invocation = (cmd) => {
     const subs = subsByCmd.get(cmd) ?? [];
     const hint = SURFACE_HINTS[cmd] ? ` ${SURFACE_HINTS[cmd]}` : "";
-    return subs.length > 0 ? `\`doctrina ${cmd} ${subs.join("|")}\`` : `\`doctrina ${cmd}${hint}\``;
+    return subs.length > 0 ? `${cmd} ${subs.join("|")}` : `${cmd}${hint}`;
   };
+
   const lines = [
     "## Doctrina command surface (generated — reach for these, don't hand-author)",
     "",
-    "Every operation of the installed CLI, grouped by workflow. The CLI",
-    "scaffolds from canonical templates and keeps `index.json` in sync, so",
-    "prefer it over writing artifacts by hand. Details: `doctrina --help`.",
-    "",
+    "Every command, with the moment you reach for it. The CLI scaffolds from",
+    "canonical templates and keeps `index.json` in sync — prefer it over",
+    "hand-authoring. Flags and detail: `doctrina <command> --help`.",
   ];
-  for (const [label, cmds] of SURFACE_GROUPS) {
-    lines.push(`- **${label}:** ${cmds.map(renderCmd).join(" · ")}`);
+  for (const moment of MOMENTS) {
+    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment);
+    if (cmds.length === 0) continue;
+    if (COMPACT_MOMENTS.has(moment)) {
+      // Each name still carries the `doctrina ` prefix: the compact line is
+      // read by validate's drift gate too, which only recognises a command
+      // reference in that form.
+      lines.push(`**${moment}** (triggers: \`doctrina <command> --help\`) — ` +
+        cmds.map((n) => `\`doctrina ${invocation(n)}\``).join(" · "));
+      continue;
+    }
+    lines.push(`**${moment}**`);
+    for (const cmd of cmds) {
+      const meta = COMMAND_META[cmd];
+      lines.push(`- \`doctrina ${invocation(cmd)}\` — ${meta.purpose}. *When:* ${meta.when}.`);
+    }
   }
-  lines.push("");
-  lines.push("Session bookends: `doctrina prime` to orient at session start;");
-  lines.push("`doctrina handoff` before compaction or handover. Continuous:");
-  lines.push("`doctrina watch`. Capture lessons: `doctrina skill suggest`.");
   return lines.join("\n");
 }
 
@@ -175,13 +261,87 @@ export function surfaceBlock() {
   return `${SURFACE_BEGIN}\n${surfaceMarkdown()}\n${SURFACE_END}`;
 }
 
+// The block's CANONICAL POSITION, defined once — by the shipped template,
+// which is the only place the intended layout exists.
+//
+// `templates update` used to APPEND the block, so the same CLI produced two
+// different AGENTS.md layouts: third section on a fresh `init`, dead last
+// after an `upgrade` — behind 117 lines the agent reads first, which is the
+// attention problem design principle #2 exists to prevent, and with no
+// heading of its own before it, so a hierarchical parse read the command
+// surface as content of "## What never goes in this file" (audit item C4).
+//
+// Returns { after, before }: the heading text the block follows in the
+// template, and the heading it precedes. Either may be null.
+export function surfaceAnchors(templateText) {
+  const block = findSurfaceBlock(templateText);
+  if (!block) return { after: null, before: null };
+  const headingsBefore = [...templateText.slice(0, block.start).matchAll(/^##\s+.*$/gm)];
+  const headingAfter = templateText.slice(block.end).match(/^##\s+.*$/m);
+  return {
+    after: headingsBefore.length > 0 ? headingsBefore[headingsBefore.length - 1][0].trim() : null,
+    before: headingAfter ? headingAfter[0].trim() : null,
+  };
+}
+
+// Place `block` into `text` at the canonical position, returning the new
+// text. Used by both `init` (via the template, which already has it there)
+// and `templates update` (on a project that has none), so the two produce
+// the same layout and running it twice is a no-op.
+export function placeSurfaceBlock(text, block, anchors) {
+  const existing = findSurfaceBlock(text);
+  if (existing) return text.slice(0, existing.start) + block + text.slice(existing.end);
+
+  const lines = text.split("\n");
+  const headingIndex = (heading) =>
+    heading ? lines.findIndex((l) => l.trim() === heading) : -1;
+
+  // A section ends at the next heading OR at the start of another CLI-owned
+  // block. The marker comment precedes that block's heading, so scanning for
+  // headings alone would place this block BETWEEN a marker and its own
+  // heading — nesting the two, after which the next regeneration treats the
+  // outer span as stale and deletes everything inside it. That corrupted a
+  // real file before this guard existed.
+  const isBoundary = (line) => /^##\s+/.test(line) || /^\s*<!--\s*doctrina:\w+:begin/.test(line);
+
+  // Preferred: immediately after the section the template puts it after.
+  const afterIdx = headingIndex(anchors.after);
+  if (afterIdx >= 0) {
+    let end = afterIdx + 1;
+    while (end < lines.length && !isBoundary(lines[end])) end += 1;
+    const head = lines.slice(0, end).join("\n").replace(/\s+$/, "");
+    const tail = lines.slice(end).join("\n");
+    return `${head}\n\n${block}\n\n${tail}`.replace(/\n{3,}/g, "\n\n");
+  }
+
+  // Next: immediately before the section the template puts it before.
+  const beforeIdx = headingIndex(anchors.before);
+  if (beforeIdx >= 0) {
+    const head = lines.slice(0, beforeIdx).join("\n").replace(/\s+$/, "");
+    const tail = lines.slice(beforeIdx).join("\n");
+    return `${head}\n\n${block}\n\n${tail}`.replace(/\n{3,}/g, "\n\n");
+  }
+
+  // Last resort: append, with a trailing newline so the file stays well-formed.
+  return `${text.replace(/\s+$/, "")}\n\n${block}\n`;
+}
+
 // Locate the managed block in an AGENTS.md text. Returns
 // { start, end, inner } (string offsets; inner excludes the marker lines)
 // or null when either marker is absent.
 export function findSurfaceBlock(text) {
-  const begin = text.match(/<!--\s*doctrina:surface:begin[\s\S]*?-->/);
+  return findMarkedBlock(text, "surface");
+}
+
+// Shared locator for the CLI-owned marker blocks (surface, changed).
+// Returns { start, end, inner } as string offsets, or null when either
+// marker is missing.
+function findMarkedBlock(text, name) {
+  // Note the doubled backslashes: these are TEMPLATE literals, so `\s`
+  // would collapse to a bare "s" before the RegExp ever sees it.
+  const begin = text.match(new RegExp(`<!--\\s*doctrina:${name}:begin[\\s\\S]*?-->`));
   if (!begin) return null;
-  const endRe = /<!--\s*doctrina:surface:end\s*-->/;
+  const endRe = new RegExp(`<!--\\s*doctrina:${name}:end\\s*-->`);
   const end = endRe.exec(text.slice(begin.index + begin[0].length));
   if (!end) return null;
   const innerStart = begin.index + begin[0].length;
@@ -214,3 +374,56 @@ export function referencedCommands(markdown) {
   }
   return out;
 }
+
+// ---------------------------------------------------------------------------
+// The agent-facing changelog (M2, part 3).
+//
+// Reported from real use: when a new command shipped, the LLM driving
+// Doctrina had no idea the capability existed. It only found out by running
+// `doctrina --help` — which it had no reason to run, because nothing told
+// it anything had changed.
+//
+// CHANGELOG.md is 46 KB of human prose and far too large to carry into a
+// context window. This is three to six lines stating only what alters
+// AGENT behaviour: a new capability, a changed trigger, a removed command.
+// `upgrade --write` refreshes it, so an agent reading AGENTS.md after an
+// upgrade learns what is new without being told to look.
+
+export const AGENT_CHANGELOG_BEGIN =
+  "<!-- doctrina:changed:begin — CLI-owned. Regenerated by `doctrina upgrade --write`. -->";
+export const AGENT_CHANGELOG_END = "<!-- doctrina:changed:end -->";
+
+// What changed for an AGENT, per version. Keyed by the version that
+// 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 = {
+  "0.14.0": [
+    "`doctrina adapter add|remove|list` — add an agent without re-scaffolding; `init --force` no longer overwrites authored AGENTS.md/product.md.",
+    "`doctrina change apply` now refuses what `analyze` refuses; `change check` previews a close, `change tick` checks boxes in bulk.",
+    "Exit codes are a 5-class contract: 1 gate, 2 usage, 3 precondition, 4 environment. Branch on the code, not the prose.",
+    "A change that alters a documented surface must carry its docs — `close` refuses otherwise (`--force` records the gap).",
+    "Project templates under `.doctrina/templates/` now override the bundled ones, per file.",
+  ],
+};
+
+// The block written into AGENTS.md for a given version. Empty string when
+// that version has no agent-visible changes.
+export function agentChangelogMarkdown(version) {
+  const entries = AGENT_CHANGELOG[version];
+  if (!entries || entries.length === 0) return "";
+  return [
+    `## What changed in ${version}`,
+    "",
+    ...entries.map((e) => `- ${e}`),
+  ].join("\n");
+}
+
+export function agentChangelogBlock(version) {
+  const md = agentChangelogMarkdown(version);
+  if (!md) return "";
+  return `${AGENT_CHANGELOG_BEGIN}\n${md}\n${AGENT_CHANGELOG_END}`;
+}
+
+export function findAgentChangelogBlock(text) {
+  return findMarkedBlock(text, "changed");
+}

package/src/lib/criteria.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Shared parser for the "## Acceptance criteria" section of a spec.
 //
 // A criterion is a numbered item that MAY span several lines (continuation

package/src/lib/dates.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Date helpers. Single source so the CLI emits consistent YYYY-MM-DD strings.
 
 export function today(now = new Date()) {

package/src/lib/diff.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Minimal line diff (LCS-based) for `change diff`. Specs are capped at a
 // few hundred lines, so the O(n*m) table is fine and keeps us at zero deps.
 

package/src/lib/doc-model.js

@@ -0,0 +1,287 @@
+// @ts-check
+// The one owner of the on-disk artifact grammar (audit item M3).
+//
+// `.doctrina/` is Doctrina's public API, and its specification had ten
+// homes. The ADR `Status:` grammar existed as ten regex literals across
+// three files, and they were NOT equivalent — some captured, one only
+// tested, two were anchored to end-of-line and so silently failed on a
+// trailing space. Section extraction was reimplemented six times under six
+// names: `extractSection` (twice), `sectionOf`, `sectionParagraph`,
+// `productSection`, and the sections map in `spec-ops`.
+//
+// This violates the framework's own design principle #1 — "single
+// ownership of every fact; no information has two homes."
+//
+// The contract here:
+//
+//   LENIENT ON READ.  `- **Status**: x` and `**Status:** x` both parse, and
+//     a non-canonical form is REPORTED (so `validate --fix` can repair it)
+//     rather than silently accepted or silently missed.
+//   STRICT ON WRITE.  One canonical form per artifact kind, always.
+
+// Artifact kinds and the header form each one canonically uses. Specs and
+// contracts use bare bold; ADRs, proposals, and the intake use list items.
+// Getting this backwards was a documented, recurring authoring mistake, so
+// the CLI now decides it rather than the author remembering.
+export const HEADER_STYLE = Object.freeze({
+  BARE: "bare",   // **Status:** active
+  LIST: "list",   // - **Status:** accepted
+});
+
+export const ARTIFACT_KIND = Object.freeze({
+  SPEC: "spec",
+  CONTRACT: "contract",
+  DECISION: "decision",
+  PROPOSAL: "proposal",
+  INTAKE: "intake",
+  PRODUCT: "product",
+  UNKNOWN: "unknown",
+});
+
+const STYLE_BY_KIND = {
+  [ARTIFACT_KIND.SPEC]: HEADER_STYLE.BARE,
+  [ARTIFACT_KIND.CONTRACT]: HEADER_STYLE.BARE,
+  [ARTIFACT_KIND.PRODUCT]: HEADER_STYLE.BARE,
+  [ARTIFACT_KIND.DECISION]: HEADER_STYLE.LIST,
+  [ARTIFACT_KIND.PROPOSAL]: HEADER_STYLE.LIST,
+  [ARTIFACT_KIND.INTAKE]: HEADER_STYLE.LIST,
+  [ARTIFACT_KIND.UNKNOWN]: HEADER_STYLE.BARE,
+};
+
+export function canonicalStyle(kind) {
+  return STYLE_BY_KIND[kind] ?? HEADER_STYLE.BARE;
+}
+
+// Infer the artifact kind from its path. Deterministic; never reads content.
+export function kindFromPath(relPathPosix) {
+  const p = String(relPathPosix).replace(/\\/g, "/");
+  if (/\/specs\/[^/]+\/spec\.md$/.test(p)) return ARTIFACT_KIND.SPEC;
+  if (/\/contracts\/[^/]+\.md$/.test(p)) return ARTIFACT_KIND.CONTRACT;
+  if (/\/decisions\/\d{4}-.*\.md$/.test(p)) return ARTIFACT_KIND.DECISION;
+  if (/\/changes\/.*\/proposal\.md$/.test(p)) return ARTIFACT_KIND.PROPOSAL;
+  if (/\/intake\.md$/.test(p)) return ARTIFACT_KIND.INTAKE;
+  if (/\/product\.md$/.test(p)) return ARTIFACT_KIND.PRODUCT;
+  return ARTIFACT_KIND.UNKNOWN;
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// THE header grammar. One definition.
+//
+// Lenient by construction: the leading "- " is optional, the colon may sit
+// inside or outside the bold span (`**Status:**` or `**Status**:`), and the
+// value runs to end of line with surrounding space trimmed by the caller.
+// Anchoring to `$` without allowing trailing whitespace is what made two of
+// the old copies fail on files saved with a trailing space.
+// A metadata header REQUIRES a colon, inside or outside the bold span.
+// Without that, bold text used as a pseudo-heading in prose — the
+// `**Positive**` / `**Negative**` / `**Neutral**` blocks every ADR carries —
+// parses as a header and floods the conformance report.
+function headerPattern(name) {
+  const n = escapeRe(name);
+  return new RegExp(`^([ \\t]*)(-[ \\t]+)?\\*\\*${n}[ \\t]*(?::\\*\\*|\\*\\*[ \\t]*:)[ \\t]*(.*?)[ \\t]*$`, "m");
+}
+
+// Read one header. Returns { value, style, conforming, line } or null.
+/**
+ * @returns {{ value: string, style: string, indent: string, raw: string,
+ *             line: number, conforming: boolean } | null}
+ */
+export function readHeader(text, name) {
+  const m = headerPattern(name).exec(String(text));
+  if (!m) return null;
+  const [raw, indent, dash, value] = m;
+  const style = dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE;
+  // Canonical is exactly `**Name:** value` (or `- **Name:** value`).
+  const canonical = `${dash ? "- " : ""}**${name}:** ${value}`.replace(/\s+$/, "");
+  return {
+    value: value.trim(),
+    style,
+    indent,
+    raw,
+    line: text.slice(0, m.index).split("\n").length,
+    conforming: raw.trim() === canonical.trim(),
+  };
+}
+
+// The value only, or null. The replacement for specHeader/listHeader and
+// every ad-hoc `match(/^-\s+\*\*Status:\*\*.../)`.
+export function getHeader(text, name) {
+  return readHeader(text, name)?.value ?? null;
+}
+
+// Write a header in the canonical form for `style`, preserving the style
+// already present when the header exists. Returns the new text, or null
+// when the header is absent — a set that silently does nothing is exactly
+// the drift this prevents.
+/**
+ * @param {string} text
+ * @param {string} name
+ * @param {string} value
+ * @param {{ style?: string }} [opts] Force a header style; defaults to the
+ *   style already present, so a set never silently reformats the artifact.
+ */
+export function setHeader(text, name, value, opts = {}) {
+  const { style } = opts;
+  const existing = readHeader(text, name);
+  if (!existing) return null;
+  const useStyle = style ?? existing.style;
+  const prefix = useStyle === HEADER_STYLE.LIST ? "- " : "";
+  const replacement = `${existing.indent}${prefix}**${name}:** ${value}`.replace(/\s+$/, "");
+  return String(text).replace(headerPattern(name), replacement);
+}
+
+// The PREAMBLE: everything before the first `## ` section. Metadata headers
+// live there in every Doctrina artifact, and only there. Bold text ending in
+// a colon further down is a prose lead-in ("**Standing constraints lived in
+// agent memory:** ..."), not a header — scoping conformance to the preamble
+// is what tells the two apart without guessing.
+export function preamble(text) {
+  const s = String(text);
+  const m = /^##\s+/m.exec(s);
+  return m ? s.slice(0, m.index) : s;
+}
+
+// Every header in the document's preamble, in order, with conformance
+// recorded.
+export function readAllHeaders(fullText) {
+  const text = preamble(fullText);
+  const out = [];
+  const re = /^([ \t]*)(-[ \t]+)?\*\*([A-Za-z][A-Za-z .-]*?)[ \t]*(?::\*\*|\*\*[ \t]*:)[ \t]*(.*?)[ \t]*$/gm;
+  let m;
+  while ((m = re.exec(String(text)))) {
+    const [raw, indent, dash, name, value] = m;
+    const style = dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE;
+    const canonical = `${indent}${dash ? "- " : ""}**${name}:** ${value}`.replace(/\s+$/, "");
+    out.push({
+      name, value: value.trim(), style, indent,
+      line: String(text).slice(0, m.index).split("\n").length,
+      conforming: raw.replace(/\s+$/, "") === canonical,
+    });
+  }
+  return out;
+}
+
+// Headers whose written form is recognised but not canonical, optionally
+// also flagging the wrong style for a known artifact kind. This is what
+// `validate` reports and `validate --fix` repairs.
+/** @param {string} text @param {string} [kind] */
+export function nonConformingHeaders(text, kind = ARTIFACT_KIND.UNKNOWN) {
+  const want = canonicalStyle(kind);
+  const out = [];
+  for (const h of readAllHeaders(text)) {
+    const wrongStyle = kind !== ARTIFACT_KIND.UNKNOWN && h.style !== want;
+    if (!h.conforming || wrongStyle) {
+      out.push({ ...h, wrongStyle, expectedStyle: want });
+    }
+  }
+  return out;
+}
+
+// Rewrite every recognised header into the canonical form for `kind`.
+// Content is never touched — only the header's own punctuation and, when
+// the kind is known, its style.
+/** @param {string} text @param {string} [kind] */
+export function repairHeaders(text, kind = ARTIFACT_KIND.UNKNOWN) {
+  const want = canonicalStyle(kind);
+  const lines = String(text).split("\n");
+  // Repair only the PREAMBLE, and only lines that carry a colon — the same
+  // two constraints reading uses. Without them this rewrote ADR prose:
+  // `**Positive**` became `- **Positive:**`, and a bulleted definition list
+  // `- **dropped intent** — ...` became `- **dropped intent:** — ...`.
+  // A repair that edits prose is worse than the drift it fixes.
+  const firstSection = lines.findIndex((l) => /^##\s+/.test(l));
+  const limit = firstSection < 0 ? lines.length : firstSection;
+  let repaired = 0;
+  for (let i = 0; i < limit; i++) {
+    // Match against the line without its carriage return. On a CRLF
+    // checkout the trailing \r is not [ \t], so anchoring to $ silently
+    // matched nothing and repair became a no-op on exactly the files most
+    // likely to need it.
+    const line = lines[i].replace(/\r$/, "");
+    const eol = lines[i].endsWith("\r") ? "\r" : "";
+    const m = /^([ \t]*)(-[ \t]+)?\*\*([A-Za-z][A-Za-z .-]*?)[ \t]*(?::\*\*|\*\*[ \t]*:)[ \t]*(.*?)[ \t]*$/.exec(line);
+    if (!m) continue;
+    const [, indent, dash, name, value] = m;
+    const style = kind === ARTIFACT_KIND.UNKNOWN ? (dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE) : want;
+    const canonical = `${indent}${style === HEADER_STYLE.LIST ? "- " : ""}**${name}:** ${value}`.replace(/[ \t]+$/, "");
+    if (line.replace(/[ \t]+$/, "") !== canonical) {
+      // Preserve the file's existing line ending: repairing a header must
+      // not rewrite every line of a CRLF file as a side effect.
+      lines[i] = canonical + eol;
+      repaired += 1;
+    }
+  }
+  return { text: lines.join("\n"), repaired };
+}
+
+// ---------------------------------------------------------------- sections
+
+// The body of a `## <name>` section: lines after the heading, up to the
+// next heading of the same or higher level. Replaces six near-identical
+// helpers that disagreed about level handling and trailing whitespace.
+export function getSection(text, name, { level = 2 } = {}) {
+  const lines = String(text).split(/\r?\n/);
+  const head = new RegExp(`^#{${level}}\\s+${escapeRe(name)}\\b`, "i");
+  const boundary = new RegExp(`^#{1,${level}}\\s+`);
+  const out = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (inSection && boundary.test(line)) break;
+    if (!inSection && head.test(line)) { inSection = true; continue; }
+    if (inSection) out.push(line);
+  }
+  return inSection ? out.join("\n") : "";
+}
+
+export function hasSection(text, name, { level = 2 } = {}) {
+  return new RegExp(`^#{${level}}\\s+${escapeRe(name)}\\b`, "im").test(String(text));
+}
+
+// The first non-empty, non-comment paragraph of a section — what `why` and
+// `skill suggest` actually wanted when they each rolled their own.
+export function getSectionParagraph(text, name, { level = 2 } = {}) {
+  const body = getSection(text, name, { level });
+  const para = [];
+  for (const line of body.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("<!--")) continue;
+    if (trimmed === "") {
+      if (para.length > 0) break;
+      continue;
+    }
+    para.push(trimmed);
+  }
+  return para.join(" ");
+}
+
+// Every `## ` heading in document order.
+export function listSections(text, { level = 2 } = {}) {
+  const re = new RegExp(`^#{${level}}\\s+(.+)$`, "gm");
+  const out = [];
+  let m;
+  while ((m = re.exec(String(text)))) out.push(m[1].trim());
+  return out;
+}
+
+// The document's H1 title, or null.
+export function getTitle(text) {
+  const m = /^#\s+(.+)$/m.exec(String(text));
+  return m ? m[1].trim() : null;
+}
+
+// One parse of an artifact: title, headers, section names. The shape
+// `parseArtifact` promises, so callers stop re-deriving it.
+export function parseArtifact(text, { kind = ARTIFACT_KIND.UNKNOWN } = {}) {
+  const headers = readAllHeaders(text);
+  return {
+    kind,
+    title: getTitle(text),
+    headers,
+    headerMap: new Map(headers.map((h) => [h.name, h.value])),
+    sections: listSections(text),
+    nonConforming: nonConformingHeaders(text, kind),
+  };
+}